@stratusagent/cli 0.2.2 → 0.3.0

package/dist/index.js

@@ -1,54 +1,74 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { appendFile, chmod, mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { once } from 'node:events';
-import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
-import { createLocalCommandExecutor, defineLocalCommandTool, } from '@stratusagent/executor-local';
-import { createOpenAICompatibleProvider, createProviderResponseBuilder, defineProvider, } from '@stratusagent/providers';
-import { createAnthropicProvider, DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
-import { createClaudeCodeProvider } from '@stratusagent/provider-claude-code';
+import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
+import { createPermissionPolicy } from '@stratusagent/permissions';
+import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
 import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-export const CLI_VERSION = '0.2.2';
-// The agent every run uses when no soul is configured. A Stratus agent is
-// a Stratus agent — never "the model" — whichever provider serves it.
-const DEFAULT_STRATUS_AGENT = {
-    id: 'stratus',
-    name: 'Stratus',
-    instructions: 'You are Stratus, a personal agent on the Stratus Agent platform. Be warm, direct, and concise. When asked who or what you are, you are Stratus — a Stratus agent — regardless of which model is serving the conversation.',
-};
-// Unsouled runs used to remember facts under a per-provider default agent.
-// Stratus inherits all of them: reads for the built-in agent also return
-// entries stored under the legacy ids, while new facts land under 'stratus'.
-const LEGACY_DEFAULT_AGENT_IDS = ['demo-agent', 'anthropic-agent', 'openai-agent'];
-const withLegacyDefaultMemories = (store) => ({
-    append: (agentId, content, metadata) => store.append(agentId, content, metadata),
-    async list(agentId) {
-        if (agentId !== DEFAULT_STRATUS_AGENT.id) {
-            return store.list(agentId);
-        }
-        const batches = await Promise.all([DEFAULT_STRATUS_AGENT.id, ...LEGACY_DEFAULT_AGENT_IDS].map((id) => store.list(id)));
-        return batches.flat().sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    },
-});
-const DEFAULT_CONFIG_FILENAME = 'stratus.config.json';
-const LEGACY_CONFIG_FILENAME = 'stratusclaw.config.json';
-const STRATUS_HOME_DIRNAME = '.stratus';
-const GLOBAL_CONFIG_FILENAME = 'config.json';
-const CREDENTIALS_FILENAME = 'credentials.json';
-const AGENTS_DIRNAME = 'agents';
-const DEFAULT_ANTHROPIC_BASE_URL = 'https://api.anthropic.com';
-const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
-const DEFAULT_OPENAI_MODEL = 'gpt-4.1-mini';
+import { agentsDirPath, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, loadRosterSouls, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, logsDirPath, readWorkingDirectory, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveCredentials, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { 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";
+export { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, parseLogLines, readRecentRecords, tailLog, } from "./logs.js";
+// The shared state package owns config resolution, credentials, memory, and
+// provider wiring now (the gateway uses the same code); the CLI re-exports
+// its historical surface so existing importers keep working.
+export { createFileMemoryStore } from '@stratusagent/state';
+// Kept in step with this package's own version by a test, because it is a
+// second copy of a number nobody re-reads: it is drawn in the setup header
+// and served from the dashboard's /api/status, so drift here misreports the
+// running build rather than failing anything.
+export const CLI_VERSION = '0.3.0';
 const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
+/**
+ * The range every package declares in its `engines` field. Two floors, not
+ * one: `node:sqlite` was unflagged in 22.13.0 on the LTS line and in 23.4.0
+ * on the 23.x line, so 23.0 through 23.3 are NEWER than the 22.x floor and
+ * still ship it behind `--experimental-sqlite`. A plain `>=22.13` admits
+ * exactly those releases.
+ */
+export const SUPPORTED_NODE_RANGE = '>=22.13 <23 || >=23.4';
+/**
+ * Why the CLI checks a version its manifests already declare: `engines` is
+ * advisory. npm and pnpm print EBADENGINE and carry on unless the user has
+ * turned on engine-strict, so an install on Node 20 succeeds and the floor
+ * is discovered later as an ERR_UNKNOWN_BUILTIN_MODULE for `node:sqlite`,
+ * thrown from a lazy import inside whichever command first needed the
+ * session store. That error names neither Node nor the version required.
+ *
+ * Returns the message to print, or undefined when the version is fine —
+ * including when it cannot be parsed at all, since an unrecognized build
+ * string is a bad reason to refuse to run.
+ */
+export const unsupportedNodeMessage = (version) => {
+    const parts = version.replace(/^v/, '').split('.');
+    const major = Number.parseInt(parts[0] ?? '', 10);
+    const minor = Number.parseInt(parts[1] ?? '', 10);
+    if (!Number.isInteger(major) || !Number.isInteger(minor)) {
+        return undefined;
+    }
+    const supported = major > 23
+        || (major === 23 && minor >= 4)
+        || (major === 22 && minor >= 13);
+    if (supported) {
+        return undefined;
+    }
+    return `Stratus Agent needs Node 22.13 or newer, and 23.4 or newer on the 23.x line — this is Node ${version.replace(/^v/, '')}.\n`
+        + "The gateway's session store uses node:sqlite, unflagged in 22.13.0 and, on the 23.x line, not until 23.4.0.\n"
+        + 'Upgrade with `brew install node` on macOS, or your package manager or nvm on Linux.';
+};
 const HELP_TEXT = `Stratus Agent CLI
 
 Usage:
   stratus setup
+  stratus chat
+  stratus chat --soul ./examples/souls/ava.md
   stratus run --prompt "Use the demo tool"
   stratus run "Say hello"
   ANTHROPIC_API_KEY=... stratus run --provider anthropic "Say hello"
@@ -56,16 +76,44 @@ Usage:
   echo "Use the echo tool" | stratus run --stdin
   STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run "Say hello"
   stratus run --config ./stratus.config.json --provider openai "Say hello"
+  stratus agents
+  stratus doctor
+  stratus service install
+  stratus service status
+  stratus logs -f
+  stratus logs --agent ava -n 200
   stratus dashboard
   stratus dashboard --port 4123 --host 0.0.0.0 --no-open
 
 Commands:
   setup            Menu-driven onboarding: pick a provider, sign in (Claude
-                   subscription or API key), create your agent, and test it —
-                   settings go to ~/.stratus/config.json, sign-ins to
-                   ~/.stratus/credentials.json (0600)
+                   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)
+  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
+  serve            Run stratusd, the always-on gateway: durable sessions, the
+                   whole roster live at once (each agent on its own provider),
+                   delegation, and a watchdog — Ctrl+C / SIGTERM drains cleanly
+                   (--idle-timeout <seconds>, --no-events, --no-log-file,
+                   --config <path>); everything it says is also written to
+                   ~/.stratus/logs, which "stratus logs" reads
+  service          Keep stratusd running under launchd (macOS) or systemd
+                   (Linux): install, uninstall, status, start, stop.
+                   Installing starts it now and at every login
+                   (--no-login installs without the login trigger,
+                   --config <path> pins the daemon to one config file)
+  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
   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)
+  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
   help             Show this help message
 
@@ -110,207 +158,6 @@ const stringifyValue = (value) => {
     }
     return JSON.stringify(value, null, 2);
 };
-const createDemoTool = () => defineLocalCommandTool({
-    name: 'demo.echo',
-    description: 'Return a tiny transformed summary for CLI demos through a real local process.',
-    parameters: {
-        type: 'object',
-        properties: {
-            text: { type: 'string', description: 'Text to echo back through the local process.' },
-        },
-        required: ['text'],
-    },
-    async createCommand(input) {
-        const text = typeof input.text === 'string' ? input.text : '';
-        const normalized = text.trim() || 'empty input';
-        const script = `const text = ${JSON.stringify(normalized)}; console.log(JSON.stringify({ received: text, uppercase: text.toUpperCase(), length: text.length }));`;
-        return {
-            command: process.execPath,
-            args: ['-e', script],
-        };
-    },
-    parseResult(result) {
-        return JSON.parse(result.stdout);
-    },
-});
-const createDemoProvider = () => defineProvider({
-    name: 'demo',
-    async generate({ session }) {
-        const builder = createProviderResponseBuilder();
-        const lastMessage = session.messages.at(-1);
-        if (lastMessage?.role === 'tool') {
-            const result = lastMessage.toolResult;
-            if (result?.ok) {
-                builder.addText(`The demo.echo tool finished with: ${JSON.stringify(result.output)}`);
-            }
-            else {
-                builder.addText(`The demo.echo tool did not run (${result?.error ?? 'unknown error'}), so this run ends here.`);
-            }
-            return builder.done();
-        }
-        const prompt = [...session.messages].reverse().find((message) => message.role === 'user')?.content?.trim() ?? '';
-        const wantsTool = /\b(tool|echo|uppercase|inspect)\b/i.test(prompt);
-        builder.addText(`Demo provider ready. Prompt received: ${prompt || '(empty)'}`);
-        if (wantsTool) {
-            builder.addToolCall({
-                id: `${session.id}:call:demo-echo`,
-                toolName: 'demo.echo',
-                input: { text: prompt },
-            });
-        }
-        else {
-            builder.addText('No tool call was needed, so this run stays text-only. Mention “tool” or “echo” to trigger the demo tool.');
-        }
-        return builder.done();
-    },
-});
-const MEMORY_FILENAME = 'memory.jsonl';
-const memoryFilePath = (env) => path.join(stratusHomePath(env), MEMORY_FILENAME);
-// Memory used to live under the working directory. Fold any such file into
-// the global store the first time a run happens from that directory, then
-// archive it — an upgrade must never look like the agent forgot.
-//
-// Every import first takes exclusive ownership by atomically renaming its
-// source to a unique claim file: of any competing processes, exactly one
-// wins the rename and the rest see ENOENT. A crash mid-import leaves the
-// claim file behind; later runs re-claim it the same way and finish the
-// job, with entries deduped against the global store by id. Only records
-// that parse as real memory entries are imported — malformed lines stay in
-// the archive instead of poisoning the global store for every agent.
-const isMemoryEntryLine = (line) => {
-    try {
-        const parsed = JSON.parse(line);
-        return typeof parsed === 'object' && parsed !== null
-            && typeof parsed.id === 'string'
-            && typeof parsed.agentId === 'string'
-            && typeof parsed.content === 'string';
-    }
-    catch {
-        return false;
-    }
-};
-const migrateLegacyMemory = async (env) => {
-    const legacyPath = path.join(readWorkingDirectory(env), '.stratus', MEMORY_FILENAME);
-    const globalPath = memoryFilePath(env);
-    if (legacyPath === globalPath) {
-        return;
-    }
-    const legacyDir = path.dirname(legacyPath);
-    const archivePath = `${legacyPath}.migrated`;
-    const claimAndImport = async (sourcePath) => {
-        const claimPath = path.join(legacyDir, `${MEMORY_FILENAME}.migrating-${randomUUID()}`);
-        try {
-            await rename(sourcePath, claimPath);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return; // another process owns it, or there is nothing to migrate
-            }
-            throw error;
-        }
-        const claimed = await readFile(claimPath, 'utf8');
-        let existingIds;
-        try {
-            existingIds = new Set((await readFile(globalPath, 'utf8'))
-                .split('\n')
-                .filter(isMemoryEntryLine)
-                .map((line) => JSON.parse(line).id));
-        }
-        catch {
-            existingIds = new Set();
-        }
-        const entries = claimed
-            .split('\n')
-            .filter((line) => line.trim().length > 0)
-            .filter(isMemoryEntryLine)
-            .filter((line) => !existingIds.has(JSON.parse(line).id));
-        if (entries.length > 0) {
-            await mkdir(path.dirname(globalPath), { recursive: true });
-            await appendFile(globalPath, `${entries.join('\n')}\n`);
-        }
-        // Archive by appending (never overwriting an earlier archive), then
-        // drop the claim — its content is fully preserved in the archive.
-        if (claimed.length > 0) {
-            await appendFile(archivePath, claimed.endsWith('\n') || claimed.length === 0 ? claimed : `${claimed}\n`);
-        }
-        await unlink(claimPath);
-    };
-    await claimAndImport(legacyPath);
-    // Finish any claims a crashed run left behind (both the current unique
-    // names and the fixed .migrating name from earlier versions).
-    let leftovers;
-    try {
-        leftovers = await readdir(legacyDir);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return;
-        }
-        throw error;
-    }
-    for (const name of leftovers) {
-        if (name.startsWith(`${MEMORY_FILENAME}.migrating`)) {
-            await claimAndImport(path.join(legacyDir, name));
-        }
-    }
-};
-// Agents keep the same memory across CLI runs: every remembered fact lands
-// in ~/.stratus/memory.jsonl (keyed by agent id), so the Ava you talk to
-// tomorrow — from any directory — is the Ava you talked to today. One JSON
-// entry per line, written with O_APPEND: concurrent runs each add their own
-// line instead of re-writing the file, so no run can clobber another's
-// remembered fact.
-export const createFileMemoryStore = (filePath) => {
-    const readEntries = async () => {
-        let raw;
-        try {
-            raw = await readFile(filePath, 'utf8');
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return [];
-            }
-            throw error;
-        }
-        return raw
-            .split('\n')
-            .filter((line) => line.trim().length > 0)
-            .map((line) => {
-            try {
-                return JSON.parse(line);
-            }
-            catch {
-                throw new Error(`Memory file has an invalid line: ${filePath}`);
-            }
-        });
-    };
-    return {
-        async append(agentId, content, metadata) {
-            const entry = {
-                id: `${agentId}:memory:${randomUUID()}`,
-                agentId,
-                content,
-                createdAt: new Date().toISOString(),
-                ...(metadata ? { metadata } : {}),
-            };
-            await mkdir(path.dirname(filePath), { recursive: true });
-            await appendFile(filePath, `${JSON.stringify(entry)}\n`);
-            return entry;
-        },
-        async list(agentId) {
-            // Dedupe by id at read time: even if a rare race double-imported a
-            // fact, the agent only ever sees it once.
-            const seen = new Set();
-            return (await readEntries()).filter((entry) => {
-                if (entry.agentId !== agentId || seen.has(entry.id)) {
-                    return false;
-                }
-                seen.add(entry.id);
-                return true;
-            });
-        },
-    };
-};
 const readPromptFromEnvironment = (env) => (env.stdin ?? '').trim();
 const readPromptFromStdin = async (stdin) => {
     stdin.setEncoding('utf8');
@@ -320,54 +167,6 @@ const readPromptFromStdin = async (stdin) => {
     }
     return data.trim();
 };
-const parseProviderName = (value, label) => {
-    if (value === 'demo' || value === 'openai' || value === 'anthropic') {
-        return value;
-    }
-    throw new Error(`Unsupported provider in ${label}: ${value}`);
-};
-const readProcessEnv = (env) => env.processEnv ?? process.env;
-const readWorkingDirectory = (env) => env.cwd ?? process.cwd();
-const readHomeDirectory = (env) => env.homeDir ?? os.homedir();
-const stratusHomePath = (env) => path.join(readHomeDirectory(env), STRATUS_HOME_DIRNAME);
-const globalConfigPath = (env) => path.join(stratusHomePath(env), GLOBAL_CONFIG_FILENAME);
-const credentialsPath = (env) => path.join(stratusHomePath(env), CREDENTIALS_FILENAME);
-const agentsDirPath = (env) => path.join(stratusHomePath(env), AGENTS_DIRNAME);
-const loadCredentials = async (env) => {
-    let raw;
-    try {
-        raw = await readFile(credentialsPath(env), 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return {};
-        }
-        throw error;
-    }
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Credentials file must contain a JSON object: ${credentialsPath(env)}`);
-    }
-    const credentials = {};
-    for (const provider of ['anthropic', 'openai']) {
-        const entry = parsed[provider];
-        if (typeof entry === 'object' && entry !== null && !Array.isArray(entry) &&
-            (entry.type === 'api_key' || entry.type === 'oauth_token') &&
-            typeof entry.value === 'string') {
-            credentials[provider] = entry;
-        }
-    }
-    return credentials;
-};
-// Credentials never live in a project directory or a shell profile — they
-// are written once by `stratus setup` and read on every run, 0600 so only
-// the owner can read them.
-const saveCredentials = async (env, credentials) => {
-    const filePath = credentialsPath(env);
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
-    await chmod(filePath, 0o600);
-};
 const readOptionValue = (tokens, index, flag) => {
     const value = tokens[index + 1];
     if (!value) {
@@ -414,13 +213,257 @@ export const parseCommand = (argv, env = {}) => {
         }
         return { command: 'dashboard', ...(port !== undefined ? { port } : {}), host, openBrowser };
     }
+    if (command === 'serve') {
+        const parsed = { command: 'serve', events: true };
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--config') {
+                parsed.configPath = readOptionValue(rest, index, '--config');
+                index += 1;
+                continue;
+            }
+            if (token === '--idle-timeout') {
+                const seconds = Number(readOptionValue(rest, index, '--idle-timeout'));
+                if (!Number.isFinite(seconds) || seconds < 0) {
+                    throw new Error(`Invalid value for --idle-timeout: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                parsed.idleTimeoutMs = Math.round(seconds * 1000);
+                index += 1;
+                continue;
+            }
+            if (token === '--no-events') {
+                parsed.events = false;
+                continue;
+            }
+            if (token === '--no-log-file') {
+                parsed.logToFile = false;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return parsed;
+    }
+    if (command === 'chat') {
+        const parsed = { command: 'chat', events: false, approvals: 'always' };
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--provider') {
+                parsed.provider = parseProviderName(readOptionValue(rest, index, '--provider'), '--provider');
+                index += 1;
+                continue;
+            }
+            if (token === '--model') {
+                parsed.model = readOptionValue(rest, index, '--model');
+                index += 1;
+                continue;
+            }
+            if (token === '--base-url') {
+                parsed.baseUrl = readOptionValue(rest, index, '--base-url');
+                index += 1;
+                continue;
+            }
+            if (token === '--soul') {
+                parsed.soul = readOptionValue(rest, index, '--soul');
+                index += 1;
+                continue;
+            }
+            if (token === '--config') {
+                parsed.configPath = readOptionValue(rest, index, '--config');
+                index += 1;
+                continue;
+            }
+            if (token === '--approvals') {
+                const value = readOptionValue(rest, index, '--approvals');
+                if (value !== 'always' && value !== 'ask' && value !== 'never') {
+                    throw new Error(`Invalid value for --approvals: ${value}`);
+                }
+                parsed.approvals = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--max-turns') {
+                const value = Number(readOptionValue(rest, index, '--max-turns'));
+                if (!Number.isInteger(value) || value < 1) {
+                    throw new Error(`Invalid value for --max-turns: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                parsed.maxTurns = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--events') {
+                parsed.events = true;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return parsed;
+    }
+    if (command === 'agents' || (command === 'agent' && rest[0] === 'list')) {
+        const agentsRest = command === 'agents' ? rest : rest.slice(1);
+        let format = 'text';
+        for (let index = 0; index < agentsRest.length; index += 1) {
+            const token = agentsRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--format') {
+                const value = readOptionValue(agentsRest, index, '--format');
+                if (value !== 'text' && value !== 'json') {
+                    throw new Error(`Unsupported format: ${value}`);
+                }
+                format = value;
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return { command: 'agents', format };
+    }
+    if (command === 'doctor') {
+        let format = 'text';
+        let configPath;
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--format') {
+                const value = readOptionValue(rest, index, '--format');
+                if (value !== 'text' && value !== 'json') {
+                    throw new Error(`Unsupported format: ${value}`);
+                }
+                format = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--config') {
+                configPath = readOptionValue(rest, index, '--config');
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return { command: 'doctor', format, ...(configPath ? { configPath } : {}) };
+    }
+    if (command === 'service') {
+        const action = rest[0];
+        if (action === '--help' || action === '-h' || action === undefined) {
+            return { command: 'help' };
+        }
+        if (action !== 'install' && action !== 'uninstall' && action !== 'status' && action !== 'start' && action !== 'stop') {
+            throw new Error(`Unknown service action: ${action} (expected install, uninstall, status, start, or stop)`);
+        }
+        const parsed = { command: 'service', action };
+        const serviceRest = rest.slice(1);
+        for (let index = 0; index < serviceRest.length; index += 1) {
+            const token = serviceRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--no-login') {
+                if (action !== 'install') {
+                    throw new Error('--no-login applies to `stratus service install`.');
+                }
+                parsed.runAtLogin = false;
+                continue;
+            }
+            if (token === '--config') {
+                if (action !== 'install') {
+                    throw new Error('--config applies to `stratus service install`.');
+                }
+                parsed.configPath = readOptionValue(serviceRest, index, '--config');
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return parsed;
+    }
+    if (command === 'logs') {
+        let follow = false;
+        let limit = 50;
+        let agentId;
+        let sessionId;
+        let format = 'text';
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--follow' || token === '-f') {
+                follow = true;
+                continue;
+            }
+            if (token === '--lines' || token === '-n') {
+                const value = Number(readOptionValue(rest, index, token));
+                if (!Number.isFinite(value) || value < 0) {
+                    throw new Error(`Invalid value for ${token}: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                limit = Math.floor(value);
+                index += 1;
+                continue;
+            }
+            if (token === '--agent') {
+                agentId = readOptionValue(rest, index, '--agent');
+                index += 1;
+                continue;
+            }
+            if (token === '--session') {
+                sessionId = readOptionValue(rest, index, '--session');
+                index += 1;
+                continue;
+            }
+            if (token === '--format') {
+                const value = readOptionValue(rest, index, '--format');
+                if (value !== 'text' && value !== 'json') {
+                    throw new Error(`Unsupported format: ${value}`);
+                }
+                format = value;
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return {
+            command: 'logs',
+            follow,
+            limit,
+            format,
+            ...(agentId ? { agentId } : {}),
+            ...(sessionId ? { sessionId } : {}),
+        };
+    }
     if (command === 'agent') {
         const [subcommand, ...agentRest] = rest;
         if (subcommand === '--help' || subcommand === '-h') {
             return { command: 'help' };
         }
         if (subcommand !== 'new') {
-            throw new Error(`Unknown agent subcommand: ${subcommand ?? '(missing)'}. Try: stratus agent new`);
+            throw new Error(`Unknown agent subcommand: ${subcommand ?? '(missing)'}. Try: stratus agent new, stratus agent list`);
         }
         let name;
         let instructions;
@@ -621,359 +664,69 @@ export const formatEvent = (event) => {
             return null;
     }
 };
-const loadConfigFile = async (configPath) => {
-    const raw = await readFile(configPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Config file must contain a JSON object: ${configPath}`);
-    }
-    const config = parsed;
-    const resolved = {};
-    if (typeof config.provider === 'string') {
-        resolved.provider = parseProviderName(config.provider, `config ${configPath}`);
-    }
-    if (typeof config.model === 'string' && config.model.length > 0) {
-        resolved.model = config.model;
-    }
-    if (typeof config.baseUrl === 'string' && config.baseUrl.length > 0) {
-        resolved.baseUrl = config.baseUrl;
-    }
-    if (typeof config.apiKeyEnv === 'string' && config.apiKeyEnv.length > 0) {
-        resolved.apiKeyEnv = config.apiKeyEnv;
-    }
-    if (typeof config.systemPrompt === 'string' && config.systemPrompt.length > 0) {
-        resolved.systemPrompt = config.systemPrompt;
-    }
-    if (typeof config.soul === 'string' && config.soul.length > 0) {
-        resolved.soul = config.soul;
-    }
-    if (typeof config.fallbackModel === 'string' && config.fallbackModel.length > 0) {
-        resolved.fallbackModel = config.fallbackModel;
-    }
-    if (typeof config.fallbackProvider === 'string') {
-        resolved.fallbackProvider = parseProviderName(config.fallbackProvider, `config ${configPath}`);
-    }
-    if (typeof config.fallbackBaseUrl === 'string' && config.fallbackBaseUrl.length > 0) {
-        resolved.fallbackBaseUrl = config.fallbackBaseUrl;
-    }
-    return resolved;
-};
-const resolveConfigLocation = async (command, env) => {
-    const processEnv = readProcessEnv(env);
-    const cwd = readWorkingDirectory(env);
-    const explicit = command.configPath ?? processEnv.STRATUS_CONFIG ?? processEnv.STRATUSCLAW_CONFIG;
-    if (explicit) {
-        return { path: path.resolve(cwd, explicit), trusted: true };
-    }
-    // Project-local configs win; the global ~/.stratus/config.json written by
-    // `stratus setup` is the fallback that makes the CLI work from anywhere.
-    const candidates = [
-        { path: path.join(cwd, DEFAULT_CONFIG_FILENAME), trusted: false },
-        { path: path.join(cwd, LEGACY_CONFIG_FILENAME), trusted: false },
-        { path: globalConfigPath(env), trusted: true },
-    ];
-    for (const candidate of candidates) {
-        try {
-            await readFile(candidate.path, 'utf8');
-            return candidate;
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== 'ENOENT') {
-                throw error;
-            }
-        }
-    }
-    return undefined;
-};
-const readNonEmptyString = (value, map) => {
-    if (typeof value !== 'string') {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (trimmed.length === 0) {
-        return undefined;
+/**
+ * The fields worth keeping per event type. Tool inputs and message text
+ * are deliberately excluded: the log is a trace of what happened, not a
+ * second copy of the transcript.
+ */
+const eventDetail = (event) => {
+    switch (event.type) {
+        case 'session.updated':
+            return { status: event.status };
+        case 'provider.response':
+            return { parts: event.parts.length };
+        case 'tool.called':
+        case 'tool.denied':
+            return { tool: event.call.toolName };
+        case 'tool.completed':
+            return { tool: event.result.toolName, ok: event.result.ok };
+        case 'session.failed':
+            return { error: event.error };
+        default:
+            return undefined;
     }
-    return map ? map(trimmed) : trimmed;
 };
-// A soul travels with the run: --soul outranks STRATUS_SOUL, which outranks
-// the config file's "soul" key.
-const resolveSoul = async (command, env, fileConfig) => {
-    const processEnv = readProcessEnv(env);
-    const soulPath = command.soul
-        ?? readNonEmptyString(processEnv.STRATUS_SOUL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL)
-        ?? fileConfig.soul;
-    if (!soulPath) {
-        return undefined;
-    }
-    const resolvedPath = path.resolve(readWorkingDirectory(env), String(soulPath));
-    let raw;
-    try {
-        raw = await readFile(resolvedPath, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            throw new Error(`Soul file not found: ${resolvedPath}`);
-        }
-        throw error;
-    }
-    try {
-        // Seeding with the resolved path keeps an unnamed soul's generated
-        // identity (name, id, avatar) stable across runs — persisted memory is
-        // keyed by that id, so it must not change between invocations.
-        return parseSoul(raw, { seed: resolvedPath });
+// Kept with its historical CLI signature: a parsed run command is a
+// RuntimeSelection plus CLI-only fields the resolver ignores.
+export const resolveRuntimeConfig = (command, env = {}) => resolveStateRuntimeConfig(command, env);
+/**
+ * A saved subscription sign-in silently demoted to per-token billing is the
+ * one config surprise that costs money — an API key in the environment
+ * outranks the stored credential, and the run otherwise looks identical.
+ * Detected from the resolved config: an apiKey where the stored credential
+ * is a subscription token means the environment won.
+ */
+export const warnOnCredentialOverride = async (runtime, streams, env = {}) => {
+    if (runtime.provider === 'demo') {
+        return;
     }
-    catch (error) {
-        throw new Error(`Could not parse soul file ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
+    const stored = (await loadCredentials(env)).anthropic;
+    if (stored?.type !== 'oauth_token') {
+        return;
     }
-};
-export const resolveRuntimeConfig = async (command, env = {}) => {
+    // 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.
+    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.
+    // The fallback path consults the provider's own conventional variable.
     const processEnv = readProcessEnv(env);
-    const configLocation = await resolveConfigLocation(command, env);
-    const fileConfig = configLocation ? await loadConfigFile(configLocation.path) : {};
-    const soul = await resolveSoul(command, env, fileConfig);
-    // Explicit flags and env vars outrank the soul's own provider/model hints,
-    // which outrank the config file's defaults.
-    const provider = command.provider
-        ?? readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
-        ?? readNonEmptyString(soul?.provider, (value) => parseProviderName(value, 'soul file'))
-        ?? fileConfig.provider
-        ?? 'demo';
-    if (provider === 'demo') {
-        return { provider: 'demo', ...(soul ? { soul } : {}) };
-    }
-    // A config file's model/baseUrl/apiKeyEnv were written for the provider
-    // named in that file. When a flag, env var, or soul selects a different
-    // provider, those values would point at the wrong API (e.g. an OpenAI
-    // base URL handed to the Anthropic SDK), so they are ignored. A file with
-    // no provider key predates the anthropic option, so its settings are
-    // treated as openai-specific.
-    const fileConfigApplies = (fileConfig.provider ?? 'openai') === provider;
-    // A soul's model was chosen for the soul's own provider. If a flag or env
-    // var overrides that provider, the model hint would target the wrong API
-    // (e.g. a Claude model sent to OpenAI), so it only applies when the soul
-    // names no provider or names the selected one.
-    const soulModelApplies = soul?.provider === undefined || soul.provider === provider;
-    const model = command.model
-        ?? readNonEmptyString(processEnv.STRATUS_MODEL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL)
-        ?? (soulModelApplies ? readNonEmptyString(soul?.model) : undefined)
-        ?? (fileConfigApplies ? fileConfig.model : undefined)
-        ?? (provider === 'anthropic' ? DEFAULT_ANTHROPIC_MODEL : DEFAULT_OPENAI_MODEL);
-    const apiKeyEnvName = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
-        ?? (fileConfigApplies ? fileConfig.apiKeyEnv : undefined)
-        ?? (provider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY');
-    const credentials = await loadCredentials(env);
-    // A custom endpoint chosen by an auto-discovered project config is not a
-    // place the stored sign-in ever gets sent — a cloned repository could
-    // point it anywhere. Flags and env vars are the user's own choice, and
-    // the provider's default endpoint is harmless.
-    const defaultEndpointFor = (target) => target === 'anthropic' ? DEFAULT_ANTHROPIC_BASE_URL : DEFAULT_OPENAI_BASE_URL;
-    const untrustedCustomBaseUrl = configLocation?.trusted === false
-        && command.baseUrl === undefined
-        && readNonEmptyString(processEnv.STRATUS_BASE_URL) === undefined
-        && readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL) === undefined
-        && fileConfigApplies
-        && fileConfig.baseUrl !== undefined
-        && fileConfig.baseUrl.replace(/\/+$/, '') !== defaultEndpointFor(String(provider));
-    // Env vars outrank the stored sign-in from `stratus setup`.
-    const envApiKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
-        ?? readNonEmptyString(processEnv[String(apiKeyEnvName)]);
-    const candidateCredential = credentials[provider];
-    // A bound credential ignores config URLs entirely, so an untrusted
-    // project URL cannot redirect it — only unbound stored keys are blocked.
-    const credentialIsBound = candidateCredential?.type === 'api_key' && candidateCredential.baseUrl !== undefined;
-    const storedCredential = envApiKey || (untrustedCustomBaseUrl && !credentialIsBound)
-        ? undefined
-        : candidateCredential;
-    const apiKey = envApiKey
-        ?? (storedCredential?.type === 'api_key' ? storedCredential.value : undefined);
-    const authToken = provider === 'anthropic' && storedCredential?.type === 'oauth_token'
-        ? storedCredential.value
+    const fallbackVar = runtime.fallback?.provider === 'anthropic'
+        && runtime.fallback.apiKey !== undefined
+        && readNonEmptyString(processEnv.ANTHROPIC_API_KEY) === runtime.fallback.apiKey
+        ? 'ANTHROPIC_API_KEY'
         : undefined;
-    // A stored key bound to an endpoint is used ONLY with that endpoint — a
-    // config file can never redirect it, not even to the official default
-    // URL (a project config could otherwise reroute a local-service key to
-    // the official API). An explicit flag or env URL that disagrees refuses
-    // the stored key instead of leaking it. This applies to both providers.
-    const boundBaseUrl = !envApiKey && storedCredential?.type === 'api_key'
-        ? storedCredential.baseUrl
-        : undefined;
-    const explicitBaseUrl = command.baseUrl
-        ?? readNonEmptyString(processEnv.STRATUS_BASE_URL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL);
-    if (boundBaseUrl && explicitBaseUrl
-        && String(explicitBaseUrl).replace(/\/+$/, '') !== boundBaseUrl.replace(/\/+$/, '')) {
-        throw new Error(`Your saved ${provider} sign-in is bound to ${boundBaseUrl} and is not sent to ${explicitBaseUrl}. Set ${apiKeyEnvName} or STRATUS_API_KEY to use that endpoint.`);
-    }
-    const baseUrl = boundBaseUrl
-        ?? explicitBaseUrl
-        ?? (fileConfigApplies ? fileConfig.baseUrl : undefined)
-        // The Anthropic SDK knows its own endpoint; only openai needs a default.
-        ?? (provider === 'anthropic' ? undefined : DEFAULT_OPENAI_BASE_URL);
-    if (!apiKey && !authToken) {
-        if (untrustedCustomBaseUrl && credentials[provider]) {
-            throw new Error(`The project config at ${configLocation?.path} sets a custom base URL (${fileConfig.baseUrl}), so your saved sign-in is not sent to it. Set ${apiKeyEnvName} or STRATUS_API_KEY to use this endpoint, or run with --config to trust the file explicitly.`);
-        }
-        throw new Error(`Missing API key for provider=${provider}. Run \`stratus setup\` to sign in, or set STRATUS_API_KEY or ${apiKeyEnvName}.`);
-    }
-    const resolved = provider === 'anthropic'
-        ? {
-            provider: 'anthropic',
-            model: String(model),
-            ...(baseUrl ? { baseUrl: String(baseUrl) } : {}),
-            ...(apiKey ? { apiKey: String(apiKey) } : {}),
-            ...(authToken ? { authToken } : {}),
-        }
-        : {
-            provider: 'openai',
-            model: String(model),
-            baseUrl: String(baseUrl),
-            apiKey: String(apiKey),
-        };
-    const systemPrompt = readNonEmptyString(processEnv.STRATUS_SYSTEM_PROMPT)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_SYSTEM_PROMPT)
-        ?? fileConfig.systemPrompt;
-    if (systemPrompt) {
-        resolved.systemPrompt = String(systemPrompt);
-    }
-    if (env.fetch) {
-        resolved.fetch = env.fetch;
-    }
-    if (soul) {
-        resolved.soul = soul;
-    }
-    // A configured fallback model kicks in when the default model errors
-    // mid-run. It needs its own working sign-in; without one the fallback is
-    // quietly skipped rather than failing the run it exists to rescue.
-    // An implicit fallback (no fallbackProvider key) was written for the
-    // config's own provider — when a flag, env var, or soul overrides that
-    // provider, the fallback model would target the wrong API, so it is
-    // ignored. An explicit fallbackProvider stays valid regardless.
-    if (fileConfig.fallbackModel && (fileConfig.fallbackProvider !== undefined || fileConfigApplies)) {
-        const fallbackProvider = fileConfig.fallbackProvider ?? provider;
-        if (fallbackProvider !== 'demo') {
-            // Same precedence as the primary sign-in: environment keys outrank
-            // the stored credential. And the same endpoint rule: an untrusted
-            // project config's custom fallback URL never receives a stored key —
-            // including the primary's stored key when both share a provider.
-            // Only env-supplied keys follow such a URL.
-            const fallbackUntrustedUrl = fallbackProvider === 'openai'
-                && configLocation?.trusted === false
-                && fileConfig.fallbackBaseUrl !== undefined
-                && fileConfig.fallbackBaseUrl.replace(/\/+$/, '') !== DEFAULT_OPENAI_BASE_URL;
-            const fallbackEnvKey = readNonEmptyString(processEnv[fallbackProvider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY']);
-            const fallbackCredential = fallbackEnvKey || fallbackUntrustedUrl ? undefined : credentials[fallbackProvider];
-            const primaryReusable = fallbackProvider === provider
-                && (envApiKey !== undefined || !fallbackUntrustedUrl);
-            const fallbackApiKey = (primaryReusable ? apiKey : undefined)
-                ?? fallbackEnvKey
-                ?? (fallbackCredential?.type === 'api_key' ? fallbackCredential.value : undefined);
-            const fallbackAuthToken = fallbackProvider !== provider && fallbackProvider === 'anthropic' && fallbackCredential?.type === 'oauth_token'
-                ? fallbackCredential.value
-                : (primaryReusable ? authToken : undefined);
-            if (fallbackApiKey || fallbackAuthToken) {
-                // When the fallback key comes out of the credential store (its own
-                // entry, or the primary's reused stored key), its bound endpoint is
-                // authoritative — config URLs cannot redirect it.
-                const fallbackBoundUrl = fallbackCredential?.type === 'api_key'
-                    ? fallbackCredential.baseUrl
-                    : (primaryReusable && !envApiKey ? boundBaseUrl : undefined);
-                // An anthropic fallback on the same provider keeps the primary's
-                // configured endpoint — retrying the same credential against the
-                // official endpoint instead of the configured service would leak
-                // it and likely fail.
-                const fallbackAnthropicBaseUrl = fallbackProvider === 'anthropic'
-                    ? (fallbackProvider === provider && baseUrl ? String(baseUrl) : undefined)
-                        ?? (fallbackCredential?.type === 'api_key' ? fallbackCredential.baseUrl : undefined)
-                    : undefined;
-                resolved.fallback = {
-                    provider: fallbackProvider,
-                    model: fileConfig.fallbackModel,
-                    ...(fallbackProvider === 'openai'
-                        ? {
-                            baseUrl: fallbackBoundUrl
-                                ?? fileConfig.fallbackBaseUrl
-                                ?? (fallbackProvider === provider ? String(baseUrl) : undefined)
-                                ?? DEFAULT_OPENAI_BASE_URL,
-                        }
-                        : (fallbackAnthropicBaseUrl ? { baseUrl: fallbackAnthropicBaseUrl } : {})),
-                    ...(fallbackApiKey ? { apiKey: String(fallbackApiKey) } : {}),
-                    ...(fallbackAuthToken ? { authToken: fallbackAuthToken } : {}),
-                };
-            }
-        }
-    }
-    return resolved;
-};
-// Wraps the fallback runtime as a provider: the primary model serves every
-// turn until it throws, then the run switches to the fallback for good.
-const createFallbackWrappedProvider = (primary, fallback, onFallback) => {
-    let usingFallback = false;
-    return {
-        name: primary.name,
-        async generate(request) {
-            if (!usingFallback) {
-                try {
-                    return await primary.generate(request);
-                }
-                catch (error) {
-                    usingFallback = true;
-                    onFallback(error);
-                }
-            }
-            return fallback.generate(request);
-        },
-    };
-};
-const createRuntimeProvider = (config, onFallback) => {
-    if (config.provider === 'demo') {
-        return createDemoProvider();
-    }
-    if (config.fallback) {
-        const { fallback, ...primaryConfig } = config;
-        const primary = createRuntimeProvider(primaryConfig);
-        const fallbackProvider = createRuntimeProvider({
-            ...fallback,
-            ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-            ...(config.fetch ? { fetch: config.fetch } : {}),
-        });
-        return createFallbackWrappedProvider(primary, fallbackProvider, onFallback ?? (() => { }));
-    }
-    if (config.provider === 'anthropic') {
-        // Subscription setup tokens are only honored inside the Claude Code
-        // harness, so they route through the Agent SDK runtime; API keys use
-        // the raw Messages API.
-        if (config.authToken && !config.apiKey) {
-            return createClaudeCodeProvider({
-                authToken: config.authToken,
-                model: config.model,
-                ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-            });
-        }
-        return createAnthropicProvider({
-            model: config.model,
-            ...(config.apiKey ? { apiKey: config.apiKey } : {}),
-            ...(config.authToken ? { authToken: config.authToken } : {}),
-            ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
-            ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-            ...(config.fetch ? { fetch: config.fetch } : {}),
-        });
+    const culprit = primary ?? fallbackVar;
+    if (!culprit) {
+        return;
     }
-    return createOpenAICompatibleProvider({
-        name: 'openai',
-        model: config.model,
-        apiKey: config.apiKey,
-        baseUrl: config.baseUrl,
-        ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-        ...(config.fetch ? { fetch: config.fetch } : {}),
-    });
+    writeLine(streams.stderr, `Warning: ${culprit} in your environment outranks the Claude subscription sign-in saved by \`stratus setup\`, `
+        + `so ${primary ? 'this run is' : 'a fallback retry would be'} billed per token instead of through your plan. `
+        + 'Unset it to use the subscription, or run `stratus doctor` to see everything that is being overridden.');
 };
-const createApprovalPolicy = (mode, streams, env) => {
+const createApprovalPolicy = (mode, streams, env, ask) => {
     if (mode === 'always') {
         return new AllowAllApprovalPolicy();
     }
@@ -984,6 +737,16 @@ const createApprovalPolicy = (mode, streams, env) => {
             },
         };
     }
+    // A caller that already owns stdin (chat's readline) supplies its own
+    // asker — two readers on one stream would race for the same bytes.
+    if (ask) {
+        return {
+            async approve({ call }) {
+                const answer = await ask(`Approve tool call ${call.toolName} with input ${JSON.stringify(call.input)}? [y/N] `);
+                return /^y(es)?$/i.test(answer.trim());
+            },
+        };
+    }
     return {
         async approve({ call }) {
             const input = env.approvalInput ?? process.stdin;
@@ -1004,7 +767,11 @@ const createApprovalPolicy = (mode, streams, env) => {
         },
     };
 };
-export const runSingleLoop = async (prompt, streams, options) => {
+// The shared wiring behind every conversational command: memory (with
+// legacy migration), tools, events, provider (with fallback), and the
+// agent the runtime resolved. run uses it for one shot; chat keeps the
+// runner alive and resumes the same session turn after turn.
+const createAgentRuntime = async (streams, options) => {
     const runEnv = options.env ?? {};
     await migrateLegacyMemory(runEnv);
     const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(runEnv)));
@@ -1016,7 +783,13 @@ export const runSingleLoop = async (prompt, streams, options) => {
             writeLine(streams.stderr, `Warning: event handler failed: ${error instanceof Error ? error.message : String(error)}`);
         },
     });
-    if (options.events ?? true) {
+    if (options.onEvent) {
+        const onEvent = options.onEvent;
+        bus.subscribe(async (event) => {
+            onEvent(event);
+        });
+    }
+    else if (options.events ?? true) {
         bus.subscribe(async (event) => {
             const line = formatEvent(event);
             if (line) {
@@ -1024,40 +797,49 @@ export const runSingleLoop = async (prompt, streams, options) => {
             }
         });
     }
+    // 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.
+    let hostedRunner;
     const runtimeProvider = createRuntimeProvider(options.runtime, (error) => {
         const fallback = options.runtime.provider === 'demo' ? undefined : options.runtime.fallback;
         writeLine(streams.stderr, `Warning: the default model failed (${error instanceof Error ? error.message : String(error)}); falling back to ${fallback?.model ?? 'the fallback model'}.`);
-    });
+    }, async (session, call, context) => {
+        if (!hostedRunner) {
+            throw new Error('The Stratus runtime is not ready to execute tools yet.');
+        }
+        return hostedRunner.executeHostedToolCall(session, call, context);
+    }, options.maxTurns);
     const runner = new AgentRunner({
         provider: runtimeProvider,
         tools,
         executor: createLocalCommandExecutor(),
-        approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}),
+        approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}, options.askApproval),
         bus,
         memory,
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
     });
+    hostedRunner = runner;
     await runner.initialize();
     // 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;
     const metadata = options.runtime.provider === 'demo'
-        ? { provider: 'demo' }
+        ? { provider: 'demo', executor: 'local-command' }
         : {
             provider: options.runtime.provider,
             model: options.runtime.model,
             ...(options.runtime.provider === 'openai' ? { baseUrl: options.runtime.baseUrl } : {}),
         };
+    return { runner, agent, metadata };
+};
+export const runSingleLoop = async (prompt, streams, options) => {
+    const { runner, agent, metadata } = await createAgentRuntime(streams, options);
     return runner.run({
         sessionId: randomUUID(),
         agent,
         userMessage: prompt,
-        metadata: options.runtime.provider === 'demo'
-            ? {
-                ...metadata,
-                executor: 'local-command',
-            }
-            : metadata,
+        metadata,
     });
 };
 export const printSessionSummary = (session, streams) => {
@@ -1077,6 +859,220 @@ export const printSessionSummary = (session, streams) => {
         writeLine(streams.stdout, `[${message.role}${nameSuffix}] ${content}`);
     }
 };
+const lastAssistantReply = (session) => {
+    for (let index = session.messages.length - 1; index >= 0; index -= 1) {
+        const message = session.messages[index];
+        if (message && message.role === 'assistant' && message.content.trim().length > 0) {
+            return message.content;
+        }
+    }
+    return '(no reply)';
+};
+const CHAT_HELP = [
+    '  /help   show this',
+    '  /exit   leave the chat (Ctrl+C and Ctrl+D work too)',
+    'Everything else is a message to your agent. The conversation persists',
+    'across turns, and facts they remember stick forever.',
+].join('\n');
+export const runChat = async (command, streams, env = {}) => {
+    const runtime = await resolveRuntimeConfig({
+        command: 'run',
+        prompt: '',
+        format: 'text',
+        events: false,
+        approvals: command.approvals,
+        ...(command.provider ? { provider: command.provider } : {}),
+        ...(command.model ? { model: command.model } : {}),
+        ...(command.baseUrl ? { baseUrl: command.baseUrl } : {}),
+        ...(command.soul ? { soul: command.soul } : {}),
+        ...(command.configPath ? { configPath: command.configPath } : {}),
+    }, env);
+    await warnOnCredentialOverride(runtime, streams, env);
+    // Interactive means the real terminal: an injected stdinStream is by
+    // definition not a TTY conversation, so it never gets prompts, ANSI
+    // styling, or a terminal readline wired to a stream that can't take it.
+    const interactive = env.setupInput === undefined
+        && env.stdinStream === undefined
+        && process.stdin.isTTY === true;
+    // Styling is for eyes: piped transcripts stay plain text.
+    const bold = (text) => (interactive ? `\u001b[1m${text}\u001b[0m` : text);
+    const dim = (text) => (interactive ? `\u001b[2m${text}\u001b[0m` : text);
+    const input = env.stdinStream ?? process.stdin;
+    const rl = interactive
+        ? createInterface({
+            input,
+            output: streams.stdout,
+            prompt: '\u001b[36myou ›\u001b[0m ',
+            terminal: true,
+        })
+        : createInterface({ input, terminal: false });
+    // One reader owns stdin. Every line lands in this queue, and whoever is
+    // waiting — the chat loop, or an approval question mid-turn — takes the
+    // next one. A second readline would race for the same bytes, and
+    // rl.question cannot be used while the interface is being iterated.
+    const lineQueue = [];
+    let inputClosed = false;
+    let pendingApproval;
+    let notifyLine;
+    rl.on('line', (rawLine) => {
+        if (pendingApproval) {
+            const resolve = pendingApproval;
+            pendingApproval = undefined;
+            resolve(rawLine);
+            return;
+        }
+        lineQueue.push(rawLine);
+        notifyLine?.();
+    });
+    rl.on('close', () => {
+        inputClosed = true;
+        if (pendingApproval) {
+            const resolve = pendingApproval;
+            pendingApproval = undefined;
+            resolve('');
+        }
+        notifyLine?.();
+    });
+    const nextLine = () => {
+        if (lineQueue.length > 0) {
+            return Promise.resolve(lineQueue.shift());
+        }
+        if (inputClosed) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve) => {
+            notifyLine = () => {
+                notifyLine = undefined;
+                resolve(lineQueue.shift());
+            };
+        });
+    };
+    // An approval consumes the next unconsumed line (typed live, or already
+    // queued from piped input). A closed stream denies instead of hanging.
+    const askApproval = (prompt) => {
+        streams.stderr.write(prompt);
+        const queued = lineQueue.shift();
+        if (queued !== undefined) {
+            return Promise.resolve(queued);
+        }
+        if (inputClosed) {
+            return Promise.resolve('');
+        }
+        return new Promise((resolve) => {
+            pendingApproval = resolve;
+        });
+    };
+    const { runner, agent, metadata } = await createAgentRuntime(streams, {
+        runtime,
+        approvals: command.approvals,
+        askApproval,
+        ...(command.maxTurns !== undefined ? { maxTurns: command.maxTurns } : {}),
+        env,
+        onEvent: (event) => {
+            if (command.events) {
+                const line = formatEvent(event);
+                if (line) {
+                    writeLine(streams.stdout, dim(line));
+                }
+                return;
+            }
+            // Quiet by default — just a whisper when the agent reaches for a tool.
+            if (event.type === 'tool.called') {
+                writeLine(streams.stdout, dim(`  · using ${event.call.toolName}`));
+            }
+            else if (event.type === 'tool.denied') {
+                writeLine(streams.stdout, dim(`  · ${event.call.toolName} denied`));
+            }
+        },
+    });
+    const modelLine = runtime.provider === 'demo'
+        ? 'demo (offline)'
+        : `${runtime.provider} · ${runtime.model}`;
+    if (interactive) {
+        streams.stdout.write('\u001b[2J\u001b[H');
+        for (const line of stratusHeaderLines()) {
+            writeLine(streams.stdout, line);
+        }
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, `Chatting with ${bold(agent.name)} — ${modelLine}.`);
+        writeLine(streams.stdout, dim('The conversation persists across turns. /exit to leave, /help for more.'));
+        writeLine(streams.stdout);
+    }
+    // Ctrl+C between turns closes the chat gracefully; mid-turn there is
+    // nothing to cancel in the kernel yet, so leave immediately instead of
+    // silently waiting out a slow provider call.
+    let turnInFlight = false;
+    rl.on('SIGINT', () => {
+        if (turnInFlight) {
+            writeLine(streams.stdout);
+            writeLine(streams.stdout, dim('Interrupted.'));
+            process.exit(130);
+        }
+        rl.close();
+    });
+    // One session for the whole sitting: the first message starts it, every
+    // later message resumes it — the same plumbing a channel will use to
+    // keep a thread alive.
+    let sessionId;
+    if (interactive) {
+        rl.prompt();
+    }
+    for (;;) {
+        const rawLine = await nextLine();
+        if (rawLine === undefined) {
+            break;
+        }
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            if (interactive) {
+                rl.prompt();
+            }
+            continue;
+        }
+        if (line === '/exit' || line === '/quit' || line === 'exit' || line === 'quit') {
+            break;
+        }
+        if (line === '/help') {
+            writeLine(streams.stdout, CHAT_HELP);
+            if (interactive) {
+                rl.prompt();
+            }
+            continue;
+        }
+        if (!interactive) {
+            writeLine(streams.stdout, `you › ${line}`);
+        }
+        try {
+            turnInFlight = true;
+            let session;
+            if (sessionId === undefined) {
+                const id = randomUUID();
+                sessionId = id;
+                session = await runner.run({ sessionId: id, agent, userMessage: line, metadata });
+            }
+            else {
+                session = await runner.resume({ sessionId, userMessage: line });
+            }
+            writeLine(streams.stdout, `${bold(`${agent.name} ›`)} ${lastAssistantReply(session)}`);
+        }
+        catch (error) {
+            writeLine(streams.stderr, `Error: ${error instanceof Error ? error.message : String(error)}`);
+            writeLine(streams.stdout, dim('(that turn failed — the conversation is still here, try again)'));
+        }
+        finally {
+            turnInFlight = false;
+        }
+        writeLine(streams.stdout);
+        if (interactive) {
+            rl.prompt();
+        }
+    }
+    rl.close();
+    if (interactive) {
+        writeLine(streams.stdout, dim(`Bye — ${agent.name} keeps what they remembered.`));
+    }
+    return 0;
+};
 const formatRuntimeBanner = (runtime) => {
     const soulSuffix = runtime.soul ? ` as ${runtime.soul.agent.name}` : '';
     if (runtime.provider === 'demo') {
@@ -1613,6 +1609,94 @@ const verifyProviderKey = async (provider, key, baseUrl, fetchImpl) => {
         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
+// on it (or on the ~9 MB of Slack SDKs underneath).
+const SLACK_API_ROOT = 'https://slack.com/api';
+const callSlack = async (method, token, fetchImpl) => {
+    if (typeof fetchImpl !== 'function') {
+        return { ok: false, verdict: { status: 'unreachable', detail: 'fetch is unavailable' } };
+    }
+    try {
+        const response = await fetchImpl(`${SLACK_API_ROOT}/${method}`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${token}`,
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+        });
+        if (!response.ok) {
+            return { ok: false, verdict: { status: 'unreachable', detail: `HTTP ${response.status}` } };
+        }
+        const body = await response.json();
+        if (body.ok === true) {
+            return { ok: true, body };
+        }
+        // Slack answers 200 with { ok: false, error } for bad credentials, so
+        // the error string — not the status — is what condemns a token.
+        return { ok: false, verdict: { status: 'rejected', detail: String(body.error ?? 'unknown error') } };
+    }
+    catch (error) {
+        return { ok: false, verdict: { status: 'unreachable', detail: error instanceof Error ? error.message : String(error) } };
+    }
+};
+/** Verifies a bot token and reports the identity it belongs to. */
+const verifySlackBotToken = async (token, fetchImpl) => {
+    const result = await callSlack('auth.test', token, fetchImpl);
+    if (!result.ok) {
+        return result.verdict;
+    }
+    return {
+        status: 'ok',
+        identity: {
+            ...(typeof result.body.user_id === 'string' ? { botUserId: result.body.user_id } : {}),
+            ...(typeof result.body.team === 'string' ? { teamName: result.body.team } : {}),
+            ...(typeof result.body.team_id === 'string' ? { teamId: result.body.team_id } : {}),
+        },
+    };
+};
+/**
+ * Verifies an app-level token by opening a Socket Mode URL. The URL is
+ * discarded — this only proves the token carries connections:write, which
+ * is the failure the daemon would otherwise hit at start time.
+ */
+const verifySlackAppToken = async (token, fetchImpl) => {
+    const result = await callSlack('apps.connections.open', token, fetchImpl);
+    return result.ok ? { status: 'ok', identity: {} } : result.verdict;
+};
+// Scopes and events the adapter needs. Kept in step with the manifest
+// shipped by @stratusagent/channel-slack (a test pins them together) so
+// setup can hand over a ready-to-paste manifest without depending on that
+// package being installed.
+const SLACK_BOT_SCOPES = [
+    'app_mentions:read',
+    'chat:write',
+    'files:write',
+    'im:history',
+    'im:read',
+    'im:write',
+    'users:read',
+];
+const SLACK_BOT_EVENTS = ['app_mention', 'message.im'];
+export const slackAppManifest = (agentName) => JSON.stringify({
+    display_information: {
+        name: agentName,
+        description: 'A Stratus agent',
+        background_color: '#1a1d21',
+    },
+    features: {
+        bot_user: { display_name: agentName, always_online: true },
+    },
+    oauth_config: { scopes: { bot: SLACK_BOT_SCOPES } },
+    settings: {
+        event_subscriptions: { bot_events: SLACK_BOT_EVENTS },
+        interactivity: { is_enabled: false },
+        org_deploy_enabled: false,
+        socket_mode_enabled: true,
+        token_rotation_enabled: false,
+    },
+}, null, 2);
 const DEFAULT_SOUL_STARTER = [
     'You are a helpful, warm generalist. Answer first, explain second, and',
     'keep replies short unless the question genuinely needs depth. Use',
@@ -1650,6 +1734,12 @@ export const runSetup = async (command, streams, env = {}) => {
     // A path passed via --config is not auto-discovered by `stratus run`, so
     // suggested commands must carry it explicitly.
     const runConfigFlag = command.configPath ? ` --config ${quoteShellArg(command.configPath)}` : '';
+    // Set once save() detects a project config shadowing the global one.
+    // Suggested commands must carry it too, or they read a different config
+    // than the one just written — for `serve` that means a different roster,
+    // and Slack apps stored here would be skipped as having no agent.
+    let shadowConfigFlag = '';
+    const serveCommand = () => `stratus serve${runConfigFlag}${shadowConfigFlag}`;
     // Seed from what is already configured, so re-running setup edits instead
     // of clobbering.
     let existing = {};
@@ -1702,6 +1792,24 @@ export const runSetup = async (command, streams, env = {}) => {
         ...(existing.fallbackBaseUrl ? { fallbackBaseUrl: existing.fallbackBaseUrl } : {}),
         credentials: await loadCredentials(env),
         credentialsDirty: false,
+        channels: await loadChannelCredentials(env),
+        channelsDirty: false,
+        // On by default: setup's whole promise is that you finish it and the
+        // agents are working. An always-on runtime you have to remember to
+        // start is not always-on, and every Slack app configured here stays
+        // silent until stratusd is up. An existing install keeps ITS login
+        // setting, though — rerunning setup and pressing save must not quietly
+        // undo a deliberate `service install --no-login`.
+        service: await (async () => {
+            const status = await readServiceStatus(serviceEnvFor(env)).catch(() => undefined);
+            // An unknown answer (a broken user bus, a timed-out query) must not
+            // read as "they chose --no-login" — that would disable a service on
+            // the next save because of a transient failure.
+            return {
+                install: true,
+                runAtLogin: status?.installed && status.runAtLogin !== undefined ? status.runAtLogin : true,
+            };
+        })(),
     };
     const prompter = createSetupPrompter(baseStreams, env, {
         header: stratusHeaderLines,
@@ -1768,6 +1876,13 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         return state.soulPath;
     };
+    const channelsSummary = () => {
+        const connected = Object.keys(state.channels.slack ?? {}).length;
+        if (connected === 0) {
+            return 'Slack: not connected';
+        }
+        return `Slack: ${connected} agent${connected === 1 ? '' : 's'} connected`;
+    };
     const storeCredential = (provider, credential) => {
         state.credentials[provider] = credential;
         state.credentialsDirty = true;
@@ -2287,18 +2402,267 @@ export const runSetup = async (command, streams, env = {}) => {
             writeLine(streams.stdout, 'You are not signed in yet — pick option 1 first (or export OPENAI_API_KEY).');
             return undefined;
         }
-        const fallback = buildTestFallback();
-        return {
-            provider: 'openai',
-            model,
-            baseUrl: boundUrl ?? state.baseUrl ?? DEFAULT_OPENAI_BASE_URL,
-            apiKey,
-            ...(state.systemPrompt ? { systemPrompt: state.systemPrompt } : {}),
-            ...(env.fetch ? { fetch: env.fetch } : {}),
-            ...(soul ? { soul } : {}),
-            ...(fallback ? { fallback } : {}),
+        const fallback = buildTestFallback();
+        return {
+            provider: 'openai',
+            model,
+            baseUrl: boundUrl ?? state.baseUrl ?? DEFAULT_OPENAI_BASE_URL,
+            apiKey,
+            ...(state.systemPrompt ? { systemPrompt: state.systemPrompt } : {}),
+            ...(env.fetch ? { fetch: env.fetch } : {}),
+            ...(soul ? { soul } : {}),
+            ...(fallback ? { fallback } : {}),
+        };
+    };
+    /**
+     * Walks an agent through connecting their own Slack app: show the
+     * manifest to paste, take both tokens, verify each against Slack, and
+     * store them under the agent's id. Tokens are keyed by a roster agent
+     * picked from a list rather than typed, so the id can never drift from
+     * the roster — the mismatch that otherwise surfaces only as a startup
+     * warning about an agent the gateway cannot find.
+     */
+    const connectSlackAgent = async (agentId, agentName) => {
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, `Create a Slack app for ${agentName}:`);
+        writeLine(streams.stdout, '  1. Open https://api.slack.com/apps → Create New App → From a manifest');
+        writeLine(streams.stdout, '  2. Pick your workspace, then paste this manifest:');
+        writeLine(streams.stdout);
+        for (const line of slackAppManifest(agentName).split('\n')) {
+            writeLine(streams.stdout, `    ${line}`);
+        }
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, '  3. Create the app, then Basic Information → App-Level Tokens →');
+        writeLine(streams.stdout, '     Generate a token with the connections:write scope (xapp-…)');
+        writeLine(streams.stdout, '  4. Install App → copy the Bot User OAuth Token (xoxb-…)');
+        writeLine(streams.stdout, `  5. Basic Information → Display Information → upload ${agentName}'s avatar`);
+        writeLine(streams.stdout);
+        const appToken = await prompter.askSecret('Paste the app-level token (xapp-…, Enter to cancel; input is hidden): ');
+        if (!appToken) {
+            writeLine(streams.stdout, 'Cancelled — nothing was saved.');
+            return;
+        }
+        if (!appToken.startsWith('xapp-')) {
+            writeLine(streams.stdout, '✗ That does not look like an app-level token (they start with xapp-). Nothing was saved.');
+            return;
+        }
+        const botToken = await prompter.askSecret('Paste the bot user OAuth token (xoxb-…, Enter to cancel; input is hidden): ');
+        if (!botToken) {
+            writeLine(streams.stdout, 'Cancelled — nothing was saved.');
+            return;
+        }
+        if (!botToken.startsWith('xoxb-')) {
+            writeLine(streams.stdout, '✗ That does not look like a bot token (they start with xoxb-). Nothing was saved.');
+            return;
+        }
+        writeLine(streams.stdout, 'Checking the tokens with Slack…');
+        const fetchImpl = env.fetch ?? globalThis.fetch;
+        const bot = await verifySlackBotToken(botToken, fetchImpl);
+        if (bot.status === 'rejected') {
+            writeLine(streams.stdout, `✗ Slack rejected the bot token (${bot.detail}). Nothing was saved — reinstall the app and copy the token again.`);
+            return;
+        }
+        const app = await verifySlackAppToken(appToken, fetchImpl);
+        if (app.status === 'rejected') {
+            writeLine(streams.stdout, `✗ Slack rejected the app-level token (${app.detail}). Nothing was saved — check it has the connections:write scope.`);
+            return;
+        }
+        const slack = { ...(state.channels.slack ?? {}) };
+        slack[agentId] = { appToken, botToken };
+        state.channels = { ...state.channels, slack };
+        state.channelsDirty = true;
+        if (bot.status === 'ok' && app.status === 'ok') {
+            const where = bot.identity.teamName ? ` in ${bot.identity.teamName}` : '';
+            const who = bot.identity.botUserId ? ` (bot ${bot.identity.botUserId})` : '';
+            writeLine(streams.stdout, `✓ Verified — ${agentName} is connected to Slack${where}${who}.`);
+        }
+        else {
+            // Unreachable is not a verdict on the tokens: save and let the
+            // daemon report on its first connection attempt.
+            const detail = bot.status === 'unreachable' ? bot.detail : app.detail;
+            writeLine(streams.stdout, `! Could not reach Slack to verify (${detail}). Saved the tokens anyway — \`${serveCommand()}\` will report on startup.`);
+        }
+    };
+    /**
+     * Every agent the gateway would dispatch to: the built-in Stratus
+     * agent, the ~/.stratus/agents roster, and the configured default soul,
+     * which `stratus setup` can point at a file anywhere. The gateway
+     * registers all three, so a Channels list built from the agents
+     * directory alone would hide agents Slack can perfectly well talk to.
+     * Reads state.soulPath rather than the saved config so a soul chosen
+     * earlier in this same setup session is already connectable.
+     */
+    const channelRoster = async () => {
+        const warnOnce = (message) => writeLine(streams.stderr, `Warning: ${message}.`);
+        // Seeded before the roster loads, exactly as loadRoster does it: a
+        // fresh install with no soul files still has an agent to put on
+        // Slack, and a roster file that declares id "stratus" cannot take the
+        // built-in's place — the gateway skips it, so offering it here would
+        // name an app after an agent that never receives the messages.
+        const entries = [{ soul: { agent: { ...DEFAULT_STRATUS_AGENT } } }];
+        // Mirror the gateway's loadRoster: two soul files declaring the same
+        // id are not two agents. Offering both would let someone create and
+        // name an app for the loser, which can never receive a message —
+        // Slack credentials are keyed by the shared id, and dispatch reaches
+        // the first sorted file.
+        for (const entry of await loadRosterSouls(env, warnOnce)) {
+            const clash = entries.find((seen) => seen.soul.agent.id === entry.soul.agent.id);
+            if (clash) {
+                warnOnce(`duplicate agent id ${entry.soul.agent.id} (${clash.path ?? 'built-in'} vs ${entry.path}); keeping the first`);
+                continue;
+            }
+            entries.push(entry);
+        }
+        // The soul a run resolves to, in resolveSoulPath's own order: an env
+        // override outranks the config value this setup session is editing.
+        // Listing the config soul while `stratus serve` registers the env one
+        // would store tokens against an id the adapter then skips.
+        const processEnv = readProcessEnv(env);
+        const envSoul = readNonEmptyString(processEnv.STRATUS_SOUL)
+            ?? readNonEmptyString(processEnv.STRATUSCLAW_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`);
+        }
+        const effectiveSoul = typeof envSoul === 'string' ? envSoul : state.soulPath;
+        if (!effectiveSoul) {
+            return entries;
+        }
+        const resolved = path.resolve(readWorkingDirectory(env), effectiveSoul);
+        if (entries.some((entry) => entry.path === resolved)) {
+            return entries;
+        }
+        try {
+            const soul = await loadSoulFile(resolved);
+            // An explicit id can collide with a roster file, or with the
+            // built-in. The gateway's defaultAgentId replaces the registered
+            // source whenever it is pathless (the built-in) or resolves to a
+            // different file, so the configured soul is the one Slack actually
+            // dispatches to — offering the namesake here would connect an app
+            // to a different agent than it names.
+            const collision = entries.findIndex((entry) => entry.soul.agent.id === soul.agent.id);
+            if (collision >= 0) {
+                entries.splice(collision, 1);
+            }
+            entries.unshift({ soul, path: resolved });
+        }
+        catch (error) {
+            warnOnce(`could not read the default soul ${resolved} (${error instanceof Error ? error.message : String(error)})`);
+        }
+        return entries;
+    };
+    const serviceSummary = () => {
+        if (!servicePlatform(serviceEnvFor(env))) {
+            return `not available on ${env.processEnv?.OSTYPE ?? process.platform} — run \`stratus serve\` yourself`;
+        }
+        if (!state.service.install) {
+            return 'off — start stratusd yourself with `stratus serve`';
+        }
+        return state.service.runAtLogin
+            ? 'stratusd runs after setup, and at every login'
+            : 'stratusd runs after setup, but not at login';
+    };
+    /**
+     * Whether the roster keeps answering once this terminal closes. On by
+     * default: an agent you have to remember to start is not always-on, and
+     * every Slack app configured above is silent until stratusd runs.
+     */
+    const chooseService = async () => {
+        if (!servicePlatform(serviceEnvFor(env))) {
+            writeLine(streams.stdout);
+            writeLine(streams.stdout, `Stratus has no service integration for ${process.platform} yet — run \`stratus serve\` yourself, or supervise it however you prefer.`);
+            await prompter.ask('Press Enter to return to the menu… ');
+            return;
+        }
+        const choice = await prompter.select('Always on — keep stratusd running in the background', [
+            'Run after setup, and start again at every login (recommended)',
+            'Run after setup, but do not start at login',
+            'Do not run it for me — I will start `stratus serve` myself',
+            'Back',
+        ], {
+            footnote: process.platform === 'darwin'
+                // Said here rather than left to be discovered after a reboot.
+                ? 'A LaunchAgent starts at login, not at power-on. For a machine that should recover unattended, turn on automatic login too.'
+                : 'A user service starts at login. `loginctl enable-linger` keeps it up on a machine you do not stay logged in to.',
+        });
+        if (choice.kind !== 'index' || choice.index === 3) {
+            return;
+        }
+        state.service = {
+            install: choice.index !== 2,
+            runAtLogin: choice.index === 0,
         };
     };
+    const chooseChannels = async () => {
+        while (true) {
+            const roster = await channelRoster();
+            const slack = state.channels.slack ?? {};
+            // The roster always holds at least the built-in agent, so there is
+            // no empty state to short-circuit on — and short-circuiting would
+            // strand orphaned tokens, which are only reachable from this list.
+            const options = roster.map((entry) => {
+                const id = entry.soul.agent.id;
+                const status = slack[id] ? '✓ connected' : '— not connected';
+                return `${entry.soul.agent.name} (${id})`.padEnd(34) + status;
+            });
+            // Orphans: tokens whose agent left the roster would otherwise be
+            // invisible here while still being loaded by `stratus serve`.
+            const orphans = Object.keys(slack).filter((id) => !roster.some((entry) => entry.soul.agent.id === id));
+            for (const id of orphans) {
+                options.push(`${id}`.padEnd(34) + '! tokens without a matching agent');
+            }
+            options.push('Back');
+            const choice = await prompter.select('Channels — Slack (one app per agent: its own name, avatar, and presence)', options, { footnote: `Run \`${serveCommand()}\` afterwards to bring the connected agents online.` });
+            if (choice.kind !== 'index' || choice.index === options.length - 1) {
+                return;
+            }
+            if (choice.index >= roster.length) {
+                // An orphaned entry — offer to clear it.
+                const orphanId = orphans[choice.index - roster.length];
+                if (!orphanId) {
+                    return;
+                }
+                const confirm = await prompter.select(`No agent with id ${orphanId} is in the roster.`, [
+                    'Remove these Slack tokens',
+                    'Keep them',
+                ]);
+                if (confirm.kind === 'index' && confirm.index === 0) {
+                    const next = { ...slack };
+                    delete next[orphanId];
+                    state.channels = { ...state.channels, slack: next };
+                    state.channelsDirty = true;
+                    writeLine(streams.stdout, `Removed the Slack tokens for ${orphanId}.`);
+                }
+                continue;
+            }
+            const entry = roster[choice.index];
+            if (!entry) {
+                return;
+            }
+            const agentId = entry.soul.agent.id;
+            const agentName = entry.soul.agent.name;
+            if (!slack[agentId]) {
+                await connectSlackAgent(agentId, agentName);
+                continue;
+            }
+            const action = await prompter.select(`${agentName} is connected to Slack.`, [
+                'Replace the tokens (re-run the app setup)',
+                'Disconnect from Slack (forget the tokens)',
+                'Back',
+            ]);
+            if (action.kind !== 'index' || action.index === 2) {
+                continue;
+            }
+            if (action.index === 0) {
+                await connectSlackAgent(agentId, agentName);
+                continue;
+            }
+            const next = { ...slack };
+            delete next[agentId];
+            state.channels = { ...state.channels, slack: next };
+            state.channelsDirty = true;
+            writeLine(streams.stdout, `${agentName} is no longer connected to Slack. The Slack app itself still exists — delete it at api.slack.com/apps if you are done with it.`);
+        }
+    };
     const testRun = async () => {
         const runtime = await buildTestRuntime();
         if (!runtime) {
@@ -2348,7 +2712,6 @@ export const runSetup = async (command, streams, env = {}) => {
         };
     };
     const save = async () => {
-        let shadowConfigFlag = '';
         const config = { provider: state.provider };
         if (state.provider !== 'demo') {
             config.model = state.model ?? defaultModelFor(state.provider);
@@ -2405,6 +2768,66 @@ export const runSetup = async (command, streams, env = {}) => {
             await saveCredentials(env, state.credentials);
             writeLine(streams.stdout, `Saved your sign-in to ${credentialsPath(env)} (readable only by you).`);
         }
+        if (state.channelsDirty) {
+            // Channel tokens live in their own namespace of the same file; the
+            // writers merge, so this never clobbers the provider sign-in above.
+            await saveChannelCredentials(env, state.channels);
+            const connected = Object.keys(state.channels.slack ?? {}).length;
+            writeLine(streams.stdout, connected > 0
+                ? `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)}.`);
+        }
+        // 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
+        // settings are already saved, and `stratus serve` still works by hand.
+        if (!state.service.install && servicePlatform(serviceEnvFor(env))) {
+            // Opting out has to actually take effect. Skipping the install would
+            // leave a unit from an earlier setup running and enabled at login,
+            // while the menu said "off" — still burning provider usage and still
+            // answering in Slack after an explicit opt-out.
+            const existing = await readServiceStatus(serviceEnvFor(env)).catch(() => undefined);
+            if (existing?.installed) {
+                // Removal deletes the unit file, so it can reject the same way the
+                // install can. Setup's settings are already written by this point;
+                // the optional service must not take the whole command down.
+                const removed = await uninstallService(serviceEnvFor(env)).catch((error) => ({
+                    ok: false,
+                    messages: [
+                        `Could not remove the always-on service: ${error instanceof Error ? error.message : String(error)}`,
+                        `${serviceUnitPath(serviceEnvFor(env))} is still in place — remove it by hand, or it will start again at login.`,
+                    ],
+                }));
+                for (const message of removed.messages) {
+                    writeLine(removed.ok ? streams.stdout : streams.stderr, message);
+                }
+            }
+        }
+        else if (state.service.install && servicePlatform(serviceEnvFor(env))) {
+            // The unit is pinned to the file setup just wrote. Its working
+            // directory is the home directory, so discovery from there would
+            // find a different config whenever setup was run with --config or
+            // STRATUS_CONFIG — the daemon would come up on another roster and
+            // leave the Slack apps configured above offline.
+            // installService writes files, so it can reject outright — an
+            // inaccessible ~/Library/LaunchAgents, a read-only home. Letting
+            // that escape would fail setup itself, after the config and
+            // credentials were already saved, when the always-on service is the
+            // one optional part of it.
+            const result = await installService(serviceEnvFor(env), {
+                runAtLogin: state.service.runAtLogin,
+                configPath,
+            }).catch((error) => ({
+                ok: false,
+                messages: [`Could not install the always-on service: ${error instanceof Error ? error.message : String(error)}`],
+            }));
+            for (const message of result.messages) {
+                writeLine(result.ok ? streams.stdout : streams.stderr, message);
+            }
+            if (!result.ok) {
+                writeLine(streams.stderr, `Setup is saved either way — start the daemon yourself with \`${serveCommand()}\`.`);
+            }
+        }
         writeLine(streams.stdout);
         // Exported STRATUS_* variables outrank the config file, so warn when one
         // would make `stratus run` behave differently from what was just saved.
@@ -2466,11 +2889,13 @@ export const runSetup = async (command, streams, env = {}) => {
                 `Providers            ${providersSummary()}`,
                 `Models               ${modelsSummary()}`,
                 `Agent                ${agentSummary()}`,
+                `Channels             ${channelsSummary()}`,
+                `Always on            ${serviceSummary()}`,
                 'Test run             say hello with the current settings',
                 'Save & finish',
             ]);
             // Backing out of the top level (Esc, or the input ending) saves.
-            if (choice.kind !== 'index' || choice.index === 4) {
+            if (choice.kind !== 'index' || choice.index === 6) {
                 break;
             }
             if (choice.index === 0) {
@@ -2483,6 +2908,12 @@ export const runSetup = async (command, streams, env = {}) => {
                 await chooseAgent();
             }
             else if (choice.index === 3) {
+                await chooseChannels();
+            }
+            else if (choice.index === 4) {
+                await chooseService();
+            }
+            else if (choice.index === 5) {
                 await testRun();
             }
         }
@@ -2493,6 +2924,663 @@ 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;
+    }
+    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));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    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);
+    });
+    if (command.format === 'json') {
+        writeLine(streams.stdout, JSON.stringify({
+            agents: listings.map(({ isDefault, ...rest }) => ({ ...rest, default: isDefault })),
+        }, null, 2));
+        return 0;
+    }
+    const describeRunsOn = (runsOn) => (runsOn.provider === 'demo' ? 'demo (offline)' : `${runsOn.provider}${runsOn.model ? ` · ${runsOn.model}` : ''}`);
+    writeLine(streams.stdout, 'Agents');
+    for (const agent of listings) {
+        const labels = [
+            ...(agent.isDefault ? ['default'] : []),
+            ...(agent.builtIn ? ['built-in'] : []),
+        ];
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, `  ${agent.name}${labels.length > 0 ? `  (${labels.join(', ')})` : ''}`);
+        writeLine(streams.stdout, `    id        ${agent.id}`);
+        if (agent.soulPath) {
+            writeLine(streams.stdout, `    soul      ${agent.soulPath}`);
+        }
+        writeLine(streams.stdout, `    runs on   ${agent.provider ? describeRunsOn(agent.runsOn) : `follows your setup — currently ${describeRunsOn(agent.runsOn)}`}`);
+        writeLine(streams.stdout, `    memory    ${agent.memories === 0 ? 'nothing yet' : `${agent.memories} remembered fact${agent.memories === 1 ? '' : 's'}`}`);
+        if (agent.persona) {
+            writeLine(streams.stdout, `    persona   ${agent.persona}`);
+        }
+        if (agent.avatar) {
+            writeLine(streams.stdout, `    avatar    ${agent.avatar}`);
+        }
+    }
+    writeLine(streams.stdout);
+    writeLine(streams.stdout, listings.length === 1
+        ? 'That is just the built-in default — create your own with: stratus agent new'
+        : 'Talk to the default with stratus run, or to anyone with stratus run --soul <file>.');
+    return 0;
+};
+/**
+ * `stratus doctor` — what a run would resolve to right now, and which file
+ * or variable decided each part. Every "why is it using X" question needs
+ * the precedence chain, and reading it out of the source is not something
+ * anyone should have to do.
+ */
+export const collectDoctorReport = async (command, warn, env = {}) => {
+    const processEnv = readProcessEnv(env);
+    const cwd = readWorkingDirectory(env);
+    const problems = [];
+    // 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.
+    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;
+    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 = [];
+    let unreadable;
+    for (const candidate of candidates) {
+        try {
+            await readFile(candidate.path, 'utf8');
+            present.push(candidate);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT') {
+                // resolveConfigLocation throws here rather than trying the next
+                // candidate, so discovery stops: a lower-priority file that a real
+                // run never reaches must not be reported as the config in use.
+                unreadable = candidate;
+                problems.push(`${candidate.path} exists but cannot be read (${error.message}). Every run fails here — discovery never reaches a lower-priority config.`);
+                break;
+            }
+            if (explicit) {
+                // Discovery treats a missing candidate as "try the next one", but
+                // an explicitly named config has no next one: a real run calls
+                // loadConfigFile on it and fails. Reporting built-in defaults here
+                // would describe a run that cannot happen, and hide the typo.
+                problems.push(`${candidate.path} does not exist, but ${candidate.label} names it — every run with this setting fails. `
+                    + 'Fix the path, or drop the setting to fall back to config discovery.');
+            }
+        }
+    }
+    const winner = unreadable ?? present[0];
+    const shadowed = unreadable ? [] : present.slice(1);
+    if (winner && shadowed.length > 0 && winner.label.startsWith('project')) {
+        problems.push(`${winner.path} outranks ${shadowed.map((entry) => entry.path).join(' and ')} for runs started in this directory. `
+            + 'Run from elsewhere, or pass --config to pick one explicitly.');
+    }
+    let fileConfig = {};
+    let configFatal = unreadable !== undefined;
+    if (winner && !unreadable) {
+        try {
+            fileConfig = await loadConfigFile(winner.path);
+        }
+        catch (error) {
+            // resolveRuntimeConfig propagates this — no run reaches provider or
+            // credential resolution, so presenting defaults as resolved settings
+            // would describe a run that cannot happen.
+            configFatal = true;
+            problems.push(`${winner.path} could not be parsed (${error.message}). Every run fails until it is fixed or removed.`);
+            warn(`ignoring unreadable config ${winner.path}`);
+        }
+    }
+    // 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;
+    };
+    /**
+     * The verdict comes from the resolver, not from a second copy of its
+     * rules. Everything below only *attributes* values to the file or
+     * variable that supplied them — which the resolver does not report —
+     * 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 soulValue = envSoul?.value ?? fileConfig.soul;
+    const soulSource = envSoul ? envSoul.name : (winner ? winner.path : '');
+    const soulPath = typeof soulValue === 'string' ? path.resolve(cwd, soulValue) : undefined;
+    // Loaded here for ATTRIBUTION only — the soul's frontmatter is what
+    // explains a provider nobody wrote in a config file. Whether a run works
+    // is still the resolver's verdict below.
+    const soul = soulPath ? await loadSoulFile(soulPath).catch(() => undefined) : undefined;
+    let resolved;
+    if (!configFatal) {
+        try {
+            resolved = await resolveStateRuntimeConfig(command.configPath ? { configPath: command.configPath } : {}, env);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            problems.push(`No run can start: ${message}`);
+            if (soulPath && /soul/i.test(message)) {
+                // Worth saying explicitly: a soul that fails to load is fatal, not
+                // a quiet downgrade to the built-in agent.
+                problems.push(`Every run fails until ${soulPath} is fixed or the soul setting is removed — the built-in agent is not substituted.`);
+            }
+        }
+    }
+    const envProviderPick = envPick('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER');
+    const providerSource = envProviderPick
+        ? envProviderPick.name
+        : soul?.provider
+            ? `${soulPath} (soul frontmatter)`
+            : fileConfig.provider
+                ? (winner?.path ?? 'config')
+                : 'built-in default — nothing set a provider';
+    // When resolution fails the intended provider is still worth reporting:
+    // "why is it anthropic" is exactly the question, and the problems below
+    // already say no run can start.
+    const intendedProvider = envProviderPick?.value ?? soul?.provider ?? fileConfig.provider ?? 'demo';
+    const provider = resolved
+        ? { value: resolved.provider, source: providerSource }
+        : { value: `${intendedProvider} (unreachable)`, source: providerSource };
+    if (provider.value === 'demo') {
+        // Setup writes the config file, which is the LOWEST precedence of the
+        // three — so when an env var or a soul chose demo, "run setup" is
+        // advice that changes nothing and leaves every run on demo.
+        const fix = envProviderPick
+            ? `Unset ${envProviderPick.name}; it outranks both your config and any soul.`
+            : soul?.provider === 'demo'
+                ? `Change or remove the provider pin in ${soulPath}; a soul outranks the config file.`
+                : fileConfig.provider === 'demo'
+                    ? `Change "provider" in ${winner?.path}, or run \`stratus setup\` → Providers.`
+                    : 'Run `stratus setup` → Providers and sign in, then Save & finish.';
+        problems.push(`Provider is the offline demo model, so replies are canned. ${fix}`);
+    }
+    let model;
+    if (resolved && resolved.provider !== 'demo') {
+        const envModel = envPick('STRATUS_MODEL', 'STRATUSCLAW_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;
+        const configModelApplies = (fileConfig.provider ?? 'openai') === resolved.provider;
+        model = {
+            value: resolved.model,
+            source: envModel
+                ? envModel.name
+                : soulModelApplies && soul?.model === resolved.model
+                    ? `${soulPath} (soul frontmatter)`
+                    : configModelApplies && fileConfig.model === resolved.model
+                        ? (winner?.path ?? 'config')
+                        : 'built-in default for this provider',
+        };
+    }
+    const credentials = await loadCredentials(env);
+    const signIns = [];
+    const usedKeyEnvVar = resolved && resolved.provider !== 'demo' ? resolved.apiKeyEnvVar : undefined;
+    const usesAuthToken = resolved?.provider === 'anthropic' && resolved.authToken !== undefined;
+    const fallback = resolved && resolved.provider !== 'demo' ? resolved.fallback : undefined;
+    for (const target of ['anthropic', 'openai']) {
+        const stored = credentials[target];
+        const label = stored?.type === 'oauth_token' ? 'Claude subscription (Pro/Max)' : 'API key';
+        const isDefault = resolved?.provider === target;
+        const isFallback = fallback?.provider === target;
+        // A provider no resolved run consults is reported, never diagnosed:
+        // flagging an override on a credential nothing reads is a false alarm.
+        if (!isDefault && !isFallback) {
+            signIns.push({
+                provider: target,
+                status: stored
+                    ? `${label} (unused — ${resolved ? resolved.provider : 'nothing'} serves your runs)`
+                    : 'not signed in',
+            });
+            continue;
+        }
+        const envVar = isDefault ? usedKeyEnvVar : (target === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY');
+        const viaEnv = isDefault
+            ? usedKeyEnvVar !== undefined
+            : fallback?.apiKey !== undefined && fallback.apiKey === readNonEmptyString(processEnv[String(envVar)]);
+        const where = isDefault ? 'runs are' : 'fallback runs are';
+        if (stored && viaEnv) {
+            signIns.push({ provider: target, status: `${label}, overridden by ${envVar} in your environment` });
+            // The costly case: an env key silently demotes a subscription to
+            // per-token billing, and nothing in a normal run says so.
+            problems.push(stored.type === 'oauth_token'
+                ? `${envVar} in your environment outranks your saved ${target} subscription sign-in, so ${where} billed per token instead of through your plan. Unset it (check your shell profile) to use the subscription.`
+                : `${envVar} in your environment outranks your saved ${target} sign-in. Unset it to use the one \`stratus setup\` stored.`);
+            continue;
+        }
+        if (viaEnv) {
+            signIns.push({ provider: target, status: `using ${envVar} from your environment` });
+            continue;
+        }
+        if (stored) {
+            signIns.push({ provider: target, status: isDefault && usesAuthToken ? `${label} — runs go through the Claude Code runtime` : label });
+            continue;
+        }
+        signIns.push({ provider: target, status: 'not signed in' });
+    }
+    // A fallback the resolver dropped is the quiet failure: the config still
+    // names one, but a failing primary has nothing to retry on.
+    if (fileConfig.fallbackModel !== undefined && resolved && resolved.provider !== 'demo' && !fallback) {
+        problems.push(`A fallback model (${fileConfig.fallbackModel}) is configured but could not be resolved — usually no sign-in for its provider, or an endpoint its saved key is not sent to. `
+            + 'A failing primary model has nothing to retry on.');
+    }
+    const channels = await loadChannelCredentials(env);
+    const slackAgents = Object.keys(channels.slack ?? {}).sort();
+    const slackPackageInstalled = (await loadSlackAdapter()) !== undefined;
+    if (slackAgents.length > 0 && !slackPackageInstalled) {
+        problems.push(`Slack tokens are stored for ${slackAgents.length} agent(s) but @stratusagent/channel-slack is not installed, so \`stratus serve\` skips them. `
+            + 'Install it with: npm install -g @stratusagent/channel-slack');
+    }
+    let rosterCount = 0;
+    try {
+        rosterCount = (await readdir(agentsDirPath(env))).filter((file) => file.endsWith('.md')).length;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    // Tokens keyed to an agent the roster no longer has are loaded and
+    // skipped on every start, silently.
+    const rosterIds = new Set((await loadRosterSouls(env, warn)).map((entry) => entry.soul.agent.id));
+    rosterIds.add(DEFAULT_STRATUS_AGENT.id);
+    if (soul) {
+        rosterIds.add(soul.agent.id);
+    }
+    const orphans = slackAgents.filter((id) => !rosterIds.has(id));
+    if (orphans.length > 0) {
+        problems.push(`Slack tokens are stored for ${orphans.join(', ')}, which no agent matches — \`stratus serve\` skips them. `
+            + 'Clear them from `stratus setup` → Channels.');
+    }
+    return {
+        ...(winner ? { configInUse: winner.path } : {}),
+        configShadowed: shadowed.map((entry) => entry.path),
+        provider,
+        ...(model ? { model } : {}),
+        ...(soulPath ? { soul: { value: soulPath, source: soulSource } } : {}),
+        ...(soul ? { agent: `${soul.agent.name} (${soul.agent.id})` } : {}),
+        ...(fallback ? { fallback: { provider: fallback.provider, model: fallback.model } } : {}),
+        signIns,
+        slackAgents,
+        slackPackageInstalled,
+        rosterCount,
+        problems,
+    };
+};
+export const runDoctor = async (command, streams, env = {}) => {
+    const report = await collectDoctorReport(command, (message) => {
+        writeLine(streams.stderr, `Warning: ${message}.`);
+    }, env);
+    if (command.format === 'json') {
+        writeLine(streams.stdout, JSON.stringify(report, null, 2));
+        return report.problems.length > 0 ? 1 : 0;
+    }
+    const field = (label, setting) => {
+        if (!setting) {
+            return;
+        }
+        writeLine(streams.stdout, `  ${label.padEnd(10)}${setting.value}`);
+        writeLine(streams.stdout, `  ${''.padEnd(10)}from ${setting.source}`);
+    };
+    writeLine(streams.stdout, 'Stratus Agent — what a run would use right now');
+    writeLine(streams.stdout);
+    field('provider', report.provider);
+    field('model', report.model);
+    field('soul', report.soul);
+    if (report.agent) {
+        writeLine(streams.stdout, `  ${'agent'.padEnd(10)}${report.agent}`);
+    }
+    else if (report.soul) {
+        // A soul is configured but did not load — saying "built-in" here would
+        // describe a run that cannot happen.
+        writeLine(streams.stdout, `  ${'agent'.padEnd(10)}unresolved — the configured soul could not be read`);
+    }
+    else {
+        writeLine(streams.stdout, `  ${'agent'.padEnd(10)}${DEFAULT_STRATUS_AGENT.name} (built-in — no soul configured)`);
+    }
+    writeLine(streams.stdout);
+    writeLine(streams.stdout, 'Files');
+    writeLine(streams.stdout, `  config    ${report.configInUse ?? 'none found — built-in defaults apply'}`);
+    for (const shadowedPath of report.configShadowed) {
+        writeLine(streams.stdout, `            (${shadowedPath} exists but is outranked)`);
+    }
+    writeLine(streams.stdout, `  agents    ${report.rosterCount} soul file${report.rosterCount === 1 ? '' : 's'}`);
+    if (report.fallback) {
+        writeLine(streams.stdout, `  ${'fallback'.padEnd(10)}${report.fallback.provider} · ${report.fallback.model}`);
+        writeLine(streams.stdout, `  ${''.padEnd(10)}used when the default model errors mid-run`);
+    }
+    writeLine(streams.stdout);
+    writeLine(streams.stdout, 'Sign-ins');
+    for (const entry of report.signIns) {
+        writeLine(streams.stdout, `  ${entry.provider.padEnd(10)}${entry.status}`);
+    }
+    writeLine(streams.stdout);
+    writeLine(streams.stdout, 'Channels');
+    writeLine(streams.stdout, `  slack     ${report.slackAgents.length === 0
+        ? 'no agents connected'
+        : `${report.slackAgents.length} connected (${report.slackAgents.join(', ')})`}`);
+    writeLine(streams.stdout, `            @stratusagent/channel-slack ${report.slackPackageInstalled ? 'installed' : 'not installed'}`);
+    writeLine(streams.stdout);
+    if (report.problems.length === 0) {
+        writeLine(streams.stdout, 'No problems found.');
+        return 0;
+    }
+    writeLine(streams.stdout, `${report.problems.length} problem${report.problems.length === 1 ? '' : 's'} found:`);
+    for (const problem of report.problems) {
+        writeLine(streams.stdout, `  ! ${problem}`);
+    }
+    return 1;
+};
+/**
+ * `stratus logs` — the daemon's structured log, filtered. `serve` streams
+ * to its own stdout, which is gone the moment it runs under a service
+ * manager; this reads the file it also writes, from any terminal.
+ */
+export const runLogs = async (command, streams, env = {}) => {
+    const dir = logsDirPath(env);
+    const filter = {
+        ...(command.agentId ? { agentId: command.agentId } : {}),
+        ...(command.sessionId ? { sessionId: command.sessionId } : {}),
+    };
+    const emit = (record) => {
+        writeLine(streams.stdout, command.format === 'json' ? JSON.stringify(record) : formatLogRecord(record));
+    };
+    // Captured BEFORE the backlog is read: the daemon keeps writing while a
+    // large backlog prints, and a follower that takes its offset afterwards
+    // skips everything written in between — permanently.
+    const followFrom = command.follow ? await currentLogPosition(dir) : undefined;
+    // Bounded by the same offset the follower resumes from: without it, a
+    // record written between the two reads is printed by the backlog and
+    // then again by the stream.
+    const recent = await readRecentRecords(dir, command.limit, filter, followFrom);
+    for (const record of recent) {
+        emit(record);
+    }
+    if (!command.follow) {
+        if (recent.length === 0 && command.format === 'text') {
+            writeLine(streams.stdout, `No log records yet in ${dir}. Start the daemon with \`stratus serve\`.`);
+        }
+        return 0;
+    }
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    env.shutdownSignal?.addEventListener('abort', stop, { once: true });
+    if (env.shutdownSignal?.aborted) {
+        stop();
+    }
+    try {
+        await tailLog({
+            dir,
+            filter,
+            ...(followFrom !== undefined ? { startPosition: followFrom } : {}),
+            signal: controller.signal,
+            onRecord: emit,
+        });
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+    }
+    return 0;
+};
+/** Builds the service view of the CLI environment (home, exec paths, runner). */
+const serviceEnvFor = (env) => ({
+    ...(env.homeDir !== undefined ? { homeDir: env.homeDir } : {}),
+    cwd: readWorkingDirectory(env),
+    ...(env.serviceRunner !== undefined ? { run: env.serviceRunner } : {}),
+});
+/**
+ * A credential that exists only in this shell cannot reach the daemon: a
+ * service manager starts with its own environment and never sources a
+ * 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 }];
+    for (const entry of await loadRosterSouls(env, () => { })) {
+        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;
+};
+/**
+ * `stratus service` — run the daemon under launchd or systemd, so it
+ * survives logout, crashes, and reboots. `serve` itself stays a plain
+ * foreground process; this only tells the platform how to keep it up.
+ */
+export const runService = async (command, streams, env = {}) => {
+    const serviceEnv = serviceEnvFor(env);
+    if (command.action === 'status') {
+        const status = await readServiceStatus(serviceEnv);
+        if (!status) {
+            writeLine(streams.stdout, `No service manager for ${process.platform}. Run \`stratus serve\` yourself.`);
+            return 1;
+        }
+        writeLine(streams.stdout, `stratusd  ${status.running ? 'running' : status.installed ? 'installed, not running' : 'not installed'}`);
+        writeLine(streams.stdout, `  manager   ${status.platform}`);
+        writeLine(streams.stdout, `  unit      ${status.unitPath}`);
+        if (status.detail) {
+            writeLine(streams.stdout, `  note      ${status.detail}`);
+        }
+        if (status.installed) {
+            writeLine(streams.stdout, `  at login  ${status.runAtLogin === undefined
+                ? 'unknown — the service manager did not answer'
+                : status.runAtLogin ? 'yes' : 'no'}`);
+        }
+        writeLine(streams.stdout, status.installed
+            ? '  logs      stratus logs -f'
+            : '  install   stratus service install');
+        return status.running ? 0 : 1;
+    }
+    // A service manager passes none of this shell's environment on, so a
+    // config selected by STRATUS_CONFIG has to be baked into the unit
+    // exactly as --config is. Without it the daemon rediscovers from the
+    // 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);
+    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
+        // loop. Better to refuse now, while there is someone reading stderr.
+        // Without an explicit selection the unit carries no --config flag and
+        // discovers from its working directory — the same directory this is
+        // running in — so the discovered file has to be validated too, not
+        // just an explicitly named one.
+        let configToCheck;
+        if (selectedConfig) {
+            configToCheck = path.resolve(readWorkingDirectory(env), String(selectedConfig));
+        }
+        else {
+            try {
+                configToCheck = (await resolveConfigLocation({}, env))?.path;
+            }
+            catch (error) {
+                // Discovery throws when a candidate exists but cannot be read.
+                // Treating that as "no config" would install a daemon that hits
+                // the same error on its first dispatch.
+                writeLine(streams.stderr, `Not installing: ${error instanceof Error ? error.message : String(error)}`);
+                writeLine(streams.stderr, 'The daemon would fail the same way on startup. Fix the file, or move it aside.');
+                return 1;
+            }
+        }
+        if (configToCheck) {
+            try {
+                await loadConfigFile(configToCheck);
+            }
+            catch (error) {
+                writeLine(streams.stderr, `Not installing: ${configToCheck} cannot be used (${error instanceof Error ? error.message : String(error)}).`);
+                writeLine(streams.stderr, 'The daemon would exit on startup and be restarted in a loop. Fix the file, or move it aside.');
+                return 1;
+            }
+        }
+    }
+    const action = command.action === 'install'
+        ? installService(serviceEnv, {
+            ...(command.runAtLogin === false ? { runAtLogin: false } : {}),
+            // Absolute: resolved against the directory the install ran in.
+            ...(selectedConfig ? { configPath: path.resolve(readWorkingDirectory(env), String(selectedConfig)) } : {}),
+        })
+        : command.action === 'uninstall'
+            ? uninstallService(serviceEnv)
+            : command.action === 'start'
+                ? startService(serviceEnv)
+                : stopService(serviceEnv);
+    const result = await action;
+    for (const message of result.messages) {
+        writeLine(result.ok ? streams.stdout : streams.stderr, message);
+    }
+    return result.ok ? 0 : 1;
+};
 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
