@stratusagent/cli 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,16 +1,23 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { readFile, writeFile } from 'node:fs/promises';
+import { appendFile, chmod, mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { once } from 'node:events';
+import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
 import { createLocalCommandExecutor, defineLocalCommandTool, } from '@stratusagent/executor-local';
 import { createOpenAICompatibleProvider, createProviderResponseBuilder, defineProvider, } from '@stratusagent/providers';
-import { defineAgent } from '@stratusagent/agents';
+import { createAnthropicProvider, DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
+import { createRememberTool, defineAgent, formatSoul, parseSoul, } from '@stratusagent/agents';
 const DEFAULT_CONFIG_FILENAME = 'stratus.config.json';
 const LEGACY_CONFIG_FILENAME = 'stratusclaw.config.json';
+const STRATUS_HOME_DIRNAME = '.stratus';
+const GLOBAL_CONFIG_FILENAME = 'config.json';
+const CREDENTIALS_FILENAME = 'credentials.json';
+const AGENTS_DIRNAME = 'agents';
+const DEFAULT_ANTHROPIC_BASE_URL = 'https://api.anthropic.com';
 const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
 const DEFAULT_OPENAI_MODEL = 'gpt-4.1-mini';
 const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
@@ -21,6 +28,8 @@ Usage:
   stratus setup
   stratus run --prompt "Use the demo tool"
   stratus run "Say hello"
+  ANTHROPIC_API_KEY=... stratus run --provider anthropic "Say hello"
+  stratus run --soul ./examples/souls/ava.md "Say hello"
   echo "Use the echo tool" | stratus run --stdin
   STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run "Say hello"
   stratus run --config ./stratus.config.json --provider openai "Say hello"
@@ -28,7 +37,10 @@ Usage:
   stratus dashboard --port 4123 --host 0.0.0.0 --no-open
 
 Commands:
-  setup            Interactive walkthrough that writes stratus.config.json
+  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)
   run              Execute one local Stratus Agent session
   agent new        Create an agent identity (generates a human-ish name + avatar theme)
   dashboard        Start the local Stratus Agent dashboard and open it in your browser
@@ -37,14 +49,15 @@ Commands:
 Agent options:
   --name           Agent name (omit to have one generated)
   --instructions   The agent's persona/instructions
-  --format         Output format for agent new: text or json
+  --format         Output format for agent new: text, json, or soul (a ready-to-edit soul file)
 
 Options:
   --prompt, -p     Prompt to send to the local agent loop
   --stdin          Read the prompt from stdin
-  --provider       Provider to use: demo or openai
-  --model          Model name for real providers (default: gpt-4.1-mini)
-  --base-url       Override the OpenAI-compatible API base URL
+  --provider       Provider to use: anthropic, openai, or demo
+  --model          Model name for real providers (anthropic default: ${DEFAULT_ANTHROPIC_MODEL}, openai default: gpt-4.1-mini)
+  --base-url       Override the provider API base URL
+  --soul           Run as the agent defined by a soul file (markdown + frontmatter, see examples/souls)
   --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
@@ -56,8 +69,14 @@ Options:
   --help, -h       Show this help message
 
 Config file:
-  The CLI looks for ./stratus.config.json by default, or a path from --config / STRATUS_CONFIG.
+  The CLI looks for ./stratus.config.json first, then a path from --config / STRATUS_CONFIG,
+  then the global ~/.stratus/config.json written by \`stratus setup\`.
+  A "soul" key (or STRATUS_SOUL) points at a soul file so every run uses that agent.
   Legacy STRATUSCLAW_* env vars and stratusclaw.config.json are still supported for compatibility.
+
+Soul files:
+  A soul file is markdown with frontmatter (name, provider, model, tools, credentials)
+  followed by the agent's persona in prose. See examples/souls/ava.md.
 `;
 const writeLine = (stream, line = '') => {
     stream.write(`${line}\n`);
@@ -122,6 +141,153 @@ const createDemoProvider = () => defineProvider({
         return builder.done();
     },
 });
+const MEMORY_FILENAME = 'memory.jsonl';
+const memoryFilePath = (env) => path.join(stratusHomePath(env), MEMORY_FILENAME);
+// Memory used to live under the working directory. Fold any such file into
+// the global store the first time a run happens from that directory, then
+// archive it — an upgrade must never look like the agent forgot.
+//
+// Every import first takes exclusive ownership by atomically renaming its
+// source to a unique claim file: of any competing processes, exactly one
+// wins the rename and the rest see ENOENT. A crash mid-import leaves the
+// claim file behind; later runs re-claim it the same way and finish the
+// job, with entries deduped against the global store by id. Only records
+// that parse as real memory entries are imported — malformed lines stay in
+// the archive instead of poisoning the global store for every agent.
+const isMemoryEntryLine = (line) => {
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === 'object' && parsed !== null
+            && typeof parsed.id === 'string'
+            && typeof parsed.agentId === 'string'
+            && typeof parsed.content === 'string';
+    }
+    catch {
+        return false;
+    }
+};
+const migrateLegacyMemory = async (env) => {
+    const legacyPath = path.join(readWorkingDirectory(env), '.stratus', MEMORY_FILENAME);
+    const globalPath = memoryFilePath(env);
+    if (legacyPath === globalPath) {
+        return;
+    }
+    const legacyDir = path.dirname(legacyPath);
+    const archivePath = `${legacyPath}.migrated`;
+    const claimAndImport = async (sourcePath) => {
+        const claimPath = path.join(legacyDir, `${MEMORY_FILENAME}.migrating-${randomUUID()}`);
+        try {
+            await rename(sourcePath, claimPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return; // another process owns it, or there is nothing to migrate
+            }
+            throw error;
+        }
+        const claimed = await readFile(claimPath, 'utf8');
+        let existingIds;
+        try {
+            existingIds = new Set((await readFile(globalPath, 'utf8'))
+                .split('\n')
+                .filter(isMemoryEntryLine)
+                .map((line) => JSON.parse(line).id));
+        }
+        catch {
+            existingIds = new Set();
+        }
+        const entries = claimed
+            .split('\n')
+            .filter((line) => line.trim().length > 0)
+            .filter(isMemoryEntryLine)
+            .filter((line) => !existingIds.has(JSON.parse(line).id));
+        if (entries.length > 0) {
+            await mkdir(path.dirname(globalPath), { recursive: true });
+            await appendFile(globalPath, `${entries.join('\n')}\n`);
+        }
+        // Archive by appending (never overwriting an earlier archive), then
+        // drop the claim — its content is fully preserved in the archive.
+        if (claimed.length > 0) {
+            await appendFile(archivePath, claimed.endsWith('\n') || claimed.length === 0 ? claimed : `${claimed}\n`);
+        }
+        await unlink(claimPath);
+    };
+    await claimAndImport(legacyPath);
+    // Finish any claims a crashed run left behind (both the current unique
+    // names and the fixed .migrating name from earlier versions).
+    let leftovers;
+    try {
+        leftovers = await readdir(legacyDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    for (const name of leftovers) {
+        if (name.startsWith(`${MEMORY_FILENAME}.migrating`)) {
+            await claimAndImport(path.join(legacyDir, name));
+        }
+    }
+};
+// Agents keep the same memory across CLI runs: every remembered fact lands
+// in ~/.stratus/memory.jsonl (keyed by agent id), so the Ava you talk to
+// tomorrow — from any directory — is the Ava you talked to today. One JSON
+// entry per line, written with O_APPEND: concurrent runs each add their own
+// line instead of re-writing the file, so no run can clobber another's
+// remembered fact.
+export const createFileMemoryStore = (filePath) => {
+    const readEntries = async () => {
+        let raw;
+        try {
+            raw = await readFile(filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+        return raw
+            .split('\n')
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                throw new Error(`Memory file has an invalid line: ${filePath}`);
+            }
+        });
+    };
+    return {
+        async append(agentId, content, metadata) {
+            const entry = {
+                id: `${agentId}:memory:${randomUUID()}`,
+                agentId,
+                content,
+                createdAt: new Date().toISOString(),
+                ...(metadata ? { metadata } : {}),
+            };
+            await mkdir(path.dirname(filePath), { recursive: true });
+            await appendFile(filePath, `${JSON.stringify(entry)}\n`);
+            return entry;
+        },
+        async list(agentId) {
+            // Dedupe by id at read time: even if a rare race double-imported a
+            // fact, the agent only ever sees it once.
+            const seen = new Set();
+            return (await readEntries()).filter((entry) => {
+                if (entry.agentId !== agentId || seen.has(entry.id)) {
+                    return false;
+                }
+                seen.add(entry.id);
+                return true;
+            });
+        },
+    };
+};
 const readPromptFromEnvironment = (env) => (env.stdin ?? '').trim();
 const readPromptFromStdin = async (stdin) => {
     stdin.setEncoding('utf8');
@@ -132,13 +298,53 @@ const readPromptFromStdin = async (stdin) => {
     return data.trim();
 };
 const parseProviderName = (value, label) => {
-    if (value === 'demo' || value === 'openai') {
+    if (value === 'demo' || value === 'openai' || value === 'anthropic') {
         return value;
     }
     throw new Error(`Unsupported provider in ${label}: ${value}`);
 };
 const readProcessEnv = (env) => env.processEnv ?? process.env;
 const readWorkingDirectory = (env) => env.cwd ?? process.cwd();
+const readHomeDirectory = (env) => env.homeDir ?? os.homedir();
+const stratusHomePath = (env) => path.join(readHomeDirectory(env), STRATUS_HOME_DIRNAME);
+const globalConfigPath = (env) => path.join(stratusHomePath(env), GLOBAL_CONFIG_FILENAME);
+const credentialsPath = (env) => path.join(stratusHomePath(env), CREDENTIALS_FILENAME);
+const agentsDirPath = (env) => path.join(stratusHomePath(env), AGENTS_DIRNAME);
+const loadCredentials = async (env) => {
+    let raw;
+    try {
+        raw = await readFile(credentialsPath(env), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Credentials file must contain a JSON object: ${credentialsPath(env)}`);
+    }
+    const credentials = {};
+    for (const provider of ['anthropic', 'openai']) {
+        const entry = parsed[provider];
+        if (typeof entry === 'object' && entry !== null && !Array.isArray(entry) &&
+            (entry.type === 'api_key' || entry.type === 'oauth_token') &&
+            typeof entry.value === 'string') {
+            credentials[provider] = entry;
+        }
+    }
+    return credentials;
+};
+// Credentials never live in a project directory or a shell profile — they
+// are written once by `stratus setup` and read on every run, 0600 so only
+// the owner can read them.
+const saveCredentials = async (env, credentials) => {
+    const filePath = credentialsPath(env);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    await chmod(filePath, 0o600);
+};
 const readOptionValue = (tokens, index, flag) => {
     const value = tokens[index + 1];
     if (!value) {
@@ -216,7 +422,7 @@ export const parseCommand = (argv, env = {}) => {
             }
             if (token === '--format') {
                 const value = readOptionValue(agentRest, index, '--format');
-                if (value !== 'text' && value !== 'json') {
+                if (value !== 'text' && value !== 'json' && value !== 'soul') {
                     throw new Error(`Unsupported format: ${value}`);
                 }
                 format = value;
@@ -259,6 +465,7 @@ export const parseCommand = (argv, env = {}) => {
     let model;
     let baseUrl;
     let configPath;
+    let soul;
     let format = 'text';
     let events = true;
     let approvals = 'always';
@@ -302,6 +509,11 @@ export const parseCommand = (argv, env = {}) => {
             index += 1;
             continue;
         }
+        if (token === '--soul') {
+            soul = readOptionValue(rest, index, '--soul');
+            index += 1;
+            continue;
+        }
         if (token === '--format') {
             const value = readOptionValue(rest, index, '--format');
             if (value !== 'text' && value !== 'json') {
@@ -357,6 +569,7 @@ export const parseCommand = (argv, env = {}) => {
         ...(model ? { model } : {}),
         ...(baseUrl ? { baseUrl } : {}),
         ...(configPath ? { configPath } : {}),
+        ...(soul ? { soul } : {}),
         format,
         events,
         approvals,
@@ -408,20 +621,38 @@ const loadConfigFile = async (configPath) => {
     if (typeof config.systemPrompt === 'string' && config.systemPrompt.length > 0) {
         resolved.systemPrompt = config.systemPrompt;
     }
+    if (typeof config.soul === 'string' && config.soul.length > 0) {
+        resolved.soul = config.soul;
+    }
+    if (typeof config.fallbackModel === 'string' && config.fallbackModel.length > 0) {
+        resolved.fallbackModel = config.fallbackModel;
+    }
+    if (typeof config.fallbackProvider === 'string') {
+        resolved.fallbackProvider = parseProviderName(config.fallbackProvider, `config ${configPath}`);
+    }
+    if (typeof config.fallbackBaseUrl === 'string' && config.fallbackBaseUrl.length > 0) {
+        resolved.fallbackBaseUrl = config.fallbackBaseUrl;
+    }
     return resolved;
 };
-const resolveConfigPath = async (command, env) => {
+const resolveConfigLocation = async (command, env) => {
     const processEnv = readProcessEnv(env);
     const cwd = readWorkingDirectory(env);
     const explicit = command.configPath ?? processEnv.STRATUS_CONFIG ?? processEnv.STRATUSCLAW_CONFIG;
     if (explicit) {
-        return path.resolve(cwd, explicit);
+        return { path: path.resolve(cwd, explicit), trusted: true };
     }
-    for (const candidate of [DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME]) {
-        const candidatePath = path.join(cwd, candidate);
+    // Project-local configs win; the global ~/.stratus/config.json written by
+    // `stratus setup` is the fallback that makes the CLI work from anywhere.
+    const candidates = [
+        { path: path.join(cwd, DEFAULT_CONFIG_FILENAME), trusted: false },
+        { path: path.join(cwd, LEGACY_CONFIG_FILENAME), trusted: false },
+        { path: globalConfigPath(env), trusted: true },
+    ];
+    for (const candidate of candidates) {
         try {
-            await readFile(candidatePath, 'utf8');
-            return candidatePath;
+            await readFile(candidate.path, 'utf8');
+            return candidate;
         }
         catch (error) {
             const code = error.code;
@@ -442,44 +673,145 @@ const readNonEmptyString = (value, map) => {
     }
     return map ? map(trimmed) : trimmed;
 };
+// A soul travels with the run: --soul outranks STRATUS_SOUL, which outranks
+// the config file's "soul" key.
+const resolveSoul = async (command, env, fileConfig) => {
+    const processEnv = readProcessEnv(env);
+    const soulPath = command.soul
+        ?? readNonEmptyString(processEnv.STRATUS_SOUL)
+        ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL)
+        ?? fileConfig.soul;
+    if (!soulPath) {
+        return undefined;
+    }
+    const resolvedPath = path.resolve(readWorkingDirectory(env), String(soulPath));
+    let raw;
+    try {
+        raw = await readFile(resolvedPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Soul file not found: ${resolvedPath}`);
+        }
+        throw error;
+    }
+    try {
+        // Seeding with the resolved path keeps an unnamed soul's generated
+        // identity (name, id, avatar) stable across runs — persisted memory is
+        // keyed by that id, so it must not change between invocations.
+        return parseSoul(raw, { seed: resolvedPath });
+    }
+    catch (error) {
+        throw new Error(`Could not parse soul file ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
 export const resolveRuntimeConfig = async (command, env = {}) => {
     const processEnv = readProcessEnv(env);
-    const configPath = await resolveConfigPath(command, env);
-    const fileConfig = configPath ? await loadConfigFile(configPath) : {};
+    const configLocation = await resolveConfigLocation(command, env);
+    const fileConfig = configLocation ? await loadConfigFile(configLocation.path) : {};
+    const soul = await resolveSoul(command, env, fileConfig);
+    // Explicit flags and env vars outrank the soul's own provider/model hints,
+    // which outrank the config file's defaults.
     const provider = command.provider
         ?? readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
         ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
+        ?? readNonEmptyString(soul?.provider, (value) => parseProviderName(value, 'soul file'))
         ?? fileConfig.provider
         ?? 'demo';
     if (provider === 'demo') {
-        return { provider: 'demo' };
+        return { provider: 'demo', ...(soul ? { soul } : {}) };
     }
+    // A config file's model/baseUrl/apiKeyEnv were written for the provider
+    // named in that file. When a flag, env var, or soul selects a different
+    // provider, those values would point at the wrong API (e.g. an OpenAI
+    // base URL handed to the Anthropic SDK), so they are ignored. A file with
+    // no provider key predates the anthropic option, so its settings are
+    // treated as openai-specific.
+    const fileConfigApplies = (fileConfig.provider ?? 'openai') === provider;
+    // A soul's model was chosen for the soul's own provider. If a flag or env
+    // var overrides that provider, the model hint would target the wrong API
+    // (e.g. a Claude model sent to OpenAI), so it only applies when the soul
+    // names no provider or names the selected one.
+    const soulModelApplies = soul?.provider === undefined || soul.provider === provider;
     const model = command.model
         ?? readNonEmptyString(processEnv.STRATUS_MODEL)
         ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL)
-        ?? fileConfig.model
-        ?? DEFAULT_OPENAI_MODEL;
-    const baseUrl = command.baseUrl
-        ?? readNonEmptyString(processEnv.STRATUS_BASE_URL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL)
-        ?? fileConfig.baseUrl
-        ?? DEFAULT_OPENAI_BASE_URL;
+        ?? (soulModelApplies ? readNonEmptyString(soul?.model) : undefined)
+        ?? (fileConfigApplies ? fileConfig.model : undefined)
+        ?? (provider === 'anthropic' ? DEFAULT_ANTHROPIC_MODEL : DEFAULT_OPENAI_MODEL);
     const apiKeyEnvName = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
         ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
-        ?? fileConfig.apiKeyEnv
-        ?? 'OPENAI_API_KEY';
-    const apiKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
+        ?? (fileConfigApplies ? fileConfig.apiKeyEnv : undefined)
+        ?? (provider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY');
+    const credentials = await loadCredentials(env);
+    // A custom endpoint chosen by an auto-discovered project config is not a
+    // place the stored sign-in ever gets sent — a cloned repository could
+    // point it anywhere. Flags and env vars are the user's own choice, and
+    // the provider's default endpoint is harmless.
+    const defaultEndpointFor = (target) => target === 'anthropic' ? DEFAULT_ANTHROPIC_BASE_URL : DEFAULT_OPENAI_BASE_URL;
+    const untrustedCustomBaseUrl = configLocation?.trusted === false
+        && command.baseUrl === undefined
+        && readNonEmptyString(processEnv.STRATUS_BASE_URL) === undefined
+        && readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL) === undefined
+        && fileConfigApplies
+        && fileConfig.baseUrl !== undefined
+        && fileConfig.baseUrl.replace(/\/+$/, '') !== defaultEndpointFor(String(provider));
+    // Env vars outrank the stored sign-in from `stratus setup`.
+    const envApiKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
         ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
         ?? readNonEmptyString(processEnv[String(apiKeyEnvName)]);
-    if (!apiKey) {
-        throw new Error(`Missing API key for provider=openai. Set STRATUS_API_KEY or ${apiKeyEnvName}.`);
-    }
-    const resolved = {
-        provider: 'openai',
-        model: String(model),
-        baseUrl: String(baseUrl),
-        apiKey: String(apiKey),
-    };
+    const candidateCredential = credentials[provider];
+    // A bound credential ignores config URLs entirely, so an untrusted
+    // project URL cannot redirect it — only unbound stored keys are blocked.
+    const credentialIsBound = candidateCredential?.type === 'api_key' && candidateCredential.baseUrl !== undefined;
+    const storedCredential = envApiKey || (untrustedCustomBaseUrl && !credentialIsBound)
+        ? undefined
+        : candidateCredential;
+    const apiKey = envApiKey
+        ?? (storedCredential?.type === 'api_key' ? storedCredential.value : undefined);
+    const authToken = provider === 'anthropic' && storedCredential?.type === 'oauth_token'
+        ? storedCredential.value
+        : undefined;
+    // A stored key bound to an endpoint is used ONLY with that endpoint — a
+    // config file can never redirect it, not even to the official default
+    // URL (a project config could otherwise reroute a local-service key to
+    // the official API). An explicit flag or env URL that disagrees refuses
+    // the stored key instead of leaking it. This applies to both providers.
+    const boundBaseUrl = !envApiKey && storedCredential?.type === 'api_key'
+        ? storedCredential.baseUrl
+        : undefined;
+    const explicitBaseUrl = command.baseUrl
+        ?? readNonEmptyString(processEnv.STRATUS_BASE_URL)
+        ?? readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL);
+    if (boundBaseUrl && explicitBaseUrl
+        && String(explicitBaseUrl).replace(/\/+$/, '') !== boundBaseUrl.replace(/\/+$/, '')) {
+        throw new Error(`Your saved ${provider} sign-in is bound to ${boundBaseUrl} and is not sent to ${explicitBaseUrl}. Set ${apiKeyEnvName} or STRATUS_API_KEY to use that endpoint.`);
+    }
+    const baseUrl = boundBaseUrl
+        ?? explicitBaseUrl
+        ?? (fileConfigApplies ? fileConfig.baseUrl : undefined)
+        // The Anthropic SDK knows its own endpoint; only openai needs a default.
+        ?? (provider === 'anthropic' ? undefined : DEFAULT_OPENAI_BASE_URL);
+    if (!apiKey && !authToken) {
+        if (untrustedCustomBaseUrl && credentials[provider]) {
+            throw new Error(`The project config at ${configLocation?.path} sets a custom base URL (${fileConfig.baseUrl}), so your saved sign-in is not sent to it. Set ${apiKeyEnvName} or STRATUS_API_KEY to use this endpoint, or run with --config to trust the file explicitly.`);
+        }
+        throw new Error(`Missing API key for provider=${provider}. Run \`stratus setup\` to sign in, or set STRATUS_API_KEY or ${apiKeyEnvName}.`);
+    }
+    const resolved = provider === 'anthropic'
+        ? {
+            provider: 'anthropic',
+            model: String(model),
+            ...(baseUrl ? { baseUrl: String(baseUrl) } : {}),
+            ...(apiKey ? { apiKey: String(apiKey) } : {}),
+            ...(authToken ? { authToken } : {}),
+        }
+        : {
+            provider: 'openai',
+            model: String(model),
+            baseUrl: String(baseUrl),
+            apiKey: String(apiKey),
+        };
     const systemPrompt = readNonEmptyString(processEnv.STRATUS_SYSTEM_PROMPT)
         ?? readNonEmptyString(processEnv.STRATUSCLAW_SYSTEM_PROMPT)
         ?? fileConfig.systemPrompt;
@@ -489,12 +821,116 @@ export const resolveRuntimeConfig = async (command, env = {}) => {
     if (env.fetch) {
         resolved.fetch = env.fetch;
     }
+    if (soul) {
+        resolved.soul = soul;
+    }
+    // A configured fallback model kicks in when the default model errors
+    // mid-run. It needs its own working sign-in; without one the fallback is
+    // quietly skipped rather than failing the run it exists to rescue.
+    // An implicit fallback (no fallbackProvider key) was written for the
+    // config's own provider — when a flag, env var, or soul overrides that
+    // provider, the fallback model would target the wrong API, so it is
+    // ignored. An explicit fallbackProvider stays valid regardless.
+    if (fileConfig.fallbackModel && (fileConfig.fallbackProvider !== undefined || fileConfigApplies)) {
+        const fallbackProvider = fileConfig.fallbackProvider ?? provider;
+        if (fallbackProvider !== 'demo') {
+            // Same precedence as the primary sign-in: environment keys outrank
+            // the stored credential. And the same endpoint rule: an untrusted
+            // project config's custom fallback URL never receives a stored key —
+            // including the primary's stored key when both share a provider.
+            // Only env-supplied keys follow such a URL.
+            const fallbackUntrustedUrl = fallbackProvider === 'openai'
+                && configLocation?.trusted === false
+                && fileConfig.fallbackBaseUrl !== undefined
+                && fileConfig.fallbackBaseUrl.replace(/\/+$/, '') !== DEFAULT_OPENAI_BASE_URL;
+            const fallbackEnvKey = readNonEmptyString(processEnv[fallbackProvider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY']);
+            const fallbackCredential = fallbackEnvKey || fallbackUntrustedUrl ? undefined : credentials[fallbackProvider];
+            const primaryReusable = fallbackProvider === provider
+                && (envApiKey !== undefined || !fallbackUntrustedUrl);
+            const fallbackApiKey = (primaryReusable ? apiKey : undefined)
+                ?? fallbackEnvKey
+                ?? (fallbackCredential?.type === 'api_key' ? fallbackCredential.value : undefined);
+            const fallbackAuthToken = fallbackProvider !== provider && fallbackProvider === 'anthropic' && fallbackCredential?.type === 'oauth_token'
+                ? fallbackCredential.value
+                : (primaryReusable ? authToken : undefined);
+            if (fallbackApiKey || fallbackAuthToken) {
+                // When the fallback key comes out of the credential store (its own
+                // entry, or the primary's reused stored key), its bound endpoint is
+                // authoritative — config URLs cannot redirect it.
+                const fallbackBoundUrl = fallbackCredential?.type === 'api_key'
+                    ? fallbackCredential.baseUrl
+                    : (primaryReusable && !envApiKey ? boundBaseUrl : undefined);
+                // An anthropic fallback on the same provider keeps the primary's
+                // configured endpoint — retrying the same credential against the
+                // official endpoint instead of the configured service would leak
+                // it and likely fail.
+                const fallbackAnthropicBaseUrl = fallbackProvider === 'anthropic'
+                    ? (fallbackProvider === provider && baseUrl ? String(baseUrl) : undefined)
+                        ?? (fallbackCredential?.type === 'api_key' ? fallbackCredential.baseUrl : undefined)
+                    : undefined;
+                resolved.fallback = {
+                    provider: fallbackProvider,
+                    model: fileConfig.fallbackModel,
+                    ...(fallbackProvider === 'openai'
+                        ? {
+                            baseUrl: fallbackBoundUrl
+                                ?? fileConfig.fallbackBaseUrl
+                                ?? (fallbackProvider === provider ? String(baseUrl) : undefined)
+                                ?? DEFAULT_OPENAI_BASE_URL,
+                        }
+                        : (fallbackAnthropicBaseUrl ? { baseUrl: fallbackAnthropicBaseUrl } : {})),
+                    ...(fallbackApiKey ? { apiKey: String(fallbackApiKey) } : {}),
+                    ...(fallbackAuthToken ? { authToken: fallbackAuthToken } : {}),
+                };
+            }
+        }
+    }
     return resolved;
 };
-const createRuntimeProvider = (config) => {
+// Wraps the fallback runtime as a provider: the primary model serves every
+// turn until it throws, then the run switches to the fallback for good.
+const createFallbackWrappedProvider = (primary, fallback, onFallback) => {
+    let usingFallback = false;
+    return {
+        name: primary.name,
+        async generate(request) {
+            if (!usingFallback) {
+                try {
+                    return await primary.generate(request);
+                }
+                catch (error) {
+                    usingFallback = true;
+                    onFallback(error);
+                }
+            }
+            return fallback.generate(request);
+        },
+    };
+};
+const createRuntimeProvider = (config, onFallback) => {
     if (config.provider === 'demo') {
         return createDemoProvider();
     }
+    if (config.fallback) {
+        const { fallback, ...primaryConfig } = config;
+        const primary = createRuntimeProvider(primaryConfig);
+        const fallbackProvider = createRuntimeProvider({
+            ...fallback,
+            ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
+            ...(config.fetch ? { fetch: config.fetch } : {}),
+        });
+        return createFallbackWrappedProvider(primary, fallbackProvider, onFallback ?? (() => { }));
+    }
+    if (config.provider === 'anthropic') {
+        return createAnthropicProvider({
+            model: config.model,
+            ...(config.apiKey ? { apiKey: config.apiKey } : {}),
+            ...(config.authToken ? { authToken: config.authToken } : {}),
+            ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+            ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
+            ...(config.fetch ? { fetch: config.fetch } : {}),
+        });
+    }
     return createOpenAICompatibleProvider({
         name: 'openai',
         model: config.model,
@@ -536,8 +972,12 @@ const createApprovalPolicy = (mode, streams, env) => {
     };
 };
 export const runSingleLoop = async (prompt, streams, options) => {
+    const runEnv = options.env ?? {};
+    await migrateLegacyMemory(runEnv);
+    const memory = createFileMemoryStore(memoryFilePath(runEnv));
     const tools = new ToolRegistry();
     tools.register(createDemoTool());
+    tools.register(createRememberTool(memory));
     const bus = new EventBus({
         onError: (error) => {
             writeLine(streams.stderr, `Warning: event handler failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -551,33 +991,45 @@ export const runSingleLoop = async (prompt, streams, options) => {
             }
         });
     }
-    const runtimeProvider = createRuntimeProvider(options.runtime);
+    const runtimeProvider = createRuntimeProvider(options.runtime, (error) => {
+        const fallback = options.runtime.provider === 'demo' ? undefined : options.runtime.fallback;
+        writeLine(streams.stderr, `Warning: the default model failed (${error instanceof Error ? error.message : String(error)}); falling back to ${fallback?.model ?? 'the fallback model'}.`);
+    });
     const runner = new AgentRunner({
         provider: runtimeProvider,
         tools,
         executor: createLocalCommandExecutor(),
         approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}),
         bus,
+        memory,
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
     });
     await runner.initialize();
-    const agent = options.runtime.provider === 'demo'
-        ? {
-            id: 'demo-agent',
-            name: 'Demo Agent',
-            instructions: 'Keep the loop tiny and readable.',
-        }
-        : {
-            id: 'openai-agent',
-            name: 'OpenAI Agent',
-            instructions: 'Respond clearly and directly to the user request.',
-        };
+    // A soul is a full identity — it replaces the built-in per-provider agent.
+    const agent = options.runtime.soul?.agent
+        ?? (options.runtime.provider === 'demo'
+            ? {
+                id: 'demo-agent',
+                name: 'Demo Agent',
+                instructions: 'Keep the loop tiny and readable.',
+            }
+            : options.runtime.provider === 'anthropic'
+                ? {
+                    id: 'anthropic-agent',
+                    name: 'Claude Agent',
+                    instructions: 'Respond clearly and directly to the user request.',
+                }
+                : {
+                    id: 'openai-agent',
+                    name: 'OpenAI Agent',
+                    instructions: 'Respond clearly and directly to the user request.',
+                });
     const metadata = options.runtime.provider === 'demo'
         ? { provider: 'demo' }
         : {
-            provider: 'openai',
+            provider: options.runtime.provider,
             model: options.runtime.model,
-            baseUrl: options.runtime.baseUrl,
+            ...(options.runtime.provider === 'openai' ? { baseUrl: options.runtime.baseUrl } : {}),
         };
     return runner.run({
         sessionId: randomUUID(),
@@ -609,10 +1061,12 @@ export const printSessionSummary = (session, streams) => {
     }
 };
 const formatRuntimeBanner = (runtime) => {
+    const soulSuffix = runtime.soul ? ` as ${runtime.soul.agent.name}` : '';
     if (runtime.provider === 'demo') {
-        return 'Starting Stratus Agent local loop with provider=demo';
+        return `Starting Stratus Agent local loop with provider=demo${soulSuffix}`;
     }
-    return `Starting Stratus Agent local loop with provider=openai model=${runtime.model}`;
+    const fallbackSuffix = runtime.fallback ? ` fallback=${runtime.fallback.model}` : '';
+    return `Starting Stratus Agent local loop with provider=${runtime.provider} model=${runtime.model}${fallbackSuffix}${soulSuffix}`;
 };
 const escapeHtml = (value) => value
     .replaceAll('&', '&')
@@ -754,7 +1208,7 @@ export const startDashboardServer = async (options) => {
             sendJson(response, 200, {
                 ok: true,
                 service: 'stratus-dashboard',
-                version: '0.1.0',
+                version: '0.2.1',
                 now: new Date().toISOString(),
             });
             return;
@@ -811,6 +1265,189 @@ export const startDashboardServer = async (options) => {
 // the safe character set gets single-quoted.
 const quoteShellArg = (value) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
 const createSetupPrompter = (streams, env) => {
+    // On a real TTY, menus are arrow-key driven and secrets are read without
+    // echo; with piped input (tests, scripts) everything is plain lines.
+    const interactive = env.setupInput === undefined && process.stdin.isTTY === true;
+    if (interactive) {
+        let closed = false;
+        process.stdin.once('end', () => {
+            closed = true;
+        });
+        const question = (prompt, secret) => {
+            const readline = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+            if (secret) {
+                const internal = readline;
+                const original = internal._writeToOutput?.bind(readline);
+                internal._writeToOutput = (chunk) => {
+                    // Echo the prompt itself, swallow the typed secret.
+                    if (chunk.startsWith(prompt)) {
+                        original?.(prompt);
+                    }
+                };
+            }
+            return new Promise((resolve) => {
+                readline.on('SIGINT', () => {
+                    readline.close();
+                    streams.stdout.write('\n');
+                    process.exit(130);
+                });
+                readline.question(prompt, (answer) => {
+                    readline.close();
+                    if (secret) {
+                        streams.stdout.write('\n');
+                    }
+                    resolve(answer.trim());
+                });
+            });
+        };
+        const selectInteractive = (heading, options, opts) => new Promise((resolve) => {
+            const stdin = process.stdin;
+            const out = streams.stdout;
+            let index = Math.min(Math.max(opts.defaultIndex ?? 0, 0), options.length - 1);
+            const wasRaw = stdin.isRaw === true;
+            stdin.setRawMode?.(true);
+            stdin.resume();
+            const render = (redraw) => {
+                if (redraw) {
+                    out.write(`\u001b[${options.length}A`);
+                }
+                else {
+                    out.write(`${heading}\n`);
+                    if (opts.footnote) {
+                        out.write(`${opts.footnote}\n`);
+                    }
+                }
+                options.forEach((option, i) => {
+                    const active = i === index;
+                    out.write(`\u001b[2K\r${active ? '\u001b[36m\u276f ' : '  '}${i + 1}) ${option}${active ? '\u001b[0m' : ''}\n`);
+                });
+            };
+            const finish = (answer) => {
+                if (pendingTimer !== undefined) {
+                    clearTimeout(pendingTimer);
+                    pendingTimer = undefined;
+                }
+                stdin.off('data', onData);
+                if (!wasRaw) {
+                    stdin.setRawMode?.(false);
+                }
+                // Pause so keys typed between menus buffer for the next consumer
+                // instead of being dropped by a flowing stream with no listener.
+                stdin.pause();
+                if (pendingEscape.length > 0) {
+                    stdin.unshift(Buffer.from(pendingEscape, 'utf8'));
+                    pendingEscape = '';
+                }
+                resolve(answer);
+            };
+            const handleKey = (key) => {
+                if (key === '\u0003') {
+                    // Ctrl-C: restore the terminal and leave setup entirely.
+                    stdin.setRawMode?.(false);
+                    out.write('\n');
+                    process.exit(130);
+                }
+                if (key === '\u001b[A' || key === '\u001bOA' || key === 'k') {
+                    index = (index - 1 + options.length) % options.length;
+                    render(true);
+                    return false;
+                }
+                if (key === '\u001b[B' || key === '\u001bOB' || key === 'j' || key === '\t') {
+                    index = (index + 1) % options.length;
+                    render(true);
+                    return false;
+                }
+                if (key === '\r' || key === '\n') {
+                    finish({ kind: 'index', index });
+                    return true;
+                }
+                if (key === '\u001b' || key === 'q') {
+                    finish({ kind: 'back' });
+                    return true;
+                }
+                if (/^[1-9]$/.test(key)) {
+                    const jump = Number(key) - 1;
+                    if (jump < options.length) {
+                        index = jump;
+                        render(true);
+                        finish({ kind: 'index', index });
+                        return true;
+                    }
+                }
+                return false;
+            };
+            // Key repeat and pasted input arrive as one chunk containing several
+            // sequences — split it into individual keys before handling. Bytes
+            // that follow the selecting key (e.g. a pasted "2sk-ant-…") are
+            // pushed back onto stdin for whatever prompt comes next. Terminals
+            // and SSH can also split an escape sequence ACROSS chunks (ESC, then
+            // "[A"), so an incomplete escape tail is held briefly: completed by
+            // the next chunk, or treated as a real Esc press after a beat.
+            let pendingEscape = '';
+            let pendingTimer;
+            const processText = (text) => {
+                let position = 0;
+                while (position < text.length) {
+                    const remaining = text.length - position;
+                    if (text[position] === '\u001b' && remaining < 3
+                        && (remaining === 1 || text[position + 1] === '[' || text[position + 1] === 'O')) {
+                        pendingEscape = text.slice(position);
+                        pendingTimer = setTimeout(() => {
+                            // No continuation arrived: it was a genuine Esc press.
+                            pendingEscape = '';
+                            pendingTimer = undefined;
+                            handleKey('\u001b');
+                        }, 75);
+                        return;
+                    }
+                    let key;
+                    if (text[position] === '\u001b' && (text[position + 1] === '[' || text[position + 1] === 'O')) {
+                        key = text.slice(position, position + 3);
+                        position += 3;
+                    }
+                    else {
+                        key = text[position];
+                        position += 1;
+                    }
+                    if (handleKey(key)) {
+                        const rest = text.slice(position);
+                        if (rest.length > 0) {
+                            stdin.unshift(Buffer.from(rest, 'utf8'));
+                        }
+                        return;
+                    }
+                }
+            };
+            const onData = (chunk) => {
+                if (pendingTimer !== undefined) {
+                    clearTimeout(pendingTimer);
+                    pendingTimer = undefined;
+                }
+                const text = pendingEscape + chunk.toString('utf8');
+                pendingEscape = '';
+                processText(text);
+            };
+            render(false);
+            stdin.on('data', onData);
+        });
+        return {
+            ask: (q) => question(q, false),
+            askSecret: (q) => question(q, true),
+            async select(heading, options, opts = {}) {
+                if (options.length === 0) {
+                    return { kind: 'back' };
+                }
+                return selectInteractive(heading, options, opts);
+            },
+            isClosed: () => closed,
+            close: () => {
+                // A resumed raw-mode stdin keeps the event loop alive; release it
+                // so the process can exit once setup returns.
+                process.stdin.setRawMode?.(false);
+                process.stdin.pause();
+            },
+        };
+    }
     const input = env.setupInput ?? process.stdin;
     const readline = createInterface({ input, terminal: false });
     const pendingLines = [];
@@ -821,179 +1458,947 @@ const createSetupPrompter = (streams, env) => {
     readline.once('close', () => {
         closed = true;
     });
-    return {
-        async ask(question) {
-            streams.stdout.write(question);
-            while (pendingLines.length === 0) {
-                if (closed) {
-                    return '';
+    const nextLine = async () => {
+        while (pendingLines.length === 0) {
+            if (closed) {
+                return '';
+            }
+            await new Promise((resolve) => {
+                readline.once('line', () => resolve());
+                readline.once('close', () => resolve());
+            });
+        }
+        return (pendingLines.shift() ?? '').trim();
+    };
+    const selectPlain = async (heading, options, opts) => {
+        const defaultIndex = Math.min(Math.max(opts.defaultIndex ?? 0, 0), options.length - 1);
+        while (true) {
+            streams.stdout.write(`${heading}\n`);
+            if (opts.footnote) {
+                streams.stdout.write(`${opts.footnote}\n`);
+            }
+            for (const [i, option] of options.entries()) {
+                streams.stdout.write(`  ${i + 1}) ${option}\n`);
+            }
+            streams.stdout.write(`Choose [${defaultIndex + 1}]: `);
+            const line = await nextLine();
+            if (line === '') {
+                if (closed && pendingLines.length === 0) {
+                    return { kind: 'back' };
                 }
-                await new Promise((resolve) => {
-                    readline.once('line', () => resolve());
-                    readline.once('close', () => resolve());
-                });
+                return { kind: 'index', index: defaultIndex };
+            }
+            if (/^\d+$/.test(line)) {
+                const picked = Number(line) - 1;
+                if (picked >= 0 && picked < options.length) {
+                    return { kind: 'index', index: picked };
+                }
+                writeLine(streams.stdout, `Pick a number between 1 and ${options.length}.`);
+                continue;
             }
-            const answer = pendingLines.shift() ?? '';
-            return answer.trim();
+            if (/^(back|b|q(uit)?)$/i.test(line)) {
+                return { kind: 'back' };
+            }
+            if (opts.allowText) {
+                return { kind: 'text', text: line };
+            }
+            const matched = options.findIndex((option) => option.toLowerCase().includes(line.toLowerCase()));
+            if (matched !== -1) {
+                return { kind: 'index', index: matched };
+            }
+            writeLine(streams.stdout, `Pick a number between 1 and ${options.length}.`);
+        }
+    };
+    return {
+        async ask(q) {
+            streams.stdout.write(q);
+            return nextLine();
         },
-        close() {
+        async askSecret(q) {
+            // Piped input never echoes, so plain reads are safe here.
+            streams.stdout.write(q);
+            return nextLine();
+        },
+        async select(heading, options, opts = {}) {
+            if (options.length === 0) {
+                return { kind: 'back' };
+            }
+            return selectPlain(heading, options, opts);
+        },
+        isClosed: () => closed && pendingLines.length === 0,
+        close: () => {
             readline.close();
         },
     };
 };
-const fileExists = async (filePath) => {
+// Live check that a pasted key actually works, so the user finds out inside
+// setup instead of on their first run.
+const verifyProviderKey = async (provider, key, baseUrl, fetchImpl) => {
+    if (typeof fetchImpl !== 'function') {
+        return { status: 'unreachable', detail: 'fetch is unavailable' };
+    }
+    const root = (baseUrl ?? (provider === 'anthropic' ? DEFAULT_ANTHROPIC_BASE_URL : DEFAULT_OPENAI_BASE_URL)).replace(/\/+$/, '');
+    const url = provider === 'anthropic' ? `${root}/v1/models` : `${root}/models`;
+    const headers = provider === 'anthropic'
+        ? { 'x-api-key': key, 'anthropic-version': '2023-06-01' }
+        : { authorization: `Bearer ${key}` };
     try {
-        await readFile(filePath, 'utf8');
-        return true;
+        const response = await fetchImpl(url, { headers });
+        if (response.ok) {
+            return { status: 'ok' };
+        }
+        // Only an explicit auth failure condemns the key. Compatible endpoints
+        // (local models, proxies) often lack GET /models entirely — a 404/405
+        // there says nothing about the key, so it stays saveable.
+        if (response.status === 401 || response.status === 403) {
+            return { status: 'rejected', detail: `HTTP ${response.status}` };
+        }
+        return { status: 'unreachable', detail: `the endpoint did not support a key check (HTTP ${response.status})` };
     }
     catch (error) {
-        if (error.code === 'ENOENT') {
-            return false;
-        }
-        throw error;
+        return { status: 'unreachable', detail: error instanceof Error ? error.message : String(error) };
     }
 };
+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',
+    'memory.remember for durable facts about the people you work with.',
+].join('\n');
+// Shown when live model listing is unavailable (e.g. subscription tokens
+// cannot call the models endpoint, or the machine is offline).
+// Model ids that cannot serve /chat/completions and must not become the
+// default: embeddings, audio, images, moderation, and legacy completions.
+const NON_CHAT_MODEL_PATTERN = /embed|whisper|tts|audio|dall-e|image|moderation|realtime|transcribe|davinci|babbage|curie|(^|[-_])ada([-_]|$)/i;
+const KNOWN_CLAUDE_MODELS = [
+    'claude-opus-5',
+    'claude-sonnet-5',
+    'claude-haiku-4-5',
+    'claude-opus-4-6',
+    'claude-sonnet-4-6',
+];
 export const runSetup = async (command, streams, env = {}) => {
     const cwd = readWorkingDirectory(env);
     const processEnv = readProcessEnv(env);
-    // Mirror resolveConfigPath's precedence (--config, then STRATUS_CONFIG /
-    // STRATUSCLAW_CONFIG, then the default filename) so the file written here
-    // is the one `stratus run` actually loads afterwards.
+    // Config target: --config, then STRATUS_CONFIG / STRATUSCLAW_CONFIG, then
+    // the global ~/.stratus/config.json — the file `stratus run` falls back to
+    // from any directory, which is what makes setup a one-time step.
     const envConfigVar = readNonEmptyString(processEnv.STRATUS_CONFIG)
         ? 'STRATUS_CONFIG'
         : readNonEmptyString(processEnv.STRATUSCLAW_CONFIG)
             ? 'STRATUSCLAW_CONFIG'
             : undefined;
     const envConfigPath = envConfigVar ? String(processEnv[envConfigVar]).trim() : undefined;
-    const chosenPath = command.configPath ?? envConfigPath ?? DEFAULT_CONFIG_FILENAME;
-    const configPath = path.resolve(cwd, chosenPath);
+    const configPath = command.configPath
+        ? path.resolve(cwd, command.configPath)
+        : envConfigPath
+            ? path.resolve(cwd, envConfigPath)
+            : globalConfigPath(env);
     // A path passed via --config is not auto-discovered by `stratus run`, so
-    // suggested commands must carry it explicitly. Env-derived paths need no
-    // flag because `run` reads the same variable.
+    // suggested commands must carry it explicitly.
     const runConfigFlag = command.configPath ? ` --config ${quoteShellArg(command.configPath)}` : '';
-    const prompter = createSetupPrompter(streams, env);
+    // Seed from what is already configured, so re-running setup edits instead
+    // of clobbering.
+    let existing = {};
     try {
-        writeLine(streams.stdout, 'Stratus Agent setup');
-        writeLine(streams.stdout, 'This walkthrough writes a stratus.config.json so `stratus run` works out of the box.');
-        writeLine(streams.stdout, 'Press Enter to accept the [default] for any question.');
-        if (!command.configPath && envConfigVar) {
-            writeLine(streams.stdout, `${envConfigVar} is set, so the config will be written to ${configPath}.`);
+        existing = await loadConfigFile(configPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            writeLine(streams.stderr, `Warning: could not read ${configPath} (${error instanceof Error ? error.message : String(error)}); starting fresh.`);
         }
-        writeLine(streams.stdout);
-        if (await fileExists(configPath)) {
-            const overwrite = await prompter.ask(`${configPath} already exists. Overwrite it? [y/N] `);
-            if (!/^y(es)?$/i.test(overwrite)) {
-                writeLine(streams.stdout, 'Keeping the existing config. Nothing was changed.');
-                return 0;
+    }
+    const state = {
+        provider: existing.provider ?? 'anthropic',
+        ...(existing.model ? { model: existing.model } : {}),
+        ...(existing.baseUrl ? { baseUrl: existing.baseUrl } : {}),
+        ...(existing.apiKeyEnv ? { apiKeyEnv: existing.apiKeyEnv } : {}),
+        ...(existing.systemPrompt ? { systemPrompt: existing.systemPrompt } : {}),
+        ...(existing.soul ? { soulPath: existing.soul } : {}),
+        ...(existing.fallbackModel ? { fallbackModel: existing.fallbackModel } : {}),
+        // Pin an implicit fallback provider now, so a later default-provider
+        // switch cannot silently change what the fallback means.
+        ...(existing.fallbackModel || existing.fallbackProvider
+            ? { fallbackProvider: existing.fallbackProvider ?? existing.provider ?? 'anthropic' }
+            : {}),
+        ...(existing.fallbackBaseUrl ? { fallbackBaseUrl: existing.fallbackBaseUrl } : {}),
+        credentials: await loadCredentials(env),
+        credentialsDirty: false,
+    };
+    const prompter = createSetupPrompter(streams, env);
+    const defaultModelFor = (provider) => provider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL;
+    const defaultKeyEnvFor = (provider) => provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    const credentialLabel = (credential) => credential.type === 'oauth_token' ? 'Claude subscription' : 'API key';
+    const providerSignInStatus = (provider) => {
+        const credential = state.credentials[provider];
+        if (credential) {
+            return `signed in (${credentialLabel(credential)})`;
+        }
+        if (readNonEmptyString(processEnv[defaultKeyEnvFor(provider)])) {
+            return `using ${defaultKeyEnvFor(provider)} from your environment`;
+        }
+        return 'not signed in';
+    };
+    const providersSummary = () => {
+        const parts = [];
+        for (const provider of ['anthropic', 'openai']) {
+            const credential = state.credentials[provider];
+            if (credential) {
+                parts.push(`${provider} (${credentialLabel(credential)})`);
+            }
+            else if (readNonEmptyString(processEnv[defaultKeyEnvFor(provider)])) {
+                parts.push(`${provider} (env key)`);
             }
-            writeLine(streams.stdout);
         }
-        const providerAnswer = await prompter.ask('Which provider do you want to use?\n  1) openai — any OpenAI-compatible API (needs an API key)\n  2) demo — built-in provider, no key required\nChoose [1]: ');
-        const provider = providerAnswer === '2' || /^demo$/i.test(providerAnswer) ? 'demo' : 'openai';
-        // Exported STRATUS_*/STRATUSCLAW_* variables outrank the config file in
-        // resolveRuntimeConfig, so any conflicting value would make the suggested
-        // bare command behave differently from what setup just wrote. Detect each
-        // conflict, warn about it, and add the matching flag so the printed
-        // command wins regardless.
-        const detectEnvOverride = (primary, legacy, chosen, flagName) => {
-            const envVar = readNonEmptyString(processEnv[primary])
-                ? primary
-                : readNonEmptyString(processEnv[legacy])
-                    ? legacy
-                    : undefined;
-            if (!envVar) {
+        if (parts.length === 0) {
+            return state.provider === 'demo' ? 'demo — offline, no account' : 'none signed in yet';
+        }
+        if (state.provider === 'demo') {
+            parts.push('default: demo');
+        }
+        return parts.join(' · ');
+    };
+    const modelsSummary = () => {
+        if (state.provider === 'demo') {
+            return 'demo (no model)';
+        }
+        const base = `default ${state.model ?? `${defaultModelFor(state.provider)} (default)`}`;
+        return state.fallbackModel ? `${base} · fallback ${state.fallbackModel}` : `${base} · no fallback`;
+    };
+    const signInSummary = () => {
+        if (state.provider === 'demo') {
+            return 'no account needed';
+        }
+        const credential = state.credentials[state.provider];
+        if (credential) {
+            return credential.type === 'oauth_token'
+                ? 'signed in with your Claude subscription'
+                : 'signed in with an API key';
+        }
+        const keyEnv = state.apiKeyEnv ?? defaultKeyEnvFor(state.provider);
+        if (readNonEmptyString(processEnv.STRATUS_API_KEY) ?? readNonEmptyString(processEnv[keyEnv])) {
+            return `using ${readNonEmptyString(processEnv.STRATUS_API_KEY) ? 'STRATUS_API_KEY' : keyEnv} from your environment`;
+        }
+        return 'not signed in yet';
+    };
+    const agentSummary = () => {
+        if (!state.soulPath) {
+            return 'none — every run uses the built-in default agent';
+        }
+        return state.soulPath;
+    };
+    const storeCredential = (provider, credential) => {
+        state.credentials[provider] = credential;
+        state.credentialsDirty = true;
+    };
+    const signInAnthropic = async () => {
+        const signedIn = state.credentials.anthropic !== undefined;
+        const answer = await prompter.select('How should Stratus connect to Claude?', [
+            'Claude subscription (Pro/Max) — sign in through Claude Code, no per-token cost',
+            'Anthropic API key — pay per use (console.anthropic.com)',
+            'Skip for now',
+            ...(signedIn ? ['Sign out'] : []),
+        ]);
+        if (signedIn && answer.kind === 'index' && answer.index === 3) {
+            delete state.credentials.anthropic;
+            state.credentialsDirty = true;
+            writeLine(streams.stdout, 'Signed out of Anthropic.');
+            return;
+        }
+        if (answer.kind !== 'index' || answer.index === 2) {
+            return;
+        }
+        if (answer.index === 1) {
+            const key = await prompter.askSecret('Paste your Anthropic API key (starts with sk-ant-, Enter to skip; input is hidden): ');
+            if (!key) {
+                writeLine(streams.stdout, 'Skipped — you can sign in any time by re-running this menu.');
+                return;
+            }
+            writeLine(streams.stdout, 'Checking the key against the Anthropic API…');
+            // The key is verified against the configured endpoint and bound to
+            // it, so a later provider switch (or an anthropic fallback) can never
+            // send a proxy credential to the official endpoint.
+            const verifyEndpoint = state.provider === 'anthropic' ? state.baseUrl : undefined;
+            const binding = verifyEndpoint && verifyEndpoint.replace(/\/+$/, '') !== DEFAULT_ANTHROPIC_BASE_URL
+                ? { baseUrl: verifyEndpoint }
+                : {};
+            const verdict = await verifyProviderKey('anthropic', key, verifyEndpoint, env.fetch ?? globalThis.fetch);
+            if (verdict.status === 'ok') {
+                storeCredential('anthropic', { type: 'api_key', value: key, ...binding });
+                writeLine(streams.stdout, '✓ Key verified — you are signed in to Anthropic.');
+            }
+            else if (verdict.status === 'rejected') {
+                writeLine(streams.stdout, `✗ Anthropic rejected that key (${verdict.detail}). It was NOT saved — check console.anthropic.com and try again from this menu.`);
+            }
+            else {
+                storeCredential('anthropic', { type: 'api_key', value: key, ...binding });
+                writeLine(streams.stdout, `! Could not reach the Anthropic API to verify (${verdict.detail}). Saved the key anyway — it will be checked on your first run.`);
+            }
+            return;
+        }
+        // Default: subscription sign-in via Claude Code.
+        writeLine(streams.stdout, 'Your Claude Pro/Max subscription covers usage made through Claude Code.');
+        writeLine(streams.stdout, 'In another terminal on this machine, run:');
+        writeLine(streams.stdout, '  claude setup-token');
+        writeLine(streams.stdout, '(requires Claude Code installed and signed in to your Claude account)');
+        const token = await prompter.askSecret('Paste the setup token it prints (starts with sk-ant-oat, Enter to skip; input is hidden): ');
+        if (!token) {
+            writeLine(streams.stdout, 'Skipped — you can sign in any time by re-running this menu.');
+            return;
+        }
+        storeCredential('anthropic', { type: 'oauth_token', value: token });
+        writeLine(streams.stdout, '✓ Subscription token saved. It is verified on your first run.');
+    };
+    const signInOpenAI = async () => {
+        const currentEndpoint = (state.provider === 'openai' ? state.baseUrl : undefined)
+            ?? state.credentials.openai?.baseUrl
+            ?? DEFAULT_OPENAI_BASE_URL;
+        const baseUrlAnswer = await prompter.ask(`API base URL [${currentEndpoint}]: `);
+        const chosenEndpoint = baseUrlAnswer || currentEndpoint;
+        // state.baseUrl describes the DEFAULT provider's endpoint; a secondary
+        // openai sign-in keeps its endpoint on the credential instead. The
+        // change is committed only once a sign-in is accepted — a rejected key
+        // must not leave a new endpoint paired with the old credential.
+        const commitEndpoint = () => {
+            if (state.provider === 'openai') {
+                state.baseUrl = chosenEndpoint;
+            }
+        };
+        const key = await prompter.askSecret('Paste your API key (Enter to skip; input is hidden): ');
+        if (!key) {
+            // Without a stored credential there is no old key the new endpoint
+            // could be mispaired with.
+            if (!state.credentials.openai) {
+                commitEndpoint();
+            }
+            else if (chosenEndpoint !== currentEndpoint) {
+                writeLine(streams.stdout, 'Endpoint left unchanged — paste a key for the new endpoint to switch to it.');
+            }
+            writeLine(streams.stdout, 'Skipped — you can sign in any time by re-running this menu.');
+            return;
+        }
+        writeLine(streams.stdout, 'Checking the key…');
+        // The endpoint travels with the credential, so this sign-in keeps
+        // working even when another provider is the default.
+        const endpoint = chosenEndpoint !== DEFAULT_OPENAI_BASE_URL ? { baseUrl: chosenEndpoint } : {};
+        const verdict = await verifyProviderKey('openai', key, chosenEndpoint, env.fetch ?? globalThis.fetch);
+        if (verdict.status === 'ok') {
+            storeCredential('openai', { type: 'api_key', value: key, ...endpoint });
+            commitEndpoint();
+            writeLine(streams.stdout, '✓ Key verified — you are signed in.');
+        }
+        else if (verdict.status === 'rejected') {
+            writeLine(streams.stdout, `✗ The API rejected that key (${verdict.detail}). It was NOT saved — try again from this menu.`);
+            if (chosenEndpoint !== currentEndpoint) {
+                writeLine(streams.stdout, 'The endpoint was left unchanged as well.');
+            }
+        }
+        else {
+            storeCredential('openai', { type: 'api_key', value: key, ...endpoint });
+            commitEndpoint();
+            writeLine(streams.stdout, `! Could not reach the API to verify (${verdict.detail}). Saved the key anyway — it will be checked on your first run.`);
+        }
+    };
+    // Changing the default provider invalidates settings that were chosen
+    // for the old one: the model and apiKeyEnv are cleared (defaults take
+    // over), while the openai base URL is kept — it belongs to the openai
+    // sign-in and still serves openai fallbacks. A soul that pins a provider
+    // outranks the config at run time, so that earns a warning, not a reset.
+    const switchDefaultProvider = async (next) => {
+        if (state.provider === next) {
+            return;
+        }
+        state.provider = next;
+        delete state.model;
+        delete state.apiKeyEnv;
+        // state.baseUrl is the DEFAULT provider's endpoint; the old provider's
+        // URL must not follow the switch. An openai default reseeds from the
+        // credential's bound endpoint.
+        delete state.baseUrl;
+        if (next === 'openai' && state.credentials.openai?.baseUrl) {
+            state.baseUrl = state.credentials.openai.baseUrl;
+        }
+        if (state.soulPath) {
+            try {
+                const soul = parseSoul(await readFile(state.soulPath, 'utf8'), { seed: state.soulPath });
+                if (soul.provider && soul.provider !== next) {
+                    writeLine(streams.stdout, `Heads up: your default agent (${soul.agent.name}) pins provider ${soul.provider} in their soul, which outranks this choice at run time. Edit ${state.soulPath} or clear the agent (menu 3).`);
+                }
+            }
+            catch {
+                // A broken soul file surfaces when it is actually used.
+            }
+        }
+    };
+    // Whether a provider could actually serve a run right now, through any
+    // credential source a real run would consider: the stored sign-in, the
+    // generic STRATUS_API_KEY, a configured apiKeyEnv, or the provider's own
+    // env var.
+    const providerUsable = (provider) => {
+        if (provider === 'demo') {
+            return true;
+        }
+        const keyEnvSelector = provider === state.provider
+            ? readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
+                ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
+                ?? state.apiKeyEnv
+            : undefined;
+        return state.credentials[provider] !== undefined
+            || readNonEmptyString(processEnv.STRATUS_API_KEY) !== undefined
+            || (keyEnvSelector ? readNonEmptyString(processEnv[String(keyEnvSelector)]) !== undefined : false)
+            || readNonEmptyString(processEnv[defaultKeyEnvFor(provider)]) !== undefined;
+    };
+    // Signing in makes that provider the default only when the current
+    // default cannot actually run (demo, or a provider with no usable key).
+    const maybeSwitchDefault = async (provider) => {
+        if (state.provider === 'demo' || (state.provider !== provider && !providerUsable(state.provider))) {
+            await switchDefaultProvider(provider);
+        }
+    };
+    const chooseProviders = async () => {
+        const answer = await prompter.select('Providers — sign in to one or more:', [
+            `Claude (Anthropic) — ${providerSignInStatus('anthropic')}`,
+            `OpenAI-compatible — ${providerSignInStatus('openai')}`,
+            'Demo — built-in fake model, offline, no account',
+            'Back',
+        ]);
+        if (answer.kind !== 'index' || answer.index === 3) {
+            return;
+        }
+        if (answer.index === 2) {
+            await switchDefaultProvider('demo');
+            writeLine(streams.stdout, 'Demo selected — no sign-in needed. Mention "echo" or "tool" in a prompt to see tool calls.');
+            return;
+        }
+        if (answer.index === 1) {
+            await signInOpenAI();
+            if (state.credentials.openai) {
+                await maybeSwitchDefault('openai');
+            }
+            return;
+        }
+        await signInAnthropic();
+        if (state.credentials.anthropic) {
+            await maybeSwitchDefault('anthropic');
+        }
+    };
+    // Every model the current sign-ins can actually reach, fetched live where
+    // possible. Subscription tokens cannot call the models endpoint, so those
+    // fall back to the known Claude lineup.
+    const collectAvailableModels = async () => {
+        const fetchImpl = env.fetch ?? globalThis.fetch;
+        const models = [];
+        for (const provider of ['anthropic', 'openai']) {
+            // Discovery uses the credential a real run would use. STRATUS_API_KEY
+            // and a configured apiKeyEnv authenticate the DEFAULT provider only —
+            // a secondary provider relies on its own env var or stored sign-in,
+            // never the default provider's secret.
+            const envKey = (provider === state.provider
+                ? readNonEmptyString(processEnv.STRATUS_API_KEY)
+                    ?? (state.apiKeyEnv ? readNonEmptyString(processEnv[state.apiKeyEnv]) : undefined)
+                : undefined)
+                ?? readNonEmptyString(processEnv[defaultKeyEnvFor(provider)]);
+            const credential = envKey ? undefined : state.credentials[provider];
+            const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
+            if (!apiKey && !credential) {
+                continue;
+            }
+            if (provider === 'anthropic') {
+                if (!apiKey || typeof fetchImpl !== 'function') {
+                    // Subscription tokens cannot call the models endpoint.
+                    models.push(...KNOWN_CLAUDE_MODELS.map((id) => ({ provider, id })));
+                    continue;
+                }
+                // The same endpoint a real run uses: the stored key's bound URL is
+                // authoritative, then a configured anthropic base URL (a proxy) —
+                // never the official endpoint by accident.
+                const anthropicRoot = ((credential?.type === 'api_key' ? credential.baseUrl : undefined)
+                    ?? (state.provider === 'anthropic' ? state.baseUrl : undefined)
+                    ?? DEFAULT_ANTHROPIC_BASE_URL).replace(/\/+$/, '');
+                try {
+                    const response = await fetchImpl(`${anthropicRoot}/v1/models?limit=100`, {
+                        headers: { 'x-api-key': String(apiKey), 'anthropic-version': '2023-06-01' },
+                    });
+                    const payload = await response.json();
+                    const ids = (payload.data ?? []).map((entry) => entry.id).filter((id) => typeof id === 'string');
+                    models.push(...(ids.length > 0 ? ids : KNOWN_CLAUDE_MODELS).map((id) => ({ provider, id })));
+                }
+                catch {
+                    models.push(...KNOWN_CLAUDE_MODELS.map((id) => ({ provider, id })));
+                }
+                continue;
+            }
+            if (!apiKey || typeof fetchImpl !== 'function') {
+                continue;
+            }
+            try {
+                // A stored key's bound endpoint is authoritative, exactly as at run
+                // time; only env-supplied keys follow the default provider's URL.
+                const root = ((credential?.type === 'api_key' ? credential.baseUrl : undefined)
+                    ?? (state.provider === 'openai' ? state.baseUrl : undefined)
+                    ?? DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, '');
+                const response = await fetchImpl(`${root}/models`, {
+                    headers: { authorization: `Bearer ${String(apiKey)}` },
+                });
+                const payload = await response.json();
+                const allIds = (payload.data ?? [])
+                    .map((entry) => entry.id)
+                    .filter((id) => typeof id === 'string');
+                // Runs always call /chat/completions, so embedding, audio, image,
+                // moderation, and legacy completion models would save a default
+                // that cannot execute. If filtering leaves nothing (an exotic local
+                // service), show everything rather than an empty menu.
+                const chatIds = allIds.filter((id) => !NON_CHAT_MODEL_PATTERN.test(id));
+                const ids = (chatIds.length > 0 ? chatIds : allIds).sort((a, b) => {
+                    const rank = (id) => (/^gpt/i.test(id) ? 0 : /^o\d/i.test(id) ? 1 : 2);
+                    return rank(a) - rank(b) || a.localeCompare(b);
+                });
+                models.push(...ids.map((id) => ({ provider, id })));
+            }
+            catch {
+                // No reachable model list for this provider; skip it.
+            }
+        }
+        return models;
+    };
+    const pickModel = async (kind) => {
+        const available = await collectAvailableModels();
+        if (available.length === 0) {
+            writeLine(streams.stdout, 'No models available yet — sign in to a provider first (menu 1).');
+            return;
+        }
+        const shown = available.slice(0, 30);
+        const labels = shown.map((entry) => `${entry.id} — ${entry.provider}`);
+        const typeItOption = labels.length;
+        labels.push('Type a model id…');
+        const footnote = available.length > shown.length
+            ? `  …and ${available.length - shown.length} more — pick "Type a model id…" to name one.`
+            : undefined;
+        const answer = await prompter.select('Available models:', labels, {
+            allowText: true,
+            ...(footnote ? { footnote } : {}),
+        });
+        if (answer.kind === 'back') {
+            return;
+        }
+        const parseTyped = (typed) => {
+            if (typed.includes(':')) {
+                const [providerPart, ...idParts] = typed.split(':');
+                const id = idParts.join(':').trim();
+                if ((providerPart === 'anthropic' || providerPart === 'openai') && id) {
+                    return { provider: providerPart, id };
+                }
+                writeLine(streams.stdout, 'Use provider:model, e.g. anthropic:claude-opus-5.');
                 return undefined;
             }
-            const envValue = String(processEnv[envVar]).trim();
-            if (envValue === chosen) {
+            // A typed id that appears in the collected list belongs to that
+            // provider, wherever the default currently points.
+            const listed = available.find((entry) => entry.id === typed);
+            const inferred = listed?.provider
+                ?? (state.provider !== 'demo' ? state.provider : available[0].provider);
+            return { provider: inferred, id: typed };
+        };
+        let choice;
+        if (answer.kind === 'text') {
+            choice = parseTyped(answer.text);
+        }
+        else if (answer.index === typeItOption) {
+            const typed = await prompter.ask('Model id (or provider:model): ');
+            choice = typed ? parseTyped(typed) : undefined;
+        }
+        else {
+            choice = shown[answer.index];
+        }
+        if (!choice) {
+            return;
+        }
+        if (kind === 'default') {
+            await switchDefaultProvider(choice.provider);
+            state.model = choice.id;
+            writeLine(streams.stdout, `Default model set to ${choice.id} (${choice.provider}).`);
+            // A soul's model pin outranks the config at run time, so a silent
+            // mismatch here would make this choice a no-op.
+            if (state.soulPath) {
+                try {
+                    const soul = parseSoul(await readFile(state.soulPath, 'utf8'), { seed: state.soulPath });
+                    if (soul.model && soul.model !== choice.id
+                        && (soul.provider === undefined || soul.provider === choice.provider)) {
+                        writeLine(streams.stdout, `Heads up: your default agent (${soul.agent.name}) pins model ${soul.model} in their soul, which outranks this choice at run time. Edit ${state.soulPath} or clear the agent (menu 3).`);
+                    }
+                }
+                catch {
+                    // A broken soul file surfaces when it is actually used.
+                }
+            }
+        }
+        else {
+            state.fallbackProvider = choice.provider;
+            state.fallbackModel = choice.id;
+            const openaiEndpoint = (state.provider === 'openai' ? state.baseUrl : undefined)
+                ?? state.credentials.openai?.baseUrl;
+            if (choice.provider === 'openai' && openaiEndpoint && openaiEndpoint !== DEFAULT_OPENAI_BASE_URL) {
+                state.fallbackBaseUrl = openaiEndpoint;
+            }
+            else {
+                delete state.fallbackBaseUrl;
+            }
+            if (choice.id === (state.model ?? defaultModelFor(state.provider)) && choice.provider === state.provider) {
+                writeLine(streams.stdout, 'Note: the fallback matches the default model, so it will not add resilience.');
+            }
+            writeLine(streams.stdout, `Fallback model set to ${choice.id} (${choice.provider}) — used when the default model errors mid-run.`);
+        }
+    };
+    const chooseModels = async () => {
+        const answer = await prompter.select(`Models — ${modelsSummary()}`, [
+            'Choose the default model',
+            'Choose a fallback model',
+            'Clear the fallback',
+            'Back',
+        ]);
+        if (answer.kind !== 'index' || answer.index === 3) {
+            return;
+        }
+        if (answer.index === 1) {
+            await pickModel('fallback');
+            return;
+        }
+        if (answer.index === 2) {
+            delete state.fallbackModel;
+            delete state.fallbackProvider;
+            writeLine(streams.stdout, 'Fallback cleared.');
+            return;
+        }
+        await pickModel('default');
+    };
+    const chooseAgent = async () => {
+        const answer = await prompter.select('Your default agent:', [
+            'Create a new agent',
+            'Use an existing soul file',
+            'No default agent',
+        ]);
+        if (answer.kind !== 'index') {
+            return;
+        }
+        if (answer.index === 2) {
+            delete state.soulPath;
+            writeLine(streams.stdout, 'Cleared — runs use the built-in default agent.');
+            return;
+        }
+        if (answer.index === 1) {
+            const soulAnswer = await prompter.ask('Path to the soul file: ');
+            if (!soulAnswer) {
+                return;
+            }
+            const resolved = path.resolve(cwd, soulAnswer);
+            try {
+                const soul = parseSoul(await readFile(resolved, 'utf8'), { seed: resolved });
+                state.soulPath = resolved;
+                writeLine(streams.stdout, `Loaded ${soul.agent.name} from ${resolved}.`);
+            }
+            catch (error) {
+                writeLine(streams.stdout, `Could not load that soul file: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return;
+        }
+        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);
+        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.`);
+    };
+    // Mirror the saved config's fallback so option 4 exercises the same
+    // failover a real run would perform.
+    const buildTestFallback = () => {
+        if (!state.fallbackModel || state.provider === 'demo') {
+            return undefined;
+        }
+        const fallbackProvider = (state.fallbackProvider ?? state.provider);
+        const envKey = (fallbackProvider === state.provider
+            ? readNonEmptyString(processEnv.STRATUS_API_KEY)
+            : undefined)
+            ?? readNonEmptyString(processEnv[defaultKeyEnvFor(fallbackProvider)]);
+        const credential = envKey ? undefined : state.credentials[fallbackProvider];
+        const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
+        const authToken = credential?.type === 'oauth_token' ? credential.value : undefined;
+        if (!apiKey && !authToken) {
+            return undefined;
+        }
+        return {
+            provider: fallbackProvider,
+            model: state.fallbackModel,
+            ...(fallbackProvider === 'openai'
+                ? {
+                    baseUrl: (credential?.type === 'api_key' ? credential.baseUrl : undefined)
+                        ?? state.fallbackBaseUrl
+                        ?? (state.provider === 'openai' ? state.baseUrl : undefined)
+                        ?? DEFAULT_OPENAI_BASE_URL,
+                }
+                : (() => {
+                    const url = (fallbackProvider === state.provider ? state.baseUrl : undefined)
+                        ?? (credential?.type === 'api_key' ? credential.baseUrl : undefined);
+                    return url ? { baseUrl: url } : {};
+                })()),
+            ...(apiKey ? { apiKey } : {}),
+            ...(authToken ? { authToken } : {}),
+        };
+    };
+    const buildTestRuntime = async () => {
+        let soul;
+        if (state.soulPath) {
+            try {
+                soul = parseSoul(await readFile(state.soulPath, 'utf8'), { seed: state.soulPath });
+            }
+            catch (error) {
+                writeLine(streams.stdout, `Warning: could not load the soul file (${error instanceof Error ? error.message : String(error)}); testing without it.`);
+            }
+        }
+        if (state.provider === 'demo') {
+            return { provider: 'demo', ...(soul ? { soul } : {}) };
+        }
+        // Mirror resolveRuntimeConfig exactly: environment keys (including the
+        // STRATUS_API_KEY_ENV selector) outrank the stored sign-in, and a
+        // stored key's bound endpoint is authoritative — so the inline test
+        // exercises precisely what a real run will use.
+        const keyEnv = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
+            ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
+            ?? state.apiKeyEnv
+            ?? defaultKeyEnvFor(state.provider);
+        const envKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
+            ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
+            ?? readNonEmptyString(processEnv[String(keyEnv)]);
+        const credential = envKey ? undefined : state.credentials[state.provider];
+        const boundUrl = credential?.type === 'api_key' ? credential.baseUrl : undefined;
+        const model = state.model ?? defaultModelFor(state.provider);
+        if (state.provider === 'anthropic') {
+            const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
+            const authToken = credential?.type === 'oauth_token' ? credential.value : undefined;
+            if (!apiKey && !authToken) {
+                writeLine(streams.stdout, 'You are not signed in yet — pick option 1 first (or export ANTHROPIC_API_KEY).');
                 return undefined;
             }
+            const fallback = buildTestFallback();
+            const anthropicUrl = boundUrl ?? state.baseUrl;
             return {
-                envVar,
-                envValue,
-                ...(flagName ? { flag: `${flagName} ${quoteShellArg(chosen)}` } : {}),
+                provider: 'anthropic',
+                model,
+                ...(anthropicUrl ? { baseUrl: anthropicUrl } : {}),
+                ...(apiKey ? { apiKey } : {}),
+                ...(authToken ? { authToken } : {}),
+                ...(state.systemPrompt ? { systemPrompt: state.systemPrompt } : {}),
+                ...(env.fetch ? { fetch: env.fetch } : {}),
+                ...(soul ? { soul } : {}),
+                ...(fallback ? { fallback } : {}),
             };
+        }
+        const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
+        if (!apiKey) {
+            writeLine(streams.stdout, 'You are not signed in yet — pick option 1 first (or export OPENAI_API_KEY).');
+            return undefined;
+        }
+        const fallback = buildTestFallback();
+        return {
+            provider: 'openai',
+            model,
+            baseUrl: boundUrl ?? state.baseUrl ?? DEFAULT_OPENAI_BASE_URL,
+            apiKey,
+            ...(state.systemPrompt ? { systemPrompt: state.systemPrompt } : {}),
+            ...(env.fetch ? { fetch: env.fetch } : {}),
+            ...(soul ? { soul } : {}),
+            ...(fallback ? { fallback } : {}),
         };
-        const warnAboutEnvOverrides = (conflicts) => {
-            for (const conflict of conflicts) {
-                writeLine(streams.stdout, `Note: ${conflict.envVar}=${conflict.envValue} is exported and takes precedence over the config file (run \`unset ${conflict.envVar}\` to clear it).`);
+    };
+    const testRun = async () => {
+        const runtime = await buildTestRuntime();
+        if (!runtime) {
+            return;
+        }
+        writeLine(streams.stdout, `Running a quick hello (${formatRuntimeBanner(runtime).replace('Starting Stratus Agent local loop with ', '')})…`);
+        try {
+            const session = await runSingleLoop('Say hello and introduce yourself in one short sentence.', streams, { events: false, runtime, env });
+            printSessionSummary(session, streams);
+            writeLine(streams.stdout);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeLine(streams.stdout, `Test run failed: ${message}`);
+            if (runtime.provider === 'anthropic' && runtime.authToken && /\b(401|403|429)\b/.test(message)) {
+                writeLine(streams.stdout, 'Subscription setup tokens are built for the Claude Code integration, which Stratus does not route through yet — sign in with an Anthropic API key instead (Providers menu → Claude → API key).');
             }
-            if (conflicts.some((conflict) => conflict.flag)) {
-                writeLine(streams.stdout, 'The suggested commands below include flags so they use what you just configured.');
+            else if (/\b429\b/.test(message)) {
+                writeLine(streams.stdout, 'A 429 means the provider rate-limited the request. On a new Anthropic account this usually means no purchased credits yet — check console.anthropic.com → Billing and Limits, then try again.');
             }
-            if (conflicts.length > 0) {
-                writeLine(streams.stdout);
+            else if (/\b(401|403)\b/.test(message)) {
+                writeLine(streams.stdout, 'The provider rejected the credential — re-run sign-in from the Providers menu.');
             }
+        }
+    };
+    const detectEnvOverride = (primary, legacy, chosen, flagName) => {
+        const envVar = readNonEmptyString(processEnv[primary])
+            ? primary
+            : readNonEmptyString(processEnv[legacy])
+                ? legacy
+                : undefined;
+        if (!envVar) {
+            return undefined;
+        }
+        const envValue = String(processEnv[envVar]).trim();
+        if (envValue === chosen) {
+            return undefined;
+        }
+        return {
+            envVar,
+            envValue,
+            ...(flagName ? { flag: `${flagName} ${quoteShellArg(chosen)}` } : {}),
         };
-        if (provider === 'demo') {
-            const conflicts = [
-                detectEnvOverride('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER', provider, '--provider'),
-            ].filter((conflict) => conflict !== undefined);
-            const extraFlags = conflicts.map((conflict) => ` ${conflict.flag}`).join('');
-            await writeFile(configPath, `${JSON.stringify({ provider: 'demo' }, null, 2)}\n`);
-            writeLine(streams.stdout);
-            writeLine(streams.stdout, `Wrote ${configPath}`);
-            writeLine(streams.stdout);
-            warnAboutEnvOverrides(conflicts);
-            writeLine(streams.stdout, 'You are ready to go — no API key needed. Try:');
-            writeLine(streams.stdout, `  stratus run${extraFlags}${runConfigFlag} "please use the echo tool"`);
-            writeLine(streams.stdout, '  stratus dashboard');
-            return 0;
+    };
+    const save = async () => {
+        let shadowConfigFlag = '';
+        const config = { provider: state.provider };
+        if (state.provider !== 'demo') {
+            config.model = state.model ?? defaultModelFor(state.provider);
+        }
+        if (state.provider === 'openai') {
+            config.baseUrl = state.baseUrl ?? state.credentials.openai?.baseUrl ?? DEFAULT_OPENAI_BASE_URL;
+        }
+        else if (state.provider === 'anthropic' && state.baseUrl) {
+            // A configured anthropic endpoint (a proxy) must survive re-running
+            // setup, or runs silently revert to the official endpoint.
+            config.baseUrl = state.baseUrl;
+        }
+        if (state.apiKeyEnv) {
+            config.apiKeyEnv = state.apiKeyEnv;
+        }
+        if (state.systemPrompt) {
+            config.systemPrompt = state.systemPrompt;
+        }
+        if (state.soulPath) {
+            config.soul = state.soulPath;
         }
-        const model = (await prompter.ask(`Model [${DEFAULT_OPENAI_MODEL}]: `)) || DEFAULT_OPENAI_MODEL;
-        const baseUrl = (await prompter.ask(`Base URL [${DEFAULT_OPENAI_BASE_URL}]: `)) || DEFAULT_OPENAI_BASE_URL;
-        const apiKeyEnv = (await prompter.ask('Environment variable holding your API key [OPENAI_API_KEY]: ')) || 'OPENAI_API_KEY';
-        const systemPrompt = await prompter.ask('System prompt (optional, Enter to skip): ');
-        const config = { provider, model, baseUrl, apiKeyEnv };
-        if (systemPrompt) {
-            config.systemPrompt = systemPrompt;
+        if (state.provider !== 'demo' && state.fallbackModel) {
+            config.fallbackModel = state.fallbackModel;
+            config.fallbackProvider = state.fallbackProvider ?? state.provider;
+            if (config.fallbackProvider === 'openai' && state.fallbackBaseUrl) {
+                config.fallbackBaseUrl = state.fallbackBaseUrl;
+            }
         }
+        await mkdir(path.dirname(configPath), { recursive: true });
         await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
-        const conflicts = [
-            detectEnvOverride('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER', provider, '--provider'),
-            detectEnvOverride('STRATUS_MODEL', 'STRATUSCLAW_MODEL', model, '--model'),
-            detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', baseUrl, '--base-url'),
-            // No run flag exists for the system prompt, so this one is warn-only.
-            detectEnvOverride('STRATUS_SYSTEM_PROMPT', 'STRATUSCLAW_SYSTEM_PROMPT', systemPrompt),
-        ].filter((conflict) => conflict !== undefined);
-        const extraFlags = conflicts.flatMap((conflict) => (conflict.flag ? [` ${conflict.flag}`] : [])).join('');
         writeLine(streams.stdout);
         writeLine(streams.stdout, `Wrote ${configPath}`);
+        // A project-local config in this directory outranks the global file for
+        // bare runs started here — say so, and make the suggested command pick
+        // the file that was just written.
+        if (configPath === globalConfigPath(env)) {
+            for (const shadow of [DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME]) {
+                const shadowPath = path.join(cwd, shadow);
+                try {
+                    await readFile(shadowPath, 'utf8');
+                    writeLine(streams.stdout, `Note: ${shadowPath} exists and takes precedence over the global config for runs started in this directory.`);
+                    writeLine(streams.stdout, 'The suggested commands below include --config so they use what you just saved.');
+                    shadowConfigFlag = ` --config ${quoteShellArg(configPath)}`;
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+        }
+        if (state.credentialsDirty) {
+            await saveCredentials(env, state.credentials);
+            writeLine(streams.stdout, `Saved your sign-in to ${credentialsPath(env)} (readable only by you).`);
+        }
         writeLine(streams.stdout);
-        warnAboutEnvOverrides(conflicts);
-        // Readiness must mirror resolveRuntimeConfig's key lookup: a direct
-        // STRATUS_API_KEY wins, then an exported *_API_KEY_ENV redirects which
-        // variable is read, and only then does the config file's apiKeyEnv apply.
-        const keyEnvOverrideVar = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-            ? 'STRATUS_API_KEY_ENV'
-            : readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
-                ? 'STRATUSCLAW_API_KEY_ENV'
-                : undefined;
-        const effectiveApiKeyEnv = keyEnvOverrideVar ? String(processEnv[keyEnvOverrideVar]).trim() : apiKeyEnv;
-        const directKeyVar = readNonEmptyString(processEnv.STRATUS_API_KEY)
-            ? 'STRATUS_API_KEY'
-            : readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
-                ? 'STRATUSCLAW_API_KEY'
-                : undefined;
-        if (keyEnvOverrideVar && effectiveApiKeyEnv !== apiKeyEnv) {
-            writeLine(streams.stdout, `Note: ${keyEnvOverrideVar}=${effectiveApiKeyEnv} is exported and takes precedence over the config file's apiKeyEnv,`);
-            writeLine(streams.stdout, `so \`stratus run\` will read ${effectiveApiKeyEnv}. Run \`unset ${keyEnvOverrideVar}\` to use ${apiKeyEnv} instead.`);
+        // Exported STRATUS_* variables outrank the config file, so warn when one
+        // would make `stratus run` behave differently from what was just saved.
+        const conflicts = [
+            detectEnvOverride('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER', state.provider, '--provider'),
+            ...(state.provider !== 'demo'
+                ? [detectEnvOverride('STRATUS_MODEL', 'STRATUSCLAW_MODEL', state.model ?? defaultModelFor(state.provider), '--model')]
+                : []),
+            ...(state.provider === 'openai'
+                ? [detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', state.baseUrl ?? DEFAULT_OPENAI_BASE_URL, '--base-url')]
+                : [detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', '')]),
+            detectEnvOverride('STRATUS_SYSTEM_PROMPT', 'STRATUSCLAW_SYSTEM_PROMPT', state.systemPrompt ?? ''),
+        ].filter((conflict) => conflict !== undefined);
+        for (const conflict of conflicts) {
+            writeLine(streams.stdout, `Note: ${conflict.envVar}=${conflict.envValue} is exported and takes precedence over the config file (run \`unset ${conflict.envVar}\` to clear it).`);
+        }
+        if (conflicts.some((conflict) => conflict.flag)) {
+            writeLine(streams.stdout, 'The suggested commands below include flags so they use what you just configured.');
+        }
+        if (conflicts.length > 0) {
             writeLine(streams.stdout);
         }
-        if (directKeyVar) {
-            writeLine(streams.stdout, `${directKeyVar} is set in your environment — you are ready to go. Try:`);
+        const extraFlags = conflicts.flatMap((conflict) => (conflict.flag ? [` ${conflict.flag}`] : [])).join('');
+        if (state.provider === 'demo') {
+            writeLine(streams.stdout, 'You are ready to go — no account needed. Try:');
         }
-        else if (processEnv[effectiveApiKeyEnv]) {
-            writeLine(streams.stdout, `${effectiveApiKeyEnv} is set in your environment — you are ready to go. Try:`);
+        else if (readNonEmptyString(processEnv.STRATUS_API_KEY)) {
+            writeLine(streams.stdout, 'STRATUS_API_KEY is exported and takes precedence over your saved sign-in. You are ready to go. Try:');
+        }
+        else if (state.credentials[state.provider]) {
+            writeLine(streams.stdout, `You are ${signInSummary()} — ready to go. Try:`);
         }
         else {
-            writeLine(streams.stdout, `${effectiveApiKeyEnv} is NOT set in your environment yet. Set it first:`);
-            writeLine(streams.stdout, `  export ${effectiveApiKeyEnv}=your-key`);
-            writeLine(streams.stdout);
-            writeLine(streams.stdout, 'Then try:');
+            const keyEnv = state.apiKeyEnv ?? defaultKeyEnvFor(state.provider);
+            if (readNonEmptyString(processEnv[keyEnv])) {
+                writeLine(streams.stdout, `${keyEnv} is set in your environment — you are ready to go. Try:`);
+            }
+            else {
+                writeLine(streams.stdout, 'You are NOT signed in yet — re-run `stratus setup` and pick option 1, or:');
+                writeLine(streams.stdout, `  export ${keyEnv}=your-key`);
+                writeLine(streams.stdout);
+                writeLine(streams.stdout, 'Then try:');
+            }
         }
-        writeLine(streams.stdout, `  stratus run${extraFlags}${runConfigFlag} "say hello"`);
+        writeLine(streams.stdout, `  stratus run${extraFlags}${runConfigFlag}${shadowConfigFlag} "say hello"`);
         writeLine(streams.stdout, '  stratus dashboard');
+    };
+    try {
+        writeLine(streams.stdout, 'Stratus Agent setup');
+        writeLine(streams.stdout, 'Pick a provider, sign in, and create your agent — all from this menu.');
+        if (envConfigVar && !command.configPath) {
+            writeLine(streams.stdout, `${envConfigVar} is set, so the config will be written to ${configPath}.`);
+        }
+        while (true) {
+            writeLine(streams.stdout);
+            const choice = await prompter.select('', [
+                `Providers            ${providersSummary()}`,
+                `Models               ${modelsSummary()}`,
+                `Agent                ${agentSummary()}`,
+                '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) {
+                break;
+            }
+            if (choice.index === 0) {
+                await chooseProviders();
+            }
+            else if (choice.index === 1) {
+                await chooseModels();
+            }
+            else if (choice.index === 2) {
+                await chooseAgent();
+            }
+            else if (choice.index === 3) {
+                await testRun();
+            }
+        }
+        await save();
         return 0;
     }
     finally {
@@ -1009,6 +2414,10 @@ export const runAgentNew = (command, streams) => {
         writeLine(streams.stdout, JSON.stringify(agent, null, 2));
         return 0;
     }
+    if (command.format === 'soul') {
+        streams.stdout.write(formatSoul({ agent, provider: 'anthropic', model: DEFAULT_ANTHROPIC_MODEL }));
+        return 0;
+    }
     writeLine(streams.stdout, `Say hello to ${agent.name}.`);
     writeLine(streams.stdout);
     writeLine(streams.stdout, `  id      ${agent.id}`);
@@ -1017,7 +2426,11 @@ export const runAgentNew = (command, streams) => {
         writeLine(streams.stdout, `  soul    ${agent.instructions}`);
     }
     writeLine(streams.stdout);
-    writeLine(streams.stdout, 'Definition (save this — soul files are coming in #13):');
+    writeLine(streams.stdout, 'Save this as a soul file and run it:');
+    writeLine(streams.stdout, `  stratus agent new --name ${quoteShellArg(agent.name)}${command.instructions ? ` --instructions ${quoteShellArg(command.instructions)}` : ''} --format soul > my-agent.md`);
+    writeLine(streams.stdout, '  stratus run --soul my-agent.md "hello"');
+    writeLine(streams.stdout);
+    writeLine(streams.stdout, 'Definition (JSON):');
     writeLine(streams.stdout, JSON.stringify(agent, null, 2));
     return 0;
 };
@@ -1082,7 +2495,9 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.format === 'json') {
             writeLine(streams.stdout, JSON.stringify({
                 provider: runtime.provider,
-                session,
+                // Replay state (Claude's raw thinking turns) stays in the stored
+                // session but never in user-facing output.
+                session: redactAnthropicRawTurns(session),
             }, null, 2));
             return 0;
         }