@stratusagent/cli 0.4.0 → 0.7.0

package/dist/index.js

@@ -1,16 +1,24 @@
+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 { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
-import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
+import { AgentRunner, AllowAllApprovalPolicy, EventBus, SkillRegistry, ToolRegistry, matchesSkillAllowlist, missingSkillRequirements, } 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, installSkillsFromDirectory, loadOperatorSkills, loadRosterSouls, skillsDirPath, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_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 +27,50 @@ 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';
+/**
+ * Whether spawning npm needs a shell on this platform.
+ *
+ * On Windows npm is `npm.cmd`, a batch file: a bare `npm` does not exist as
+ * an executable there (PATHEXT is a shell's job, not spawn's), and naming
+ * the `.cmd` directly has thrown EINVAL since the fix for CVE-2024-27980 —
+ * both land in the caller's error handler, so a Windows setup would report
+ * that it could not install and leave Slack and the dashboard missing.
+ *
+ * Every package name reaching the shell is a constant in this file, so
+ * there is nothing user-supplied here for it to re-parse.
+ */
+export const npmNeedsShell = (platform) => platform === 'win32';
+const defaultPackageInstaller = async (packages) => {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        // npm's own output is inherited rather than captured: a global install
+        // runs for tens of seconds, and a silent one is indistinguishable from
+        // a setup that has hung. stdin is NOT inherited — the setup prompter
+        // owns it, and two readers on one stream race for the same bytes.
+        const child = spawn('npm', ['install', '-g', ...packages], {
+            stdio: ['ignore', 'inherit', 'inherit'],
+            shell: npmNeedsShell(process.platform),
+        });
+        // `error` and `close` can both fire — a spawn that fails still closes.
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(result);
+        };
+        child.once('error', (error) => {
+            finish({ ok: false, message: error.message });
+        });
+        child.once('close', (code) => {
+            finish(code === 0
+                ? { ok: true, message: '' }
+                : { ok: false, message: `npm exited with code ${code ?? 'unknown'}` });
+        });
+    });
+};
+export const CLI_VERSION = '0.7.0';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 /**
  * The range every package declares in its `engines` field. Two floors, not
@@ -77,6 +123,10 @@ 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 skill add stratuslabs/skill-code-review
+  stratus skill add ./my-skills --skill code-review --agent ava
+  stratus skills
   stratus doctor
   stratus service install
   stratus service status
@@ -90,7 +140,9 @@ Commands:
                    subscription or API key), create your agent, connect it to
                    Slack, and test it — settings go to ~/.stratus/config.json,
                    sign-ins and channel tokens to ~/.stratus/credentials.json
-                   (0600)
+                   (0600). Save & finish offers to install any optional
+                   package your answers imply (the Slack channel, the control
+                   API and dashboard) before it starts the daemon
   chat             Talk with your agent — the conversation persists across turns
                    and remembered facts accumulate; /exit or Ctrl+C to leave
   run              Execute one local Stratus Agent session
@@ -100,7 +152,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
@@ -109,13 +164,27 @@ Commands:
   logs             Read the daemon's log from any terminal: -f to follow,
                    -n <count> for backlog, --agent / --session to filter,
                    --format json for the raw records
+  skill add        Install skills from a GitHub repo (owner/repo or URL) or a
+                   local path into ~/.stratus/skills — whole directories, one
+                   per skill; works with skills published for other agents
+                   (skills.sh-style repos). Installed is not enabled: a soul
+                   opts in via skills:, or pass --agent <id> to enable now.
+                   --skill <id> picks from a multi-skill repo (repeatable),
+                   --force replaces an already-installed id
+  skills           List installed skills and which agents enable each
+                   (also: stratus skill list)
   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,20 +207,46 @@ 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:
   The CLI looks for ./stratus.config.json first, then a path from --config / STRATUS_CONFIG,
   then the global ~/.stratus/config.json written by \`stratus setup\`.
   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)
+  A soul file is markdown with frontmatter (name, provider, model, tools, skills, 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.
+  "skills" is the same allowlist shape over installed skills (see stratus
+  skills), except omitted means none — a skill is enabled per agent, never
+  by being installed.
 `;
 const writeLine = (stream, line = '') => {
     stream.write(`${line}\n`);
@@ -185,7 +280,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 +310,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 +358,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 +444,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 +463,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';
@@ -470,6 +608,69 @@ export const parseCommand = (argv, env = {}) => {
             ...(sessionId ? { sessionId } : {}),
         };
     }
+    if (command === 'skills' || (command === 'skill' && rest[0] === 'list')) {
+        const skillsRest = command === 'skills' ? rest : rest.slice(1);
+        for (const token of skillsRest) {
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return { command: 'skills' };
+    }
+    if (command === 'skill') {
+        const [subcommand, ...skillRest] = rest;
+        if (subcommand === '--help' || subcommand === '-h') {
+            return { command: 'help' };
+        }
+        if (subcommand !== 'add') {
+            throw new Error(`Unknown skill subcommand: ${subcommand ?? '(missing)'}. Try: stratus skill add <source>, stratus skills`);
+        }
+        let source;
+        const skillIds = [];
+        let force = false;
+        let agentId;
+        for (let index = 0; index < skillRest.length; index += 1) {
+            const token = skillRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--skill') {
+                skillIds.push(readOptionValue(skillRest, index, '--skill'));
+                index += 1;
+                continue;
+            }
+            if (token === '--agent') {
+                agentId = readOptionValue(skillRest, index, '--agent');
+                index += 1;
+                continue;
+            }
+            if (token === '--force') {
+                force = true;
+                continue;
+            }
+            if (token.startsWith('--')) {
+                throw new Error(`Unknown option: ${token}`);
+            }
+            if (source !== undefined) {
+                throw new Error(`skill add takes one source; got both ${JSON.stringify(source)} and ${JSON.stringify(token)}.`);
+            }
+            source = token;
+        }
+        if (source === undefined) {
+            throw new Error('skill add needs a source: a GitHub owner/repo, a git URL, or a local path.');
+        }
+        return {
+            command: 'skill-add',
+            source,
+            ...(skillIds.length > 0 ? { skillIds } : {}),
+            ...(force ? { force } : {}),
+            ...(agentId !== undefined ? { agentId } : {}),
+        };
+    }
     if (command === 'agent') {
         const [subcommand, ...agentRest] = rest;
         if (subcommand === '--help' || subcommand === '-h') {
@@ -746,9 +947,8 @@ export const warnOnCredentialOverride = async (runtime, streams, env = {}) => {
         return;
     }
     // The resolver records the variable that actually won — guessing it here
-    // would name the wrong one whenever a custom apiKeyEnv or the legacy
-    // STRATUSCLAW_ prefix supplied the key, sending the reader to unset
-    // something that was never the cause.
+    // would name the wrong one whenever a custom apiKeyEnv supplied the key,
+    // sending the reader to unset something that was never the cause.
     const primary = runtime.provider === 'anthropic' && runtime.apiKey ? runtime.apiKeyEnvVar : undefined;
     // A fallback demoted the same way costs exactly as much, and only bites
     // once the primary is already failing — the worst moment to discover it.
@@ -819,6 +1019,15 @@ const createAgentRuntime = async (streams, options) => {
     const tools = new ToolRegistry();
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
+    // The same skills the daemon would serve, from the same directory, for
+    // the same reason the plugins below match: a skill that routes in
+    // `stratus run` routes in `stratus serve`, and one that is broken is
+    // broken (and warned about) in both. The runner registers `skill.read`
+    // itself, gated on the soul enabling any skill.
+    const skills = new SkillRegistry();
+    await loadOperatorSkills(runEnv, skills, (line) => {
+        writeLine(streams.stderr, `Warning: ${line}`);
+    });
     const bus = new EventBus({
         onError: (error) => {
             writeLine(streams.stderr, `Warning: event handler failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -838,6 +1047,31 @@ 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,
+            skills,
+            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.
@@ -857,6 +1091,7 @@ const createAgentRuntime = async (streams, options) => {
         executor: createLocalCommandExecutor(),
         approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}, options.askApproval),
         bus,
+        skills,
         memory,
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
     });
@@ -865,6 +1100,13 @@ const createAgentRuntime = async (streams, options) => {
     // A soul is a full identity — without one, every provider serves the
     // same built-in Stratus persona.
     const agent = options.runtime.soul?.agent ?? DEFAULT_STRATUS_AGENT;
+    // The same advisory the daemon gives at roster load, from the same
+    // kernel check: a soul enabling a skill whose `requires:` its `tools:`
+    // does not cover must warn here too, or the local test stays silent
+    // about a configuration `stratus serve` flags.
+    for (const { skill, missing } of missingSkillRequirements(agent, skills)) {
+        writeLine(streams.stderr, `Warning: agent ${agent.id} enables skill ${skill.id}, which expects tools the agent is not allowed: ${missing.join(', ')}`);
+    }
     const metadata = options.runtime.provider === 'demo'
         ? { provider: 'demo', executor: 'local-command' }
         : {
@@ -872,16 +1114,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 +1265,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 +1372,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 +1387,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 +1400,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 +1707,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,128 +1805,14 @@ 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);
-    // Config target: --config, then STRATUS_CONFIG / STRATUSCLAW_CONFIG, then
-    // the global ~/.stratus/config.json — the file `stratus run` falls back to
-    // from any directory, which is what makes setup a one-time step.
-    const envConfigVar = readNonEmptyString(processEnv.STRATUS_CONFIG)
-        ? 'STRATUS_CONFIG'
-        : readNonEmptyString(processEnv.STRATUSCLAW_CONFIG)
-            ? 'STRATUSCLAW_CONFIG'
-            : undefined;
-    const envConfigPath = envConfigVar ? String(processEnv[envConfigVar]).trim() : undefined;
+    // Config target: --config, then STRATUS_CONFIG, then the global
+    // ~/.stratus/config.json — the file `stratus run` falls back to from any
+    // directory, which is what makes setup a one-time step.
+    const envConfigVar = readNonEmptyString(processEnv.STRATUS_CONFIG) ? 'STRATUS_CONFIG' : undefined;
+    const envConfigPath = envConfigVar ? String(processEnv.STRATUS_CONFIG).trim() : undefined;
     const configPath = command.configPath
         ? path.resolve(cwd, command.configPath)
         : envConfigPath
@@ -1960,7 +1903,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];
@@ -2180,7 +2125,6 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         const keyEnvSelector = provider === state.provider
             ? readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-                ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
                 ?? state.apiKeyEnv
             : undefined;
         return state.credentials[provider] !== undefined
@@ -2222,85 +2166,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 +2321,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;
@@ -2507,11 +2381,9 @@ export const runSetup = async (command, streams, env = {}) => {
         // stored key's bound endpoint is authoritative — so the inline test
         // exercises precisely what a real run will use.
         const keyEnv = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-            ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
             ?? state.apiKeyEnv
             ?? defaultKeyEnvFor(state.provider);
         const envKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
-            ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
             ?? readNonEmptyString(processEnv[String(keyEnv)]);
         const credential = envKey ? undefined : state.credentials[state.provider];
         const boundUrl = credential?.type === 'api_key' ? credential.baseUrl : undefined;
@@ -2670,8 +2542,7 @@ export const runSetup = async (command, streams, env = {}) => {
         // Listing the config soul while `stratus serve` registers the env one
         // would store tokens against an id the adapter then skips.
         const processEnv = readProcessEnv(env);
-        const envSoul = readNonEmptyString(processEnv.STRATUS_SOUL)
-            ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL);
+        const envSoul = readNonEmptyString(processEnv.STRATUS_SOUL);
         if (typeof envSoul === 'string' && state.soulPath && envSoul !== state.soulPath) {
             warnOnce(`STRATUS_SOUL points at ${envSoul}, which outranks the configured ${state.soulPath} — Channels lists what a run would actually use`);
         }
@@ -2856,25 +2727,126 @@ export const runSetup = async (command, streams, env = {}) => {
             }
         }
     };
-    const detectEnvOverride = (primary, legacy, chosen, flagName) => {
-        const envVar = readNonEmptyString(processEnv[primary])
-            ? primary
-            : readNonEmptyString(processEnv[legacy])
-                ? legacy
-                : undefined;
-        if (!envVar) {
+    const detectEnvOverride = (primary, chosen, flagName) => {
+        if (!readNonEmptyString(processEnv[primary])) {
             return undefined;
         }
-        const envValue = String(processEnv[envVar]).trim();
+        const envValue = String(processEnv[primary]).trim();
         if (envValue === chosen) {
             return undefined;
         }
         return {
-            envVar,
+            envVar: primary,
             envValue,
             ...(flagName ? { flag: `${flagName} ${quoteShellArg(chosen)}` } : {}),
         };
     };
+    /**
+     * Whether `stratus dashboard` can work. Read before the offer and set by
+     * it, so the closing suggestions never name a command this machine cannot
+     * run — the failure that sends someone to the logs to find out why.
+     */
+    let dashboardReady = packageInstalled('@stratusagent/control-api', env)
+        && packageInstalled('@stratusagent/dashboard', env);
+    const missingPackageGroups = () => {
+        const groups = [];
+        const slackAgents = Object.keys(state.channels.slack ?? {}).length;
+        if (slackAgents > 0 && !packageInstalled('@stratusagent/channel-slack', env)) {
+            groups.push({
+                id: 'slack',
+                label: 'Slack channel',
+                why: `Slack tokens are stored for ${slackAgents} agent(s), but nothing connects to Slack without it`,
+                packages: ['@stratusagent/channel-slack'],
+            });
+        }
+        // Both, because the dashboard is what was offered: the control API is
+        // the port and the dashboard is the page served on it. Only the missing
+        // half is installed, so accepting this on a machine that already has
+        // the API does not reinstall it.
+        const dashboardPackages = ['@stratusagent/control-api', '@stratusagent/dashboard']
+            .filter((name) => !packageInstalled(name, env));
+        if (dashboardPackages.length > 0) {
+            groups.push({
+                id: 'dashboard',
+                label: 'Web dashboard',
+                why: '`stratus dashboard` needs it, and it opens an authenticated port on 127.0.0.1',
+                packages: dashboardPackages,
+            });
+        }
+        return groups;
+    };
+    /**
+     * Offers the packages above. Declining is a real answer and prints the
+     * command; the control API in particular binds a port, and installing it
+     * is how an operator says they want one open, so this asks rather than
+     * deciding for them.
+     */
+    const offerOptionalPackages = async () => {
+        const groups = missingPackageGroups();
+        if (groups.length === 0) {
+            return;
+        }
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, groups.length === 1
+            ? 'One optional package is not installed:'
+            : `${groups.length} optional packages are not installed:`);
+        for (const group of groups) {
+            writeLine(streams.stdout, `  ${group.packages.join(' ')}`);
+            writeLine(streams.stdout, `    ${group.why}.`);
+        }
+        const answer = await prompter.select('Install now with npm install -g?', groups.length === 1
+            ? ['Install it now', 'Skip']
+            : ['Install all of them now', ...groups.map((group) => `Install the ${group.label} only`), 'Skip']);
+        const chosen = (() => {
+            if (answer.kind !== 'index') {
+                return [];
+            }
+            if (groups.length === 1) {
+                return answer.index === 0 ? groups : [];
+            }
+            if (answer.index === 0) {
+                return groups;
+            }
+            const only = groups[answer.index - 1];
+            return only ? [only] : [];
+        })();
+        // Held before the install rather than derived after it: picking one
+        // group is not a decision about the other, and the daemon starts a few
+        // lines below and warns about exactly what is still missing — the
+        // notice this whole offer exists to pre-empt.
+        const declined = groups.filter((group) => !chosen.includes(group));
+        if (chosen.length > 0) {
+            const packages = chosen.flatMap((group) => group.packages);
+            writeLine(streams.stdout, `Running: npm install -g ${packages.join(' ')}`);
+            // Never fails setup, for the same reason the service install does not:
+            // the config and credentials are already written, and a package that
+            // did not install is a warning at the next start, not a broken machine.
+            const result = await (env.packageInstaller ?? defaultPackageInstaller)(packages)
+                .catch((error) => ({
+                ok: false,
+                message: error instanceof Error ? error.message : String(error),
+            }));
+            if (result.ok) {
+                writeLine(streams.stdout, `Installed ${packages.join(' ')}.`);
+                // npm's exit code, not a second resolve: a package written into the
+                // global prefix a moment ago need not be resolvable from THIS
+                // process, whose module resolution was fixed when it started.
+                if (chosen.some((group) => group.id === 'dashboard')) {
+                    dashboardReady = true;
+                }
+            }
+            else {
+                writeLine(streams.stderr, `Could not install: ${result.message}`);
+                writeLine(streams.stderr, `Setup is saved either way — run \`npm install -g ${packages.join(' ')}\` yourself.`);
+            }
+        }
+        if (declined.length > 0) {
+            const rest = declined.flatMap((group) => group.packages).join(' ');
+            writeLine(streams.stdout, chosen.length > 0
+                ? `Still missing. Install with: npm install -g ${rest}`
+                : `Skipped. Install them yourself with: npm install -g ${rest}`);
+        }
+    };
     const save = async () => {
         const config = { provider: state.provider };
         if (state.provider !== 'demo') {
@@ -2904,27 +2876,23 @@ 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
         // bare runs started here — say so, and make the suggested command pick
         // the file that was just written.
         if (configPath === globalConfigPath(env)) {
-            for (const shadow of [DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME]) {
-                const shadowPath = path.join(cwd, shadow);
-                try {
-                    await readFile(shadowPath, 'utf8');
-                    writeLine(streams.stdout, `Note: ${shadowPath} exists and takes precedence over the global config for runs started in this directory.`);
-                    writeLine(streams.stdout, 'The suggested commands below include --config so they use what you just saved.');
-                    shadowConfigFlag = ` --config ${quoteShellArg(configPath)}`;
-                    break;
-                }
-                catch (error) {
-                    if (error.code !== 'ENOENT') {
-                        throw error;
-                    }
+            const shadowPath = path.join(cwd, DEFAULT_CONFIG_FILENAME);
+            try {
+                await readFile(shadowPath, 'utf8');
+                writeLine(streams.stdout, `Note: ${shadowPath} exists and takes precedence over the global config for runs started in this directory.`);
+                writeLine(streams.stdout, 'The suggested commands below include --config so they use what you just saved.');
+                shadowConfigFlag = ` --config ${quoteShellArg(configPath)}`;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
                 }
             }
         }
@@ -2941,6 +2909,13 @@ export const runSetup = async (command, streams, env = {}) => {
                 ? `Saved Slack tokens for ${connected} agent${connected === 1 ? '' : 's'} to ${credentialsPath(env)} — run \`${serveCommand()}\` to bring them online.`
                 : `Removed the stored Slack tokens from ${credentialsPath(env)}.`);
         }
+        // Before the service block below, deliberately. A package installed
+        // after the daemon starts is invisible to it — installing does not
+        // reload a running process — so offering here is what makes the
+        // LaunchAgent come up with the Slack channel and the control API
+        // already present, instead of warning about them in a log nobody reads
+        // until the dashboard fails.
+        await offerOptionalPackages();
         // Last, so the daemon starts against the config and credentials that
         // were just written rather than the ones it would have found a moment
         // ago. A service failure is reported and never fails setup: the
@@ -2996,14 +2971,14 @@ export const runSetup = async (command, streams, env = {}) => {
         // Exported STRATUS_* variables outrank the config file, so warn when one
         // would make `stratus run` behave differently from what was just saved.
         const conflicts = [
-            detectEnvOverride('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER', state.provider, '--provider'),
+            detectEnvOverride('STRATUS_PROVIDER', state.provider, '--provider'),
             ...(state.provider !== 'demo'
-                ? [detectEnvOverride('STRATUS_MODEL', 'STRATUSCLAW_MODEL', state.model ?? defaultModelFor(state.provider), '--model')]
+                ? [detectEnvOverride('STRATUS_MODEL', state.model ?? defaultModelFor(state.provider), '--model')]
                 : []),
             ...(state.provider === 'openai'
-                ? [detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', state.baseUrl ?? DEFAULT_OPENAI_BASE_URL, '--base-url')]
-                : [detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', '')]),
-            detectEnvOverride('STRATUS_SYSTEM_PROMPT', 'STRATUSCLAW_SYSTEM_PROMPT', state.systemPrompt ?? ''),
+                ? [detectEnvOverride('STRATUS_BASE_URL', state.baseUrl ?? DEFAULT_OPENAI_BASE_URL, '--base-url')]
+                : [detectEnvOverride('STRATUS_BASE_URL', '')]),
+            detectEnvOverride('STRATUS_SYSTEM_PROMPT', state.systemPrompt ?? ''),
         ].filter((conflict) => conflict !== undefined);
         for (const conflict of conflicts) {
             writeLine(streams.stdout, `Note: ${conflict.envVar}=${conflict.envValue} is exported and takes precedence over the config file (run \`unset ${conflict.envVar}\` to clear it).`);
@@ -3037,7 +3012,9 @@ export const runSetup = async (command, streams, env = {}) => {
             }
         }
         writeLine(streams.stdout, `  stratus run${extraFlags}${runConfigFlag}${shadowConfigFlag} "say hello"`);
-        writeLine(streams.stdout, '  stratus dashboard');
+        if (dashboardReady) {
+            writeLine(streams.stdout, '  stratus dashboard');
+        }
     };
     try {
         if (!interactive) {
@@ -3088,127 +3065,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 +3166,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);
@@ -3245,23 +3188,20 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     // Config discovery, spelled out rather than delegated: doctor has to
     // report the files that LOST as well as the one in use, which is the
     // whole point when a stray project config is the answer.
-    // Which of the three named it, not just that one did: telling someone to
-    // fix STRATUS_CONFIG when STRATUSCLAW_CONFIG is what is set leaves the
-    // real override in place — the same mistake as provider and key
-    // attribution, in the one place a typo is most likely.
+    // Which of the two named it, not just that one did: telling someone to
+    // fix STRATUS_CONFIG when --config is what is set leaves the real
+    // override in place — the same mistake as provider and key attribution,
+    // in the one place a typo is most likely.
     const explicitSource = command.configPath !== undefined
         ? { name: '--config', value: command.configPath }
         : readNonEmptyString(processEnv.STRATUS_CONFIG)
             ? { name: 'STRATUS_CONFIG', value: String(processEnv.STRATUS_CONFIG) }
-            : readNonEmptyString(processEnv.STRATUSCLAW_CONFIG)
-                ? { name: 'STRATUSCLAW_CONFIG', value: String(processEnv.STRATUSCLAW_CONFIG) }
-                : undefined;
+            : undefined;
     const explicit = explicitSource?.value;
     const candidates = explicitSource
         ? [{ path: path.resolve(cwd, explicitSource.value), label: explicitSource.name }]
         : [
             { path: path.join(cwd, DEFAULT_CONFIG_FILENAME), label: 'project' },
-            { path: path.join(cwd, LEGACY_CONFIG_FILENAME), label: 'project (legacy)' },
             { path: globalConfigPath(env), label: 'global' },
         ];
     const present = [];
@@ -3314,16 +3254,10 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     }
     // Which variable supplied a value, not just the value: naming the wrong
     // one sends the reader to unset something that was never the cause,
-    // leaving the real override in place. The legacy STRATUSCLAW_ prefix is
-    // still honored by the resolver, so it has to be reportable too.
-    const envPick = (...names) => {
-        for (const name of names) {
-            const value = readNonEmptyString(processEnv[name]);
-            if (typeof value === 'string') {
-                return { name, value };
-            }
-        }
-        return undefined;
+    // leaving the real override in place.
+    const envPick = (name) => {
+        const value = readNonEmptyString(processEnv[name]);
+        return typeof value === 'string' ? { name, value } : undefined;
     };
     /**
      * The verdict comes from the resolver, not from a second copy of its
@@ -3332,7 +3266,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
      * while whether a run works at all, and what it bills, is whatever
      * resolveRuntimeConfig actually returns or throws.
      */
-    const envSoul = envPick('STRATUS_SOUL', 'STRATUSCLAW_SOUL');
+    const envSoul = envPick('STRATUS_SOUL');
     const soulValue = envSoul?.value ?? fileConfig.soul;
     const soulSource = envSoul ? envSoul.name : (winner ? winner.path : '');
     const soulPath = typeof soulValue === 'string' ? path.resolve(cwd, soulValue) : undefined;
@@ -3355,7 +3289,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
             }
         }
     }
-    const envProviderPick = envPick('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER');
+    const envProviderPick = envPick('STRATUS_PROVIDER');
     const providerSource = envProviderPick
         ? envProviderPick.name
         : soul?.provider
@@ -3385,7 +3319,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     }
     let model;
     if (resolved && resolved.provider !== 'demo') {
-        const envModel = envPick('STRATUS_MODEL', 'STRATUSCLAW_MODEL');
+        const envModel = envPick('STRATUS_MODEL');
         // A soul's model belongs to the soul's provider, and the config's model
         // to the config's provider — either can be stranded by an override.
         const soulModelApplies = soul?.provider === undefined || soul.provider === resolved.provider;
@@ -3641,40 +3575,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 +3597,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
@@ -3781,8 +3672,7 @@ export const runService = async (command, streams, env = {}) => {
     // install directory and can come up on a different roster entirely.
     const processEnv = readProcessEnv(env);
     const selectedConfig = command.configPath
-        ?? readNonEmptyString(processEnv.STRATUS_CONFIG)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_CONFIG);
+        ?? readNonEmptyString(processEnv.STRATUS_CONFIG);
     if (command.action === 'install') {
         // A config the daemon cannot parse kills it during gateway.start(),
         // and the manager — having accepted the start — restarts it on a
@@ -3836,6 +3726,159 @@ export const runService = async (command, streams, env = {}) => {
     }
     return result.ok ? 0 : 1;
 };
+/**
+ * What a `skill add` source string means, in order: a directory on this
+ * machine, a GitHub `owner/repo` shorthand, or a URL git can clone. The
+ * shorthand is the form skills.sh and its CLI print, so a skill published
+ * there installs by the name its listing shows.
+ */
+const resolveSkillSource = async (source, env) => {
+    const localPath = path.resolve(readWorkingDirectory(env), source);
+    try {
+        if ((await stat(localPath)).isDirectory()) {
+            return { kind: 'local', directory: localPath };
+        }
+    }
+    catch {
+        // Not a local directory; read it as a remote source.
+    }
+    if (/^[\w.-]+\/[\w.-]+$/.test(source)) {
+        return { kind: 'git', url: `https://github.com/${source}` };
+    }
+    if (/^(https?|git|ssh|file):\/\//.test(source) || /^git@[\w.-]+:/.test(source)) {
+        return { kind: 'git', url: source };
+    }
+    throw new Error(`Cannot read ${JSON.stringify(source)} as a skill source. Pass a GitHub owner/repo, a git URL, or a local path.`);
+};
+/** Shallow-clone a skills source. Git owns every transport we would otherwise re-implement. */
+const cloneSkillSource = async (url, destination) => {
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', ['clone', '--depth', '1', '--quiet', url, destination], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', (error) => {
+            reject(new Error(`Could not run git to fetch ${url}: ${error.message}`));
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`git clone failed for ${url}: ${stderr.trim() || `exit code ${code}`}`));
+            }
+        });
+    });
+};
+export const runSkillAdd = async (command, streams, env = {}) => {
+    const resolved = await resolveSkillSource(command.source, env);
+    let sourceDir;
+    let cleanup;
+    if (resolved.kind === 'local') {
+        sourceDir = resolved.directory;
+    }
+    else {
+        const scratch = await mkdtemp(path.join(os.tmpdir(), 'stratus-skill-add-'));
+        cleanup = () => rm(scratch, { recursive: true, force: true });
+        writeLine(streams.stdout, `Fetching ${resolved.url} …`);
+        try {
+            await cloneSkillSource(resolved.url, scratch);
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+        sourceDir = scratch;
+    }
+    try {
+        const result = await installSkillsFromDirectory(env, sourceDir, {
+            ...(command.skillIds ? { only: command.skillIds } : {}),
+            ...(command.force ? { force: true } : {}),
+        });
+        for (const skill of result.installed) {
+            writeLine(streams.stdout, `installed ${skill.id} — ${skill.description}`);
+        }
+        for (const skip of result.skipped) {
+            writeLine(streams.stderr, `Warning: skipped ${skip.id}: ${skip.reason}`);
+        }
+        if (result.installed.length === 0) {
+            writeLine(streams.stderr, result.skipped.length > 0
+                ? 'Error: nothing was installed.'
+                : `Error: no skills found in ${command.source}. A skill is a directory with a SKILL.md.`);
+            return 1;
+        }
+        // Installed is not enabled: a soul opts in through its skills:
+        // allowlist, and that stays true when the install came through a
+        // command. --agent is the explicit way to say both at once.
+        const ids = result.installed.map((skill) => skill.id);
+        if (command.agentId === undefined) {
+            writeLine(streams.stdout);
+            writeLine(streams.stdout, 'Installed, not yet enabled. Add to an agent\'s soul frontmatter:');
+            writeLine(streams.stdout, '  skills:');
+            for (const id of ids) {
+                writeLine(streams.stdout, `    - ${id}`);
+            }
+            writeLine(streams.stdout, `(or rerun with --agent <id>, or list them: stratus skills)`);
+            return 0;
+        }
+        const roster = await loadRosterSouls(env, (line) => writeLine(streams.stderr, `Warning: ${line}`));
+        const entry = roster.find((candidate) => candidate.soul.agent.id === command.agentId);
+        if (!entry) {
+            writeLine(streams.stderr, `Error: no agent with id ${command.agentId} in ${agentsDirPath(env)}. The skills are installed; enable them by editing a soul.`);
+            return 1;
+        }
+        const existing = entry.soul.agent.skills ?? [];
+        const additions = ids.filter((id) => !matchesSkillAllowlist(id, existing));
+        if (additions.length === 0) {
+            writeLine(streams.stdout, `${entry.soul.agent.name} already has all of these enabled.`);
+            return 0;
+        }
+        // A field edit renders through formatSoul, which canonicalizes the
+        // file — same trade the control API's field edits make.
+        const next = {
+            ...entry.soul,
+            agent: { ...entry.soul.agent, skills: [...existing, ...additions] },
+        };
+        await writeFile(entry.path, formatSoul(next));
+        writeLine(streams.stdout, `enabled for ${next.agent.name} (${entry.path}): ${additions.join(', ')}`);
+        return 0;
+    }
+    finally {
+        await cleanup?.();
+    }
+};
+export const runSkills = async (streams, env = {}) => {
+    const registry = new SkillRegistry();
+    const skills = await loadOperatorSkills(env, registry, (line) => {
+        writeLine(streams.stderr, `Warning: ${line}`);
+    });
+    if (skills.length === 0) {
+        writeLine(streams.stdout, `No skills installed in ${skillsDirPath(env)}.`);
+        writeLine(streams.stdout, 'Install some: stratus skill add <owner/repo | git url | path>');
+        return 0;
+    }
+    // Who has each skill enabled, so the listing answers the question that
+    // follows "what is installed" — read from the same roster a dispatch
+    // serves. Plugin-contributed skills are the daemon's to list
+    // (/catalog/tools); this command reads the operator directory.
+    const roster = await loadRosterSouls(env, () => { }).catch(() => []);
+    for (const skill of skills) {
+        const enabledBy = roster
+            .filter((entry) => {
+            const allowlist = entry.soul.agent.skills;
+            return allowlist !== undefined
+                && allowlist.length > 0
+                && matchesSkillAllowlist(skill.id, allowlist);
+        })
+            .map((entry) => entry.soul.agent.name);
+        const suffix = enabledBy.length > 0 ? ` — enabled by ${enabledBy.join(', ')}` : ' — enabled by nobody yet';
+        writeLine(streams.stdout, `${skill.id.padEnd(24)}${skill.description}${suffix}`);
+    }
+    return 0;
+};
 export const runAgentNew = async (command, streams, env = {}) => {
     // On a real terminal, creating an agent is the same guided experience as
     // setup: a headed screen, a prefilled (editable) name, a personality, and
@@ -3872,18 +3915,15 @@ export const runAgentNew = async (command, streams, env = {}) => {
                 writeLine(streams.stdout, `Note: ${message}.`);
             });
             const soulProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
-                ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
                 ?? activeConfig.provider
                 ?? 'demo';
             // The active config's model was written for the provider named in
             // that config; it only travels into the soul when they still match.
             const configModelApplies = (activeConfig.provider ?? 'openai') === soulProvider;
             const soulModel = readNonEmptyString(processEnv.STRATUS_MODEL)
-                ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL)
                 ?? (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 +3948,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,31 +4006,192 @@ 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();
+    }
+    return serving;
+};
+/**
+ * Resolution and loading are separate questions, and only the first one
+ * means "not installed". Inspecting an import's error message cannot tell
+ * them apart: a package that IS installed but is missing one of its own
+ * dependencies throws ERR_MODULE_NOT_FOUND naming that dependency and the
+ * importer — so a broken install would read as an absent one, silently
+ * disabling a channel whose stored tokens say it should be running, or
+ * leaving a daemon without the API an operator installed it to have.
+ */
+const defaultPackageResolver = (specifier) => {
+    try {
+        import.meta.resolve(specifier);
+        return true;
+    }
+    catch {
+        return false;
     }
-    await once(process, 'SIGINT');
-    await handle.close();
-    return 0;
 };
