@stratusagent/cli 0.9.0 → 0.9.2

package/dist/index.js

@@ -17,16 +17,69 @@ import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
 import { loadPlugins } from '@stratusagent/plugins';
 import { createFileCommandWhitelist, createPermissionPolicy, describeCommandScope, } from '@stratusagent/permissions';
 import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
+import { DEFAULT_CODEX_MODEL } from '@stratusagent/provider-codex';
 import { canonicalDestination, createForgetTool, createRecallTool, createRememberTool, defineAgent, describeCadence, describeSchedule, FORGET_TOOL_NAME, MEMORY_TOOL_NAME, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, installSkillsFromDirectory, loadOperatorSkills, loadRosterSouls, skillsDirPath, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, resolveConfiguredSoul, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, servedRuntimes, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, } from '@stratusagent/state';
-import { installService, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, uninstallService, } from "./service.js";
-export { installService, launchdPlist, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, systemdUnit, uninstallService, SERVICE_LABEL, } from "./service.js";
+import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, installSkillsFromDirectory, loadOperatorSkills, loadRosterSouls, skillsDirPath, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, resolveConfiguredSoul, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, servedRuntimes, CREDENTIAL_PROVIDER_NAMES, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, newerStateMessage, pendingStateMigrations, readStateStamp, runStateMigrations, STATE_SCHEMA_VERSION, } from '@stratusagent/state';
+import { installService, readServiceCommand, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, uninstallService, } from "./service.js";
+export { installService, launchdPlist, readServiceCommand, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, systemdUnit, uninstallService, SERVICE_LABEL, } from "./service.js";
 import { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, readRecentRecords, tailLog, } from "./logs.js";
 export { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, parseLogLines, readRecentRecords, tailLog, } from "./logs.js";
 // The shared state package owns config resolution, credentials, memory, and
 // provider wiring now (the gateway uses the same code); the CLI re-exports
 // its historical surface so existing importers keep working.
 export { createFileMemoryStore } from '@stratusagent/state';
