@stratusagent/cli 0.2.5 → 0.4.0

package/dist/index.js

@@ -7,16 +7,62 @@ import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
 import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
+import { createPermissionPolicy } from '@stratusagent/permissions';
 import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
-import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-import { agentsDirPath, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, readWorkingDirectory, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveRuntimeConfig as resolveStateRuntimeConfig, saveCredentials, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { agentIdWithSuffix, createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
+import { agentsDirPath, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, loadRosterSouls, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, resolveConfiguredSoul, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveCredentials, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { 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';
-export const CLI_VERSION = '0.2.5';
+// Kept in step with this package's own version by a test, because it is a
+// second copy of a number nobody re-reads: it is drawn in the setup header
+// and served from the dashboard's /api/status, so drift here misreports the
+// running build rather than failing anything.
+export const CLI_VERSION = '0.4.0';
 const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
 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:
@@ -31,24 +77,44 @@ Usage:
   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, --config <path>)
+                   (--idle-timeout <seconds>, --approvals <headless|remote>,
+                   --no-events, --no-log-file, --config <path>); everything it
+                   says is also written to ~/.stratus/logs, which
+                   "stratus logs" reads
+  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
 
@@ -67,7 +133,10 @@ Options:
   --config         Config file path (run: load settings from it, setup: write it)
   --format         Output format: text or json (default: text)
   --no-events      Hide event-by-event progress lines in text mode
-  --approvals      Tool approval mode: always, ask, or never (default: always)
+  --approvals      run/chat: tool approval mode — always, ask, or never (default: always)
+                   serve: how the daemon reaches a human — headless (refuse every
+                   gated call) or remote (ask in Slack). Default headless, or
+                   the config file's "approvals.mode"
   --max-turns      Maximum provider turns per run (default: 8)
   --port           Dashboard port, defaults to an open local port
   --host           Dashboard host (default: 127.0.0.1)
@@ -172,10 +241,23 @@ export const parseCommand = (argv, env = {}) => {
                 index += 1;
                 continue;
             }
+            if (token === '--approvals') {
+                const value = readOptionValue(rest, index, '--approvals');
+                if (value !== 'headless' && value !== 'remote') {
+                    throw new Error(`Unsupported approvals mode: ${value}. Use headless or remote.`);
+                }
+                parsed.approvals = value;
+                index += 1;
+                continue;
+            }
             if (token === '--no-events') {
                 parsed.events = false;
                 continue;
             }
+            if (token === '--no-log-file') {
+                parsed.logToFile = false;
+                continue;
+            }
             throw new Error(`Unknown option: ${token}`);
         }
         return parsed;
@@ -265,6 +347,129 @@ export const parseCommand = (argv, env = {}) => {
         }
         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') {
@@ -464,6 +669,10 @@ export const formatEvent = (event) => {
             return `• tool.completed ${event.result.toolName} ok=${String(event.result.ok)}`;
         case 'tool.denied':
             return `• tool.denied ${event.call.toolName}`;
+        case 'tool.approval-requested':
+            return `• tool.approval-requested ${event.call.toolName} (${event.risk}) for ${event.agentId}`;
+        case 'tool.approval-resolved':
+            return `• tool.approval-resolved ${event.answer} (${event.reason})${event.actor ? ` by ${event.actor}` : ''}`;
         case 'session.completed':
             return `• session.completed ${event.sessionId}`;
         case 'session.failed':
@@ -472,9 +681,92 @@ export const formatEvent = (event) => {
             return null;
     }
 };
-// Kept with its historical CLI signature: a parsed run command is a
-// RuntimeSelection plus CLI-only fields the resolver ignores.
+/**
+ * The fields worth keeping per event type. Tool inputs and message text
+ * are deliberately excluded: the log is a trace of what happened, not a
+ * second copy of the transcript.
+ *
+ * The approval pair is the one place the trace carries a person's id, and
+ * it earns it: `always` widens what an agent may do unattended for the rest
+ * of the session, and "who decided that" is unanswerable afterwards from
+ * anything else. The refusal path is warned about by `onDecision`, but an
+ * *approval* produces no warning at all — without these two records a
+ * granted permission leaves no trace whatsoever. Still no tool input: what
+ * was asked is here, what it was asked with is not.
+ */
+const eventDetail = (event) => {
+    switch (event.type) {
+        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 'tool.approval-requested':
+            return { tool: event.call.toolName, risk: event.risk, requestId: event.requestId };
+        case 'tool.approval-resolved':
+            return {
+                requestId: event.requestId,
+                answer: event.answer,
+                reason: event.reason,
+                ...(event.actor ? { actor: event.actor } : {}),
+            };
+        case 'session.failed':
+            return { error: event.error };
+        default:
+            return undefined;
+    }
+};
+/**
+ * Kept with its historical CLI signature: a parsed run command is a
+ * RuntimeSelection plus CLI-only fields the resolver ignores.
+ *
+ * Those fields are *permitted*, not required. Demanding a whole
+ * `ParsedRunCommand` made the type claim the resolver cared about
+ * `approvals`, `format`, and `events` — it reads none of them — so every
+ * caller with a selection in hand had to invent values to get past it.
+ */
 export const resolveRuntimeConfig = (command, env = {}) => resolveStateRuntimeConfig(command, env);
+/**
+ * A saved subscription sign-in silently demoted to per-token billing is the
+ * 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;
+    }
+    const stored = (await loadCredentials(env)).anthropic;
+    if (stored?.type !== 'oauth_token') {
+        return;
+    }
+    // The resolver records the variable that actually won — guessing it here
+    // would name the wrong one whenever a custom apiKeyEnv or the legacy
+    // STRATUSCLAW_ prefix supplied the key, sending the reader to unset
+    // something that was never the cause.
+    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 fallbackVar = runtime.fallback?.provider === 'anthropic'
+        && runtime.fallback.apiKey !== undefined
+        && readNonEmptyString(processEnv.ANTHROPIC_API_KEY) === runtime.fallback.apiKey
+        ? 'ANTHROPIC_API_KEY'
+        : undefined;
+    const culprit = primary ?? fallbackVar;
+    if (!culprit) {
+        return;
+    }
+    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, ask) => {
     if (mode === 'always') {
         return new AllowAllApprovalPolicy();
@@ -636,6 +928,7 @@ export const runChat = async (command, streams, env = {}) => {
         ...(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.
@@ -1357,6 +1650,99 @@ 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 },
+        // Required for remote approval: Allow / Always allow / Deny arrive as
+        // block_actions, and Slack delivers none of them to an app that has
+        // interactivity switched off. Enabled unconditionally rather than per
+        // mode — an app is created once, and discovering months later that the
+        // buttons do nothing means editing the manifest and reinstalling.
+        interactivity: { is_enabled: true },
+        org_deploy_enabled: false,
+        socket_mode_enabled: true,
+        token_rotation_enabled: false,
+    },
+}, 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',
@@ -1374,6 +1760,104 @@ const KNOWN_CLAUDE_MODELS = [
     'claude-opus-4-6',
     'claude-sonnet-4-6',
 ];
+/**
+ * The ids a newly created soul must not claim: every id the served roster
+ * holds, which is three things and not one directory.
+ *
+ * - **What the roster files declare.** A filename is not an id: a soul at
+ *   `renamed.md` may declare `id: ava`, so `ava.md` being free proves
+ *   nothing — and since a duplicate refuses the whole roster, writing one
+ *   would hand back an agent whose daemon cannot start.
+ * - **The configured default soul**, which the daemon registers whether or
+ *   not its file lives in the agents directory. It wins a same-id contest
+ *   with a roster file — `defaultAgentId` replaces the source when the
+ *   path differs — so a new agent sharing its id is not refused, it is
+ *   shadowed: created, then undispatchable by id or from Slack, with
+ *   nothing saying so.
+ * - **The reserved `stratus`**, since a roster soul claiming it is skipped
+ *   at load, so writing one creates an agent that silently never appears.
+ *
+ * The two readable sources fail **independently**, and what they return is
+ * what they know rather than all-or-nothing. A configured soul that is
+ * missing or mid-edit does not stop the daemon serving the roster, so it
+ * must not discard the roster's claims either: collapsing both to unknown
+ * would let this command write the very duplicate that refuses the roster
+ * it could have read. `unread` names what could not be answered, so the
+ * caller can say which check did not run instead of implying none did.
+ */
+const declaredAgentIds = async (env) => {
+    const [roster, configured] = await Promise.allSettled([
+        loadRosterSouls(env, () => { }),
+        // Empty selection: the soul a run started here would resolve, by the
+        // same precedence the daemon uses — never a second reading of it.
+        resolveConfiguredSoul({}, env),
+    ]);
+    const ids = new Set([DEFAULT_STRATUS_AGENT.id]);
+    const unread = [];
+    if (roster.status === 'fulfilled') {
+        for (const entry of roster.value) {
+            ids.add(entry.soul.agent.id);
+        }
+    }
+    else {
+        unread.push('the roster');
+    }
+    if (configured.status === 'fulfilled') {
+        if (configured.value) {
+            ids.add(configured.value.soul.agent.id);
+        }
+    }
+    else {
+        unread.push('the configured default soul');
+    }
+    return { ids, unread };
+};
+/**
+ * Write a new soul under an id nothing else holds, and return the agent
+ * that got written.
+ *
+ * The name stays theirs, but the id — the soul filename, the memory key,
+ * the credential scope — must be unique: the suggestion pool is small, so
+ * a repeat name would otherwise share an earlier agent's memory. Two
+ * claims have to fail here, and only one of them is a filename:
+ *
+ * - An id another soul declares, whatever that soul is called on disk.
+ *   Since a duplicate refuses the whole roster, writing one would leave a
+ *   daemon that will not start — created by the command meant to help.
+ * - The path itself, via `wx`, which makes the claim atomic against a
+ *   concurrent writer that the roster read above cannot see.
+ *
+ * On either, the id takes a fresh suffix and we try again — through the
+ * shared bound, since appending a suffix to a maxed-out base would build
+ * an id the validator refuses, turning a collision into a crash.
+ */
+const claimSoulFile = async (env, input, render, note) => {
+    const { ids: taken, unread } = await declaredAgentIds(env);
+    if (unread.length > 0) {
+        note(`Note: could not read ${unread.join(' or ')}, so this id was not checked against the ids it declares.`);
+    }
+    let agent = defineAgent({ ...(input.name ? { name: input.name } : {}), instructions: input.instructions });
+    const baseId = agent.id;
+    for (;;) {
+        const soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
+        if (!taken.has(agent.id)) {
+            try {
+                await writeFile(soulPath, render(agent), { flag: 'wx' });
+                return { agent, soulPath };
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST') {
+                    throw error;
+                }
+            }
+        }
+        agent = defineAgent({
+            id: agentIdWithSuffix(baseId, randomUUID().slice(0, 4)),
+            ...(input.name ? { name: input.name } : { name: agent.name }),
+            instructions: input.instructions,
+        });
+    }
+};
 export const runSetup = async (command, streams, env = {}) => {
     const cwd = readWorkingDirectory(env);
     const processEnv = readProcessEnv(env);
@@ -1394,6 +1878,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 = {};
@@ -1446,6 +1936,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,
@@ -1512,6 +2020,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;
@@ -1927,17 +2442,13 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         const name = await prompter.ask('Name your agent (Enter to have one generated): ');
         const instructions = await prompter.ask('Describe their personality in a sentence or two (Enter for a starter you can edit later): ');
-        const agent = defineAgent({
-            ...(name ? { name } : {}),
-            instructions: instructions || DEFAULT_SOUL_STARTER,
-        });
-        const soul = formatSoul({
-            agent,
-            ...(state.provider !== 'demo' ? { provider: state.provider, model: state.model ?? defaultModelFor(state.provider) } : {}),
-        });
-        const soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-        await mkdir(path.dirname(soulPath), { recursive: true });
-        await writeFile(soulPath, soul);
+        const persona = instructions || DEFAULT_SOUL_STARTER;
+        const pin = state.provider !== 'demo'
+            ? { provider: state.provider, model: state.model ?? defaultModelFor(state.provider) }
+            : {};
+        await mkdir(agentsDirPath(env), { recursive: true });
+        const claimed = await claimSoulFile(env, { ...(name ? { name } : {}), instructions: persona }, (agent) => formatSoul({ agent, ...pin }), (message) => writeLine(streams.stdout, message));
+        const { agent, soulPath } = claimed;
         state.soulPath = soulPath;
         writeLine(streams.stdout, `Say hello to ${agent.name}.`);
         writeLine(streams.stdout, `Their soul lives at ${soulPath} — edit it any time to change how they talk.`);
@@ -2043,6 +2554,279 @@ export const runSetup = async (command, streams, env = {}) => {
             ...(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 } } }];