+/**
+ * Whether an optional package is installed. The resolver is injectable
+ * because what is installed is a property of the machine: a test asserting
+ * on the real one would be asserting on its own node_modules, which is why
+ * every optional package is a devDependency here in the first place.
+ */
+const packageInstalled = (specifier, env = {}) => (env.packageResolver ?? defaultPackageResolver)(specifier);
 /**
  * Loads the optional Slack channel package, or undefined when it is not
  * installed. Only that package being absent is tolerated: an adapter that
@@ -3992,23 +4200,69 @@ export const runDashboard = async (command, streams, env = {}) => {
  * whose stored tokens say it should be running.
  */
 const loadSlackAdapter = async () => {
-    // Resolution and loading are separate questions, and only the first one
-    // means "not installed". Inspecting the import's error message cannot
-    // tell them apart: a package that IS installed but is missing one of
-    // its own dependencies throws ERR_MODULE_NOT_FOUND naming that
-    // dependency and this package as the importer — a broken install would
-    // read as an absent one, silently disabling a channel whose tokens say
-    // it should be running.
-    try {
-        import.meta.resolve('@stratusagent/channel-slack');
-    }
-    catch {
+    if (!packageInstalled('@stratusagent/channel-slack')) {
         return undefined;
     }
     // Resolvable: any failure from here is a real problem with the
     // 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 () => {
+    if (!packageInstalled('@stratusagent/control-api')) {
+        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 +4307,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 +4362,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 +4437,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 +4552,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 `
@@ -4311,6 +4637,12 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.command === 'agents') {
             return await runAgents(command, streams, resolvedEnv);
         }
+        if (command.command === 'skill-add') {
+            return await runSkillAdd(command, streams, resolvedEnv);
+        }
+        if (command.command === 'skills') {
+            return await runSkills(streams, resolvedEnv);
+        }
         if (command.command === 'doctor') {
             return await runDoctor(command, streams, resolvedEnv);
         }
@@ -4342,6 +4674,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') {