@stratusagent/cli 0.2.0 → 0.2.1

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';
@@ -141,12 +141,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 +275,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;
+            });
         },
     };
 };
@@ -874,7 +972,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 = createFileMemoryStore(memoryFilePath(runEnv));
     const tools = new ToolRegistry();
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
@@ -1108,7 +1208,7 @@ export const startDashboardServer = async (options) => {
             sendJson(response, 200, {
                 ok: true,
                 service: 'stratus-dashboard',
-                version: '0.2.0',
+                version: '0.2.1',
                 now: new Date().toISOString(),
             });
             return;
@@ -1165,25 +1265,191 @@ 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) => {
-    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.
+    // 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) => {
+            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 = [];
     let closed = false;
     readline.on('line', (line) => {
@@ -1204,28 +1470,63 @@ 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) {
+            streams.stdout.write(q);
+            return nextLine();
         },
-        isClosed() {
-            return closed && pendingLines.length === 0;
+        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);
         },
-        close() {
+        isClosed: () => closed && pendingLines.length === 0,
+        close: () => {
             readline.close();
         },
     };
@@ -1391,22 +1692,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 +1855,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 +1967,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 +2048,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;
@@ -1919,7 +2229,17 @@ export const runSetup = async (command, streams, env = {}) => {
             writeLine(streams.stdout);
         }
         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 && /\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).');
+            }
+            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) => {
@@ -2054,33 +2374,29 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         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;