+        // loadRosterSouls refuses a roster whose files collide, and drops the
+        // ones claiming the reserved built-in id, so what comes back here is
+        // already unambiguous.
+        let rosterSouls = [];
+        let rosterLoaded = true;
+        try {
+            rosterSouls = await loadRosterSouls(env, warnOnce);
+        }
+        catch (error) {
+            // A roster that cannot say who its agents are cannot have channels
+            // configured for them — but the rest of setup (providers, models,
+            // sign-ins) still works, so this reports and moves on rather than
+            // taking the whole command down.
+            rosterLoaded = false;
+            warnOnce(error instanceof Error ? error.message : String(error));
+            // Nothing is offered, not merely the colliding pair. A roster that
+            // refuses to load fails `createGateway.start()` outright, so no
+            // agent is servable — not the built-in seeded above, and not the
+            // configured soul resolved below (which can itself BE one of the
+            // colliding files). Listing any of them invites connecting a Slack
+            // app to an agent the daemon cannot bring online, and connecting an
+            // app is the expensive half of that mistake.
+            return { entries: [], loaded: false };
+        }
+        entries.push(...rosterSouls);
+        // The soul a run resolves to, in resolveSoulPath's own order: an env
+        // override outranks the config value this setup session is editing.
+        // Listing the config soul while `stratus serve` registers the env one
+        // 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, loaded: rosterLoaded };
+        }
+        const resolved = path.resolve(readWorkingDirectory(env), effectiveSoul);
+        if (entries.some((entry) => entry.path === resolved)) {
+            return { entries, loaded: rosterLoaded };
+        }
+        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, loaded: rosterLoaded };
+    };
+    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 { entries: roster, loaded: rosterLoaded } = await channelRoster();
+            const slack = state.channels.slack ?? {};
+            // The roster always holds at least the built-in agent, so there is
+            // no empty state to short-circuit on — and short-circuiting would
+            // 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`.
+            //
+            // Only when the roster actually loaded. "No agent has this id" is a
+            // claim about the roster, and a roster that refused to load cannot
+            // support it — every stored token would look orphaned, and this list
+            // offers to DELETE them. Losing a working agent's Slack credentials
+            // because a different pair of files collided is a far worse outcome
+            // than leaving a real orphan on screen for one run.
+            const orphans = rosterLoaded
+                ? Object.keys(slack).filter((id) => !roster.some((entry) => entry.soul.agent.id === id))
+                : [];
+            if (!rosterLoaded) {
+                writeLine(streams.stderr, 'Warning: no agents are offered while the roster is unreadable — the daemon cannot start either. Fix the roster first.');
+            }
+            for (const id of orphans) {
+                options.push(`${id}`.padEnd(34) + '! tokens without a matching agent');
+            }
+            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) {
@@ -2092,7 +2876,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);
@@ -2149,6 +2932,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.
@@ -2210,11 +3053,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) {
@@ -2227,6 +3072,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();
             }
         }