+/** How long `stratus update` waits for npm to answer a version lookup. */
+export const VERSION_LOOKUP_TIMEOUT_MS = 15_000;
+const defaultPackageVersionFetcher = async (packageName) => {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['view', packageName, 'version'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: npmNeedsShell(process.platform),
+        });
+        let stdout = '';
+        let settled = false;
+        const finish = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        // An unreachable registry must degrade to "unknown", never hang the
+        // update on someone's terminal.
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(undefined);
+        }, VERSION_LOOKUP_TIMEOUT_MS);
+        timer.unref?.();
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+        child.once('error', () => finish(undefined));
+        child.once('close', (code) => finish(code === 0 && stdout.trim().length > 0 ? stdout.trim() : undefined));
+    });
+};
+/**
+ * Dotted-numeric comparison, enough for this package's own versions:
+ * positive when `a` is newer than `b`. Anything unparseable in a segment
+ * counts as zero rather than throwing — a weird registry answer must not
+ * crash the update that would fix things.
+ */
+export const compareVersions = (a, b) => {
+    const parse = (value) => value.trim().replace(/^v/, '').split('.').map((part) => {
+        const numeric = Number.parseInt(part, 10);
+        return Number.isInteger(numeric) ? numeric : 0;
+    });
+    const left = parse(a);
+    const right = parse(b);
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+};
 /**
  * Whether spawning npm needs a shell on this platform.
  *
@@ -70,7 +123,7 @@ const defaultPackageInstaller = async (packages) => {
         });
     });
 };
-export const CLI_VERSION = '0.9.0';
+export const CLI_VERSION = '0.9.2';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 /**
  * The range every package declares in its `engines` field. Two floors, not
@@ -130,6 +183,8 @@ Usage:
   stratus schedules
   stratus schedules cancel <id>
   stratus doctor
+  stratus update
+  stratus update --check
   stratus service install
   stratus service status
   stratus logs -f
@@ -190,6 +245,14 @@ Commands:
   doctor           Show what a run would use right now — provider, model, soul —
                    and which file or environment variable decided each, then
                    flag anything that would surprise you (--format json)
+  update           The whole upgrade dance, in the order that cannot lose
+                   data: stop stratusd, upgrade the package from npm, run
+                   pending state migrations, rewrite the service unit with
+                   current node/entrypoint paths, restart. --check reports
+                   what it would do without doing any of it (exits 1 when
+                   something is actionable). Works offline too — an
+                   unreachable npm skips the upgrade but still migrates and
+                   repairs the unit
   dashboard        Open the web dashboard: finds a running daemon (or starts one),
                    mints a single-use sign-in link, and opens your browser at it.
                    Needs @stratusagent/control-api and @stratusagent/dashboard
@@ -203,8 +266,8 @@ Agent options:
 Options:
   --prompt, -p     Prompt to send to the local agent loop
   --stdin          Read the prompt from stdin
-  --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)
+  --provider       Provider to use: anthropic, openai, codex, or demo
+  --model          Model name for real providers (anthropic default: ${DEFAULT_ANTHROPIC_MODEL}, openai default: gpt-4.1-mini, codex default: ${DEFAULT_CODEX_MODEL})
   --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)
@@ -564,6 +627,23 @@ export const parseCommand = (argv, env = {}) => {
         }
         return { command: 'doctor', format, ...(configPath ? { configPath } : {}) };
     }
+    if (command === 'update') {
+        let check = false;
+        for (const token of rest) {
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--check') {
+                check = true;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return { command: 'update', check };
+    }
     if (command === 'service') {
         const action = rest[0];
         if (action === '--help' || action === '-h' || action === undefined) {
@@ -1003,30 +1083,42 @@ export const warnOnCredentialOverride = async (runtime, streams, env = {}) => {
     if (runtime.provider === 'demo') {
         return;
     }
-    const stored = (await loadCredentials(env)).anthropic;
-    if (stored?.type !== 'oauth_token') {
-        return;
-    }
+    const credentials = await loadCredentials(env);
+    const processEnv = readProcessEnv(env);
     // The resolver records the variable that actually won — guessing it here
     // would name the wrong one whenever a custom apiKeyEnv supplied the key,
     // sending the reader to unset something that was never the cause.
-    const primary = runtime.provider === 'anthropic' && runtime.apiKey ? runtime.apiKeyEnvVar : undefined;
-    // A fallback demoted the same way costs exactly as much, and only bites
-    // once the primary is already failing — the worst moment to discover it.
-    // The fallback path consults the provider's own conventional variable.
-    const processEnv = readProcessEnv(env);
-    const fallbackVar = runtime.fallback?.provider === 'anthropic'
-        && runtime.fallback.apiKey !== undefined
-        && readNonEmptyString(processEnv.ANTHROPIC_API_KEY) === runtime.fallback.apiKey
-        ? 'ANTHROPIC_API_KEY'
+    const primaryOverride = runtime.apiKey !== undefined
+        ? { provider: runtime.provider, envVar: runtime.apiKeyEnvVar }
         : undefined;
-    const culprit = primary ?? fallbackVar;
-    if (!culprit) {
-        return;
+    // Both subscription sign-ins demote the same way: a Claude setup token
+    // and the codex ChatGPT marker each lose to an environment API key, and
+    // the run otherwise looks identical while billing per token.
+    for (const target of ['anthropic', 'codex']) {
+        if (credentials[target]?.type !== 'oauth_token') {
+            continue;
+        }
+        const planName = target === 'anthropic'
+            ? 'Claude subscription sign-in'
+            : 'ChatGPT (codex login) sign-in';
+        const primary = primaryOverride?.provider === target ? primaryOverride.envVar : undefined;
+        // A fallback demoted the same way costs exactly as much, and only bites
+        // once the primary is already failing — the worst moment to discover it.
+        // The fallback path consults the provider's own conventional variable.
+        const conventionalVar = defaultApiKeyEnvName(target);
+        const fallbackVar = runtime.fallback?.provider === target
+            && runtime.fallback.apiKey !== undefined
+            && readNonEmptyString(processEnv[conventionalVar]) === runtime.fallback.apiKey
+            ? conventionalVar
+            : undefined;
+        const culprit = primary ?? fallbackVar;
+        if (!culprit) {
+            continue;
+        }
+        writeLine(streams.stderr, `Warning: ${culprit} in your environment outranks the ${planName} saved by \`stratus setup\`, `
+            + `so ${primary ? 'this run is' : 'a fallback retry would be'} billed per token instead of through your plan. `
+            + 'Unset it to use the subscription, or run `stratus doctor` to see everything that is being overridden.');
     }
-    writeLine(streams.stderr, `Warning: ${culprit} in your environment outranks the Claude subscription sign-in saved by \`stratus setup\`, `
-        + `so ${primary ? 'this run is' : 'a fallback retry would be'} billed per token instead of through your plan. `
-        + 'Unset it to use the subscription, or run `stratus doctor` to see everything that is being overridden.');
 };
 const createApprovalPolicy = (mode, streams, env, ask) => {
     if (mode === 'always') {
@@ -1972,15 +2064,21 @@ export const runSetup = async (command, streams, env = {}) => {
         header: stratusHeaderLines,
         consumeNotices: () => recentNotices.splice(0),
     });
-    const defaultModelFor = (provider) => provider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL;
+    const defaultModelFor = (provider) => provider === 'openai'
+        ? DEFAULT_OPENAI_MODEL
+        : provider === 'codex'
+            ? DEFAULT_CODEX_MODEL
+            : DEFAULT_ANTHROPIC_MODEL;
     // Widened to CliProviderName only so setup can ask about the provider it
     // currently has selected, `demo` included; the rule itself is the shared one.
-    const defaultKeyEnvFor = (provider) => defaultApiKeyEnvName(provider === 'openai' ? 'openai' : 'anthropic');
-    const credentialLabel = (credential) => credential.type === 'oauth_token' ? 'Claude subscription' : 'API key';
+    const defaultKeyEnvFor = (provider) => defaultApiKeyEnvName(provider === 'demo' ? 'anthropic' : provider);
+    const credentialLabel = (provider, credential) => credential.type === 'oauth_token'
+        ? (provider === 'codex' ? 'ChatGPT sign-in' : 'Claude subscription')
+        : 'API key';
     const providerSignInStatus = (provider) => {
         const credential = state.credentials[provider];
         if (credential) {
-            return `signed in (${credentialLabel(credential)})`;
+            return `signed in (${credentialLabel(provider, credential)})`;
         }
         if (readNonEmptyString(processEnv[defaultKeyEnvFor(provider)])) {
             return `using ${defaultKeyEnvFor(provider)} from your environment`;
@@ -1989,10 +2087,10 @@ export const runSetup = async (command, streams, env = {}) => {
     };
     const providersSummary = () => {
         const parts = [];
-        for (const provider of ['anthropic', 'openai']) {
+        for (const provider of CREDENTIAL_PROVIDER_NAMES) {
             const credential = state.credentials[provider];
             if (credential) {
-                parts.push(`${provider} (${credentialLabel(credential)})`);
+                parts.push(`${provider} (${credentialLabel(provider, credential)})`);
             }
             else if (readNonEmptyString(processEnv[defaultKeyEnvFor(provider)])) {
                 parts.push(`${provider} (env key)`);
@@ -2020,7 +2118,9 @@ export const runSetup = async (command, streams, env = {}) => {
         const credential = state.credentials[state.provider];
         if (credential) {
             return credential.type === 'oauth_token'
-                ? 'signed in with your Claude subscription'
+                ? (state.provider === 'codex'
+                    ? 'using your ChatGPT (codex login) sign-in'
+                    : 'signed in with your Claude subscription')
                 : 'signed in with an API key';
         }
         const keyEnv = state.apiKeyEnv ?? defaultKeyEnvFor(state.provider);
@@ -2154,6 +2254,59 @@ export const runSetup = async (command, streams, env = {}) => {
             writeLine(streams.stdout, `! Could not reach the API to verify (${verdict.detail}). Saved the key anyway — it will be checked on your first run.`);
         }
     };
+    const signInCodex = async () => {
+        const signedIn = state.credentials.codex !== undefined;
+        const answer = await prompter.select('How should Stratus connect to Codex?', [
+            'ChatGPT subscription — uses this machine\'s `codex login` sign-in, no per-token cost',
+            'OpenAI API key — pay per use (platform.openai.com)',
+            'Skip for now',
+            ...(signedIn ? ['Sign out'] : []),
+        ]);
+        if (signedIn && answer.kind === 'index' && answer.index === 3) {
+            delete state.credentials.codex;
+            state.credentialsDirty = true;
+            writeLine(streams.stdout, 'Signed out of Codex. (A `codex login` sign-in, if any, stays with codex itself — run `codex logout` to clear it.)');
+            return;
+        }
+        if (answer.kind !== 'index' || answer.index === 2) {
+            return;
+        }
+        if (answer.index === 1) {
+            const key = await prompter.askSecret('Paste your OpenAI API key (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 OpenAI API…');
+            const verdict = await verifyProviderKey('codex', key, undefined, env.fetch ?? globalThis.fetch);
+            if (verdict.status === 'ok') {
+                storeCredential('codex', { type: 'api_key', value: key });
+                writeLine(streams.stdout, '✓ Key verified — Codex runs will bill this OpenAI API key.');
+            }
+            else if (verdict.status === 'rejected') {
+                writeLine(streams.stdout, `✗ OpenAI rejected that key (${verdict.detail}). It was NOT saved — check platform.openai.com and try again from this menu.`);
+            }
+            else {
+                storeCredential('codex', { type: 'api_key', value: key });
+                writeLine(streams.stdout, `! Could not reach the OpenAI API to verify (${verdict.detail}). Saved the key anyway — it will be checked on your first run.`);
+            }
+            return;
+        }
+        // Default: the machine's own ChatGPT sign-in. Codex keeps those tokens
+        // in its own auth store; Stratus records only that this machine uses
+        // it, so nothing secret is written here.
+        writeLine(streams.stdout, 'Your ChatGPT plan covers usage made through Codex.');
+        writeLine(streams.stdout, 'If you have not signed in yet, run this in another terminal on this machine:');
+        writeLine(streams.stdout, '  codex login');
+        writeLine(streams.stdout, '(requires the Codex CLI: npm install -g @openai/codex)');
+        const confirmed = await prompter.select('Use this machine\'s codex sign-in?', ['Yes — codex is (or will be) signed in here', 'Skip for now']);
+        if (confirmed.kind !== 'index' || confirmed.index !== 0) {
+            writeLine(streams.stdout, 'Skipped — you can sign in any time by re-running this menu.');
+            return;
+        }
+        storeCredential('codex', { type: 'oauth_token', value: 'chatgpt' });
+        writeLine(streams.stdout, '✓ Recorded — Codex runs use this machine\'s ChatGPT sign-in. It is verified 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
@@ -2213,17 +2366,25 @@ export const runSetup = async (command, streams, env = {}) => {
         const answer = await prompter.select('Providers — sign in to one or more:', [
             `Claude (Anthropic) — ${providerSignInStatus('anthropic')}`,
             `OpenAI-compatible — ${providerSignInStatus('openai')}`,
+            `Codex (ChatGPT) — ${providerSignInStatus('codex')}`,
             'Demo — built-in fake model, offline, no account',
             'Back',
         ]);
-        if (answer.kind !== 'index' || answer.index === 3) {
+        if (answer.kind !== 'index' || answer.index === 4) {
             return;
         }
-        if (answer.index === 2) {
+        if (answer.index === 3) {
             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 === 2) {
+            await signInCodex();
+            if (state.credentials.codex) {
+                await maybeSwitchDefault('codex');
+            }
+            return;
+        }
         if (answer.index === 1) {
             await signInOpenAI();
             if (state.credentials.openai) {
@@ -2270,10 +2431,10 @@ export const runSetup = async (command, streams, env = {}) => {
             if (typed.includes(':')) {
                 const [providerPart, ...idParts] = typed.split(':');
                 const id = idParts.join(':').trim();
-                if ((providerPart === 'anthropic' || providerPart === 'openai') && id) {
+                if ((providerPart === 'anthropic' || providerPart === 'openai' || providerPart === 'codex') && id) {
                     return { provider: providerPart, id };
                 }
-                writeLine(streams.stdout, 'Use provider:model, e.g. anthropic:claude-opus-5.');
+                writeLine(streams.stdout, 'Use provider:model, e.g. anthropic:claude-opus-5 or codex:gpt-5.5.');
                 return undefined;
             }
             // A typed id that appears in the collected list belongs to that
@@ -2408,10 +2569,17 @@ export const runSetup = async (command, streams, env = {}) => {
             ? readNonEmptyString(processEnv.STRATUS_API_KEY)
             : undefined)
             ?? readNonEmptyString(processEnv[defaultKeyEnvFor(fallbackProvider)]);
-        const credential = envKey ? undefined : state.credentials[fallbackProvider];
+        const candidate = envKey ? undefined : state.credentials[fallbackProvider];
+        // A codex fallback consumes no endpoint URL, so a stored key bound to
+        // one cannot serve it — the same skip resolveRuntimeConfig performs.
+        const credential = fallbackProvider === 'codex' && candidate?.type === 'api_key' && candidate.baseUrl !== undefined
+            ? undefined
+            : candidate;
         const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
-        const authToken = credential?.type === 'oauth_token' ? credential.value : undefined;
-        if (!apiKey && !authToken) {
+        // A codex oauth entry is the subscription marker, not a token to send.
+        const codexSubscription = fallbackProvider === 'codex' && !apiKey && credential?.type === 'oauth_token';
+        const authToken = fallbackProvider !== 'codex' && credential?.type === 'oauth_token' ? credential.value : undefined;
+        if (!apiKey && !authToken && !codexSubscription) {
             return undefined;
         }
         return {
@@ -2424,13 +2592,17 @@ export const runSetup = async (command, streams, env = {}) => {
                         ?? (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 } : {};
-                })()),
+                // The codex harness owns its endpoints; only anthropic can carry one.
+                : fallbackProvider === 'codex'
+                    ? {}
+                    : (() => {
+                        const url = (fallbackProvider === state.provider ? state.baseUrl : undefined)
+                            ?? (credential?.type === 'api_key' ? credential.baseUrl : undefined);
+                        return url ? { baseUrl: url } : {};
+                    })()),
             ...(apiKey ? { apiKey } : {}),
             ...(authToken ? { authToken } : {}),
+            ...(codexSubscription ? { codexSubscription: true } : {}),
         };
     };
     const buildTestRuntime = async () => {
@@ -2479,6 +2651,32 @@ export const runSetup = async (command, streams, env = {}) => {
                 ...(fallback ? { fallback } : {}),
             };
         }
+        if (state.provider === 'codex') {
+            // The harness owns its endpoints: a key bound to one cannot be
+            // honored on codex — resolveRuntimeConfig refuses this outright, and
+            // the inline test mirrors it rather than quietly unbinding the key.
+            if (boundUrl !== undefined) {
+                writeLine(streams.stdout, `Your saved codex key is bound to ${boundUrl}, and codex does not use a custom base URL. Store the key without one to run on codex.`);
+                return undefined;
+            }
+            const apiKey = envKey ?? (credential?.type === 'api_key' ? credential.value : undefined);
+            // The subscription marker means the machine's own codex sign-in
+            // serves the run — nothing more to resolve here.
+            if (!apiKey && credential?.type !== 'oauth_token') {
+                writeLine(streams.stdout, 'You are not signed in yet — pick option 1 first (or export CODEX_API_KEY).');
+                return undefined;
+            }
+            const fallback = buildTestFallback();
+            return {
+                provider: 'codex',
+                model,
+                ...(apiKey ? { apiKey } : {}),
+                ...(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).');
@@ -3410,9 +3608,11 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     const usedKeyEnvVar = resolved && resolved.provider !== 'demo' ? resolved.apiKeyEnvVar : undefined;
     const usesAuthToken = resolved?.provider === 'anthropic' && resolved.authToken !== undefined;
     const fallback = resolved && resolved.provider !== 'demo' ? resolved.fallback : undefined;
-    for (const target of ['anthropic', 'openai']) {
+    for (const target of CREDENTIAL_PROVIDER_NAMES) {
         const stored = credentials[target];
-        const label = stored?.type === 'oauth_token' ? 'Claude subscription (Pro/Max)' : 'API key';
+        const label = stored?.type === 'oauth_token'
+            ? (target === 'codex' ? 'ChatGPT sign-in (codex login)' : 'Claude subscription (Pro/Max)')
+            : 'API key';
         const isDefault = resolved?.provider === target;
         const isFallback = fallback?.provider === target;
         // A provider no resolved run consults is reported, never diagnosed:
@@ -3426,7 +3626,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
             });
             continue;
         }
-        const envVar = isDefault ? usedKeyEnvVar : (target === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY');
+        const envVar = isDefault ? usedKeyEnvVar : defaultApiKeyEnvName(target);
         const viaEnv = isDefault
             ? usedKeyEnvVar !== undefined
             : fallback?.apiKey !== undefined && fallback.apiKey === readNonEmptyString(processEnv[String(envVar)]);
@@ -3500,6 +3700,19 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
         problems.push(`Slack tokens are stored for ${orphans.join(', ')}, which no agent matches — \`stratus serve\` skips them. `
             + 'Clear them from `stratus setup` → Channels.');
     }
+    // The invisible failure doctor exists to surface: the service unit embeds
+    // absolute node and entrypoint paths, and upgrading node (an nvm version
+    // directory, say) leaves the unit pointing at an interpreter that no
+    // longer exists. The service stops working and nothing else says so.
+    const unitCommand = await readServiceCommand(serviceEnvFor(env));
+    if (unitCommand?.execPath !== undefined && !(await pathExists(unitCommand.execPath))) {
+        problems.push(`The service unit points at a node interpreter that no longer exists (${unitCommand.execPath}), so stratusd cannot start. `
+            + 'Run `stratus update` (or `stratus service install`) to rewrite it with current paths.');
+    }
+    if (unitCommand?.scriptPath !== undefined && !(await pathExists(unitCommand.scriptPath))) {
+        problems.push(`The service unit points at a CLI entrypoint that no longer exists (${unitCommand.scriptPath}), so stratusd cannot start. `
+            + 'Run `stratus update` (or `stratus service install`) to rewrite it with current paths.');
+    }
     return {
         ...(winner ? { configInUse: winner.path } : {}),
         configShadowed: shadowed.map((entry) => entry.path),
@@ -3638,6 +3851,7 @@ const serviceEnvFor = (env) => ({
     ...(env.homeDir !== undefined ? { homeDir: env.homeDir } : {}),
     cwd: readWorkingDirectory(env),
     ...(env.serviceRunner !== undefined ? { run: env.serviceRunner } : {}),
+    ...(env.servicePlatform !== undefined ? { platform: env.servicePlatform } : {}),
 });
 /**
  * A credential that exists only in this shell cannot reach the daemon: a
@@ -3720,7 +3934,9 @@ export const runService = async (command, streams, env = {}) => {
             writeLine(streams.stdout, `No service manager for ${process.platform}. Run \`stratus serve\` yourself.`);
             return 1;
         }
-        writeLine(streams.stdout, `stratusd  ${status.running ? 'running' : status.installed ? 'installed, not running' : 'not installed'}`);
+        writeLine(streams.stdout, `stratusd  ${status.running === undefined
+            ? 'state unknown — the service manager did not answer'
+            : status.running ? 'running' : status.installed ? 'installed, not running' : 'not installed'}`);
         writeLine(streams.stdout, `  manager   ${status.platform}`);
         writeLine(streams.stdout, `  unit      ${status.unitPath}`);
         if (status.detail) {
@@ -3734,7 +3950,7 @@ export const runService = async (command, streams, env = {}) => {
         writeLine(streams.stdout, status.installed
             ? '  logs      stratus logs -f'
             : '  install   stratus service install');
-        return status.running ? 0 : 1;
+        return status.running === true ? 0 : 1;
     }
     // A service manager passes none of this shell's environment on, so a
     // config selected by STRATUS_CONFIG has to be baked into the unit
@@ -3796,6 +4012,227 @@ export const runService = async (command, streams, env = {}) => {
     }
     return result.ok ? 0 : 1;
 };
+const CLI_PACKAGE_NAME = '@stratusagent/cli';
+const pathExists = async (candidate) => {
+    try {
+        await stat(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * `stratus update` — the whole upgrade dance, in the order that cannot lose
+ * data: stop the service (so no daemon holds the session database while
+ * state migrates), upgrade the package, run pending migrations, rewrite the
+ * service unit with current paths, restart.
+ *
+ * The unit rewrite is the step that repairs the failure nothing else
+ * surfaces: the unit embeds absolute node and entrypoint paths (a service
+ * manager loads no shell profile, so it must), and upgrading node — under
+ * nvm, a whole new version directory — leaves the unit pointing at an
+ * interpreter that no longer exists. The service stops working and nothing
+ * says so; the agents just stop answering.
+ *
+ * Each step degrades independently: an unreachable npm skips the version
+ * check and package upgrade but still migrates and rewrites the unit —
+ * which is exactly the repair the offline case needs.
+ */
+const runUpdate = async (command, streams, env) => {
+    const serviceEnv = serviceEnvFor(env);
+    const out = (line) => writeLine(streams.stdout, line);
+    const latest = await (env.packageVersionFetcher ?? defaultPackageVersionFetcher)(CLI_PACKAGE_NAME);
+    const upgradeAvailable = latest !== undefined && compareVersions(latest, CLI_VERSION) > 0;
+    // A stamp from a newer build makes every later step wrong, not just the
+    // migration one: this build would migrate — and stop the daemon to do it —
+    // against a format it does not understand. Checked here, before anything
+    // has a side effect.
+    const stamp = await readStateStamp(env);
+    const stateNewer = stamp.schemaVersion > STATE_SCHEMA_VERSION;
+    const status = await readServiceStatus(serviceEnv).catch(() => undefined);
+    const unit = status?.installed ? await readServiceCommand(serviceEnv) : undefined;
+    const unitNotes = [];
+    if (status?.installed && unit?.execPath !== undefined) {
+        if (!(await pathExists(unit.execPath))) {
+            unitNotes.push(`the unit's interpreter no longer exists: ${unit.execPath} — stratusd cannot start until the unit is rewritten`);
+        }
+        else if (unit.execPath !== process.execPath) {
+            unitNotes.push(`the unit runs ${unit.execPath}; this shell runs ${process.execPath}`);
+        }
+        if (unit.scriptPath !== undefined && !(await pathExists(unit.scriptPath))) {
+            unitNotes.push(`the unit's entrypoint no longer exists: ${unit.scriptPath}`);
+        }
+        else if (unit.scriptPath !== undefined && process.argv[1] !== undefined && unit.scriptPath !== process.argv[1]) {
+            // A versioned package directory can keep the old file alive after an
+            // upgrade — the daemon then runs the old CLI indefinitely with
+            // nothing missing on disk to notice.
+            unitNotes.push(`the unit runs entrypoint ${unit.scriptPath}; this shell runs ${process.argv[1]}`);
+        }
+    }
+    const pending = await pendingStateMigrations(env);
+    out(`stratus ${CLI_VERSION}`);
+    out(latest === undefined
+        ? '  latest      unknown — npm did not answer'
+        : `  latest      ${latest}${upgradeAvailable ? ' — update available' : ' — up to date'}`);
+    out(`  state       schema ${stamp.schemaVersion}${stateNewer
+        ? ` — written by a NEWER build than this one (which understands ${STATE_SCHEMA_VERSION})`
+        : `, ${pending.length === 0 ? 'no pending migrations' : `${pending.length} pending migration${pending.length === 1 ? '' : 's'}`}`}`);
+    out(`  service     ${status === undefined
+        ? `no service manager for ${process.platform}`
+        : status.installed
+            ? (status.running === undefined ? 'installed, state unknown' : status.running ? 'installed, running' : 'installed, not running')
+            : 'not installed'}`);
+    for (const note of unitNotes) {
+        out(`  unit        ${note}`);
+    }
+    if (command.check) {
+        for (const migration of pending) {
+            out(`  pending     ${migration.id} — ${migration.description}`);
+        }
+        if (stateNewer) {
+            out('This build cannot update that state — upgrade the package itself (`npm install -g @stratusagent/cli`).');
+            return 1;
+        }
+        const actionable = upgradeAvailable || pending.length > 0 || unitNotes.length > 0;
+        out(actionable
+            ? 'Run `stratus update` to apply the above.'
+            : 'Nothing to do.');
+        // Actionable exits 1, so a cron job or script can notice.
+        return actionable ? 1 : 0;
+    }
+    if (stateNewer) {
+        writeLine(streams.stderr, newerStateMessage(stamp.schemaVersion));
+        return 1;
+    }
+    if (status?.installed && (status.runAtLogin === undefined || status.running === undefined)) {
+        // The rewrite has to re-state the login setting and restore the prior
+        // run state, and the manager could not say what either currently is.
+        // Guessing would let a transient status failure convert a deliberate
+        // --no-login install, or rewrite-and-stop a daemon that was actually
+        // running — refuse instead, before anything has been stopped.
+        writeLine(streams.stderr, `Not updating: whether stratusd ${status.running === undefined ? 'is running' : 'starts at login'} could not be determined (the service manager did not answer), and the unit rewrite would have to guess. Check \`stratus service status\` and retry.`);
+        return 1;
+    }
+    const wasRunning = status?.running === true;
+    if (wasRunning) {
+        // No daemon may hold the session database while state migrates — this
+        // bracket is the one place an update could otherwise lose data.
+        out('Stopping stratusd for the update…');
+        const stopped = await stopService(serviceEnv);
+        for (const message of stopped.messages) {
+            writeLine(stopped.ok ? streams.stdout : streams.stderr, message);
+        }
+        if (!stopped.ok) {
+            writeLine(streams.stderr, 'Not updating while the daemon may still be running.');
+            return 1;
+        }
+    }
+    let upgradeFailed = false;
+    if (upgradeAvailable) {
+        out(`Upgrading ${CLI_PACKAGE_NAME} ${CLI_VERSION} → ${latest}…`);
+        const installed = await (env.packageInstaller ?? defaultPackageInstaller)([`${CLI_PACKAGE_NAME}@latest`]);
+        if (installed.ok) {
+            // This process is still the old build; migrations the new version
+            // adds run when it first starts — which the restart below is.
+            out('Upgraded. Migrations the new version adds run on its first start.');
+        }
+        else {
+            upgradeFailed = true;
+            writeLine(streams.stderr, `npm install failed: ${installed.message || 'unknown error'} — continuing with migrations and the unit rewrite.`);
+        }
+    }
+    else {
+        out(latest === undefined
+            ? 'Skipping the package upgrade — npm did not answer.'
+            : 'Package already up to date.');
+    }
+    let applied;
+    try {
+        applied = await runStateMigrations(env);
+    }
+    catch (error) {
+        // A daemon stopped for an update that then failed must not stay down:
+        // the old unit is still in place (the rewrite has not happened), so
+        // restarting restores the world the update found. The failure is still
+        // a failure — but an offline fleet on top of it is not.
+        writeLine(streams.stderr, `State migration failed: ${error instanceof Error ? error.message : String(error)}`);
+        if (wasRunning) {
+            const restarted = await startService(serviceEnv);
+            for (const message of restarted.messages) {
+                writeLine(restarted.ok ? streams.stdout : streams.stderr, message);
+            }
+            writeLine(streams.stderr, restarted.ok
+                ? 'stratusd was restarted on its previous unit. Fix the migration failure and run `stratus update` again.'
+                : 'stratusd could not be restarted either — bring it back with `stratus service start` once the failure is fixed.');
+        }
+        return 1;
+    }
+    if (applied.length === 0) {
+        out('No pending state migrations.');
+    }
+    for (const migration of applied) {
+        out(`Migrated: ${migration.description}${migration.detail !== undefined ? ` — ${migration.detail}` : ''}`);
+    }
+    if (status?.installed) {
+        out('Rewriting the service unit with current node and entrypoint paths…');
+        // The rewrite overwrites the unit before it bootstraps, so a failure
+        // in between must be able to put the old definition back — otherwise
+        // a stopped daemon is left with neither unit to start from.
+        const previousUnit = await readFile(serviceUnitPath(serviceEnv), 'utf8').catch(() => undefined);
+        const install = await installService(
+        // The unit's own working directory survives the rewrite: relative
+        // paths in the pinned config (a `soul`) resolve against it, so a
+        // rewrite run from some other directory must not substitute its own.
+        unit?.workingDirectory !== undefined ? { ...serviceEnv, cwd: unit.workingDirectory } : serviceEnv, {
+            ...(status.runAtLogin === false ? { runAtLogin: false } : {}),
+            // The config the existing unit was pinned to survives the rewrite —
+            // a unit rewritten onto a different roster is its own outage.
+            ...(unit?.configPath !== undefined ? { configPath: unit.configPath } : {}),
+        });
+        for (const message of install.messages) {
+            writeLine(install.ok ? streams.stdout : streams.stderr, message);
+        }
+        if (!install.ok) {
+            if (wasRunning) {
+                // The fleet was up when the update began and must not stay down
+                // over a failed rewrite: restore the previous unit definition and
+                // start it again. The exit code stays 1 — the update failed — but
+                // the world it found is put back.
+                if (previousUnit !== undefined) {
+                    await writeFile(serviceUnitPath(serviceEnv), previousUnit, { mode: 0o644 }).catch((error) => {
+                        writeLine(streams.stderr, `Could not restore the previous unit either: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                }
+                const restarted = await startService(serviceEnv);
+                for (const message of restarted.messages) {
+                    writeLine(restarted.ok ? streams.stdout : streams.stderr, message);
+                }
+                writeLine(streams.stderr, restarted.ok
+                    ? 'The unit rewrite failed, so stratusd was restarted on its previous unit. Fix the failure above and run `stratus update` again.'
+                    : 'The unit rewrite failed AND stratusd could not be restarted — bring it back with `stratus service start`, or `stratus service install` to rewrite the unit by hand.');
+            }
+            return 1;
+        }
+        if (!wasRunning) {
+            // installService starts the daemon; a service that was deliberately
+            // stopped before the update stays that way.
+            const stopped = await stopService(serviceEnv);
+            if (!stopped.ok) {
+                // The update itself succeeded, but the user's prior state was not
+                // restored: an intentionally stopped daemon is now running. That
+                // is a failure a script must see, not a footnote.
+                writeLine(streams.stderr, 'stratusd was not running before the update, and stopping it again failed — it is now RUNNING. Stop it with `stratus service stop`.');
+                return 1;
+            }
+            out('stratusd was not running before the update, so it was left stopped.');
+        }
+    }
+    else if (status !== undefined) {
+        out('No service installed — nothing to rewrite. `stratus service install` sets one up.');
+    }
+    return upgradeFailed ? 1 : 0;
+};
 /**
  * What a `skill add` source string means, in order: a directory on this
  * machine, a GitHub `owner/repo` shorthand, or a URL git can clone. The
@@ -4088,6 +4525,37 @@ export const runSkills = async (streams, env = {}) => {
     }
     return 0;
 };
+/**
+ * The provider/model a newly created soul pins. 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 model at all: the soul keeps following the
+ * machine's configuration instead of demanding credentials nothing has
+ * signed in for. The active config's model was written for the provider
+ * named in that config, so it only travels into the soul when they still
+ * match; otherwise the selected provider's own default model stands in.
+ *
+ * Exported for tests: the interactive path that consumes it needs a TTY.
+ */
+export const soulPinForNewAgent = (activeConfig, processEnv) => {
+    // The map already validates, so the value is a provider name; the cast
+    // only undoes `readNonEmptyString`'s widening to `string`.
+    const envProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'));
+    const provider = envProvider ?? activeConfig.provider ?? 'demo';
+    if (provider === 'demo') {
+        return { provider };
+    }
+    const configModelApplies = (activeConfig.provider ?? 'openai') === provider;
+    const model = readNonEmptyString(processEnv.STRATUS_MODEL)
+        ?? (configModelApplies ? activeConfig.model : undefined)
+        ?? (provider === 'openai'
+            ? DEFAULT_OPENAI_MODEL
+            : provider === 'codex'
+                ? DEFAULT_CODEX_MODEL
+                : DEFAULT_ANTHROPIC_MODEL);
+    return { provider, model };
+};
 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
@@ -4111,28 +4579,16 @@ export const runAgentNew = async (command, streams, env = {}) => {
             const name = (await prompter.ask('Choose your name: ', { prefill: suggested })) || suggested;
             const instructions = await prompter.ask('Describe their personality (Enter for a starter you can edit later): ', ...(command.instructions ? [{ prefill: command.instructions }] : []));
             const persona = instructions || DEFAULT_SOUL_STARTER;
-            // 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);
             // 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.
             const { location: configLocation, config: activeConfig } = await discoverActiveConfig(env, (message) => {
                 writeLine(streams.stdout, `Note: ${message}.`);
             });
-            const soulProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
-                ?? 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)
-                ?? (configModelApplies ? activeConfig.model : undefined)
-                ?? (soulProvider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
-            const soulPin = soulProvider !== 'demo' ? { provider: soulProvider, model: soulModel } : {};
+            const { provider: soulProvider, model: soulModel } = soulPinForNewAgent(activeConfig, processEnv);
+            const soulPin = soulProvider !== 'demo' && soulModel !== undefined
+                ? { provider: soulProvider, model: soulModel }
+                : {};
             const claimed = await claimSoulFile(env, { name, instructions: persona }, (candidate) => formatSoul({ agent: candidate, ...soulPin }), (message) => writeLine(streams.stdout, message));
             const { agent, soulPath } = claimed;
             const makeDefault = await prompter.select(`Make ${agent.name} your default agent?`, [
@@ -4840,6 +5296,55 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
             writeLine(streams.stdout, HELP_TEXT);
             return 0;
         }
+        // Migrations run on first use of a newer build — every command, every
+        // install path — not only via `stratus update`: state that migrates
+        // only sometimes is worse than state that never migrates, because the
+        // two populations diverge silently. `update` is excluded because it
+        // owns the migration step at its own place in the upgrade sequence
+        // (after the service stop and the package upgrade), and `--check` has
+        // to be able to report what is pending rather than having just done it.
+        if (command.command !== 'update') {
+            const stamp = await readStateStamp(resolvedEnv);
+            if (stamp.schemaVersion > STATE_SCHEMA_VERSION) {
+                // Anything that writes under ~/.stratus refuses, not only the
+                // daemon: a downgraded build's setup, chat, or run can discard
+                // fields and invariants the newer format relies on — the exact
+                // hazard the stamp exists to close. Read-only commands warn and
+                // continue, because reading logs or the roster is how someone
+                // diagnoses their way OUT of this state; so do `service stop`,
+                // `status`, and `uninstall`, for the same reason. (`agent new`
+                // only prints an identity — it writes nothing.)
+                const writesState = command.command === 'serve'
+                    || command.command === 'setup'
+                    || command.command === 'chat'
+                    || command.command === 'run'
+                    || command.command === 'skill-add'
+                    || command.command === 'dashboard'
+                    || (command.command === 'schedules' && command.action === 'cancel')
+                    || (command.command === 'service' && (command.action === 'install' || command.action === 'start'));
+                if (writesState) {
+                    writeLine(streams.stderr, newerStateMessage(stamp.schemaVersion));
+                    writeLine(streams.stderr, `Refusing \`stratus ${command.command}\` — it writes state the newer format owns. Read-only commands (logs, agents, doctor, service status/stop) still work.`);
+                    return 1;
+                }
+                writeLine(streams.stderr, `Warning: ${newerStateMessage(stamp.schemaVersion)}`);
+            }
+            else {
+                try {
+                    for (const migration of await runStateMigrations(resolvedEnv)) {
+                        if (migration.detail !== undefined) {
+                            writeLine(streams.stderr, `state migration ${migration.id}: ${migration.detail}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    // A failed migration must not brick every command, but running
+                    // on unmigrated state is worth a line: silence here is how the
+                    // migrated and unmigrated populations diverge.
+                    writeLine(streams.stderr, `Warning: state migration failed (${error instanceof Error ? error.message : String(error)}). Continuing on unmigrated state — \`stratus update\` retries it.`);
+                }
+            }
+        }
         // Every handler is awaited, never bare-returned: a bare `return
         // promise` inside try/catch settles the async function before the
         // catch can see it, so a command that fails at runtime — a gateway
@@ -4869,6 +5374,9 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.command === 'service') {
             return await runService(command, streams, resolvedEnv);
         }
+        if (command.command === 'update') {
+            return await runUpdate(command, streams, resolvedEnv);
+        }
         if (command.command === 'chat') {
             return await runChat(command, streams, resolvedEnv);
         }