@stratusagent/cli 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { appendFile, chmod, mkdir, 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';
@@ -10,7 +10,30 @@ import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@s
 import { createLocalCommandExecutor, defineLocalCommandTool, } from '@stratusagent/executor-local';
 import { createOpenAICompatibleProvider, createProviderResponseBuilder, defineProvider, } from '@stratusagent/providers';
 import { createAnthropicProvider, DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
-import { createRememberTool, defineAgent, formatSoul, parseSoul, } from '@stratusagent/agents';
+import { createClaudeCodeProvider } from '@stratusagent/provider-claude-code';
+import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
+export const CLI_VERSION = '0.2.2';
+// The agent every run uses when no soul is configured. A Stratus agent is
+// a Stratus agent — never "the model" — whichever provider serves it.
+const DEFAULT_STRATUS_AGENT = {
+    id: 'stratus',
+    name: 'Stratus',
+    instructions: 'You are Stratus, a personal agent on the Stratus Agent platform. Be warm, direct, and concise. When asked who or what you are, you are Stratus — a Stratus agent — regardless of which model is serving the conversation.',
+};
+// Unsouled runs used to remember facts under a per-provider default agent.
+// Stratus inherits all of them: reads for the built-in agent also return
+// entries stored under the legacy ids, while new facts land under 'stratus'.
+const LEGACY_DEFAULT_AGENT_IDS = ['demo-agent', 'anthropic-agent', 'openai-agent'];
+const withLegacyDefaultMemories = (store) => ({
+    append: (agentId, content, metadata) => store.append(agentId, content, metadata),
+    async list(agentId) {
+        if (agentId !== DEFAULT_STRATUS_AGENT.id) {
+            return store.list(agentId);
+        }
+        const batches = await Promise.all([DEFAULT_STRATUS_AGENT.id, ...LEGACY_DEFAULT_AGENT_IDS].map((id) => store.list(id)));
+        return batches.flat().sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    },
+});
 const DEFAULT_CONFIG_FILENAME = 'stratus.config.json';
 const LEGACY_CONFIG_FILENAME = 'stratusclaw.config.json';
 const STRATUS_HOME_DIRNAME = '.stratus';
@@ -141,12 +164,102 @@ const createDemoProvider = () => defineProvider({
         return builder.done();
     },
 });
-const MEMORY_FILE_RELATIVE_PATH = path.join('.stratus', 'memory.jsonl');
+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 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.
+// 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;
@@ -185,8 +298,16 @@ export const createFileMemoryStore = (filePath) => {
             return entry;
         },
         async list(agentId) {
-            const entries = await readEntries();
-            return entries.filter((entry) => entry.agentId === 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;
+            });
         },
     };
 };
@@ -824,6 +945,16 @@ const createRuntimeProvider = (config, onFallback) => {
         return createFallbackWrappedProvider(primary, fallbackProvider, onFallback ?? (() => { }));
     }
     if (config.provider === 'anthropic') {
+        // Subscription setup tokens are only honored inside the Claude Code
+        // harness, so they route through the Agent SDK runtime; API keys use
+        // the raw Messages API.
+        if (config.authToken && !config.apiKey) {
+            return createClaudeCodeProvider({
+                authToken: config.authToken,
+                model: config.model,
+                ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
+            });
+        }
         return createAnthropicProvider({
             model: config.model,
             ...(config.apiKey ? { apiKey: config.apiKey } : {}),
@@ -874,7 +1005,9 @@ const createApprovalPolicy = (mode, streams, env) => {
     };
 };
 export const runSingleLoop = async (prompt, streams, options) => {
-    const memory = createFileMemoryStore(path.join(readWorkingDirectory(options.env ?? {}), MEMORY_FILE_RELATIVE_PATH));
+    const runEnv = options.env ?? {};
+    await migrateLegacyMemory(runEnv);
+    const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(runEnv)));
     const tools = new ToolRegistry();
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
@@ -905,25 +1038,9 @@ export const runSingleLoop = async (prompt, streams, options) => {
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
     });
     await runner.initialize();
