@stratusagent/cli 0.3.0 → 0.6.0

package/dist/index.js

@@ -1,16 +1,23 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import { createServer } from 'node:http';
-import { once } from 'node:events';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
 import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
-import { createPermissionPolicy } from '@stratusagent/permissions';
+import { loadPlugins } from '@stratusagent/plugins';
+import { createFileCommandWhitelist, createPermissionPolicy, describeCommandScope, } from '@stratusagent/permissions';
 import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
 import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-import { agentsDirPath, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, loadRosterSouls, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, logsDirPath, readWorkingDirectory, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveCredentials, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, loadRosterSouls, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, servedRuntimes, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, } from '@stratusagent/state';
 import { installService, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, uninstallService, } from "./service.js";
 export { installService, launchdPlist, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, systemdUnit, uninstallService, SERVICE_LABEL, } from "./service.js";
 import { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, readRecentRecords, tailLog, } from "./logs.js";
@@ -19,12 +26,7 @@ export { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRec
 // provider wiring now (the gateway uses the same code); the CLI re-exports
 // its historical surface so existing importers keep working.
 export { createFileMemoryStore } from '@stratusagent/state';
-// Kept in step with this package's own version by a test, because it is a
-// second copy of a number nobody re-reads: it is drawn in the setup header
-// and served from the dashboard's /api/status, so drift here misreports the
-// running build rather than failing anything.
-export const CLI_VERSION = '0.3.0';
-const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
+export const CLI_VERSION = '0.6.0';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 /**
  * The range every package declares in its `engines` field. Two floors, not
@@ -77,6 +79,7 @@ Usage:
   STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run "Say hello"
   stratus run --config ./stratus.config.json --provider openai "Say hello"
   stratus agents
+  stratus agents --gateway http://127.0.0.1:4123
   stratus doctor
   stratus service install
   stratus service status
@@ -97,9 +100,13 @@ Commands:
   serve            Run stratusd, the always-on gateway: durable sessions, the
                    whole roster live at once (each agent on its own provider),
                    delegation, and a watchdog — Ctrl+C / SIGTERM drains cleanly
-                   (--idle-timeout <seconds>, --no-events, --no-log-file,
-                   --config <path>); everything it says is also written to
-                   ~/.stratus/logs, which "stratus logs" reads
+                   (--idle-timeout <seconds>, --approvals <headless|remote>,
+                   --no-events, --no-log-file, --config <path>); everything it
+                   says is also written to ~/.stratus/logs, which
+                   "stratus logs" reads. With @stratusagent/control-api
+                   installed it also serves the HTTP + WebSocket control API
+                   on 127.0.0.1:4123 (--no-api, --api-host, --api-port, or
+                   the config file's "api" block)
   service          Keep stratusd running under launchd (macOS) or systemd
                    (Linux): install, uninstall, status, start, stop.
                    Installing starts it now and at every login
@@ -110,11 +117,16 @@ Commands:
                    --format json for the raw records
   agent new        Create an agent identity (generates a human-ish name + avatar theme)
   agents           List your agents: who they are, where their souls live, what
-                   they run on, what they remember (also: stratus agent list)
+                   they run on, what they remember (also: stratus agent list).
+                   --gateway <url> asks a running daemon instead of resolving
+                   locally, authenticating with ~/.stratus/gateway-token
+                   (override with --token or STRATUS_GATEWAY_TOKEN)
   doctor           Show what a run would use right now — provider, model, soul —
                    and which file or environment variable decided each, then
                    flag anything that would surprise you (--format json)
-  dashboard        Start the local Stratus Agent dashboard and open it in your browser
+  dashboard        Open the web dashboard: finds a running daemon (or starts one),
+                   mints a single-use sign-in link, and opens your browser at it.
+                   Needs @stratusagent/control-api and @stratusagent/dashboard
   help             Show this help message
 
 Agent options:
@@ -132,11 +144,19 @@ Options:
   --config         Config file path (run: load settings from it, setup: write it)
   --format         Output format: text or json (default: text)
   --no-events      Hide event-by-event progress lines in text mode
-  --approvals      Tool approval mode: always, ask, or never (default: always)
+  --approvals      run/chat: tool approval mode — always, ask, or never (default: always)
+                   serve: how the daemon reaches a human — headless (refuse every
+                   gated call) or remote (ask in Slack). Default headless, or
+                   the config file's "approvals.mode"
   --max-turns      Maximum provider turns per run (default: 8)
-  --port           Dashboard port, defaults to an open local port
-  --host           Dashboard host (default: 127.0.0.1)
+  --port           dashboard: port for a daemon it starts (default: 4123)
+  --host           dashboard: host for a daemon it starts (default: 127.0.0.1)
   --no-open        Do not open the browser automatically
+  --gateway        agents: read the roster from a running daemon's control API
+  --token          Bearer token for --gateway (default: ~/.stratus/gateway-token)
+  --no-api         serve: do not serve the control API
+  --api-host       serve: control API interface (default: 127.0.0.1)
+  --api-port       serve: control API port (default: 4123, 0 for any free port)
   --help, -h       Show this help message
 
 Config file:
@@ -145,9 +165,28 @@ Config file:
   A "soul" key (or STRATUS_SOUL) points at a soul file so every run uses that agent.
   Legacy STRATUSCLAW_* env vars and stratusclaw.config.json are still supported for compatibility.
 
+Plugins (tools):
+  Capability is optional: install a package, then list it under "plugins" in a
+  TRUSTED config (--config, STRATUS_CONFIG, or ~/.stratus/config.json), keyed by
+  package name. A plugin runs inside this process, so an auto-discovered
+  project-local stratus.config.json may not enable one.
+
+    "plugins": {
+      "@stratusagent/tool-fs": { "enabled": true, "roots": ["~/notes"],
+                                 "agents": { "ava": { "roots": ["~/work/ava"] } } },
+      "@stratusagent/tool-web": { "enabled": true }
+    }
+
+  Available: @stratusagent/tool-fs (fs.read/list/search/write),
+  @stratusagent/tool-shell (shell.run), @stratusagent/tool-web (web.fetch),
+  @stratusagent/tool-browser (browser.goto/read/screenshot/act).
+  Installing one grants no agent anything — each soul lists what it may call.
+
 Soul files:
   A soul file is markdown with frontmatter (name, provider, model, tools, credentials)
   followed by the agent's persona in prose. See examples/souls/ava.md.
+  "tools" takes exact names or a whole toolset: tools: [fs.read, fs.search] or
+  tools: [fs.*]. Omitted means every registered tool.
 `;
 const writeLine = (stream, line = '') => {
     stream.write(`${line}\n`);
@@ -181,7 +220,7 @@ export const parseCommand = (argv, env = {}) => {
     }
     if (command === 'dashboard') {
         let port;
-        let host = DEFAULT_DASHBOARD_HOST;
+        let host;
         let openBrowser = true;
         for (let index = 0; index < rest.length; index += 1) {
             const token = rest[index];
@@ -211,7 +250,12 @@ export const parseCommand = (argv, env = {}) => {
             }
             throw new Error(`Unknown option: ${token}`);
         }
-        return { command: 'dashboard', ...(port !== undefined ? { port } : {}), host, openBrowser };
+        return {
+            command: 'dashboard',
+            ...(port !== undefined ? { port } : {}),
+            ...(host !== undefined ? { host } : {}),
+            openBrowser,
+        };
     }
     if (command === 'serve') {
         const parsed = { command: 'serve', events: true };
@@ -237,6 +281,15 @@ export const parseCommand = (argv, env = {}) => {
                 index += 1;
                 continue;
             }
+            if (token === '--approvals') {
+                const value = readOptionValue(rest, index, '--approvals');
+                if (value !== 'headless' && value !== 'remote') {
+                    throw new Error(`Unsupported approvals mode: ${value}. Use headless or remote.`);
+                }
+                parsed.approvals = value;
+                index += 1;
+                continue;
+            }
             if (token === '--no-events') {
                 parsed.events = false;
                 continue;
@@ -245,6 +298,24 @@ export const parseCommand = (argv, env = {}) => {
                 parsed.logToFile = false;
                 continue;
             }
+            if (token === '--no-api') {
+                parsed.api = false;
+                continue;
+            }
+            if (token === '--api-port') {
+                const port = Number(readOptionValue(rest, index, '--api-port'));
+                if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+                    throw new Error(`Invalid value for --api-port: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                parsed.apiPort = port;
+                index += 1;
+                continue;
+            }
+            if (token === '--api-host') {
+                parsed.apiHost = readOptionValue(rest, index, '--api-host');
+                index += 1;
+                continue;
+            }
             throw new Error(`Unknown option: ${token}`);
         }
         return parsed;
@@ -313,15 +384,17 @@ export const parseCommand = (argv, env = {}) => {
     if (command === 'agents' || (command === 'agent' && rest[0] === 'list')) {
         const agentsRest = command === 'agents' ? rest : rest.slice(1);
         let format = 'text';
+        let gateway;
+        let token;
         for (let index = 0; index < agentsRest.length; index += 1) {
-            const token = agentsRest[index];
-            if (!token) {
+            const argument = agentsRest[index];
+            if (!argument) {
                 continue;
             }
-            if (token === '--help' || token === '-h') {
+            if (argument === '--help' || argument === '-h') {
                 return { command: 'help' };
             }
-            if (token === '--format') {
+            if (argument === '--format') {
                 const value = readOptionValue(agentsRest, index, '--format');
                 if (value !== 'text' && value !== 'json') {
                     throw new Error(`Unsupported format: ${value}`);
@@ -330,9 +403,27 @@ export const parseCommand = (argv, env = {}) => {
                 index += 1;
                 continue;
             }
-            throw new Error(`Unknown option: ${token}`);
+            if (argument === '--gateway') {
+                gateway = readOptionValue(agentsRest, index, '--gateway');
+                index += 1;
+                continue;
+            }
+            if (argument === '--token') {
+                token = readOptionValue(agentsRest, index, '--token');
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${argument}`);
+        }
+        if (token !== undefined && gateway === undefined) {
+            throw new Error('--token only applies with --gateway.');
         }
-        return { command: 'agents', format };
+        return {
+            command: 'agents',
+            format,
+            ...(gateway ? { gateway } : {}),
+            ...(token ? { token } : {}),
+        };
     }
     if (command === 'doctor') {
         let format = 'text';
@@ -656,6 +747,10 @@ export const formatEvent = (event) => {
             return `• tool.completed ${event.result.toolName} ok=${String(event.result.ok)}`;
         case 'tool.denied':
             return `• tool.denied ${event.call.toolName}`;
+        case 'tool.approval-requested':
+            return `• tool.approval-requested ${event.call.toolName} (${event.risk}) for ${event.agentId}`;
+        case 'tool.approval-resolved':
+            return `• tool.approval-resolved ${event.answer} (${event.reason})${event.actor ? ` by ${event.actor}` : ''}`;
         case 'session.completed':
             return `• session.completed ${event.sessionId}`;
         case 'session.failed':
@@ -668,6 +763,14 @@ export const formatEvent = (event) => {
  * The fields worth keeping per event type. Tool inputs and message text
  * are deliberately excluded: the log is a trace of what happened, not a
  * second copy of the transcript.
+ *
+ * The approval pair is the one place the trace carries a person's id, and
+ * it earns it: `always` widens what an agent may do unattended for the rest
+ * of the session, and "who decided that" is unanswerable afterwards from
+ * anything else. The refusal path is warned about by `onDecision`, but an
+ * *approval* produces no warning at all — without these two records a
+ * granted permission leaves no trace whatsoever. Still no tool input: what
+ * was asked is here, what it was asked with is not.
  */
 const eventDetail = (event) => {
     switch (event.type) {
@@ -680,14 +783,30 @@ const eventDetail = (event) => {
             return { tool: event.call.toolName };
         case 'tool.completed':
             return { tool: event.result.toolName, ok: event.result.ok };
+        case 'tool.approval-requested':
+            return { tool: event.call.toolName, risk: event.risk, requestId: event.requestId };
+        case 'tool.approval-resolved':
+            return {
+                requestId: event.requestId,
+                answer: event.answer,
+                reason: event.reason,
+                ...(event.actor ? { actor: event.actor } : {}),
+            };
         case 'session.failed':
             return { error: event.error };
         default:
             return undefined;
     }
 };
-// Kept with its historical CLI signature: a parsed run command is a
-// RuntimeSelection plus CLI-only fields the resolver ignores.
+/**
+ * Kept with its historical CLI signature: a parsed run command is a
+ * RuntimeSelection plus CLI-only fields the resolver ignores.
+ *
+ * Those fields are *permitted*, not required. Demanding a whole
+ * `ParsedRunCommand` made the type claim the resolver cared about
+ * `approvals`, `format`, and `events` — it reads none of them — so every
+ * caller with a selection in hand had to invent values to get past it.
+ */
 export const resolveRuntimeConfig = (command, env = {}) => resolveStateRuntimeConfig(command, env);
 /**
  * A saved subscription sign-in silently demoted to per-token billing is the
@@ -797,6 +916,30 @@ const createAgentRuntime = async (streams, options) => {
             }
         });
     }
+    // The same plugins the daemon would load, from the same trusted config,
+    // so a tool that works in `stratus run` works in `stratus serve` and a
+    // tool that is missing is missing in both. A local test that silently ran
+    // a different toolset than the daemon would be worse than no local test.
+    const pluginsConfig = await loadServePlugins(runEnv, options.configPath, (line) => {
+        writeLine(streams.stderr, `Warning: ${line}`);
+    });
+    const loadedPlugins = [];
+    if (Object.keys(pluginsConfig).length > 0) {
+        const result = await loadPlugins({
+            config: pluginsConfig,
+            host: {
+                resolve: (specifier) => import.meta.resolve(specifier),
+                import: (specifier) => import(__rewriteRelativeImportExtension(specifier)),
+            },
+            tools,
+            bus,
+            workspaceRoot: workspacesDirPath(runEnv),
+        });
+        loadedPlugins.push(...result.loaded);
+        for (const failure of result.failures) {
+            writeLine(streams.stderr, `Warning: plugin ${failure.package} did not load: ${failure.reason}`);
+        }
+    }
     // The Claude Code runtime executes kernel tools by calling back into the
     // runner built just below — late-bound because the runner needs the
     // provider first.
@@ -831,16 +974,36 @@ const createAgentRuntime = async (streams, options) => {
             model: options.runtime.model,
             ...(options.runtime.provider === 'openai' ? { baseUrl: options.runtime.baseUrl } : {}),
         };
-    return { runner, agent, metadata };
+    // Handed back so a command can release what a plugin acquired — a browser
+    // above all. A one-shot `stratus run` that left a Chromium behind would
+    // be a leak per invocation.
+    const disposePlugins = async () => {
+        for (const plugin of loadedPlugins) {
+            try {
+                await plugin.instance.dispose?.();
+            }
+            catch (error) {
+                writeLine(streams.stderr, `Warning: plugin ${plugin.package} failed to shut down: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    };
+    return { runner, agent, metadata, disposePlugins };
 };
 export const runSingleLoop = async (prompt, streams, options) => {
-    const { runner, agent, metadata } = await createAgentRuntime(streams, options);
-    return runner.run({
-        sessionId: randomUUID(),
-        agent,
-        userMessage: prompt,
-        metadata,
-    });
+    const { runner, agent, metadata, disposePlugins } = await createAgentRuntime(streams, options);
+    try {
+        return await runner.run({
+            sessionId: randomUUID(),
+            agent,
+            userMessage: prompt,
+            metadata,
+        });
+    }
+    finally {
+        // Even when the run failed: a plugin that started a browser started it
+        // before the turn could fail.
+        await disposePlugins();
+    }
 };
 export const printSessionSummary = (session, streams) => {
     writeLine(streams.stdout);
@@ -962,11 +1125,12 @@ export const runChat = async (command, streams, env = {}) => {
             pendingApproval = resolve;
         });
     };
-    const { runner, agent, metadata } = await createAgentRuntime(streams, {
+    const { runner, agent, metadata, disposePlugins } = await createAgentRuntime(streams, {
         runtime,
         approvals: command.approvals,
         askApproval,
         ...(command.maxTurns !== undefined ? { maxTurns: command.maxTurns } : {}),
+        ...(command.configPath ? { configPath: command.configPath } : {}),
         env,
         onEvent: (event) => {
             if (command.events) {
@@ -1068,6 +1232,8 @@ export const runChat = async (command, streams, env = {}) => {
         }
     }
     rl.close();
+    // A chat that held a browser open for an hour still has to put it down.
+    await disposePlugins();
     if (interactive) {
         writeLine(streams.stdout, dim(`Bye — ${agent.name} keeps what they remembered.`));
     }
@@ -1081,118 +1247,6 @@ const formatRuntimeBanner = (runtime) => {
     const fallbackSuffix = runtime.fallback ? ` fallback=${runtime.fallback.model}` : '';
     return `Starting Stratus Agent local loop with provider=${runtime.provider} model=${runtime.model}${fallbackSuffix}${soulSuffix}`;
 };
-const escapeHtml = (value) => value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;');
-const renderDashboardHtml = (url) => `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${DASHBOARD_TITLE}</title>
-    <style>
-      :root { color-scheme: dark; }
-      * { box-sizing: border-box; }
-      body {
-        margin: 0;
-        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
-        background: radial-gradient(circle at top, #1f3a5f 0%, #0b1020 45%, #05070f 100%);
-        color: #f3f7ff;
-      }
-      main { max-width: 960px; margin: 0 auto; padding: 40px 20px 72px; }
-      .hero, .card { background: rgba(10, 16, 32, 0.74); border: 1px solid rgba(148, 163, 184, 0.2); border-radius: 20px; backdrop-filter: blur(12px); }
-      .hero { padding: 32px; margin-bottom: 20px; }
-      .eyebrow { display: inline-block; font-size: 12px; letter-spacing: 0.12em; text-transform: uppercase; color: #93c5fd; }
-      h1 { font-size: clamp(32px, 6vw, 56px); line-height: 1; margin: 14px 0 12px; }
-      p { color: #cbd5e1; line-height: 1.6; }
-      .grid { display: grid; gap: 20px; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); }
-      .card { padding: 24px; }
-      .stat { font-size: 28px; font-weight: 700; margin: 6px 0; }
-      code, pre, textarea { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
-      textarea {
-        width: 100%; min-height: 120px; border-radius: 14px; border: 1px solid rgba(148, 163, 184, 0.28);
-        background: rgba(15, 23, 42, 0.9); color: #e2e8f0; padding: 14px; resize: vertical;
-      }
-      button {
-        margin-top: 12px; border: 0; border-radius: 999px; padding: 12px 18px; font-weight: 700; cursor: pointer;
-        background: linear-gradient(135deg, #60a5fa, #22d3ee); color: #08111f;
-      }
-      pre {
-        margin: 14px 0 0; padding: 14px; border-radius: 14px; overflow: auto;
-        background: rgba(2, 6, 23, 0.9); border: 1px solid rgba(148, 163, 184, 0.2); color: #bfdbfe;
-      }
-      a { color: #7dd3fc; }
-    </style>
-  </head>
-  <body>
-    <main>
-      <section class="hero">
-        <span class="eyebrow">Stratus Agent local dashboard</span>
-        <h1>Stratus Agent is up.</h1>
-        <p>A tiny dashboard for local testing. It confirms the CLI is reachable, gives you a quick action, and keeps the current repo intent visible.</p>
-        <p><strong>Local URL:</strong> <a href="${escapeHtml(url)}">${escapeHtml(url)}</a></p>
-      </section>
-      <section class="grid">
-        <article class="card">
-          <div class="eyebrow">Status</div>
-          <div class="stat">Ready</div>
-          <p>The local server is running with Node standard library primitives only.</p>
-        </article>
-        <article class="card">
-          <div class="eyebrow">About</div>
-          <div class="stat">Minimal by design</div>
-          <p>Use <code>stratus run</code> for the agent loop, or use the tester here to verify browser-to-local requests during development.</p>
-        </article>
-      </section>
-      <section class="card" style="margin-top:20px;">
-        <div class="eyebrow">Actionable test</div>
-        <h2 style="margin:12px 0 8px;">Echo tester</h2>
-        <p>Send a payload to the local dashboard API and inspect the response.</p>
-        <textarea id="payload">Hello from Stratus Agent dashboard</textarea>
-        <button id="send">POST /api/echo</button>
-        <pre id="result">Waiting for input…</pre>
-      </section>
-    </main>
-    <script>
-      const button = document.getElementById('send');
-      const payload = document.getElementById('payload');
-      const result = document.getElementById('result');
-      button.addEventListener('click', async () => {
-        result.textContent = 'Sending...';
-        try {
-          const response = await fetch('/api/echo', {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ text: payload.value })
-          });
-          const data = await response.json();
-          result.textContent = JSON.stringify(data, null, 2);
-        } catch (error) {
-          result.textContent = String(error);
-        }
-      });
-    </script>
-  </body>
-</html>`;
-const readBody = async (request) => {
-    let data = '';
-    for await (const chunk of request) {
-        data += chunk.toString();
-    }
-    return data;
-};
-const sendJson = (response, statusCode, payload) => {
-    response.statusCode = statusCode;
-    response.setHeader('content-type', 'application/json; charset=utf-8');
-    response.end(JSON.stringify(payload, null, 2));
-};
-const sendHtml = (response, html) => {
-    response.statusCode = 200;
-    response.setHeader('content-type', 'text/html; charset=utf-8');
-    response.end(html);
-};
 export const openExternalUrl = async (url) => {
     const platform = process.platform;
     const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
@@ -1206,74 +1260,6 @@ export const openExternalUrl = async (url) => {
         });
     });
 };
-export const startDashboardServer = async (options) => {
-    const server = createServer(async (request, response) => {
-        const method = request.method ?? 'GET';
-        const requestUrl = new URL(request.url ?? '/', 'http://localhost');
-        if (method === 'GET' && requestUrl.pathname === '/') {
-            const address = server.address();
-            const port = typeof address === 'object' && address ? address.port : options.port ?? 0;
-            const host = typeof address === 'object' && address && address.address ? address.address : options.host;
-            sendHtml(response, renderDashboardHtml(`http://${host === '::' ? '127.0.0.1' : host}:${port}`));
-            return;
-        }
-        if (method === 'GET' && requestUrl.pathname === '/api/status') {
-            sendJson(response, 200, {
-                ok: true,
-                service: 'stratus-dashboard',
-                version: CLI_VERSION,
-                now: new Date().toISOString(),
-            });
-            return;
-        }
-        if (method === 'POST' && requestUrl.pathname === '/api/echo') {
-            const raw = await readBody(request);
-            let text = '';
-            if (raw.trim().length > 0) {
-                const payload = JSON.parse(raw);
-                text = typeof payload.text === 'string' ? payload.text : '';
-            }
-            sendJson(response, 200, {
-                ok: true,
-                received: text,
-                uppercase: text.toUpperCase(),
-                length: text.length,
-            });
-            return;
-        }
-        sendJson(response, 404, { ok: false, error: 'Not found' });
-    });
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(options.port ?? 0, options.host, () => {
-            server.off('error', reject);
-            resolve();
-        });
-    });
-    const address = server.address();
-    if (!address || typeof address === 'string') {
-        throw new Error('Unable to determine dashboard server address.');
-    }
-    const host = address.address === '::' ? '127.0.0.1' : address.address;
-    const url = `http://${host}:${address.port}`;
-    return {
-        url,
-        close: async () => {
-            if (!server.listening) {
-                return;
-            }
-            await new Promise((resolve, reject) => {
-                server.close((error) => {
-                    if (error) {
-                        reject(error);
-                        return;
-                    }
-                    resolve();
-                });
-            });
-        },
-    };
-};
 // Printed commands must survive copy-paste into a shell, so anything outside
 // the safe character set gets single-quoted.
 const quoteShellArg = (value) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
@@ -1581,34 +1567,6 @@ const createSetupPrompter = (streams, env, view) => {
         },
     };
 };
-// Live check that a pasted key actually works, so the user finds out inside
-// setup instead of on their first run.
-const verifyProviderKey = async (provider, key, baseUrl, fetchImpl) => {
-    if (typeof fetchImpl !== 'function') {
-        return { status: 'unreachable', detail: 'fetch is unavailable' };
-    }
-    const root = (baseUrl ?? (provider === 'anthropic' ? DEFAULT_ANTHROPIC_BASE_URL : DEFAULT_OPENAI_BASE_URL)).replace(/\/+$/, '');
-    const url = provider === 'anthropic' ? `${root}/v1/models` : `${root}/models`;
-    const headers = provider === 'anthropic'
-        ? { 'x-api-key': key, 'anthropic-version': '2023-06-01' }
-        : { authorization: `Bearer ${key}` };
-    try {
-        const response = await fetchImpl(url, { headers });
-        if (response.ok) {
-            return { status: 'ok' };
-        }
-        // Only an explicit auth failure condemns the key. Compatible endpoints
-        // (local models, proxies) often lack GET /models entirely — a 404/405
-        // there says nothing about the key, so it stays saveable.
-        if (response.status === 401 || response.status === 403) {
-            return { status: 'rejected', detail: `HTTP ${response.status}` };
-        }
-        return { status: 'unreachable', detail: `the endpoint did not support a key check (HTTP ${response.status})` };
-    }
-    catch (error) {
-        return { status: 'unreachable', detail: error instanceof Error ? error.message : String(error) };
-    }
-};
 // Slack verification talks to the Web API over plain fetch rather than
 // through @stratusagent/channel-slack. Setup must stay usable before that
 // optional package is installed, and the CLI deliberately does not depend
@@ -1691,7 +1649,12 @@ export const slackAppManifest = (agentName) => JSON.stringify({
     oauth_config: { scopes: { bot: SLACK_BOT_SCOPES } },
     settings: {
         event_subscriptions: { bot_events: SLACK_BOT_EVENTS },
-        interactivity: { is_enabled: false },
+        // Required for remote approval: Allow / Always allow / Deny arrive as
+        // block_actions, and Slack delivers none of them to an app that has
+        // interactivity switched off. Enabled unconditionally rather than per
+        // mode — an app is created once, and discovering months later that the
+        // buttons do nothing means editing the manifest and reinstalling.
+        interactivity: { is_enabled: true },
         org_deploy_enabled: false,
         socket_mode_enabled: true,
         token_rotation_enabled: false,
@@ -1702,18 +1665,6 @@ const DEFAULT_SOUL_STARTER = [
     'keep replies short unless the question genuinely needs depth. Use',
     'memory.remember for durable facts about the people you work with.',
 ].join('\n');
-// Shown when live model listing is unavailable (e.g. subscription tokens
-// cannot call the models endpoint, or the machine is offline).
-// Model ids that cannot serve /chat/completions and must not become the
-// default: embeddings, audio, images, moderation, and legacy completions.
-const NON_CHAT_MODEL_PATTERN = /embed|whisper|tts|audio|dall-e|image|moderation|realtime|transcribe|davinci|babbage|curie|(^|[-_])ada([-_]|$)/i;
-const KNOWN_CLAUDE_MODELS = [
-    'claude-opus-5',
-    'claude-sonnet-5',
-    'claude-haiku-4-5',
-    'claude-opus-4-6',
-    'claude-sonnet-4-6',
-];
 export const runSetup = async (command, streams, env = {}) => {
     const cwd = readWorkingDirectory(env);
     const processEnv = readProcessEnv(env);
@@ -1816,7 +1767,9 @@ export const runSetup = async (command, streams, env = {}) => {
         consumeNotices: () => recentNotices.splice(0),
     });
     const defaultModelFor = (provider) => provider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL;
-    const defaultKeyEnvFor = (provider) => provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    // Widened to CliProviderName only so setup can ask about the provider it
+    // currently has selected, `demo` included; the rule itself is the shared one.
+    const defaultKeyEnvFor = (provider) => defaultApiKeyEnvName(provider === 'openai' ? 'openai' : 'anthropic');
     const credentialLabel = (credential) => credential.type === 'oauth_token' ? 'Claude subscription' : 'API key';
     const providerSignInStatus = (provider) => {
         const credential = state.credentials[provider];
@@ -2078,85 +2031,16 @@ export const runSetup = async (command, streams, env = {}) => {
             await maybeSwitchDefault('anthropic');
         }
     };
-    // Every model the current sign-ins can actually reach, fetched live where
-    // possible. Subscription tokens cannot call the models endpoint, so those
-    // fall back to the known Claude lineup.
-    const collectAvailableModels = async () => {
-        const fetchImpl = env.fetch ?? globalThis.fetch;
-        const models = [];
-        for (const provider of ['anthropic', 'openai']) {
-            // Discovery uses the credential a real run would use. STRATUS_API_KEY
-            // and a configured apiKeyEnv authenticate the DEFAULT provider only —
-            // a secondary provider relies on its own env var or stored sign-in,
-            // never the default provider's secret.
-            const envKey = (provider === state.provider
-                ? readNonEmptyString(processEnv.STRATUS_API_KEY)
-                    ?? (state.apiKeyEnv ? readNonEmptyString(processEnv[state.apiKeyEnv]) : undefined)
-                : undefined)
-                ?? readNonEmptyString(processEnv[defaultKeyEnvFor(provider)]);
-            const credential = envKey ? undefined : state.credentials[provider];
-            const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
-            if (!apiKey && !credential) {
-                continue;
-            }
-            if (provider === 'anthropic') {
-                if (!apiKey || typeof fetchImpl !== 'function') {
-                    // Subscription tokens cannot call the models endpoint.
-                    models.push(...KNOWN_CLAUDE_MODELS.map((id) => ({ provider, id })));
-                    continue;
-                }
-                // The same endpoint a real run uses: the stored key's bound URL is
-                // authoritative, then a configured anthropic base URL (a proxy) —
-                // never the official endpoint by accident.
-                const anthropicRoot = ((credential?.type === 'api_key' ? credential.baseUrl : undefined)
-                    ?? (state.provider === 'anthropic' ? state.baseUrl : undefined)
-                    ?? DEFAULT_ANTHROPIC_BASE_URL).replace(/\/+$/, '');
-                try {
-                    const response = await fetchImpl(`${anthropicRoot}/v1/models?limit=100`, {
-                        headers: { 'x-api-key': String(apiKey), 'anthropic-version': '2023-06-01' },
-                    });
-                    const payload = await response.json();
-                    const ids = (payload.data ?? []).map((entry) => entry.id).filter((id) => typeof id === 'string');
-                    models.push(...(ids.length > 0 ? ids : KNOWN_CLAUDE_MODELS).map((id) => ({ provider, id })));
-                }
-                catch {
-                    models.push(...KNOWN_CLAUDE_MODELS.map((id) => ({ provider, id })));
-                }
-                continue;
-            }
-            if (!apiKey || typeof fetchImpl !== 'function') {
-                continue;
-            }
-            try {
-                // A stored key's bound endpoint is authoritative, exactly as at run
-                // time; only env-supplied keys follow the default provider's URL.
-                const root = ((credential?.type === 'api_key' ? credential.baseUrl : undefined)
-                    ?? (state.provider === 'openai' ? state.baseUrl : undefined)
-                    ?? DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, '');
-                const response = await fetchImpl(`${root}/models`, {
-                    headers: { authorization: `Bearer ${String(apiKey)}` },
-                });
-                const payload = await response.json();
-                const allIds = (payload.data ?? [])
-                    .map((entry) => entry.id)
-                    .filter((id) => typeof id === 'string');
-                // Runs always call /chat/completions, so embedding, audio, image,
-                // moderation, and legacy completion models would save a default
-                // that cannot execute. If filtering leaves nothing (an exotic local
-                // service), show everything rather than an empty menu.
-                const chatIds = allIds.filter((id) => !NON_CHAT_MODEL_PATTERN.test(id));
-                const ids = (chatIds.length > 0 ? chatIds : allIds).sort((a, b) => {
-                    const rank = (id) => (/^gpt/i.test(id) ? 0 : /^o\d/i.test(id) ? 1 : 2);
-                    return rank(a) - rank(b) || a.localeCompare(b);
-                });
-                models.push(...ids.map((id) => ({ provider, id })));
-            }
-            catch {
-                // No reachable model list for this provider; skip it.
-            }
-        }
-        return models;
-    };
+    // Every model the current sign-ins can actually reach. The rule lives in
+    // @stratusagent/state because the control API answers the same question —
+    // setup passes the selection it is *holding* rather than the saved one, so
+    // a key pasted a moment ago is already in play.
+    const collectAvailableModels = () => collectModels({
+        provider: state.provider,
+        ...(state.baseUrl !== undefined ? { baseUrl: state.baseUrl } : {}),
+        ...(state.apiKeyEnv !== undefined ? { apiKeyEnv: state.apiKeyEnv } : {}),
+        credentials: state.credentials,
+    }, env);
     const pickModel = async (kind) => {
         const available = await collectAvailableModels();
         if (available.length === 0) {
@@ -2298,17 +2182,12 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         const name = await prompter.ask('Name your agent (Enter to have one generated): ');
         const instructions = await prompter.ask('Describe their personality in a sentence or two (Enter for a starter you can edit later): ');
-        const agent = defineAgent({
-            ...(name ? { name } : {}),
-            instructions: instructions || DEFAULT_SOUL_STARTER,
-        });
-        const soul = formatSoul({
-            agent,
-            ...(state.provider !== 'demo' ? { provider: state.provider, model: state.model ?? defaultModelFor(state.provider) } : {}),
-        });
-        const soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-        await mkdir(path.dirname(soulPath), { recursive: true });
-        await writeFile(soulPath, soul);
+        const persona = instructions || DEFAULT_SOUL_STARTER;
+        const pin = state.provider !== 'demo'
+            ? { provider: state.provider, model: state.model ?? defaultModelFor(state.provider) }
+            : {};
+        const claimed = await claimSoulFile(env, { ...(name ? { name } : {}), instructions: persona }, (agent) => formatSoul({ agent, ...pin }), (message) => writeLine(streams.stdout, message));
+        const { agent, soulPath } = claimed;
         state.soulPath = soulPath;
         writeLine(streams.stdout, `Say hello to ${agent.name}.`);
         writeLine(streams.stdout, `Their soul lives at ${soulPath} — edit it any time to change how they talk.`);
@@ -2500,19 +2379,31 @@ export const runSetup = async (command, streams, env = {}) => {
         // built-in's place — the gateway skips it, so offering it here would
         // name an app after an agent that never receives the messages.
         const entries = [{ soul: { agent: { ...DEFAULT_STRATUS_AGENT } } }];
-        // Mirror the gateway's loadRoster: two soul files declaring the same
-        // id are not two agents. Offering both would let someone create and
-        // name an app for the loser, which can never receive a message —
-        // Slack credentials are keyed by the shared id, and dispatch reaches
-        // the first sorted file.
-        for (const entry of await loadRosterSouls(env, warnOnce)) {
-            const clash = entries.find((seen) => seen.soul.agent.id === entry.soul.agent.id);
-            if (clash) {
-                warnOnce(`duplicate agent id ${entry.soul.agent.id} (${clash.path ?? 'built-in'} vs ${entry.path}); keeping the first`);
-                continue;
-            }
-            entries.push(entry);
+        // loadRosterSouls refuses a roster whose files collide, and drops the
+        // ones claiming the reserved built-in id, so what comes back here is
+        // already unambiguous.
+        let rosterSouls = [];
+        let rosterLoaded = true;
+        try {
+            rosterSouls = await loadRosterSouls(env, warnOnce);
         }
+        catch (error) {
+            // A roster that cannot say who its agents are cannot have channels
+            // configured for them — but the rest of setup (providers, models,
+            // sign-ins) still works, so this reports and moves on rather than
+            // taking the whole command down.
+            rosterLoaded = false;
+            warnOnce(error instanceof Error ? error.message : String(error));
+            // Nothing is offered, not merely the colliding pair. A roster that
+            // refuses to load fails `createGateway.start()` outright, so no
+            // agent is servable — not the built-in seeded above, and not the
+            // configured soul resolved below (which can itself BE one of the
+            // colliding files). Listing any of them invites connecting a Slack
+            // app to an agent the daemon cannot bring online, and connecting an
+            // app is the expensive half of that mistake.
+            return { entries: [], loaded: false };
+        }
+        entries.push(...rosterSouls);
         // The soul a run resolves to, in resolveSoulPath's own order: an env
         // override outranks the config value this setup session is editing.
         // Listing the config soul while `stratus serve` registers the env one
@@ -2525,11 +2416,11 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         const effectiveSoul = typeof envSoul === 'string' ? envSoul : state.soulPath;
         if (!effectiveSoul) {
-            return entries;
+            return { entries, loaded: rosterLoaded };
         }
         const resolved = path.resolve(readWorkingDirectory(env), effectiveSoul);
         if (entries.some((entry) => entry.path === resolved)) {
-            return entries;
+            return { entries, loaded: rosterLoaded };
         }
         try {
             const soul = await loadSoulFile(resolved);
@@ -2548,7 +2439,7 @@ export const runSetup = async (command, streams, env = {}) => {
         catch (error) {
             warnOnce(`could not read the default soul ${resolved} (${error instanceof Error ? error.message : String(error)})`);
         }
-        return entries;
+        return { entries, loaded: rosterLoaded };
     };
     const serviceSummary = () => {
         if (!servicePlatform(serviceEnvFor(env))) {
@@ -2594,7 +2485,7 @@ export const runSetup = async (command, streams, env = {}) => {
     };
     const chooseChannels = async () => {
         while (true) {
-            const roster = await channelRoster();
+            const { entries: roster, loaded: rosterLoaded } = await channelRoster();
             const slack = state.channels.slack ?? {};
             // The roster always holds at least the built-in agent, so there is
             // no empty state to short-circuit on — and short-circuiting would
@@ -2606,7 +2497,19 @@ export const runSetup = async (command, streams, env = {}) => {
             });
             // Orphans: tokens whose agent left the roster would otherwise be
             // invisible here while still being loaded by `stratus serve`.
-            const orphans = Object.keys(slack).filter((id) => !roster.some((entry) => entry.soul.agent.id === id));
+            //
+            // Only when the roster actually loaded. "No agent has this id" is a
+            // claim about the roster, and a roster that refused to load cannot
+            // support it — every stored token would look orphaned, and this list
+            // offers to DELETE them. Losing a working agent's Slack credentials
+            // because a different pair of files collided is a far worse outcome
+            // than leaving a real orphan on screen for one run.
+            const orphans = rosterLoaded
+                ? Object.keys(slack).filter((id) => !roster.some((entry) => entry.soul.agent.id === id))
+                : [];
+            if (!rosterLoaded) {
+                writeLine(streams.stderr, 'Warning: no agents are offered while the roster is unreadable — the daemon cannot start either. Fix the roster first.');
+            }
             for (const id of orphans) {
                 options.push(`${id}`.padEnd(34) + '! tokens without a matching agent');
             }
@@ -2740,8 +2643,7 @@ export const runSetup = async (command, streams, env = {}) => {
                 config.fallbackBaseUrl = state.fallbackBaseUrl;
             }
         }
-        await mkdir(path.dirname(configPath), { recursive: true });
-        await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+        await saveConfigFile(configPath, config);
         writeLine(streams.stdout);
         writeLine(streams.stdout, `Wrote ${configPath}`);
         // A project-local config in this directory outranks the global file for
@@ -2924,127 +2826,93 @@ export const runSetup = async (command, streams, env = {}) => {
         prompter.close();
     }
 };
-const personaSnippet = (instructions) => {
-    const firstLine = instructions?.split('\n').map((line) => line.trim()).find((line) => line.length > 0);
-    if (!firstLine) {
-        return undefined;
+/**
+ * The bearer token for a gateway: an explicit flag, the environment, or the
+ * token file this machine's daemon wrote.
+ *
+ * The file is the normal case and the reason `--gateway` needs no ceremony
+ * locally. It is not always right, though: a gateway reached through a tunnel
+ * has its own token, which is what the flag and the variable are for.
+ */
+const gatewayToken = async (env, explicit) => {
+    const fromEnv = readNonEmptyString(readProcessEnv(env).STRATUS_GATEWAY_TOKEN);
+    if (explicit || fromEnv) {
+        return String(explicit ?? fromEnv);
     }
-    return firstLine.length > 78 ? `${firstLine.slice(0, 77)}…` : firstLine;
-};
-export const runAgents = async (command, streams, env = {}) => {
-    // Fold any legacy per-directory memory in first so the counts below
-    // reflect everything each agent actually remembers.
-    await migrateLegacyMemory(env);
-    const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(env)));
-    const processEnv = readProcessEnv(env);
-    // Listing must never be blocked by a broken config — it only feeds the
-    // default marker and the "runs on" lines.
-    const { config: activeConfig } = await discoverActiveConfig(env, (message) => {
-        writeLine(streams.stderr, `Warning: ${message}.`);
-    });
-    const envProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'));
-    const envModel = readNonEmptyString(processEnv.STRATUS_MODEL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL);
-    // What a run as this soul would actually use right now — the same
-    // precedence as resolveRuntimeConfig (env vars, soul hints, config,
-    // demo), so a model-only or provider-only pin still resolves honestly.
-    const runsOnFor = (soulProvider, soulModel) => {
-        const provider = envProvider ?? soulProvider ?? activeConfig.provider ?? 'demo';
-        if (provider === 'demo') {
-            return { provider };
-        }
-        const soulModelApplies = soulProvider === undefined || soulProvider === provider;
-        const configModelApplies = (activeConfig.provider ?? 'openai') === provider;
-        const model = envModel
-            ?? (soulModelApplies ? soulModel : undefined)
-            ?? (configModelApplies ? activeConfig.model : undefined)
-            ?? (provider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
-        return { provider, model };
-    };
-    const defaultSoulPath = readNonEmptyString(processEnv.STRATUS_SOUL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL)
-        ?? activeConfig.soul;
-    const resolvedDefaultSoul = defaultSoulPath
-        ? path.resolve(readWorkingDirectory(env), defaultSoulPath)
-        : undefined;
-    const listings = [];
-    const addSoul = async (soulPath) => {
-        let parsed;
-        try {
-            parsed = parseSoul(await readFile(soulPath, 'utf8'), { seed: soulPath });
-        }
-        catch (error) {
-            writeLine(streams.stderr, `Warning: skipping ${soulPath}: ${error instanceof Error ? error.message : String(error)}`);
-            return;
-        }
-        const { agent } = parsed;
-        const persona = personaSnippet(agent.instructions);
-        listings.push({
-            id: agent.id,
-            name: agent.name,
-            isDefault: soulPath === resolvedDefaultSoul,
-            builtIn: false,
-            soulPath,
-            ...(parsed.provider ? { provider: parsed.provider } : {}),
-            ...(parsed.model ? { model: parsed.model } : {}),
-            runsOn: runsOnFor(parsed.provider, parsed.model),
-            memories: (await memory.list(agent.id)).length,
-            ...(persona ? { persona } : {}),
-            ...(agent.avatar ? { avatar: `${agent.avatar.style} theme, hue ${agent.avatar.hue}, palette ${agent.avatar.palette.join(' ')}` } : {}),
-        });
-    };
-    let rosterFiles = [];
     try {
-        rosterFiles = (await readdir(agentsDirPath(env)))
-            .filter((file) => file.endsWith('.md'))
-            .sort()
-            .map((file) => path.join(agentsDirPath(env), file));
+        return (await readFile(gatewayTokenPath(env), 'utf8')).trim();
     }
     catch (error) {
         if (error.code !== 'ENOENT') {
             throw error;
         }
+        throw new Error(`No gateway token: ${gatewayTokenPath(env)} does not exist, and neither --token nor STRATUS_GATEWAY_TOKEN was set. `
+            + 'Start the daemon with `stratus serve` (or `stratus service install`) to create one, or pass the remote gateway\'s token.');
     }
-    for (const soulPath of rosterFiles) {
-        await addSoul(soulPath);
-    }
-    // A default soul can live outside ~/.stratus/agents (a project soul, a
-    // hand-written file) — the roster would be lying without it.
-    if (resolvedDefaultSoul && !rosterFiles.includes(resolvedDefaultSoul)) {
-        await addSoul(resolvedDefaultSoul);
-    }
-    // The built-in Stratus persona serves every run that has no soul.
-    const builtInPersona = personaSnippet(DEFAULT_STRATUS_AGENT.instructions);
-    listings.push({
-        id: DEFAULT_STRATUS_AGENT.id,
-        name: DEFAULT_STRATUS_AGENT.name,
-        isDefault: resolvedDefaultSoul === undefined,
-        builtIn: true,
-        runsOn: runsOnFor(),
-        memories: (await memory.list(DEFAULT_STRATUS_AGENT.id)).length,
-        ...(builtInPersona ? { persona: builtInPersona } : {}),
-    });
-    listings.sort((a, b) => {
-        if (a.isDefault !== b.isDefault) {
-            return a.isDefault ? -1 : 1;
-        }
-        if (a.builtIn !== b.builtIn) {
-            return a.builtIn ? 1 : -1;
-        }
-        return a.name.localeCompare(b.name);
-    });
+};
+/** Ask a running gateway for its roster, as data. */
+const remoteAgentSummaries = async (command, env) => {
+    const token = await gatewayToken(env, command.token);
+    const base = String(command.gateway).replace(/\/+$/, '');
+    const fetchImpl = env.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('fetch is unavailable, so --gateway cannot reach a daemon from this runtime.');
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${base}/api/v1/agents`, {
+            headers: { authorization: `Bearer ${token}` },
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach the gateway at ${base} (${error instanceof Error ? error.message : String(error)}). `
+            + 'Is stratusd running, and does it have @stratusagent/control-api installed?');
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(`The gateway at ${base} rejected this token. Check --token, STRATUS_GATEWAY_TOKEN, or ~/.stratus/gateway-token.`);
+    }
+    if (!response.ok) {
+        throw new Error(`The gateway at ${base} answered HTTP ${response.status} for the roster.`);
+    }
+    const payload = await response.json();
+    return payload.agents ?? [];
+};
+export const runAgents = async (command, streams, env = {}) => {
+    // The same listing either way — the shared builder produces it locally, and
+    // the control API serves exactly what that builder produced. Rendering is
+    // the only thing this command does with it.
+    let listings;
+    if (command.gateway) {
+        listings = await remoteAgentSummaries(command, env);
+    }
+    else {
+        // Fold any legacy per-directory memory in first so the counts below
+        // reflect everything each agent actually remembers.
+        await migrateLegacyMemory(env);
+        listings = await listAgentSummaries(env, (message) => {
+            writeLine(streams.stderr, `Warning: ${message}.`);
+        });
+    }
+    // The palette travels structurally now, because a web or macOS surface has
+    // to draw it. This output has always been one prose line, and a shape
+    // change here would break every script reading it — so the rendering, not
+    // the data, stays where it was.
+    const describeAvatar = (avatar) => `${avatar.style} theme, hue ${avatar.hue}, palette ${avatar.palette.join(' ')}`;
     if (command.format === 'json') {
         writeLine(streams.stdout, JSON.stringify({
-            agents: listings.map(({ isDefault, ...rest }) => ({ ...rest, default: isDefault })),
+            agents: listings.map(({ default: isDefault, avatar, ...rest }) => ({
+                ...rest,
+                ...(avatar ? { avatar: describeAvatar(avatar) } : {}),
+                default: isDefault,
+            })),
         }, null, 2));
         return 0;
     }
     const describeRunsOn = (runsOn) => (runsOn.provider === 'demo' ? 'demo (offline)' : `${runsOn.provider}${runsOn.model ? ` · ${runsOn.model}` : ''}`);
-    writeLine(streams.stdout, 'Agents');
+    writeLine(streams.stdout, command.gateway ? `Agents on ${command.gateway}` : 'Agents');
     for (const agent of listings) {
         const labels = [
-            ...(agent.isDefault ? ['default'] : []),
+            ...(agent.default ? ['default'] : []),
             ...(agent.builtIn ? ['built-in'] : []),
         ];
         writeLine(streams.stdout);
@@ -3059,7 +2927,7 @@ export const runAgents = async (command, streams, env = {}) => {
             writeLine(streams.stdout, `    persona   ${agent.persona}`);
         }
         if (agent.avatar) {
-            writeLine(streams.stdout, `    avatar    ${agent.avatar}`);
+            writeLine(streams.stdout, `    avatar    ${describeAvatar(agent.avatar)}`);
         }
     }
     writeLine(streams.stdout);
@@ -3306,12 +3174,28 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     }
     // Tokens keyed to an agent the roster no longer has are loaded and
     // skipped on every start, silently.
