@monster-orange/den 0.4.2 → 0.4.4

package/src/ui/mcp/views.ts

@@ -0,0 +1,450 @@
+/**
+ * MCP-2: what an agent reads, shaped so it gets a whole, honest picture.
+ *
+ *   - Scoped answers say so (MCP-2.2): a `scope` block naming the workspace
+ *     shown and how much is left out (`hidden: { repos: 6 }`), pointing at
+ *     `org_summary` for the rest.
+ *   - Health is honest (MCP-2.4): every row has a `state` (up, down,
+ *     redirect, pending, unknown, not-checked), and a row with no verdict
+ *     says why.
+ *   - `org_summary` (MCP-2.1): every workspace and repo with status counts,
+ *     the graph, the edge and the environments, for every agent. It never
+ *     carries logs, env values, commands, URLs, paths or check output from
+ *     outside the agent's own workspace: only names and counts.
+ *
+ * Pure: the tools fetch, these shape.
+ */
+import { rollupRepo } from "../../shared/health/rollup.js";
+import { notCheckedReason } from "../../shared/health/not-checked.js";
+import type { McpScope } from "./scope.js";
+
+type Rec = Record<string, unknown>;
+
+const asRecord = (v: unknown): Rec =>
+  v && typeof v === "object" && !Array.isArray(v) ? (v as Rec) : {};
+const asArray = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.length > 0 ? v : undefined;
+
+// ── Workspaces and their repos ──────────────────────────────────────────────
+
+/** Workspace names in an /api/workspaces body. */
+export function workspaceNames(body: unknown): string[] {
+  return Object.keys(asRecord(asRecord(body).workspaces));
+}
+
+/**
+ * The repos a workspace's config names: its service addresses' repos
+ * ("shop/api" → shop) and its managed clones.
+ */
+export function workspaceRepos(body: unknown, ws: string): string[] {
+  const cfg = asRecord(asRecord(asRecord(body).workspaces)[ws]);
+  const repos = new Set<string>();
+  for (const address of Object.keys(asRecord(cfg.services)))
+    repos.add(address.split("/")[0]);
+  for (const repo of Object.keys(asRecord(cfg.repos))) repos.add(repo);
+  return [...repos].sort();
+}
+
+/** Every repo any workspace names. */
+function orgRepos(body: unknown): Set<string> {
+  const all = new Set<string>();
+  for (const ws of workspaceNames(body))
+    for (const r of workspaceRepos(body, ws)) all.add(r);
+  return all;
+}
+
+// ── The scope block (MCP-2.2) ───────────────────────────────────────────────
+
+export interface ScopeBlock {
+  workspace: string;
+  actor: string;
+  /** Set when `workspace` is a granted one, not the agent's own. */
+  grantedFrom?: string;
+  grants?: string[];
+  otherWorkspaces: number;
+  hidden: Record<string, number>;
+  note: string;
+}
+
+/**
+ * The `scope` of a scoped answer about workspace `shown`: what it shows
+ * ("3 services in north (your scope)"), and what it leaves out: the other
+ * workspaces and their repos (`hidden.repos`: repos only they name), plus
+ * any count the tool adds (`extraHidden`, e.g. stacks).
+ */
+export function scopeBlock(
+  scope: McpScope,
+  workspacesBody: unknown,
+  shown: string,
+  shows: { count: number; noun: string },
+  extraHidden: Record<string, number> = {},
+): ScopeBlock {
+  const mine = new Set(workspaceRepos(workspacesBody, shown));
+  const hiddenRepos = [...orgRepos(workspacesBody)].filter(
+    (r) => !mine.has(r),
+  ).length;
+  const others = workspaceNames(workspacesBody).filter(
+    (w) => w !== shown,
+  ).length;
+  const hidden = { repos: hiddenRepos, ...extraHidden };
+  const what = `${shows.count} ${shows.noun}${shows.count === 1 ? "" : "s"}`;
+  const yours =
+    shown === scope.workspace ? "your scope" : `granted to ${scope.actor}`;
+  return {
+    workspace: shown,
+    actor: scope.actor,
+    ...(shown !== scope.workspace ? { grantedFrom: scope.workspace } : {}),
+    ...(scope.grants?.length ? { grants: scope.grants } : {}),
+    otherWorkspaces: others,
+    hidden,
+    note:
+      `${what} in ${shown} (${yours}); ` +
+      `${others} other workspace${others === 1 ? "" : "s"}` +
+      (hiddenRepos
+        ? ` with ${hiddenRepos} more repo${hiddenRepos === 1 ? "" : "s"}`
+        : "") +
+      ": summary only, see org_summary",
+  };
+}
+
+// ── Honest health (MCP-2.4) ─────────────────────────────────────────────────
+
+export type RowState =
+  | "up"
+  | "down"
+  | "redirect"
+  | "pending"
+  | "unknown"
+  | "not-checked";
+
+/** One /api/health row's state. */
+export function rowState(row: Rec): RowState {
+  if (row.ok === true) return "up";
+  if (row.ok === false) return "down";
+  if (str(row.redirect) !== undefined) return "redirect";
+  if (row.pending === true) return "pending";
+  if (str(row.url) !== undefined || str(row.check) !== undefined)
+    return "unknown";
+  return "not-checked";
+}
+
+/** Why a row has the state it has, when that is not obvious from it. */
+function rowWhy(row: Rec, state: RowState, env: string): string | undefined {
+  if (state === "redirect")
+    return `redirect: ${row.status ?? "3xx"} → ${String(row.redirect)} (answering; not counted as down)`;
+  if (state === "pending")
+    return `checked, no answer yet${str(row.error) ? ` (${String(row.error)})` : ""}`;
+  if (state === "unknown")
+    return `checked, but the check could not tell${str(row.error) ? `: ${String(row.error)}` : ""}`;
+  if (state === "not-checked")
+    return (
+      str(row.why) ??
+      notCheckedReason({
+        env,
+        runs: row.runs as never,
+        target: asRecord(row.target) as { env?: string },
+      })
+    );
+  return undefined;
+}
+
+/** A health row with its `state`, and `why` when it has no plain verdict. */
+export function annotateRow(row: unknown, env: string): Rec {
+  const r = asRecord(row);
+  const state = rowState(r);
+  const why = rowWhy(r, state, env);
+  return { ...r, state, ...(why ? { why } : {}) };
+}
+
+export interface StateCounts {
+  services: number;
+  up: number;
+  down: number;
+  redirect: number;
+  pending: number;
+  unknown: number;
+  notChecked: number;
+}
+
+function countStates(states: RowState[]): StateCounts {
+  const c: StateCounts = {
+    services: states.length,
+    up: 0,
+    down: 0,
+    redirect: 0,
+    pending: 0,
+    unknown: 0,
+    notChecked: 0,
+  };
+  for (const s of states) {
+    if (s === "not-checked") c.notChecked++;
+    else c[s]++;
+  }
+  return c;
+}
+
+/** The `status` answer: counts, then every row with its state. */
+export function statusView(rows: unknown, env: string): Rec {
+  const services = asArray(rows).map((r) => annotateRow(r, env));
+  return {
+    env,
+    counts: countStates(services.map((s) => s.state as RowState)),
+    services,
+  };
+}
+
+// ── The graph ───────────────────────────────────────────────────────────────
+
+/**
+ * A scoped `graph` (MCP-2.2): the workspace's own repos and the edges out
+ * of them. A repo they depend on outside the workspace is named in
+ * `outside`; the org-wide map is `org_summary.graph`.
+ */
+export function graphInScope(graph: unknown, repos: readonly string[]): Rec {
+  const g = asRecord(graph);
+  const mine = new Set(repos);
+  const nodes = asArray(g.nodes).filter((n) => mine.has(String(n)));
+  const edges = asArray(g.edges).filter((e) =>
+    mine.has(String(asRecord(e).from)),
+  );
+  const outside = [
+    ...new Set(
+      edges.map((e) => String(asRecord(e).to)).filter((to) => !mine.has(to)),
+    ),
+  ].sort();
+  return {
+    map: "workspace",
+    nodes,
+    edges,
+    ...(Array.isArray(g.order)
+      ? { order: g.order.filter((n) => mine.has(String(n))) }
+      : {}),
+    outside,
+    hiddenNodes: asArray(g.nodes).length - nodes.length,
+  };
+}
+
+/**
+ * The org-wide map from each active workspace's /api/graph (the web server
+ * derives a graph for one workspace: its repos, as that workspace checks
+ * them out). Nodes are the union; an edge two workspaces both derive is
+ * listed once (the first's). `order` is a startup order within one
+ * workspace, so it is kept only when there is one. A workspace whose graph
+ * failed is named in `unavailable`; when every one failed, the first error.
+ */
+export function mergeGraphs(
+  graphs: readonly { workspace: string; graph: unknown }[],
+): Rec {
+  const ok = graphs.filter((x) => !str(asRecord(x.graph).error));
+  const unavailable = graphs
+    .filter((x) => str(asRecord(x.graph).error))
+    .map((x) => ({ workspace: x.workspace, error: asRecord(x.graph).error }));
+  if (!ok.length && unavailable.length) return { error: unavailable[0].error };
+  const nodes = new Set<string>();
+  const edges: unknown[] = [];
+  const seen = new Set<string>();
+  for (const { graph } of ok) {
+    const g = asRecord(graph);
+    for (const n of asArray(g.nodes)) nodes.add(String(n));
+    for (const e of asArray(g.edges)) {
+      const x = asRecord(e);
+      const key = `${String(x.from)}\0${String(x.to)}\0${String(x.kind)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push(e);
+    }
+  }
+  const only = ok.length === 1 ? asRecord(ok[0].graph) : null;
+  return {
+    map: "org-wide",
+    workspaces: ok.map((x) => x.workspace),
+    nodes: [...nodes].sort(),
+    edges,
+    ...(only && Array.isArray(only.order) ? { order: only.order } : {}),
+    ...(unavailable.length ? { unavailable } : {}),
+  };
+}
+
+/** The org-wide graph with names and edge kinds only (no evidence). */
+function graphSummary(graph: unknown): Rec {
+  const g = asRecord(graph);
+  if (str(g.error)) return { error: g.error };
+  return {
+    map: "org-wide",
+    ...(Array.isArray(g.workspaces)
+      ? { workspaces: g.workspaces.map(String) }
+      : {}),
+    nodes: asArray(g.nodes).map(String),
+    edges: asArray(g.edges).map((e) => {
+      const x = asRecord(e);
+      return {
+        from: String(x.from),
+        to: String(x.to),
+        kind: x.kind,
+        blocking: x.blocking,
+      };
+    }),
+    ...(Array.isArray(g.order) ? { order: g.order.map(String) } : {}),
+    ...(Array.isArray(g.unavailable)
+      ? {
+          unavailable: g.unavailable.map((u) => ({
+            workspace: String(asRecord(u).workspace),
+            error: String(asRecord(u).error),
+          })),
+        }
+      : {}),
+  };
+}
+
+// ── The org summary (MCP-2.1) ───────────────────────────────────────────────
+
+export type WorkspaceState =
+  | "running"
+  | "partial"
+  | "stopped"
+  | "unknown"
+  | "inactive";
+
+function workspaceState(active: boolean, c: StateCounts): WorkspaceState {
+  if (!active) return "inactive";
+  const answering = c.up + c.redirect;
+  if (answering > 0 && c.down === 0) return "running";
+  if (answering > 0) return "partial";
+  if (c.down > 0) return "stopped";
+  return "unknown";
+}
+
+/** Rows that belong to workspace `ws`: named in `workspaces`, else by repo. */
+function rowsOf(rows: Rec[], ws: string, repos: Set<string>): Rec[] {
+  return rows.filter((r) =>
+    Array.isArray(r.workspaces)
+      ? r.workspaces.includes(ws)
+      : repos.has(String(r.repo)),
+  );
+}
+
+function repoSummary(repo: string, rows: Rec[], active: boolean): Rec {
+  if (!active) return { repo, state: "inactive" };
+  const states = rows.map((r) => rowState(r));
+  const counts = countStates(states);
+  const rolled = rollupRepo(
+    repo,
+    rows.map((r, i) => ({
+      service: String(r.service),
+      ok: states[i] === "up" ? true : states[i] === "down" ? false : null,
+      isEntrypoint: r.isEntrypoint === true,
+      awaiting: states[i] === "pending",
+    })),
+  );
+  const state =
+    rolled.state === "unknown" && counts.redirect > 0
+      ? "redirect"
+      : rolled.state;
+  return {
+    repo,
+    state,
+    services: counts.services,
+    up: counts.up,
+    down: counts.down,
+    ...(counts.redirect ? { redirect: counts.redirect } : {}),
+    ...(counts.notChecked ? { notChecked: counts.notChecked } : {}),
+  };
+}
+
+/** The edge in a few fields: up, domains, TLS and whether HTTPS serves. */
+function edgeSummary(edge: unknown): Rec {
+  const e = asRecord(edge);
+  if (e.configured === false) return { configured: false };
+  if (str(e.error) && e.configured === undefined) return { error: e.error };
+  const tls = asRecord(e.tls);
+  const https = asRecord(e.https);
+  return {
+    configured: true,
+    up: e.up === true,
+    state: e.state,
+    domains: asArray(e.domains),
+    routes: asArray(e.routes).length,
+    https: {
+      strategy: https.strategy ?? tls.strategy ?? null,
+      ...(https.certs !== undefined ? { certs: https.certs } : {}),
+      serving: typeof https.serving === "boolean" ? https.serving : null,
+      ...(str(https.detail)
+        ? { detail: https.detail }
+        : { detail: "the web server did not say (it predates 0.4.4)" }),
+    },
+  };
+}
+
+export interface OrgSummaryInput {
+  workspaces: unknown;
+  /** /api/health for every active workspace (local). */
+  health: unknown;
+  graph: unknown;
+  edge: unknown;
+  environments: unknown;
+  /** Scoped: the agent's own workspace's /api/health rows (local). */
+  own?: unknown;
+}
+
+/**
+ * The org summary. For workspaces outside the scope only names and counts
+ * are copied: never a row's url, check, error, path or links, and never
+ * the graph's evidence.
+ */
+export function orgSummary(input: OrgSummaryInput, scope?: McpScope): Rec {
+  const body = asRecord(input.workspaces);
+  const active = new Set(asArray(body.active).map(String));
+  const focus = str(body.focus);
+  const rows = asArray(input.health).map(asRecord);
+  const names = workspaceNames(body);
+  const workspaces = names.map((ws) => {
+    const repos = workspaceRepos(body, ws);
+    const isActive = active.has(ws);
+    const mine = isActive ? rowsOf(rows, ws, new Set(repos)) : [];
+    const counts = countStates(mine.map((r) => rowState(r)));
+    return {
+      name: ws,
+      active: isActive,
+      ...(focus === ws ? { focused: true } : {}),
+      ...(scope?.workspace === ws ? { yours: true } : {}),
+      state: workspaceState(isActive, counts),
+      ...(isActive ? { counts } : {}),
+      repos: repos.map((repo) =>
+        repoSummary(
+          repo,
+          mine.filter((r) => String(r.repo) === repo),
+          isActive,
+        ),
+      ),
+    };
+  });
+  const repoCount = orgRepos(body).size;
+  const activeCount = workspaces.filter((w) => w.active).length;
+  const out: Rec = {
+    summary:
+      `${names.length} workspace${names.length === 1 ? "" : "s"} ` +
+      `(${activeCount} active), ${repoCount} repo${repoCount === 1 ? "" : "s"}. ` +
+      "Counts are local health; an inactive workspace is not checked." +
+      (scope
+        ? ` Your scope: ${scope.workspace} (its services are in "yours"); ` +
+          "other workspaces are names and counts only."
+        : ""),
+    workspaces,
+    graph: graphSummary(input.graph),
+    edge: edgeSummary(input.edge),
+    environments: asArray(input.environments).map(String),
+  };
+  if (scope) {
+    out.scope = {
+      workspace: scope.workspace,
+      actor: scope.actor,
+      ...(scope.grants?.length ? { grants: scope.grants } : {}),
+    };
+    out.yours = {
+      workspace: scope.workspace,
+      ...statusView(input.own, "local"),
+    };
+  }
+  return out;
+}

package/src/ui/server/agent-routes.ts

@@ -1,7 +1,17 @@
 /**
  * The Workspaces page's Agents section (AG-4a, AG spec §5c), its routes:
  *
- *   GET  /api/personas                            personas and runtimes
+ *   GET  /api/personas[?workspace=<ws>]           personas and runtimes (each
+ *                                                 with its path, where it came
+ *                                                 from and its version: AG-0.2;
+ *                                                 for <ws>, its own paths win)
+ *   GET  /api/agents/runtimes[?workspace=<ws>]    the runtime catalog as
+ *                                                 Settings › Agents lists it
+ *   POST /api/agents/runtimes/<id>/path           { scope: global|workspace,
+ *                                                 workspace?, bin: path|null }:
+ *                                                 runs its version command and
+ *                                                 refuses a path that isn't
+ *                                                 that runtime (AG-0.5)
  *   GET  /api/workspaces/<ws>/agents              the workspace's agents
  *   POST /api/workspaces/<ws>/agents              start { persona, runtime?, model?, id? }
  *   POST /api/workspaces/<ws>/agents/<id>/stop
@@ -12,14 +22,15 @@
  * `<cli> agents list -w <ws>` shows, and the other way round. A workspace
  * lists its own agents only: another workspace's id is no agent here.
  *
- * Guards on Start, Stop and Resume, as on a service action:
- *   - the lock (R8): locked, the action is refused (423 locked); the page
- *     opens the lock popover first, as Local Dev's service actions do;
+ * Guards on Start, Stop and Resume:
  *   - a person only: an agent (its actor token, SEC-1c) can't start or
  *     stop agents from the page (403; agents use MCP agent_spawn, §5,
  *     under its own guards);
  *   - agents.max_concurrent (the host's cap on agents, never plain
  *     sessions: 429 cap).
+ * The admin password (R8) is no guard here (LK-0): it is for sudo, and
+ * nothing an agent route does runs sudo. Starting, stopping and resuming
+ * an agent never asks for it.
  * The env is the CLI's (§5a-env): the allowlist and the runtime's, built
  * from this server's environment, never all of it. Every action, refused
  * or done, is audited (recordAction) with the person as its actor.
@@ -42,6 +53,7 @@ import {
   listPersonas,
   listRuntimes,
   NOT_IN_WORKSPACE,
+  setRuntimePath,
   resolveAgentsDeps,
   resumeAgent,
   startAgent,
@@ -53,18 +65,16 @@ import {
 import { recordAction } from "./audit.js";
 import { auditActorOf, principalOf } from "./request-guard.js";
 import { readBody, sendJson } from "./http-helpers.js";
-import { hasPasswordlessSudo, hasSudoPassword } from "./sudo-store.js";
 import type { Actor } from "../../shared/agent-actor.js";
 
 export interface AgentRouteDeps {
   /** The operations' deps (tests: an in-process host, a temp state dir). */
   agents?: AgentsDeps;
-  /** R8: whether the lock is open (the lock chip's own status). */
-  unlocked?: () => boolean;
 }
 
 const AGENTS_PATH =
   /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume))?$/;
+const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
 /** A start's body is a few short names. */
 const MAX_BODY = 4096;
 
@@ -87,11 +97,6 @@ function webDeps(over: AgentsDeps = {}): AgentsResolved {
   });
 }
 
-/** The lock chip's state: an admin password set, or sudo without one. */
-function defaultUnlocked(): boolean {
-  return hasSudoPassword() || hasPasswordlessSudo();
-}
-
 /** An AgentError (or the host's refusal) as the R26 answer. */
 function sendError(res: http.ServerResponse, e: unknown, ws?: string): void {
   if (e instanceof AgentError) {
@@ -197,14 +202,31 @@ export async function handleAgentRoutes(
   deps: AgentRouteDeps = {},
 ): Promise<boolean> {
   const m = AGENTS_PATH.exec(pathname);
-  if (pathname !== "/api/personas" && !m) return false;
+  const rp = RUNTIME_PATH.exec(pathname);
+  if (
+    pathname !== "/api/personas" &&
+    pathname !== "/api/agents/runtimes" &&
+    !m &&
+    !rp
+  )
+    return false;
   const method = req.method ?? "GET";
   const d = webDeps(deps.agents);
 
+  if (rp) return runtimePath(req, res, safeDecode(rp[1]), d);
   if (!m) {
-    if (method !== "GET") return methodNotAllowed(res, "GET");
+    if (method !== "GET" && method !== "HEAD")
+      return methodNotAllowed(res, "GET");
     try {
-      sendJson(res, { personas: listPersonas(d), runtimes: listRuntimes(d) });
+      const ws = queryWorkspace(req, d);
+      const runtimes = await listRuntimes(d, ws);
+      sendJson(res, {
+        ...(pathname === "/api/personas" ? { personas: listPersonas(d) } : {}),
+        runtimes,
+        ...(ws ? { workspace: ws } : {}),
+        // AG-0.2: the file a person edits to set a runtime's path.
+        userConfig: d.userConfigFile(),
+      });
     } catch (e) {
       sendError(res, e);
     }
@@ -257,9 +279,9 @@ export async function handleAgentRoutes(
   let what = `${verb} ${id ?? "?"} in ${ws}`;
   try {
     // Another workspace's agent is no agent here: a 404 that doesn't name
-    // it, before the lock (a locked request says the same).
+    // it, before anything else is said about it.
     if (id !== undefined) agentRecord(d, id, ws);
-    guard(actor, deps.unlocked ?? defaultUnlocked);
+    guard(actor);
     if (verb === "start") {
       const body = await startBody(req);
       if (!body.persona)
@@ -291,22 +313,97 @@ export async function handleAgentRoutes(
   return true;
 }
 
+/** `?workspace=<ws>`, when it names a workspace here; else none. */
+function queryWorkspace(
+  req: http.IncomingMessage,
+  d: AgentsResolved,
+): string | undefined {
+  const ws = new URL(req.url ?? "/", "http://x").searchParams.get("workspace");
+  if (!ws) return undefined;
+  if (!d.workspaceExists(ws))
+    throw new AgentError(`workspace "${ws}" does not exist`, { status: 404 });
+  return ws;
+}
+
 /**
- * R8 and the actor: a person, with the lock open. An agent is one its actor
- * token proves (the request checks already refuse its start and resume);
- * an x-den-actor header alone is an unverified claim, not an agent.
+ * POST /api/agents/runtimes/<id>/path: a person only, never an agent (it
+ * runs the path given). Audited, refused or done; never the path's output.
  */
-function guard(actor: Actor, unlocked: () => boolean): void {
+async function runtimePath(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  id: string,
+  d: AgentsResolved,
+): Promise<true> {
+  if (req.method !== "POST") return methodNotAllowed(res, "POST");
+  const actor = auditActorOf(req);
+  let what = `runtime ${id} path`;
+  const audit = (reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "agents",
+        detail: what,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  try {
+    if (actor && !actor.unverified)
+      throw new AgentError("an agent can't set a runtime's path", {
+        status: 403,
+      });
+    const raw = await readBody(req).catch(() => "");
+    if (raw.length > MAX_BODY)
+      throw new AgentError("request too large", { status: 413, usage: true });
+    let v: unknown;
+    try {
+      v = JSON.parse(raw || "{}");
+    } catch {
+      throw new AgentError("invalid JSON", { usage: true });
+    }
+    const b = (v && typeof v === "object" ? v : {}) as Record<string, unknown>;
+    const scope = b.scope === "workspace" ? "workspace" : "global";
+    if (
+      b.scope !== undefined &&
+      b.scope !== "global" &&
+      b.scope !== "workspace"
+    )
+      throw new AgentError('scope must be "global" or "workspace"', {
+        usage: true,
+      });
+    if (b.bin !== null && typeof b.bin !== "string")
+      throw new AgentError("bin must be an absolute path, or null to clear", {
+        usage: true,
+      });
+    const ws = typeof b.workspace === "string" ? b.workspace : undefined;
+    what = `runtime ${id} path (${scope === "workspace" ? `workspace ${ws ?? "?"}` : "global"}${b.bin === null ? ", cleared" : ""})`;
+    const row = await setRuntimePath(d, {
+      id,
+      scope,
+      ...(ws ? { workspace: ws } : {}),
+      bin: b.bin === null ? null : b.bin.trim(),
+    });
+    audit();
+    sendJson(res, { ok: true, runtime: row });
+  } catch (e) {
+    audit(e instanceof Error ? e.message : String(e));
+    sendError(res, e);
+  }
+  return true;
+}
+
+/**
+ * The actor: a person. An agent is one its actor token proves (the request
+ * checks already refuse its start and resume); an x-den-actor header alone
+ * is an unverified claim, not an agent.
+ */
+function guard(actor: Actor): void {
   if (actor && !actor.unverified)
     throw new AgentError(
       "an agent can't start, stop or resume agents from the page; agents use MCP agent_spawn",
       { status: 403 },
     );
-  if (!unlocked())
-    throw new AgentError("Unlock first: agent actions need the lock open", {
-      status: 423,
-      code: "locked",
-    });
 }
 
 function safeDecode(s: string): string {