-    // 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.',
-                });
+    // A soul is a full identity — without one, every provider serves the
+    // same built-in Stratus persona.
+    const agent = options.runtime.soul?.agent ?? DEFAULT_STRATUS_AGENT;
     const metadata = options.runtime.provider === 'demo'
         ? { provider: 'demo' }
         : {
@@ -1108,7 +1225,7 @@ export const startDashboardServer = async (options) => {
             sendJson(response, 200, {
                 ok: true,
                 service: 'stratus-dashboard',
-                version: '0.2.0',
+                version: CLI_VERSION,
                 now: new Date().toISOString(),
             });
             return;
@@ -1164,26 +1281,227 @@ export const startDashboardServer = async (options) => {
 // Printed commands must survive copy-paste into a shell, so anything outside
 // the safe character set gets single-quoted.
 const quoteShellArg = (value) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
-const createSetupPrompter = (streams, env) => {
-    const input = env.setupInput ?? process.stdin;
-    // On a real TTY the readline must own the terminal so we can suppress the
-    // echo of pasted secrets; piped input (tests, scripts) never echoes.
+// The fixed header drawn at the top of every interactive screen.
+const stratusHeaderLines = () => {
+    const title = 'Stratus Agent';
+    const version = `v${CLI_VERSION}`;
+    const gap = '   ';
+    const content = `  ${title}${gap}${version}  `;
+    return [
+        `\u001b[2m╭${'─'.repeat(content.length)}╮\u001b[0m`,
+        `\u001b[2m│\u001b[0m  \u001b[1m${title}\u001b[0m${gap}\u001b[2m${version}\u001b[0m  \u001b[2m│\u001b[0m`,
+        `\u001b[2m╰${'─'.repeat(content.length)}╯\u001b[0m`,
+    ];
+};
+const createSetupPrompter = (streams, env, view) => {
+    // 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;
-    const readline = createInterface(interactive
-        ? { input, output: process.stdout, terminal: true }
-        : { input, terminal: false });
-    let secretMode = false;
     if (interactive) {
-        const internal = readline;
-        const original = internal._writeToOutput?.bind(readline);
-        internal._writeToOutput = (chunk) => {
-            if (!secretMode) {
-                original?.(chunk);
-            }
-            // Secrets: swallow the echo entirely — the prompt itself is written
-            // through streams.stdout before secretMode turns on.
+        let closed = false;
+        process.stdin.once('end', () => {
+            closed = true;
+        });
+        const question = (prompt, secret, prefill) => {
+            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());
+                });
+                if (prefill) {
+                    // Pre-typed and editable: backspace over it or press Enter to keep.
+                    readline.write(prefill);
+                }
+            });
+        };
+        // Each menu replaces the screen: clear, draw the header, carry over the
+        // most recent status lines, then the menu itself.
+        const drawScreen = (out) => {
+            out.write('\u001b[2J\u001b[H');
+            for (const line of view?.header() ?? []) {
+                out.write(`${line}\n`);
+            }
+            const notices = view?.consumeNotices() ?? [];
+            if (notices.length > 0) {
+                for (const line of notices) {
+                    out.write(`\u001b[2m${line}\u001b[0m\n`);
+                }
+                out.write('\n');
+            }
+        };
+        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 {
+                    drawScreen(out);
+                    if (heading.length > 0) {
+                        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, opts) => question(q, false, opts?.prefill),
+            askSecret: (q) => question(q, true),
+            isInteractive: () => 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 = [];
     let closed = false;
     readline.on('line', (line) => {
@@ -1204,28 +1522,65 @@ const createSetupPrompter = (streams, env) => {
         }
         return (pendingLines.shift() ?? '').trim();
     };
-    return {
-        async ask(question) {
-            streams.stdout.write(question);
-            return nextLine();
-        },
-        async askSecret(question) {
-            streams.stdout.write(question);
-            secretMode = true;
-            try {
-                return await nextLine();
+    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' };
+                }
+                return { kind: 'index', index: defaultIndex };
             }
-            finally {
-                secretMode = false;
-                if (interactive) {
-                    streams.stdout.write('\n');
+            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;
+            }
+            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, opts) {
+            streams.stdout.write(q);
+            const line = await nextLine();
+            return line || (opts?.prefill ?? '');
+        },
+        async askSecret(q) {
+            // Piped input never echoes, so plain reads are safe here.
+            streams.stdout.write(q);
+            return nextLine();
         },
-        isClosed() {
-            return closed && pendingLines.length === 0;
+        isInteractive: () => false,
+        async select(heading, options, opts = {}) {
+            if (options.length === 0) {
+                return { kind: 'back' };
+            }
+            return selectPlain(heading, options, opts);
         },
-        close() {
+        isClosed: () => closed && pendingLines.length === 0,
+        close: () => {
             readline.close();
         },
     };
@@ -1306,6 +1661,31 @@ export const runSetup = async (command, streams, env = {}) => {
             writeLine(streams.stderr, `Warning: could not read ${configPath} (${error instanceof Error ? error.message : String(error)}); starting fresh.`);
         }
     }
+    // Interactive mode is a screen-based interface: every menu clears and
+    // redraws under a fixed header, and status lines printed between menus
+    // are carried onto the next screen (dimmed) so nothing is missed.
+    const interactive = env.setupInput === undefined && process.stdin.isTTY === true;
+    const baseStreams = streams;
+    const recentNotices = [];
+    if (interactive) {
+        streams = {
+            stderr: baseStreams.stderr,
+            stdout: {
+                write(chunk) {
+                    for (const raw of String(chunk).split('\n')) {
+                        const line = raw.trimEnd();
+                        if (line.trim().length > 0) {
+                            recentNotices.push(line);
+                            if (recentNotices.length > 8) {
+                                recentNotices.shift();
+                            }
+                        }
+                    }
+                    return baseStreams.stdout.write(chunk);
+                },
+            },
+        };
+    }
     const state = {
         provider: existing.provider ?? 'anthropic',
         ...(existing.model ? { model: existing.model } : {}),
@@ -1323,7 +1703,10 @@ export const runSetup = async (command, streams, env = {}) => {
         credentials: await loadCredentials(env),
         credentialsDirty: false,
     };
-    const prompter = createSetupPrompter(streams, env);
+    const prompter = createSetupPrompter(baseStreams, env, {
+        header: stratusHeaderLines,
+        consumeNotices: () => recentNotices.splice(0),
+    });
     const defaultModelFor = (provider) => provider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL;
     const defaultKeyEnvFor = (provider) => provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
     const credentialLabel = (credential) => credential.type === 'oauth_token' ? 'Claude subscription' : 'API key';
@@ -1391,22 +1774,22 @@ export const runSetup = async (command, streams, env = {}) => {
     };
     const signInAnthropic = async () => {
         const signedIn = state.credentials.anthropic !== undefined;
-        const answer = await prompter.ask('How should Stratus connect to Claude?\n'
-            + '  1) Claude subscription (Pro/Max) — sign in through Claude Code, no per-token cost\n'
-            + '  2) Anthropic API key — pay per use (console.anthropic.com)\n'
-            + '  3) Skip for now\n'
-            + (signedIn ? '  4) Sign out\n' : '')
-            + 'Choose [1]: ');
-        if (signedIn && (answer === '4' || /^sign ?out$/i.test(answer))) {
+        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 === '3' || /^skip$/i.test(answer)) {
+        if (answer.kind !== 'index' || answer.index === 2) {
             return;
         }
-        if (answer === '2' || /^(api|key)/i.test(answer)) {
+        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.');
@@ -1554,21 +1937,21 @@ export const runSetup = async (command, streams, env = {}) => {
         }
     };
     const chooseProviders = async () => {
-        const answer = await prompter.ask('Providers — sign in to one or more:\n'
-            + `  1) Claude (Anthropic) — ${providerSignInStatus('anthropic')}\n`
-            + `  2) OpenAI-compatible — ${providerSignInStatus('openai')}\n`
-            + '  3) Demo — built-in fake model, offline, no account\n'
-            + '  4) Back\n'
-            + 'Choose [1]: ');
-        if (answer === '4' || /^back$/i.test(answer)) {
+        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 === '3' || /^demo$/i.test(answer)) {
+        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 === '2' || /^openai$/i.test(answer)) {
+        if (answer.index === 1) {
             await signInOpenAI();
             if (state.credentials.openai) {
                 await maybeSwitchDefault('openai');
@@ -1666,40 +2049,46 @@ export const runSetup = async (command, streams, env = {}) => {
             return;
         }
         const shown = available.slice(0, 30);
-        const lines = shown.map((entry, index) => `  ${index + 1}) ${entry.id} — ${entry.provider}`);
-        if (available.length > shown.length) {
-            lines.push(`  …and ${available.length - shown.length} more — type the model id instead.`);
-        }
-        const answer = await prompter.ask(`Available models:\n${lines.join('\n')}\nChoose a number, or type a model id [1]: `);
-        let choice;
-        if (!answer) {
-            choice = shown[0];
-        }
-        else if (/^\d+$/.test(answer)) {
-            choice = shown[Number(answer) - 1];
-            if (!choice) {
-                writeLine(streams.stdout, `Pick a number between 1 and ${shown.length}.`);
-                return;
-            }
+        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;
         }
-        else if (answer.includes(':')) {
-            const [providerPart, ...idParts] = answer.split(':');
-            const id = idParts.join(':').trim();
-            if ((providerPart === 'anthropic' || providerPart === 'openai') && id) {
-                choice = { provider: providerPart, id };
-            }
-            else {
+        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;
+                return undefined;
             }
-        }
-        else {
             // 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 === answer);
+            const listed = available.find((entry) => entry.id === typed);
             const inferred = listed?.provider
                 ?? (state.provider !== 'demo' ? state.provider : available[0].provider);
-            choice = { provider: inferred, id: answer };
+            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;
@@ -1741,39 +2130,42 @@ export const runSetup = async (command, streams, env = {}) => {
         }
     };
     const chooseModels = async () => {
-        const answer = await prompter.ask(`Models — ${modelsSummary()}\n`
-            + '  1) Choose the default model\n'
-            + '  2) Choose a fallback model\n'
-            + '  3) Clear the fallback\n'
-            + '  4) Back\n'
-            + 'Choose [1]: ');
-        if (answer === '2') {
+        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 === '3') {
+        if (answer.index === 2) {
             delete state.fallbackModel;
             delete state.fallbackProvider;
             writeLine(streams.stdout, 'Fallback cleared.');
             return;
         }
-        if (answer === '4' || /^back$/i.test(answer)) {
-            return;
-        }
         await pickModel('default');
     };
     const chooseAgent = async () => {
-        const answer = await prompter.ask('Your default agent:\n'
-            + '  1) Create a new agent\n'
-            + '  2) Use an existing soul file\n'
-            + '  3) No default agent\n'
-            + 'Choose [1]: ');
-        if (answer === '3' || /^none$/i.test(answer)) {
+        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 === '2') {
+        if (answer.index === 1) {
             const soulAnswer = await prompter.ask('Path to the soul file: ');
             if (!soulAnswer) {
                 return;
@@ -1917,9 +2309,23 @@ export const runSetup = async (command, streams, env = {}) => {
             const session = await runSingleLoop('Say hello and introduce yourself in one short sentence.', streams, { events: false, runtime, env });
             printSessionSummary(session, streams);
             writeLine(streams.stdout);
+            if (prompter.isInteractive()) {
+                await prompter.ask('Press Enter to return to the menu… ');
+                recentNotices.length = 0;
+            }
         }
         catch (error) {
-            writeLine(streams.stdout, `Test run failed: ${error instanceof Error ? error.message : String(error)}`);
+            const message = error instanceof Error ? error.message : String(error);
+            writeLine(streams.stdout, `Test run failed: ${message}`);
+            if (runtime.provider === 'anthropic' && runtime.authToken && /Claude Code|\b(401|403|429)\b/.test(message)) {
+                writeLine(streams.stdout, 'Subscription runs go through Claude Code. Make sure it is installed (npm install -g @anthropic-ai/claude-code) and signed in (run `claude`), or sign in with an Anthropic API key instead (Providers menu → Claude → API key).');
+            }
+            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.');
+            }
+            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) => {
@@ -2047,40 +2453,38 @@ export const runSetup = async (command, streams, env = {}) => {
         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 (!interactive) {
+            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.ask(`  1) Providers            ${providersSummary()}\n`
-                + `  2) Models               ${modelsSummary()}\n`
-                + `  3) Agent                ${agentSummary()}\n`
-                + '  4) Test run             say hello with the current settings\n'
-                + '  5) Save & finish\n'
-                + 'Choose [1-5]: ');
-            if (prompter.isClosed() && choice === '') {
+            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 === '1') {
+            if (choice.index === 0) {
                 await chooseProviders();
             }
-            else if (choice === '2') {
+            else if (choice.index === 1) {
                 await chooseModels();
             }
-            else if (choice === '3') {
+            else if (choice.index === 2) {
                 await chooseAgent();
             }
-            else if (choice === '4') {
+            else if (choice.index === 3) {
                 await testRun();
             }
-            else if (choice === '5' || /^(save|done|finish|q(uit)?)$/i.test(choice)) {
-                break;
-            }
-            else {
-                writeLine(streams.stdout, 'Pick a number between 1 and 5.');
-            }
         }
         await save();
         return 0;
@@ -2089,7 +2493,127 @@ export const runSetup = async (command, streams, env = {}) => {
         prompter.close();
     }
 };
-export const runAgentNew = (command, streams) => {
+export const runAgentNew = async (command, streams, env = {}) => {
+    // On a real terminal, creating an agent is the same guided experience as
+    // setup: a headed screen, a prefilled (editable) name, a personality, and
+    // an offer to make them the default. Scripted formats and piped input
+    // keep the plain one-shot output.
+    const interactive = env.setupInput === undefined
+        && process.stdin.isTTY === true
+        && command.format === 'text';
+    if (interactive) {
+        const prompter = createSetupPrompter(streams, env, {
+            header: stratusHeaderLines,
+            consumeNotices: () => [],
+        });
+        try {
+            streams.stdout.write('\u001b[2J\u001b[H');
+            for (const line of stratusHeaderLines()) {
+                writeLine(streams.stdout, line);
+            }
+            writeLine(streams.stdout);
+            const suggested = command.name ?? generateAgentName();
+            const name = (await prompter.ask('Choose your name: ', { prefill: suggested })) || suggested;
+            const instructions = await prompter.ask('Describe their personality (Enter for a starter you can edit later): ', ...(command.instructions ? [{ prefill: command.instructions }] : []));
+            const persona = instructions || DEFAULT_SOUL_STARTER;
+            let agent = defineAgent({ name, instructions: persona });
+            // Frontmatter pins what a run from this directory would actually use:
+            // env vars outrank the active config file (project-local or explicit
+            // first, global otherwise), and no provider anywhere falls back to
+            // demo — the exact precedence of stratus run. Demo produces no pin
+            // at all: the soul keeps following the machine's configuration
+            // instead of demanding credentials nothing has signed in for.
+            const processEnv = readProcessEnv(env);
+            const configLocation = await resolveConfigLocation({}, env);
+            // Creating an agent must not be blocked by a broken config — it only
+            // feeds the soul's provider/model hint, so fall back to defaults.
+            let activeConfig = {};
+            if (configLocation) {
+                try {
+                    activeConfig = await loadConfigFile(configLocation.path);
+                }
+                catch (error) {
+                    writeLine(streams.stdout, `Note: ignoring unreadable config ${configLocation.path} (${error instanceof Error ? error.message : String(error)}).`);
+                }
+            }
+            const soulProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
+                ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
+                ?? activeConfig.provider
+                ?? 'demo';
+            // The active config's model was written for the provider named in
+            // that config; it only travels into the soul when they still match.
+            const configModelApplies = (activeConfig.provider ?? 'openai') === soulProvider;
+            const soulModel = readNonEmptyString(processEnv.STRATUS_MODEL)
+                ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL)
+                ?? (configModelApplies ? activeConfig.model : undefined)
+                ?? (soulProvider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
+            const soulPin = soulProvider !== 'demo' ? { provider: soulProvider, model: soulModel } : {};
+            // The name stays theirs, but the id — the soul filename and the
+            // memory key — must be unique: the suggestion pool is small, so a
+            // repeat name would otherwise silently overwrite an earlier agent's
+            // soul and share their memory. 'wx' makes each claim atomic; on a
+            // collision the id gets a fresh suffix and we try again.
+            await mkdir(agentsDirPath(env), { recursive: true });
+            const baseId = agent.id;
+            let soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
+            for (;;) {
+                try {
+                    await writeFile(soulPath, formatSoul({ agent, ...soulPin }), { flag: 'wx' });
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST') {
+                        throw error;
+                    }
+                    agent = defineAgent({ id: `${baseId}-${randomUUID().slice(0, 4)}`, name, instructions: persona });
+                    soulPath = path.join(agentsDirPath(env), `${agent.id}.md`);
+                }
+            }
+            const makeDefault = await prompter.select(`Make ${agent.name} your default agent?`, [
+                'Yes — every stratus run talks to them',
+                'Not now',
+            ]);
+            let madeDefault = false;
+            if (makeDefault.kind === 'index' && makeDefault.index === 0) {
+                // The default agent is a machine-wide setting, so it lands in the
+                // global config even when a project config is active here.
+                let globalConfig;
+                try {
+                    globalConfig = await loadConfigFile(globalConfigPath(env));
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT') {
+                        globalConfig = {};
+                    }
+                    else {
+                        // A malformed config is recoverable by hand — never overwrite it.
+                        writeLine(streams.stdout, `Could not read ${globalConfigPath(env)} (${error instanceof Error ? error.message : String(error)}), so it was left untouched. Fix it, then make ${agent.name} the default from stratus setup.`);
+                    }
+                }
+                if (globalConfig !== undefined) {
+                    const config = { ...globalConfig, provider: globalConfig.provider ?? soulProvider, soul: soulPath };
+                    await mkdir(path.dirname(globalConfigPath(env)), { recursive: true });
+                    await writeFile(globalConfigPath(env), `${JSON.stringify(config, null, 2)}\n`);
+                    madeDefault = true;
+                    if (configLocation && configLocation.path !== globalConfigPath(env)) {
+                        writeLine(streams.stdout, `Note: ${configLocation.path} takes precedence over the global config for runs started in this directory.`);
+                    }
+                }
+            }
+            writeLine(streams.stdout);
+            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.`);
+            writeLine(streams.stdout);
+            writeLine(streams.stdout, 'Try:');
+            writeLine(streams.stdout, madeDefault
+                ? '  stratus run "introduce yourself"'
+                : `  stratus run --soul ${quoteShellArg(soulPath)} "introduce yourself"`);
+            return 0;
+        }
+        finally {
+            prompter.close();
+        }
+    }
     const agent = defineAgent({
         ...(command.name ? { name: command.name } : {}),
         ...(command.instructions ? { instructions: command.instructions } : {}),
@@ -2157,7 +2681,7 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
             return 0;
         }
         if (command.command === 'agent-new') {
-            return runAgentNew(command, streams);
+            return runAgentNew(command, streams, resolvedEnv);
         }
         if (command.command === 'setup') {
             return runSetup(command, streams, resolvedEnv);