@@ -2524,18 +3612,11 @@ export const runAgentNew = async (command, streams, env = {}) => {
             // at all: the soul keeps following the machine's configuration
             // instead of demanding credentials nothing has signed in for.
             const processEnv = readProcessEnv(env);
-            const configLocation = await resolveConfigLocation({}, env);
             // Creating an agent must not be blocked by a broken config — it only
             // feeds the soul's provider/model hint, so fall back to defaults.
-            let activeConfig = {};
-            if (configLocation) {
-                try {
-                    activeConfig = await loadConfigFile(configLocation.path);
-                }
-                catch (error) {
-                    writeLine(streams.stdout, `Note: ignoring unreadable config ${configLocation.path} (${error instanceof Error ? error.message : String(error)}).`);
-                }
-            }
+            const { location: configLocation, config: activeConfig } = await discoverActiveConfig(env, (message) => {
+                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
@@ -2667,6 +3748,271 @@ export const runDashboard = async (command, streams, env = {}) => {
     await handle.close();
     return 0;
 };
+/**
+ * Loads the optional Slack channel package, or undefined when it is not
+ * installed. Only that package being absent is tolerated: an adapter that
+ * fails to load for any other reason (a broken install, a bad transitive
+ * dependency) surfaces rather than silently disabling Slack for a daemon
+ * 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 {
+        return undefined;
+    }
+    // Resolvable: any failure from here is a real problem with the
+    // installed package, and surfaces.
+    return (await import('@stratusagent/channel-slack')).createSlackChannelAdapter;
+};
+/**
+ * `stratus serve` — run the gateway (stratusd) in the foreground: load the
+ * roster, accept dispatches, print events, and drain cleanly on SIGTERM,
+ * SIGINT, or the injected shutdown signal.
+ */
+export const runServe = async (command, streams, env = {}) => {
+    // First, before anything that can throw. A broken install makes the
+    // gateway import below fail, the manager restarts, and the CLI's error
+    // and help text append to the redirect file again — the crash loop this
+    // bounding exists for. Running it after the import would skip exactly
+    // that case.
+    if (command.logToFile !== false) {
+        await truncateRedirectLogs(logsDirPath(env)).catch(() => undefined);
+    }
+    // Loaded lazily: the gateway pulls in node:sqlite, which every other CLI
+    // command neither needs nor should pay for (Node still prints an
+    // experimental warning for it).
+    const { createGateway } = await import('@stratusagent/gateway');
+    // Under a service manager the daemon's stdout is gone, so everything it
+    // says is also written to ~/.stratus/logs — that file is what `stratus
+    // logs` reads, and the only record of an overnight run.
+    const logWriter = command.logToFile === false
+        ? undefined
+        : createLogWriter({
+            dir: logsDirPath(env),
+            onError: (error) => writeLine(streams.stderr, `Warning: could not write the log file (${error instanceof Error ? error.message : String(error)}); continuing.`),
+        });
+    const log = (line) => {
+        writeLine(streams.stdout, line);
+        void logWriter?.write({ ts: new Date().toISOString(), level: 'info', msg: line });
+    };
+    const warn = (line) => {
+        writeLine(streams.stderr, `Warning: ${line}`);
+        void logWriter?.write({ ts: new Date().toISOString(), level: 'warn', msg: line });
+    };
+    // Agents with stored Slack tokens go live in Slack automatically — the
+    // tokens are gateway infrastructure secrets in the channels namespace of
+    // ~/.stratus/credentials.json (see @stratusagent/channel-slack's README
+    // for the 2-minute per-agent app setup).
+    const channelCredentials = await loadChannelCredentials(env);
+    const slackAgents = Object.entries(channelCredentials.slack ?? {});
+    const channels = [];
+    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
+        // missing one degrades like a broken app does — the daemon serves
+        // every other channel — with an actionable line instead of a
+        // module-not-found stack.
+        const adapter = await loadSlackAdapter();
+        if (adapter) {
+            channels.push(adapter({
+                agents: slackAgents.map(([agentId, tokens]) => ({
+                    agentId,
+                    appToken: tokens.appToken,
+                    botToken: tokens.botToken,
+                })),
+                log,
+                warn,
+            }));
+        }
+        else {
+            warn(`Slack tokens are stored for ${slackAgents.length} agent(s), but @stratusagent/channel-slack is not installed. `
+                + 'Run `npm install -g @stratusagent/channel-slack` to bring them online; starting without the Slack channel.');
+        }
+    }
+    // A daemon is the costliest place for a silently demoted subscription:
+    // every dispatch for as long as it runs, with nobody watching. The
+    // gateway resolves each agent's soul independently on dispatch, so an
+    // agent pinning anthropic can pick up an environment key even when the
+    // daemon's own default is openai — checking only the default selection
+    // would miss exactly the agent that is being billed. Each distinct
+    // selection is resolved once here, and duplicate warnings are collapsed
+    // so a ten-agent roster does not print ten identical lines.
+    {
+        const warned = new Set();
+        const collect = (line) => {
+            if (warned.has(line)) {
+                return;
+            }
+            warned.add(line);
+            // Through `warn`, not straight to stderr: under a service manager
+            // stderr is gone, and a cost warning that only exists there is
+            // invisible in exactly the deployment it matters for. `warn` adds
+            // its own prefix, so the one already on the line comes off.
+            warn(line.replace(/^Warning: /, ''));
+        };
+        const captured = {
+            stdout: { write: () => true },
+            stderr: { write: (chunk) => { collect(chunk.replace(/\n$/, '')); return true; } },
+        };
+        // A pinned soul does not merely add a provider — the gateway DEMOTES
+        // the daemon-wide defaults it outranks, including STRATUS_PROVIDER, so
+        // each served runtime is resolved the way a dispatch resolves it.
+        for (const served of await servedRuntimes(env, command.configPath)) {
+            await warnOnCredentialOverride(served.runtime, captured, served.env);
+        }
+    }
+    // The daemon had no policy at all: createGateway falls back to
+    // AllowAllApprovalPolicy, so every tool call from every agent
+    // auto-approved, indefinitely, with nobody watching. That was survivable
+    // while `serve` was something you ran in a terminal you were sitting at;
+    // it is not, now that setup installs it under launchd by default.
+    //
+    // Headless is the only honest mode here until a turn can park and ask
+    // through a channel: there is no terminal behind a service manager, so
+    // `safe` runs and anything riskier is refused rather than waved through.
+    // Every refusal is logged — an unattended denial that appears nowhere
+    // reads like an agent that decided not to bother.
+    const approvals = createPermissionPolicy({
+        mode: 'headless',
+        onDecision: (decision) => {
+            if (decision.allowed) {
+                return;
+            }
+            warn(`${decision.agentId}: ${decision.reason} (session ${decision.sessionId})`);
+        },
+    });
+    const gateway = createGateway({
+        env,
+        approvals,
+        ...(command.configPath ? { selection: { configPath: command.configPath } } : {}),
+        ...(command.idleTimeoutMs !== undefined ? { idleTimeoutMs: command.idleTimeoutMs } : {}),
+        ...(channels.length > 0 ? { channels } : {}),
+        log,
+        warn,
+    });
+    if (command.events) {
+        gateway.bus.subscribe((event) => {
+            const line = formatEvent(event);
+            if (line) {
+                writeLine(streams.stdout, line);
+            }
+        });
+    }
+    if (logWriter) {
+        // Only session.created carries the agent id, so it seeds a map the
+        // later events in that session read from. A session resumed after a
+        // restart never re-creates, so an unmapped id falls back to the
+        // durable store — which is exactly the case where attribution matters.
+        const agentBySession = new Map();
+        // EventBus.emit awaits its subscribers, and a streaming provider awaits
+        // the delta sink — so anything awaited here lands on the critical path
+        // of every streamed token. This handler is deliberately synchronous:
+        // provider.delta is dropped outright (it carries no detail worth
+        // keeping, one record per token), the timestamp is taken now, and the
+        // write is queued without awaiting it.
+        gateway.bus.subscribe((event) => {
+            if (event.type === 'provider.delta') {
+                return;
+            }
+            const ts = new Date().toISOString();
+            if (event.type === 'session.created') {
+                agentBySession.set(event.sessionId, event.agentId);
+            }
+            const detail = eventDetail(event);
+            const base = {
+                ts,
+                level: 'event',
+                event: event.type,
+                sessionId: event.sessionId,
+                ...(detail ? { detail } : {}),
+            };
+            const known = agentBySession.get(event.sessionId);
+            if (known) {
+                void logWriter.write({ ...base, agentId: known });
+            }
+            else {
+                // A session resumed after a restart never re-creates, so its agent
+                // is only in the store. That lookup is deferred off this path; the
+                // timestamp above keeps ordering honest.
+                void gateway.store.get(event.sessionId)
+                    .then((session) => {
+                    const agentId = session?.agent.id;
+                    if (agentId) {
+                        agentBySession.set(event.sessionId, agentId);
+                    }
+                    return logWriter.write({ ...base, ...(agentId ? { agentId } : {}) });
+                })
+                    .catch(() => logWriter.write(base));
+            }
+            if (event.type === 'session.completed' || event.type === 'session.failed') {
+                agentBySession.delete(event.sessionId);
+            }
+        });
+    }
+    await gateway.start();
+    writeLine(streams.stdout, 'Press Ctrl+C to stop.');
+    // And periodically, for a long-running daemon that warns steadily
+    // without ever writing enough records to rotate. Unref'd, so it never
+    // holds the process open. Armed only once the daemon is actually
+    // serving: every step above can throw, and runServe is an exported
+    // function as much as a process entry point — in a host that survives
+    // the failure, a timer armed before the throw would outlive the call
+    // and go on truncating that environment's redirect logs. The finally
+    // below takes it down on every other exit path.
+    let redirectTimer;
+    if (logWriter) {
+        redirectTimer = setInterval(() => void truncateRedirectLogs(logsDirPath(env)), 5 * 60_000);
+        redirectTimer.unref?.();
+    }
+    try {
+        // Hold the event loop open until a shutdown request, then drain: new
+        // dispatches are refused while in-flight turns finish.
+        await new Promise((resolve) => {
+            const keepAlive = setInterval(() => { }, 2_147_000_000);
+            let settled = false;
+            const shutdown = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearInterval(keepAlive);
+                process.off('SIGTERM', shutdown);
+                process.off('SIGINT', shutdown);
+                resolve();
+            };
+            process.once('SIGTERM', shutdown);
+            process.once('SIGINT', shutdown);
+            if (env.shutdownSignal?.aborted) {
+                shutdown();
+            }
+            else {
+                env.shutdownSignal?.addEventListener('abort', shutdown, { once: true });
+            }
+        });
+        writeLine(streams.stdout, 'Stopping — draining in-flight turns.');
+        await gateway.stop();
+        return 0;
+    }
+    finally {
+        if (redirectTimer) {
+            clearInterval(redirectTimer);
+        }
+        // Writes are queued and dropped on the hot path so logging never sits
+        // on a streamed token. That makes the tail of the log the part most
+        // likely to be lost — and the tail is the shutdown reason, the last
+        // warning, the line explaining a restart.
+        await logWriter?.flush();
+    }
+};
 export const runCli = async ({ argv, streams = process, env = {} }) => {
     try {
         const resolvedEnv = argv.includes('--stdin') && env.stdin === undefined
@@ -2680,16 +4026,40 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
             writeLine(streams.stdout, HELP_TEXT);
             return 0;
         }
+        // Every handler is awaited, never bare-returned: a bare `return
+        // promise` inside try/catch settles the async function before the
+        // catch can see it, so a command that fails at runtime — a gateway
+        // that cannot open its store, a missing credential — would escape as
+        // a raw rejection instead of the error line and exit code below.
         if (command.command === 'agent-new') {
-            return runAgentNew(command, streams, resolvedEnv);
+            return await runAgentNew(command, streams, resolvedEnv);
+        }
+        if (command.command === 'agents') {
+            return await runAgents(command, streams, resolvedEnv);
+        }
+        if (command.command === 'doctor') {
+            return await runDoctor(command, streams, resolvedEnv);
+        }
+        if (command.command === 'logs') {
+            return await runLogs(command, streams, resolvedEnv);
+        }
+        if (command.command === 'service') {
+            return await runService(command, streams, resolvedEnv);
+        }
+        if (command.command === 'chat') {
+            return await runChat(command, streams, resolvedEnv);
         }
         if (command.command === 'setup') {
-            return runSetup(command, streams, resolvedEnv);
+            return await runSetup(command, streams, resolvedEnv);
         }
         if (command.command === 'dashboard') {
-            return runDashboard(command, streams, resolvedEnv);
+            return await runDashboard(command, streams, resolvedEnv);
+        }
+        if (command.command === 'serve') {
+            return await runServe(command, streams, resolvedEnv);
         }
         const runtime = await resolveRuntimeConfig(command, resolvedEnv);
+        await warnOnCredentialOverride(runtime, streams, resolvedEnv);
         if (command.format === 'text') {
             writeLine(streams.stdout, formatRuntimeBanner(runtime));
         }