@@ -2381,6 +3232,610 @@ export const runAgents = async (command, streams, env = {}) => {
         : '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.
+    let rosterEntries = [];
+    let rosterLoaded = true;
+    try {
+        rosterEntries = await loadRosterSouls(env, warn);
+    }
+    catch (error) {
+        // Doctor exists to name problems, so a roster it cannot load is a
+        // finding to report — not an exception that replaces the report.
+        rosterLoaded = false;
+        problems.push(error instanceof Error ? error.message : String(error));
+    }
+    const rosterIds = new Set(rosterEntries.map((entry) => entry.soul.agent.id));
+    rosterIds.add(DEFAULT_STRATUS_AGENT.id);
+    if (soul) {
+        rosterIds.add(soul.agent.id);
+    }
+    // Only against a roster that actually loaded. "No agent has this id" is
+    // a claim about the roster, and a refused one cannot support it — every
+    // stored token would be reported as orphaned, and this advises clearing
+    // them. Advice is not deletion, but an operator who follows it loses the
+    // same credentials by hand.
+    const orphans = rosterLoaded ? slackAgents.filter((id) => !rosterIds.has(id)) : [];
+    if (orphans.length > 0) {
+        problems.push(`Slack tokens are stored for ${orphans.join(', ')}, which no agent matches — \`stratus serve\` skips them. `
+            + 'Clear them from `stratus setup` → Channels.');
+    }
+    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 }];
+    // A roster that will not load is the gateway's to refuse, with a better
+    // message than this preflight could give — so it checks what it can and
+    // leaves the failing to start().
+    const rosterForRuntimes = await loadRosterSouls(env, () => { }).catch(() => []);
+    for (const entry of rosterForRuntimes) {
+        const normalized = applySoulPins(entry.soul, {}, env, context);
+        passes.push({ selection: normalized.selection, env: normalized.env });
+    }
+    const resolved = [];
+    for (const pass of passes) {
+        // A runtime that cannot resolve is the gateway's to report, per
+        // dispatch and with far better context than a startup pass has.
+        const runtime = await resolveStateRuntimeConfig({ ...pass.selection, ...(configPath ? { configPath } : {}) }, pass.env).catch(() => undefined);
+        if (runtime) {
+            resolved.push({ runtime, env: pass.env });
+        }
+    }
+    return resolved;
+};
+/**
+ * The daemon's `approvals` block, from the config file the daemon itself
+ * would load. Discovery goes through the shared resolver rather than
+ * reading ~/.stratus/config.json directly: `--config` and STRATUS_CONFIG
+ * both move it, and a second copy of that precedence would resolve the
+ * approver set from a file the gateway is not running on.
+ *
+ * **Only from a trusted location.** An auto-discovered project-local
+ * `stratus.config.json` outranks the global one and can be checked into any
+ * repository — which is why stored credentials are already never combined
+ * with an endpoint it selects. This block is the same kind of boundary and
+ * a sharper one: it names the people who may authorize an agent's gated
+ * tool calls, and it would do so through Slack tokens the user configured
+ * globally. A cloned repo must not be able to appoint its own approver, so
+ * an untrusted config's approvals are ignored — loudly, since silently
+ * dropping the block someone is looking at is its own kind of wrong.
+ *
+ * An unreadable config degrades to headless with a warning, matching how
+ * every other consumer treats one: refusing to start would take the whole
+ * fleet down over a policy block that may not even be present.
+ */
+const loadServeApprovals = async (env, configPath, warn) => {
+    try {
+        const location = await resolveConfigLocation(configPath ? { configPath } : {}, env);
+        if (!location) {
+            return {};
+        }
+        const approvals = (await loadConfigFile(location.path)).approvals;
+        if (!approvals) {
+            return {};
+        }
+        if (!location.trusted) {
+            warn(`ignoring the approvals config in ${location.path}: a project-local config cannot decide who may approve `
+                + 'this daemon\'s tool calls. Move it to ~/.stratus/config.json, or pass it with --config.');
+            return {};
+        }
+        return approvals;
+    }
+    catch (error) {
+        warn(`ignoring the approvals config (${error instanceof Error ? error.message : String(error)}); refusing gated calls`);
+        return {};
+    }
+};
+/**
+ * One line naming who can actually answer, so a remote daemon does not look
+ * configured when it is not. Two ways it can be hollow, and they fail
+ * differently, so they read differently:
+ *
+ * - No channel running at all (no Slack tokens, or the optional package is
+ *   not installed) — nothing renders the request, so the turn waits out the
+ *   whole timeout before being denied. That is the bad one, and the only
+ *   place it is visible is here, at startup.
+ * - A channel is running but an agent has no approvers — the adapter denies
+ *   that agent's requests on arrival, which is at least prompt.
+ *
+ * `agentIds` is therefore the agents that can actually be *asked*, not
+ * every agent with tokens on disk.
+ */
+const describeApprovers = (approvals, agentIds) => {
+    if (agentIds.length === 0) {
+        return 'but no channel is running to ask through, so gated calls will wait out the approval timeout and then be denied';
+    }
+    const covered = agentIds.filter((agentId) => (resolveAgentApprovals(approvals, agentId).slackApprovers ?? []).length > 0);
+    if (covered.length === 0) {
+        return 'but no approvers are configured, so every gated call is denied on arrival';
+    }
+    const uncovered = agentIds.filter((agentId) => !covered.includes(agentId));
+    return uncovered.length === 0
+        ? `approvers set for ${covered.join(', ')}`
+        : `approvers set for ${covered.join(', ')}; none for ${uncovered.join(', ')}, whose calls are denied on arrival`;
+};
+/**
+ * `stratus service` — run the daemon under launchd or systemd, so it
+ * 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
@@ -2404,7 +3859,6 @@ export const runAgentNew = async (command, streams, env = {}) => {
             const name = (await prompter.ask('Choose your name: ', { prefill: suggested })) || suggested;
             const instructions = await prompter.ask('Describe their personality (Enter for a starter you can edit later): ', ...(command.instructions ? [{ prefill: command.instructions }] : []));
             const persona = instructions || DEFAULT_SOUL_STARTER;
-            let agent = defineAgent({ name, instructions: persona });
             // Frontmatter pins what a run from this directory would actually use:
             // env vars outrank the active config file (project-local or explicit
             // first, global otherwise), and no provider anywhere falls back to
@@ -2429,27 +3883,9 @@ export const runAgentNew = async (command, streams, env = {}) => {
                 ?? (configModelApplies ? activeConfig.model : undefined)
                 ?? (soulProvider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
             const soulPin = soulProvider !== 'demo' ? { provider: soulProvider, model: soulModel } : {};
-            // The name stays theirs, but the id — the soul filename and the
-            // memory key — must be unique: the suggestion pool is small, so a
-            // repeat name would otherwise silently overwrite an earlier agent's
-            // soul and share their memory. 'wx' makes each claim atomic; on a
-            // collision the id gets a fresh suffix and we try again.
             await mkdir(agentsDirPath(env), { recursive: true });
-            const baseId = agent.id;
-            let soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-            for (;;) {
-                try {
-                    await writeFile(soulPath, formatSoul({ agent, ...soulPin }), { flag: 'wx' });
-                    break;
-                }
-                catch (error) {
-                    if (error.code !== 'EEXIST') {
-                        throw error;
-                    }
-                    agent = defineAgent({ id: `${baseId}-${randomUUID().slice(0, 4)}`, name, instructions: persona });
-                    soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
-                }
-            }
+            const claimed = await claimSoulFile(env, { name, instructions: persona }, (candidate) => formatSoul({ agent: candidate, ...soulPin }), (message) => writeLine(streams.stdout, message));
+            const { agent, soulPath } = claimed;
             const makeDefault = await prompter.select(`Make ${agent.name} your default agent?`, [
                 'Yes — every stratus run talks to them',
                 'Not now',
@@ -2579,16 +4015,44 @@ const loadSlackAdapter = async () => {
  * 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');
-    const log = (line) => writeLine(streams.stdout, line);
-    const warn = (line) => writeLine(streams.stderr, `Warning: ${line}`);
+    // 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).
+    // The approval policy and the Slack approver sets come from the same
+    // config block, resolved once here: the daemon must not answer "who can
+    // approve this" differently from "is anyone being asked at all".
+    const approvalsConfig = await loadServeApprovals(env, command.configPath, warn);
+    const approvalMode = command.approvals ?? approvalsConfig.mode ?? 'headless';
     const channelCredentials = await loadChannelCredentials(env);
     const slackAgents = Object.entries(channelCredentials.slack ?? {});
     const channels = [];
@@ -2601,11 +4065,16 @@ export const runServe = async (command, streams, env = {}) => {
         const adapter = await loadSlackAdapter();
         if (adapter) {
             channels.push(adapter({
-                agents: slackAgents.map(([agentId, tokens]) => ({
-                    agentId,
-                    appToken: tokens.appToken,
-                    botToken: tokens.botToken,
-                })),
+                agents: slackAgents.map(([agentId, tokens]) => {
+                    const route = resolveAgentApprovals(approvalsConfig, agentId);
+                    return {
+                        agentId,
+                        appToken: tokens.appToken,
+                        botToken: tokens.botToken,
+                        ...(route.slackApprovers ? { approvers: route.slackApprovers } : {}),
+                        ...(route.slackChannel ? { approvalChannel: route.slackChannel } : {}),
+                    };
+                }),
                 log,
                 warn,
             }));
@@ -2615,8 +4084,74 @@ export const runServe = async (command, streams, env = {}) => {
                 + '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.
+    //
+    // There is no terminal behind a service manager, so the choice is
+    // between refusing every gated call (`headless`) and parking the turn to
+    // ask through a channel (`remote`). Headless stays the default: a daemon
+    // that starts waiting on people who were never told they are on the hook
+    // hangs turns instead of refusing them. Every refusal is logged — an
+    // unattended denial that appears nowhere reads like an agent that decided
+    // not to bother.
+    const onDecision = (decision) => {
+        if (decision.allowed) {
+            return;
+        }
+        warn(`${decision.agentId}: ${decision.reason} (session ${decision.sessionId})`);
+    };
+    // A factory, not a policy: remote mode parks turns on a transport the
+    // gateway owns, so the policy cannot exist until the gateway is building
+    // it. Headless takes the same path so there is one construction site.
+    const approvals = (transport) => createPermissionPolicy(approvalMode === 'remote'
+        ? { mode: 'remote', request: transport.request, onDecision }
+        : { mode: 'headless', onDecision });
+    if (approvalMode === 'remote') {
+        // Only agents whose channel actually came up can be asked: tokens on
+        // disk with the Slack package missing means nothing renders the
+        // request, and the turn discovers that by hanging.
+        const askable = channels.length > 0 ? slackAgents.map(([agentId]) => agentId) : [];
+        log(`approvals: remote — gated calls are parked and asked in Slack (${describeApprovers(approvalsConfig, askable)})`);
+    }
     const gateway = createGateway({
         env,
+        approvals,
+        ...(approvalsConfig.timeoutMs !== undefined ? { approvalTimeoutMs: approvalsConfig.timeoutMs } : {}),
         ...(command.configPath ? { selection: { configPath: command.configPath } } : {}),
         ...(command.idleTimeoutMs !== undefined ? { idleTimeoutMs: command.idleTimeoutMs } : {}),
         ...(channels.length > 0 ? { channels } : {}),
@@ -2631,35 +4166,126 @@ export const runServe = async (command, streams, env = {}) => {
             }
         });
     }
-    await gateway.start();
-    writeLine(streams.stdout, 'Press Ctrl+C to stop.');
-    // 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) {
+    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;
             }
-            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 });
+            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();
+    // The roster is only known once the gateway has loaded it, and in remote
+    // mode an agent no channel can ask for is the quietest failure this
+    // feature has: its gated calls park with nobody rendering them and wait
+    // out the whole timeout before being denied. No channel can detect this
+    // on its own — a request is a broadcast, and no adapter knows whether
+    // another one is about to answer — so it is reported here, where the
+    // roster and the channel list are both in view.
+    if (approvalMode === 'remote') {
+        const askable = new Set(channels.length > 0 ? slackAgents.map(([agentId]) => agentId) : []);
+        const unreachable = gateway.agents().map((agent) => agent.id).filter((id) => !askable.has(id));
+        if (unreachable.length > 0) {
+            warn(`no channel can ask for ${unreachable.join(', ')}, so their gated calls will wait out the `
+                + 'approval timeout and then be denied. Connect a Slack app for them, or run with --approvals headless.');
         }
-    });
-    writeLine(streams.stdout, 'Stopping — draining in-flight turns.');
-    await gateway.stop();
-    return 0;
+    }
+    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 {
@@ -2674,25 +4300,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 runAgents(command, streams, resolvedEnv);
+            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 runChat(command, streams, resolvedEnv);
+            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 runServe(command, streams, resolvedEnv);
+            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));
         }