-    const rosterIds = new Set((await loadRosterSouls(env, warn)).map((entry) => entry.soul.agent.id));
+    let rosterEntries = [];
+    let rosterLoaded = true;
+    try {
+        rosterEntries = await loadRosterSouls(env, warn);
+    }
+    catch (error) {
+        // Doctor exists to name problems, so a roster it cannot load is a
+        // finding to report — not an exception that replaces the report.
+        rosterLoaded = false;
+        problems.push(error instanceof Error ? error.message : String(error));
+    }
+    const rosterIds = new Set(rosterEntries.map((entry) => entry.soul.agent.id));
     rosterIds.add(DEFAULT_STRATUS_AGENT.id);
     if (soul) {
         rosterIds.add(soul.agent.id);
     }
-    const orphans = slackAgents.filter((id) => !rosterIds.has(id));
+    // Only against a roster that actually loaded. "No agent has this id" is
+    // a claim about the roster, and a refused one cannot support it — every
+    // stored token would be reported as orphaned, and this advises clearing
+    // them. Advice is not deletion, but an operator who follows it loses the
+    // same credentials by hand.
+    const orphans = rosterLoaded ? slackAgents.filter((id) => !rosterIds.has(id)) : [];
     if (orphans.length > 0) {
         problems.push(`Slack tokens are stored for ${orphans.join(', ')}, which no agent matches — \`stratus serve\` skips them. `
             + 'Clear them from `stratus setup` → Channels.');
@@ -3462,34 +3346,66 @@ const serviceEnvFor = (env) => ({
  * reported everything ready. Returns the variable to name, if so.
  */
 /**
- * Every runtime the daemon would resolve: the config-wide default plus one
- * per roster soul, normalized the way a dispatch normalizes it. A soul that
- * pins its own provider resolves to different credentials entirely, so any
- * check that looks only at the default misses exactly the agent that is
- * misconfigured.
+ * The daemon's `approvals` block, from the config file the daemon itself
+ * would load. Discovery goes through the shared resolver rather than
+ * reading ~/.stratus/config.json directly: `--config` and STRATUS_CONFIG
+ * both move it, and a second copy of that precedence would resolve the
+ * approver set from a file the gateway is not running on.
+ *
+ * **Only from a trusted location.** An auto-discovered project-local
+ * `stratus.config.json` outranks the global one and can be checked into any
+ * repository — which is why stored credentials are already never combined
+ * with an endpoint it selects. This block is the same kind of boundary and
+ * a sharper one: it names the people who may authorize an agent's gated
+ * tool calls, and it would do so through Slack tokens the user configured
+ * globally. A cloned repo must not be able to appoint its own approver, so
+ * an untrusted config's approvals are ignored — loudly, since silently
+ * dropping the block someone is looking at is its own kind of wrong.
+ *
+ * An unreadable config degrades to headless with a warning, matching how
+ * every other consumer treats one: refusing to start would take the whole
+ * fleet down over a policy block that may not even be present.
  */
-const servedRuntimes = async (env, configPath) => {
-    const { applySoulPins } = await import('@stratusagent/gateway');
-    const { config: activeConfig, location } = await discoverActiveConfig(env, () => { });
-    const context = {
-        ...(activeConfig.provider !== undefined ? { configProvider: activeConfig.provider } : {}),
-        configPresent: location !== undefined,
-    };
-    const passes = [{ selection: {}, env }];
-    for (const entry of await loadRosterSouls(env, () => { })) {
-        const normalized = applySoulPins(entry.soul, {}, env, context);
-        passes.push({ selection: normalized.selection, env: normalized.env });
+const loadServeApprovals = async (env, configPath, warn) => {
+    const block = await readTrustedConfigBlock('approvals', env, configPath);
+    if (block.status === 'untrusted') {
+        warn(`ignoring the approvals config in ${block.path}: a project-local config cannot decide who may approve `
+            + 'this daemon\'s tool calls. Move it to ~/.stratus/config.json, or pass it with --config.');
+        return {};
     }
-    const resolved = [];
-    for (const pass of passes) {
-        // A runtime that cannot resolve is the gateway's to report, per
-        // dispatch and with far better context than a startup pass has.
-        const runtime = await resolveStateRuntimeConfig({ ...pass.selection, ...(configPath ? { configPath } : {}) }, pass.env).catch(() => undefined);
-        if (runtime) {
-            resolved.push({ runtime, env: pass.env });
-        }
+    if (block.status === 'unreadable') {
+        warn(`ignoring the approvals config (${block.error instanceof Error ? block.error.message : String(block.error)}); refusing gated calls`);
+        return {};
+    }
+    return block.status === 'present' ? block.value : {};
+};
+/**
+ * One line naming who can actually answer, so a remote daemon does not look
+ * configured when it is not. Two ways it can be hollow, and they fail
+ * differently, so they read differently:
+ *
+ * - No channel running at all (no Slack tokens, or the optional package is
+ *   not installed) — nothing renders the request, so the turn waits out the
+ *   whole timeout before being denied. That is the bad one, and the only
+ *   place it is visible is here, at startup.
+ * - A channel is running but an agent has no approvers — the adapter denies
+ *   that agent's requests on arrival, which is at least prompt.
+ *
+ * `agentIds` is therefore the agents that can actually be *asked*, not
+ * every agent with tokens on disk.
+ */
+const describeApprovers = (approvals, agentIds) => {
+    if (agentIds.length === 0) {
+        return 'but no channel is running to ask through, so gated calls will wait out the approval timeout and then be denied';
+    }
+    const covered = agentIds.filter((agentId) => (resolveAgentApprovals(approvals, agentId).slackApprovers ?? []).length > 0);
+    if (covered.length === 0) {
+        return 'but no approvers are configured, so every gated call is denied on arrival';
     }
-    return resolved;
+    const uncovered = agentIds.filter((agentId) => !covered.includes(agentId));
+    return uncovered.length === 0
+        ? `approvers set for ${covered.join(', ')}`
+        : `approvers set for ${covered.join(', ')}; none for ${uncovered.join(', ')}, whose calls are denied on arrival`;
 };
 /**
  * `stratus service` — run the daemon under launchd or systemd, so it
@@ -3604,7 +3520,6 @@ export const runAgentNew = async (command, streams, env = {}) => {
             const name = (await prompter.ask('Choose your name: ', { prefill: suggested })) || suggested;
             const instructions = await prompter.ask('Describe their personality (Enter for a starter you can edit later): ', ...(command.instructions ? [{ prefill: command.instructions }] : []));
             const persona = instructions || DEFAULT_SOUL_STARTER;
-            let agent = defineAgent({ name, instructions: persona });
             // Frontmatter pins what a run from this directory would actually use:
             // env vars outrank the active config file (project-local or explicit
             // first, global otherwise), and no provider anywhere falls back to
@@ -3629,27 +3544,8 @@ export const runAgentNew = async (command, streams, env = {}) => {
                 ?? (configModelApplies ? activeConfig.model : undefined)
                 ?? (soulProvider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
             const soulPin = soulProvider !== 'demo' ? { provider: soulProvider, model: soulModel } : {};
-            // The name stays theirs, but the id — the soul filename and the
-            // memory key — must be unique: the suggestion pool is small, so a
-            // repeat name would otherwise silently overwrite an earlier agent's
-            // soul and share their memory. 'wx' makes each claim atomic; on a
-            // collision the id gets a fresh suffix and we try again.
-            await mkdir(agentsDirPath(env), { recursive: true });
-            const baseId = agent.id;
-            let soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-            for (;;) {
-                try {
-                    await writeFile(soulPath, formatSoul({ agent, ...soulPin }), { flag: 'wx' });
-                    break;
-                }
-                catch (error) {
-                    if (error.code !== 'EEXIST') {
-                        throw error;
-                    }
-                    agent = defineAgent({ id: `${baseId}-${randomUUID().slice(0, 4)}`, name, instructions: persona });
-                    soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-                }
-            }
+            const claimed = await claimSoulFile(env, { name, instructions: persona }, (candidate) => formatSoul({ agent: candidate, ...soulPin }), (message) => writeLine(streams.stdout, message));
+            const { agent, soulPath } = claimed;
             const makeDefault = await prompter.select(`Make ${agent.name} your default agent?`, [
                 'Yes — every stratus run talks to them',
                 'Not now',
@@ -3672,9 +3568,16 @@ export const runAgentNew = async (command, streams, env = {}) => {
                     }
                 }
                 if (globalConfig !== undefined) {
-                    const config = { ...globalConfig, provider: globalConfig.provider ?? soulProvider, soul: soulPath };
-                    await mkdir(path.dirname(globalConfigPath(env)), { recursive: true });
-                    await writeFile(globalConfigPath(env), `${JSON.stringify(config, null, 2)}\n`);
+                    // Re-validated rather than cast: `readNonEmptyString` widens to
+                    // `string`, and the shared parser is what says which strings are
+                    // provider names. Every source feeding soulProvider is already one,
+                    // so this narrows without being able to throw.
+                    const config = {
+                        ...globalConfig,
+                        provider: globalConfig.provider ?? parseProviderName(soulProvider, 'provider'),
+                        soul: soulPath,
+                    };
+                    await saveConfigFile(globalConfigPath(env), config);
                     madeDefault = true;
                     if (configLocation && configLocation.path !== globalConfigPath(env)) {
                         writeLine(streams.stdout, `Note: ${configLocation.path} takes precedence over the global config for runs started in this directory.`);
@@ -3723,30 +3626,166 @@ export const runAgentNew = async (command, streams, env = {}) => {
     writeLine(streams.stdout, JSON.stringify(agent, null, 2));
     return 0;
 };
-export const runDashboard = async (command, streams, env = {}) => {
-    const handle = await startDashboardServer({
-        host: command.host,
-        ...(command.port !== undefined ? { port: command.port } : {}),
+const readGatewayInfo = async (env) => {
+    try {
+        const parsed = JSON.parse(await readFile(gatewayInfoPath(env), 'utf8'));
+        return typeof parsed.url === 'string' ? { url: parsed.url, ...(parsed.pid ? { pid: parsed.pid } : {}) } : undefined;
+    }
+    catch {
+        // No file, or one left behind by a daemon that died without cleaning up.
+        // Either way there is nothing to talk to until the health check says so.
+        return undefined;
+    }
+};
+/**
+ * A one-time URL for the browser.
+ *
+ * This is the whole reason the exchange exists: the CLI can read the token
+ * file and a page cannot, so the CLI lends its authority for exactly one
+ * short-lived trip.
+ */
+const mintDashboardUrl = async (env, base, fetchImpl) => {
+    const token = await gatewayToken(env, undefined);
+    const response = await fetchImpl(`${base}/api/v1/auth/ott`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}` },
     });
-    writeLine(streams.stdout, `${DASHBOARD_TITLE} ready at ${handle.url}`);
-    writeLine(streams.stdout, 'Press Ctrl+C to stop.');
+    if (!response.ok) {
+        throw new Error(`The gateway at ${base} refused to open a dashboard session (HTTP ${response.status}).`);
+    }
+    const payload = await response.json();
+    // The relative form joined to the base we already reached, in preference to
+    // the absolute one: this command knows exactly which address answered, and
+    // the daemon can only infer it from headers.
+    if (payload.path) {
+        return `${base.replace(/\/+$/, '')}${payload.path}`;
+    }
+    if (!payload.url) {
+        throw new Error(`The gateway at ${base} did not return a dashboard URL.`);
+    }
+    return payload.url;
+};
+/** Whether something is actually answering there, as opposed to a stale file. */
+const gatewayAnswering = async (env, base, fetchImpl) => {
+    try {
+        const token = await gatewayToken(env, undefined);
+        const response = await fetchImpl(`${base}/api/v1/health`, {
+            headers: { authorization: `Bearer ${token}` },
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * `stratus dashboard` — open the web UI against a running daemon, starting
+ * one in the foreground when there is none.
+ *
+ * The daemon is started by calling `runServe`, not by rebuilding its wiring:
+ * channels, approvals, the credential preflight, and the log writer are all
+ * decisions `serve` already makes, and a second copy of them here would drift
+ * the first time either side gained a rule.
+ */
+export const runDashboard = async (command, streams, env = {}) => {
+    const fetchImpl = env.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        writeLine(streams.stderr, 'Error: fetch is unavailable, so the dashboard cannot reach a gateway.');
+        return 1;
+    }
+    const existing = await readGatewayInfo(env);
+    let base = existing && await gatewayAnswering(env, existing.url, fetchImpl) ? existing.url : undefined;
+    const ownDaemon = new AbortController();
+    let serving;
+    if (!base) {
+        writeLine(streams.stdout, 'No daemon is running — starting one. It stops when you do.');
+        writeLine(streams.stdout, 'Run `stratus service install` to keep one running instead.');
+        serving = runServe({
+            command: 'serve',
+            events: false,
+            // Explicitly on. A trusted config may set `api.enabled: false` — a
+            // reasonable thing for a headless box — but this command exists to
+            // open the dashboard, and honouring it here would start a daemon
+            // with no API and then time out waiting for the one it promised.
+            api: true,
+            ...(command.port !== undefined ? { apiPort: command.port } : {}),
+            // Passed whenever it was asked for, including when it is the default.
+            // `--host 127.0.0.1` against a config saying `0.0.0.0` is an operator
+            // narrowing the bind, and dropping it because it matched the default
+            // did the reverse of what they typed.
+            ...(command.host !== undefined ? { apiHost: command.host } : {}),
+        }, 
+        // The daemon's own chatter belongs on stderr here: stdout is where this
+        // command says where to point a browser, and interleaving the two makes
+        // the one line that matters hard to find.
+        { stdout: streams.stderr, stderr: streams.stderr }, { ...env, shutdownSignal: ownDaemon.signal });
+        // Attached now, not at the end. `runServe` can reject before it publishes
+        // anything — an unreadable roster, a session store that will not open —
+        // and a rejected promise nobody is watching for fifteen seconds is an
+        // unhandled rejection, which terminates the process instead of reaching
+        // the message below. Captured rather than swallowed, so the reason the
+        // daemon gave is the reason this command reports.
+        let daemonFailure;
+        const daemonExit = serving.then(() => undefined, (error) => { daemonFailure = error; });
+        // Gated on the daemon actually answering, not on a delay: it publishes
+        // where it bound the moment it binds, and anything less would be a race
+        // dressed up as a timeout. It also stops the moment the daemon gives up,
+        // rather than waiting out a timeout for a process that is already gone.
+        const startedBy = Date.now() + 15_000;
+        let daemonStopped = false;
+        void daemonExit.then(() => { daemonStopped = true; });
+        while (!base && !daemonStopped && Date.now() < startedBy) {
+            const info = await readGatewayInfo(env);
+            if (info && await gatewayAnswering(env, info.url, fetchImpl)) {
+                base = info.url;
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 150));
+        }
+        if (!base) {
+            ownDaemon.abort();
+            await daemonExit;
+            writeLine(streams.stderr, daemonFailure
+                ? `Error: the daemon could not start: ${daemonFailure instanceof Error ? daemonFailure.message : String(daemonFailure)}`
+                : 'Error: the daemon did not start serving its control API. Is @stratusagent/control-api installed?');
+            return 1;
+        }
+    }
+    let url;
+    try {
+        url = await mintDashboardUrl(env, base, fetchImpl);
+    }
+    catch (error) {
+        ownDaemon.abort();
+        await serving?.catch(() => 0);
+        writeLine(streams.stderr, `Error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    writeLine(streams.stdout, `${DASHBOARD_TITLE} ready at ${base}`);
+    writeLine(streams.stdout, 'That link signs one browser in and can only be used once.');
     if (command.openBrowser) {
         try {
-            await (env.openExternal ?? openExternalUrl)(handle.url);
+            await (env.openExternal ?? openExternalUrl)(url);
             writeLine(streams.stdout, 'Opened your default browser.');
         }
         catch (error) {
             writeLine(streams.stderr, `Warning: Could not open the browser automatically: ${error instanceof Error ? error.message : String(error)}`);
+            writeLine(streams.stdout, `Open this yourself: ${url}`);
         }
     }
+    else {
+        writeLine(streams.stdout, `Open this to sign in: ${url}`);
+    }
+    if (!serving) {
+        // Someone else owns the daemon; this command's job is done.
+        return 0;
+    }
+    writeLine(streams.stdout, 'Press Ctrl+C to stop the daemon.');
     if (env.dashboardAutoShutdownMs !== undefined) {
         await new Promise((resolve) => setTimeout(resolve, env.dashboardAutoShutdownMs));
-        await handle.close();
-        return 0;
+        ownDaemon.abort();
     }
-    await once(process, 'SIGINT');
-    await handle.close();
-    return 0;
+    return serving;
 };
 /**
  * Loads the optional Slack channel package, or undefined when it is not
@@ -3773,6 +3812,65 @@ const loadSlackAdapter = async () => {
     // installed package, and surfaces.
     return (await import('@stratusagent/channel-slack')).createSlackChannelAdapter;
 };
+/**
+ * Loads the optional control-API package, or undefined when it is not
+ * installed. Same two-step as the Slack adapter, and for the same reason:
+ * only the package being absent means "not installed". A package that IS
+ * installed but is missing one of its own dependencies throws
+ * ERR_MODULE_NOT_FOUND naming that dependency, so inspecting the message
+ * would read a broken install as an absent one — silently leaving a daemon
+ * without the API an operator installed it to have.
+ */
+const loadControlApi = async () => {
+    try {
+        import.meta.resolve('@stratusagent/control-api');
+    }
+    catch {
+        return undefined;
+    }
+    return (await import('@stratusagent/control-api')).createControlApi;
+};
+/**
+ * The daemon's `api` block, from the config file the daemon itself would
+ * load — and only from a trusted location.
+ *
+ * An auto-discovered project-local `stratus.config.json` outranks the global
+ * one and can be checked into any repository. Which interface a daemon binds
+ * is exactly the kind of decision a cloned repo must not get to make, so an
+ * untrusted config's block is ignored loudly rather than obeyed.
+ */
+const loadServeApi = async (env, configPath, warn) => {
+    const block = await readTrustedConfigBlock('api', env, configPath);
+    if (block.status === 'untrusted') {
+        warn(`ignoring the api config in ${block.path}: a project-local config cannot decide which interface this `
+            + 'daemon binds. Move it to ~/.stratus/config.json, or pass it with --config.');
+        return {};
+    }
+    if (block.status === 'unreadable') {
+        warn(`ignoring the api config (${block.error instanceof Error ? block.error.message : String(block.error)}); using the defaults`);
+        return {};
+    }
+    return block.status === 'present' ? block.value : {};
+};
+/**
+ * The daemon's `plugins` block — the same trust boundary as the two above,
+ * and the one it was written for. A plugin runs in-process with the daemon,
+ * so a list of them is a list of code; a `stratus.config.json` that ships
+ * in a cloned repository must not be able to write it.
+ */
+const loadServePlugins = async (env, configPath, warn) => {
+    const block = await readTrustedConfigBlock('plugins', env, configPath);
+    if (block.status === 'untrusted') {
+        warn(`ignoring the plugins config in ${block.path}: a project-local config cannot decide which code runs inside `
+            + 'this daemon. Move it to ~/.stratus/config.json, or pass it with --config.');
+        return {};
+    }
+    if (block.status === 'unreadable') {
+        warn(`ignoring the plugins config (${block.error instanceof Error ? block.error.message : String(block.error)}); loading no plugins`);
+        return {};
+    }
+    return block.status === 'present' ? block.value : {};
+};
 /**
  * `stratus serve` — run the gateway (stratusd) in the foreground: load the
  * roster, accept dispatches, print events, and drain cleanly on SIGTERM,
@@ -3812,9 +3910,58 @@ export const runServe = async (command, streams, env = {}) => {
     // tokens are gateway infrastructure secrets in the channels namespace of
     // ~/.stratus/credentials.json (see @stratusagent/channel-slack's README
     // for the 2-minute per-agent app setup).
+    // The approval policy and the Slack approver sets come from the same
+    // config block, resolved once here: the daemon must not answer "who can
+    // approve this" differently from "is anyone being asked at all".
+    const approvalsConfig = await loadServeApprovals(env, command.configPath, warn);
+    const approvalMode = command.approvals ?? approvalsConfig.mode ?? 'headless';
+    // Read here rather than inside the gateway for the same reason as the two
+    // blocks above: the trust boundary is a property of *which file* said it,
+    // and this is where the file precedence is already understood.
+    const pluginsConfig = await loadServePlugins(env, command.configPath, warn);
+    // The control API is a channel adapter like any other: started after the
+    // roster loads, stopped before the store drains. It is optional because
+    // installing it is how an operator says they want a port open.
+    const apiConfig = await loadServeApi(env, command.configPath, warn);
+    const apiWanted = command.api ?? apiConfig.enabled ?? true;
+    // Typed as the seam, not as whatever the first push happens to be: the
+    // list holds the control API and the Slack adapter alike.
+    const controlApiChannels = [];
+    if (apiWanted) {
+        const createControlApi = await loadControlApi();
+        // Resolved into locals first. Inlined, `a ?? b !== undefined` parses as
+        // `a ?? (b !== undefined)` — so an explicit `--api-port 0`, which is how
+        // you ask for any free port, was falsy and fell through to the default.
+        // Everything still bound and every test still passed, on whichever port
+        // nobody happened to be using.
+        const apiHost = command.apiHost ?? apiConfig.host;
+        const apiPort = command.apiPort ?? apiConfig.port;
+        if (createControlApi) {
+            controlApiChannels.push(createControlApi({
+                env,
+                ...(apiHost !== undefined ? { host: apiHost } : {}),
+                ...(apiPort !== undefined ? { port: apiPort } : {}),
+                ...(command.configPath ? { configPath: command.configPath } : {}),
+                log,
+                warn,
+            }));
+        }
+        else if (command.api === true || apiConfig.enabled === true) {
+            // Only when someone asked for it explicitly. A daemon that was never
+            // told to serve an API should not complain about not having one.
+            warn('the control API was requested, but @stratusagent/control-api is not installed. '
+                + 'Run `npm install -g @stratusagent/control-api` to bring it online; starting without it.');
+        }
+    }
     const channelCredentials = await loadChannelCredentials(env);
     const slackAgents = Object.entries(channelCredentials.slack ?? {});
-    const channels = [];
+    const channels = [...controlApiChannels];
+    // Tracked on its own, never as `channels.length`: the list now holds the
+    // control API too, and "can anyone be asked for an approval" is a question
+    // about the Slack adapter specifically. Reading it off the list length
+    // would tell a daemon with an API and no Slack app that every agent is
+    // reachable, and its gated calls would park with nobody rendering them.
+    let slackAdapterUp = false;
     if (slackAgents.length > 0) {
         // Channel packages are optional peers: the CLI never bundles a
         // transport nobody asked for (the Slack SDKs alone are ~9 MB). A
@@ -3823,12 +3970,18 @@ export const runServe = async (command, streams, env = {}) => {
         // module-not-found stack.
         const adapter = await loadSlackAdapter();
         if (adapter) {
+            slackAdapterUp = true;
             channels.push(adapter({
-                agents: slackAgents.map(([agentId, tokens]) => ({
-                    agentId,
-                    appToken: tokens.appToken,
-                    botToken: tokens.botToken,
-                })),
+                agents: slackAgents.map(([agentId, tokens]) => {
+                    const route = resolveAgentApprovals(approvalsConfig, agentId);
+                    return {
+                        agentId,
+                        appToken: tokens.appToken,
+                        botToken: tokens.botToken,
+                        ...(route.slackApprovers ? { approvers: route.slackApprovers } : {}),
+                        ...(route.slackChannel ? { approvalChannel: route.slackChannel } : {}),
+                    };
+                }),
                 log,
                 warn,
             }));
@@ -3876,23 +4029,63 @@ export const runServe = async (command, streams, env = {}) => {
     // while `serve` was something you ran in a terminal you were sitting at;
     // it is not, now that setup installs it under launchd by default.
     //
-    // Headless is the only honest mode here until a turn can park and ask
-    // through a channel: there is no terminal behind a service manager, so
-    // `safe` runs and anything riskier is refused rather than waved through.
-    // Every refusal is logged — an unattended denial that appears nowhere
-    // reads like an agent that decided not to bother.
-    const approvals = createPermissionPolicy({
-        mode: 'headless',
-        onDecision: (decision) => {
-            if (decision.allowed) {
-                return;
-            }
-            warn(`${decision.agentId}: ${decision.reason} (session ${decision.sessionId})`);
+    // There is no terminal behind a service manager, so the choice is
+    // between refusing every gated call (`headless`) and parking the turn to
+    // ask through a channel (`remote`). Headless stays the default: a daemon
+    // that starts waiting on people who were never told they are on the hook
+    // hangs turns instead of refusing them. Every refusal is logged — an
+    // unattended denial that appears nowhere reads like an agent that decided
+    // not to bother.
+    const onDecision = (decision) => {
+        if (decision.allowed) {
+            return;
+        }
+        warn(`${decision.agentId}: ${decision.reason} (session ${decision.sessionId})`);
+    };
+    // A factory, not a policy: remote mode parks turns on a transport the
+    // gateway owns, so the policy cannot exist until the gateway is building
+    // it. Headless takes the same path so there is one construction site.
+    // The command-scope engine, which only has a caller once a shell pack is
+    // installed. Wired unconditionally because it costs nothing without one:
+    // a tool that carries no command string is judged by its risk exactly as
+    // before. The whitelist lives beside the agent's soul, per agent.
+    const commands = {
+        whitelist: createFileCommandWhitelist({ directory: agentsDirPath(env) }),
+        onScopeRemembered: ({ agentId, scope }) => {
+            // An approval that widens what runs unattended, for every future
+            // session, is precisely the decision that must not be the one leaving
+            // no trace.
+            log(`${agentId}: "${describeCommandScope(scope)}" now runs without asking`);
         },
-    });
+    };
+    const approvals = (transport) => createPermissionPolicy(approvalMode === 'remote'
+        ? { mode: 'remote', request: transport.request, onDecision, commands }
+        : { mode: 'headless', onDecision, commands });
+    if (approvalMode === 'remote') {
+        // Only agents whose channel actually came up can be asked: tokens on
+        // disk with the Slack package missing means nothing renders the
+        // request, and the turn discovers that by hanging.
+        const askable = slackAdapterUp ? slackAgents.map(([agentId]) => agentId) : [];
+        log(`approvals: remote — gated calls are parked and asked in Slack (${describeApprovers(approvalsConfig, askable)})`);
+    }
     const gateway = createGateway({
         env,
         approvals,
+        ...(Object.keys(pluginsConfig).length > 0
+            ? {
+                plugins: pluginsConfig,
+                // Resolved from *here*, not from inside the gateway.
+                // `import.meta.resolve` answers relative to the module that calls
+                // it, and a plugin is installed alongside the thing the operator
+                // installed — this CLI. Letting the gateway resolve from its own
+                // location works only where the layout happens to be flat.
+                pluginHost: {
+                    resolve: (specifier) => import.meta.resolve(specifier),
+                    import: (specifier) => import(__rewriteRelativeImportExtension(specifier)),
+                },
+            }
+            : {}),
+        ...(approvalsConfig.timeoutMs !== undefined ? { approvalTimeoutMs: approvalsConfig.timeoutMs } : {}),
         ...(command.configPath ? { selection: { configPath: command.configPath } } : {}),
         ...(command.idleTimeoutMs !== undefined ? { idleTimeoutMs: command.idleTimeoutMs } : {}),
         ...(channels.length > 0 ? { channels } : {}),
@@ -3959,6 +4152,21 @@ export const runServe = async (command, streams, env = {}) => {
         });
     }
     await gateway.start();
+    // The roster is only known once the gateway has loaded it, and in remote
+    // mode an agent no channel can ask for is the quietest failure this
+    // feature has: its gated calls park with nobody rendering them and wait
+    // out the whole timeout before being denied. No channel can detect this
+    // on its own — a request is a broadcast, and no adapter knows whether
+    // another one is about to answer — so it is reported here, where the
+    // roster and the channel list are both in view.
+    if (approvalMode === 'remote') {
+        const askable = new Set(slackAdapterUp ? slackAgents.map(([agentId]) => agentId) : []);
+        const unreachable = gateway.agents().map((agent) => agent.id).filter((id) => !askable.has(id));
+        if (unreachable.length > 0) {
+            warn(`no channel can ask for ${unreachable.join(', ')}, so their gated calls will wait out the `
+                + 'approval timeout and then be denied. Connect a Slack app for them, or run with --approvals headless.');
+        }
+    }
     writeLine(streams.stdout, 'Press Ctrl+C to stop.');
     // And periodically, for a long-running daemon that warns steadily
     // without ever writing enough records to rotate. Unref'd, so it never
@@ -4068,6 +4276,7 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
             runtime,
             approvals: command.approvals,
             ...(command.maxTurns !== undefined ? { maxTurns: command.maxTurns } : {}),
+            ...(command.configPath ? { configPath: command.configPath } : {}),
             env: resolvedEnv,
         });
         if (command.format === 'json') {