@stratusagent/cli 0.4.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 { agentIdWithSuffix, 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, resolveConfiguredSoul, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveCredentials, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
+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.4.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
@@ -100,7 +103,10 @@ Commands:
                    (--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
+                   "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
@@ -111,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:
@@ -138,9 +149,14 @@ Options:
                    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:
@@ -149,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`);
@@ -185,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];
@@ -215,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 };
@@ -258,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;
@@ -326,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}`);
@@ -343,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';
@@ -838,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.
@@ -872,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);
@@ -1003,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) {
@@ -1109,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.`));
     }
@@ -1122,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';
@@ -1247,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("'", "'\\''")}'`;
@@ -1622,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
@@ -1748,116 +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',
-];
-/**
- * The ids a newly created soul must not claim: every id the served roster
- * holds, which is three things and not one directory.
- *
- * - **What the roster files declare.** A filename is not an id: a soul at
- *   `renamed.md` may declare `id: ava`, so `ava.md` being free proves
- *   nothing — and since a duplicate refuses the whole roster, writing one
- *   would hand back an agent whose daemon cannot start.
- * - **The configured default soul**, which the daemon registers whether or
- *   not its file lives in the agents directory. It wins a same-id contest
- *   with a roster file — `defaultAgentId` replaces the source when the
- *   path differs — so a new agent sharing its id is not refused, it is
- *   shadowed: created, then undispatchable by id or from Slack, with
- *   nothing saying so.
- * - **The reserved `stratus`**, since a roster soul claiming it is skipped
- *   at load, so writing one creates an agent that silently never appears.
- *
- * The two readable sources fail **independently**, and what they return is
- * what they know rather than all-or-nothing. A configured soul that is
- * missing or mid-edit does not stop the daemon serving the roster, so it
- * must not discard the roster's claims either: collapsing both to unknown
- * would let this command write the very duplicate that refuses the roster
- * it could have read. `unread` names what could not be answered, so the
- * caller can say which check did not run instead of implying none did.
- */
-const declaredAgentIds = async (env) => {
-    const [roster, configured] = await Promise.allSettled([
-        loadRosterSouls(env, () => { }),
-        // Empty selection: the soul a run started here would resolve, by the
-        // same precedence the daemon uses — never a second reading of it.
-        resolveConfiguredSoul({}, env),
-    ]);
-    const ids = new Set([DEFAULT_STRATUS_AGENT.id]);
-    const unread = [];
-    if (roster.status === 'fulfilled') {
-        for (const entry of roster.value) {
-            ids.add(entry.soul.agent.id);
-        }
-    }
-    else {
-        unread.push('the roster');
-    }
-    if (configured.status === 'fulfilled') {
-        if (configured.value) {
-            ids.add(configured.value.soul.agent.id);
-        }
-    }
-    else {
-        unread.push('the configured default soul');
-    }
-    return { ids, unread };
-};
-/**
- * Write a new soul under an id nothing else holds, and return the agent
- * that got written.
- *
- * The name stays theirs, but the id — the soul filename, the memory key,
- * the credential scope — must be unique: the suggestion pool is small, so
- * a repeat name would otherwise share an earlier agent's memory. Two
- * claims have to fail here, and only one of them is a filename:
- *
- * - An id another soul declares, whatever that soul is called on disk.
- *   Since a duplicate refuses the whole roster, writing one would leave a
- *   daemon that will not start — created by the command meant to help.
- * - The path itself, via `wx`, which makes the claim atomic against a
- *   concurrent writer that the roster read above cannot see.
- *
- * On either, the id takes a fresh suffix and we try again — through the
- * shared bound, since appending a suffix to a maxed-out base would build
- * an id the validator refuses, turning a collision into a crash.
- */
-const claimSoulFile = async (env, input, render, note) => {
-    const { ids: taken, unread } = await declaredAgentIds(env);
-    if (unread.length > 0) {
-        note(`Note: could not read ${unread.join(' or ')}, so this id was not checked against the ids it declares.`);
-    }
-    let agent = defineAgent({ ...(input.name ? { name: input.name } : {}), instructions: input.instructions });
-    const baseId = agent.id;
-    for (;;) {
-        const soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-        if (!taken.has(agent.id)) {
-            try {
-                await writeFile(soulPath, render(agent), { flag: 'wx' });
-                return { agent, soulPath };
-            }
-            catch (error) {
-                if (error.code !== 'EEXIST') {
-                    throw error;
-                }
-            }
-        }
-        agent = defineAgent({
-            id: agentIdWithSuffix(baseId, randomUUID().slice(0, 4)),
-            ...(input.name ? { name: input.name } : { name: agent.name }),
-            instructions: input.instructions,
-        });
-    }
-};
 export const runSetup = async (command, streams, env = {}) => {
     const cwd = readWorkingDirectory(env);
     const processEnv = readProcessEnv(env);
@@ -1960,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];
@@ -2222,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) {
@@ -2446,7 +2186,6 @@ export const runSetup = async (command, streams, env = {}) => {
         const pin = state.provider !== 'demo'
             ? { provider: state.provider, model: state.model ?? defaultModelFor(state.provider) }
             : {};
-        await mkdir(agentsDirPath(env), { recursive: true });
         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;
@@ -2904,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
@@ -3088,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);
@@ -3223,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);
@@ -3641,40 +3345,6 @@ const serviceEnvFor = (env) => ({
  * profile, so the unit would come up unauthenticated while setup had just
  * 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.
- */
-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 }];
-    // A roster that will not load is the gateway's to refuse, with a better
-    // message than this preflight could give — so it checks what it can and
-    // leaves the failing to start().
-    const rosterForRuntimes = await loadRosterSouls(env, () => { }).catch(() => []);
-    for (const entry of rosterForRuntimes) {
-        const normalized = applySoulPins(entry.soul, {}, env, context);
-        passes.push({ selection: normalized.selection, env: normalized.env });
-    }
-    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 });
-        }
-    }
-    return resolved;
-};
 /**
  * The daemon's `approvals` block, from the config file the daemon itself
  * would load. Discovery goes through the shared resolver rather than
@@ -3697,26 +3367,17 @@ const servedRuntimes = async (env, configPath) => {
  * fleet down over a policy block that may not even be present.
  */
 const loadServeApprovals = async (env, configPath, warn) => {
-    try {
-        const location = await resolveConfigLocation(configPath ? { configPath } : {}, env);
-        if (!location) {
-            return {};
-        }
-        const approvals = (await loadConfigFile(location.path)).approvals;
-        if (!approvals) {
-            return {};
-        }
-        if (!location.trusted) {
-            warn(`ignoring the approvals config in ${location.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 {};
-        }
-        return approvals;
+    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 {};
     }
-    catch (error) {
-        warn(`ignoring the approvals config (${error instanceof Error ? error.message : String(error)}); refusing gated calls`);
+    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
@@ -3883,7 +3544,6 @@ 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 } : {};
-            await mkdir(agentsDirPath(env), { recursive: true });
             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?`, [
@@ -3908,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.`);
@@ -3959,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
@@ -4009,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,
@@ -4053,9 +3915,53 @@ export const runServe = async (command, streams, env = {}) => {
     // 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
@@ -4064,6 +3970,7 @@ 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]) => {
                     const route = resolveAgentApprovals(approvalsConfig, agentId);
@@ -4138,19 +4045,46 @@ export const runServe = async (command, streams, env = {}) => {
     // 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 }
-        : { mode: 'headless', onDecision });
+        ? { 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 = channels.length > 0 ? slackAgents.map(([agentId]) => agentId) : [];
+        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 } : {}),
@@ -4226,7 +4160,7 @@ export const runServe = async (command, streams, env = {}) => {
     // 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(channels.length > 0 ? slackAgents.map(([agentId]) => agentId) : []);
+        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 `
@@ -4342,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') {