@kaelio/ktx 0.8.0 → 0.9.0

package/dist/setup-models.d.ts

@@ -39,7 +39,7 @@ export interface AnthropicModelChoice {
     label: string;
     recommended: boolean;
 }
-export type KtxSetupLlmBackend = 'anthropic' | 'vertex' | 'claude-code';
+export type KtxSetupLlmBackend = 'anthropic' | 'vertex' | 'claude-code' | 'codex';
 /** @internal */
 export interface KtxSetupModelPromptAdapter {
     select(options: {
@@ -76,6 +76,15 @@ export interface KtxSetupModelDeps {
         ok: false;
         message: string;
     }>;
+    codexAuthProbe?: (input: {
+        projectDir: string;
+        model: string;
+    }) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }>;
     readGcloudProject?: () => Promise<string | undefined>;
     listGcloudProjects?: () => Promise<GcloudProjectChoice[]>;
     spinner?: () => KtxCliSpinner;

package/dist/setup-models.js

@@ -3,6 +3,9 @@ import { writeFile } from 'node:fs/promises';
 import { promisify } from 'node:util';
 import { resolveLocalKtxLlmConfig } from './context/llm/local-config.js';
 import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
+import { formatCodexIsolationWarning } from './context/llm/codex-isolation.js';
+import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
+import { DEFAULT_CODEX_MODEL } from './context/llm/codex-models.js';
 import { resolveKtxConfigReference } from './context/core/config-reference.js';
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
@@ -37,6 +40,19 @@ const CLAUDE_CODE_MODELS = [
     { id: 'opus', label: 'Claude Opus', recommended: false },
     { id: 'haiku', label: 'Claude Haiku', recommended: false },
 ];
+// Curated Codex models from OpenAI's current lineup that work under both
+// ChatGPT-account (subscription) and API-key auth. Intentionally omitted:
+// the `*-codex` ids (e.g. gpt-5.3-codex, gpt-5.2-codex) are API-key-only and
+// fail on ChatGPT-account auth, and gpt-5.3-codex-spark is a ChatGPT-Pro-only
+// research preview. Codex resolves real availability per account at runtime
+// (its binary remote-fetches the model list), so this is a convenience
+// shortlist only — the manual-entry option accepts any id your account's
+// `codex` picker exposes, and the auth probe reports an unsupported choice.
+const CODEX_MODELS = [
+    { id: 'gpt-5.5', label: 'GPT-5.5', recommended: true },
+    { id: 'gpt-5.4', label: 'GPT-5.4', recommended: false },
+    { id: 'gpt-5.4-mini', label: 'GPT-5.4 mini', recommended: false },
+];
 const HIDDEN_ANTHROPIC_MODEL_PATTERNS = [
     /^claude-sonnet-4$/i,
     /^claude-opus-4$/i,
@@ -149,7 +165,10 @@ export function isKtxSetupLlmConfigReady(config) {
     if (resolved.backend === 'vertex') {
         return typeof resolved.vertex?.location === 'string' && resolved.vertex.location.trim().length > 0;
     }
-    return resolved.backend === 'anthropic' || resolved.backend === 'gateway' || resolved.backend === 'claude-code';
+    return (resolved.backend === 'anthropic' ||
+        resolved.backend === 'gateway' ||
+        resolved.backend === 'claude-code' ||
+        resolved.backend === 'codex');
 }
 function hasUsableConfiguredLlm(config) {
     return isKtxSetupLlmConfigReady(config.llm);
@@ -162,6 +181,13 @@ function buildProjectLlmConfig(existing, provider, model) {
             promptCaching: existing.promptCaching,
         };
     }
+    if (provider.backend === 'codex') {
+        return {
+            provider: { backend: 'codex' },
+            models: { ...existing.models, default: model },
+            promptCaching: existing.promptCaching,
+        };
+    }
     if (provider.backend === 'vertex') {
         return {
             provider: {
@@ -340,6 +366,7 @@ async function chooseBackend(args, io, deps) {
         message: 'Which LLM provider should KTX use?',
         options: [
             { value: 'claude-code', label: 'Claude subscription (Pro/Max)' },
+            { value: 'codex', label: 'Codex subscription' },
             { value: 'anthropic', label: 'Anthropic API key' },
             { value: 'vertex', label: 'Google Vertex AI for Anthropic Claude' },
             { value: 'back', label: 'Back' },
@@ -350,7 +377,7 @@ async function chooseBackend(args, io, deps) {
     }
     return {
         status: 'ready',
-        backend: choice === 'vertex' || choice === 'claude-code' ? choice : 'anthropic',
+        backend: choice === 'vertex' || choice === 'claude-code' || choice === 'codex' ? choice : 'anthropic',
         prompted: true,
     };
 }
@@ -671,6 +698,42 @@ async function chooseClaudeCodeModel(args, deps) {
     }
     return { status: 'ready', model: choice };
 }
+async function chooseCodexModel(args, deps) {
+    const providedModel = requestedModel(args);
+    if (providedModel) {
+        return { status: 'ready', model: providedModel };
+    }
+    if (args.inputMode === 'disabled') {
+        return { status: 'ready', model: DEFAULT_CODEX_MODEL };
+    }
+    const prompts = deps.prompts ?? createPromptAdapter();
+    const choice = await prompts.select({
+        message: `Which Codex model should KTX use?\n\n${ANTHROPIC_MODEL_PROMPT_CONTEXT}`,
+        options: [
+            ...CODEX_MODELS.map((model) => ({
+                value: model.id,
+                label: model.label,
+                ...(model.recommended ? { hint: 'recommended' } : {}),
+            })),
+            { value: 'manual', label: 'Enter a Codex model ID manually' },
+            { value: 'back', label: 'Back' },
+        ],
+    });
+    if (choice === 'back') {
+        return { status: 'back' };
+    }
+    if (choice === 'manual') {
+        const manual = await prompts.text({
+            message: withTextInputNavigation('Codex model ID'),
+            placeholder: CODEX_MODELS.find((model) => model.recommended)?.id ?? CODEX_MODELS[0]?.id,
+        });
+        if (manual === undefined) {
+            return { status: 'back' };
+        }
+        return manual.trim() ? { status: 'ready', model: manual.trim() } : { status: 'missing-input' };
+    }
+    return { status: 'ready', model: choice };
+}
 async function persistLlmConfig(projectDir, provider, model) {
     const project = await loadKtxProject({ projectDir });
     const config = {
@@ -783,6 +846,31 @@ export async function runKtxSetupAnthropicModelStep(args, io, deps = {}) {
             io.stdout.write(`│  LLM ready: yes (${model.model})\n`);
             return { status: 'ready', projectDir: args.projectDir };
         }
+        if (backendChoice.backend === 'codex') {
+            const model = await chooseCodexModel(backendArgs, deps);
+            if (model.status === 'back' && backendChoice.prompted) {
+                attemptArgs = buildInteractiveRetryArgs(args);
+                continue;
+            }
+            if (model.status === 'invalid-credential') {
+                return { status: 'failed', projectDir: args.projectDir };
+            }
+            if (model.status !== 'ready') {
+                return { status: model.status, projectDir: args.projectDir };
+            }
+            const probe = deps.codexAuthProbe ?? runCodexAuthProbe;
+            const health = await probe({ projectDir: args.projectDir, model: model.model });
+            if (!health.ok) {
+                io.stderr.write(`${health.message}\n`);
+                return { status: 'failed', projectDir: args.projectDir };
+            }
+            // Prefix the clack gutter so the warning sits inside the setup frame
+            // instead of breaking out of it; kept on stderr for scripted runs.
+            io.stderr.write(`│  ${formatCodexIsolationWarning()}\n`);
+            await persistLlmConfig(args.projectDir, { backend: 'codex' }, model.model);
+            io.stdout.write(`│  LLM ready: yes (codex, ${model.model})\n`);
+            return { status: 'ready', projectDir: args.projectDir };
+        }
         const credential = await chooseCredentialRef(backendArgs, io, deps);
         if (credential.status === 'back' && backendChoice.prompted) {
             attemptArgs = buildInteractiveRetryArgs(args);

package/dist/setup-ready-menu.d.ts

@@ -1,6 +1,11 @@
 import { type KtxSetupPromptOption } from './setup-prompts.js';
 import type { KtxSetupStatus } from './setup.js';
 export type KtxSetupReadyAction = 'models' | 'embeddings' | 'databases' | 'sources' | 'runtime' | 'context' | 'agents' | 'exit';
+/**
+ * Where a project stands once its `ktx.yaml` exists. Single source of truth for the
+ * end-of-setup interception: each state maps to exactly one obvious next action.
+ */
+export type KtxSetupCompletion = 'incomplete' | 'needs-context' | 'needs-agents' | 'ready';
 interface KtxSetupReadyMenuPromptAdapter {
     select(options: {
         message: string;
@@ -11,8 +16,17 @@ interface KtxSetupReadyMenuPromptAdapter {
 export interface KtxSetupReadyMenuDeps {
     prompts?: KtxSetupReadyMenuPromptAdapter;
 }
-export declare function isKtxPreAgentSetupReady(status: KtxSetupStatus): boolean;
-export declare function isKtxSetupReady(status: KtxSetupStatus): boolean;
+export declare function setupHasContextTargets(status: KtxSetupStatus): boolean;
+export declare function classifyKtxSetupCompletion(status: KtxSetupStatus): KtxSetupCompletion;
+/**
+ * Shown when a returning user re-runs `ktx setup` on a fully-ready project. Leads with
+ * "you're done" (the readiness note is printed by the caller first) and keeps the
+ * section editor one explicit step away rather than defaulting into it.
+ */
+export declare function runKtxSetupReadyMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
+    action: KtxSetupReadyAction;
+}>;
+/** @internal Reached only through {@link runKtxSetupReadyMenu}; exported for unit tests. */
 export declare function runKtxSetupReadyChangeMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
     action: KtxSetupReadyAction;
 }>;

package/dist/setup-ready-menu.js

@@ -1,23 +1,55 @@
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
-export function isKtxPreAgentSetupReady(status) {
+export function setupHasContextTargets(status) {
+    return status.databases.length > 0 || status.sources.length > 0;
+}
+function setupConfigReady(status) {
     return (status.project.ready &&
         status.llm.ready &&
         status.embeddings.ready &&
         status.databases.every((database) => database.ready) &&
         status.sources.every((source) => source.ready) &&
         status.runtime.ready &&
-        status.context.ready);
+        setupHasContextTargets(status));
 }
-export function isKtxSetupReady(status) {
-    return isKtxPreAgentSetupReady(status) && status.agents.some((agent) => agent.ready);
+export function classifyKtxSetupCompletion(status) {
+    if (!setupConfigReady(status)) {
+        return 'incomplete';
+    }
+    if (!status.context.ready) {
+        return 'needs-context';
+    }
+    if (!status.agents.some((agent) => agent.ready)) {
+        return 'needs-agents';
+    }
+    return 'ready';
 }
 function createPromptAdapter() {
     return createKtxSetupPromptAdapter({ selectCancelValue: 'exit' });
 }
+/**
+ * Shown when a returning user re-runs `ktx setup` on a fully-ready project. Leads with
+ * "you're done" (the readiness note is printed by the caller first) and keeps the
+ * section editor one explicit step away rather than defaulting into it.
+ */
+export async function runKtxSetupReadyMenu(status, deps = {}) {
+    const prompts = deps.prompts ?? createPromptAdapter();
+    const choice = await prompts.select({
+        message: 'Anything else?',
+        options: [
+            { value: 'done', label: "Done — I'll start using ktx" },
+            { value: 'change', label: 'Change a setting' },
+        ],
+    });
+    if (choice !== 'change') {
+        return { action: 'exit' };
+    }
+    return runKtxSetupReadyChangeMenu(status, { prompts });
+}
+/** @internal Reached only through {@link runKtxSetupReadyMenu}; exported for unit tests. */
 export async function runKtxSetupReadyChangeMenu(status, deps = {}) {
     const prompts = deps.prompts ?? createPromptAdapter();
     const action = (await prompts.select({
-        message: `KTX is already set up for ${status.project.name ?? status.project.path}. What would you like to change?`,
+        message: 'What would you like to change?',
         options: [
             { value: 'models', label: 'Models' },
             { value: 'embeddings', label: 'Embeddings' },

package/dist/setup-sources.js

@@ -19,6 +19,7 @@ import { markKtxSetupStateStepComplete } from './context/project/setup-config.js
 import { errorMessage, writePrefixedLines } from './clack.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { runKtxSourceMapping } from './source-mapping.js';
+import { runConnectionSetupWithRecovery, } from './connection-recovery.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
 import { runKtxPublicIngest } from './public-ingest.js';
 import { writeProjectLocalSecretReference } from './setup-secrets.js';
@@ -1434,56 +1435,125 @@ async function validateSource(source, args, deps) {
     }
     return await (deps.validateNotion ?? defaultValidateNotion)(args.connection);
 }
-async function saveValidateAndMaybeBuildSource(input) {
-    const connectionId = input.sourceChoice.kind === 'existing'
+async function createSourceSetupRollback(projectDir) {
+    const project = await loadKtxProject({ projectDir });
+    const previousConfig = project.config;
+    const configPath = project.configPath;
+    return async () => {
+        await writeFile(configPath, serializeKtxProjectConfig(previousConfig), 'utf-8');
+    };
+}
+function sourceConnectionId(input) {
+    return input.sourceChoice.kind === 'existing' || input.sourceChoice.kind === 'edited'
         ? input.sourceChoice.connectionId
-        : input.sourceChoice.kind === 'edited'
-            ? input.sourceChoice.connectionId
-            : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
-    const connection = input.sourceChoice.kind === 'existing'
-        ? input.sourceChoice.connection
-        : buildConnection(input.source, input.sourceChoice.args);
-    const rollback = input.sourceChoice.kind === 'existing'
-        ? undefined
-        : await writeSourceConnection(input.args.projectDir, connectionId, connection, sourceAdapter(input.source), input.io);
-    if (input.sourceChoice.kind === 'existing') {
-        await ensureSourceAdapterEnabled(input.args.projectDir, input.source);
-    }
-    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId, connection }, input.deps);
+        : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
+}
+async function validateSourceConnectionAndMapping(input) {
+    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId: input.connectionId, connection: input.connection }, input.deps);
     if (!validation.ok) {
-        await rollback?.();
         input.io.stderr.write(`${validation.message}\n`);
         return { status: 'failed' };
     }
     if (input.source === 'metabase' || input.source === 'looker') {
-        input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping…`);
-        const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, connectionId, createSetupPrefixedIo(input.io));
+        input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping...`);
+        const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, input.connectionId, createSetupPrefixedIo(input.io));
         if (mappingCode !== 0) {
-            await rollback?.();
             return { status: 'failed' };
         }
     }
+    return { status: 'ok' };
+}
+async function saveValidateAndMaybeBuildSource(input) {
+    let latestChoice = input.sourceChoice;
+    let latestConnectionId = sourceConnectionId({ source: input.source, sourceChoice: latestChoice });
+    let latestConnection = latestChoice.kind === 'existing'
+        ? latestChoice.connection
+        : buildConnection(input.source, latestChoice.args);
+    let configureCount = 0;
+    let rollbackAfterConfigure;
+    const outcome = await runConnectionSetupWithRecovery({
+        label: latestConnectionId,
+        interactive: input.args.inputMode !== 'disabled',
+        allowSkip: true,
+        io: input.io,
+        prompts: input.prompts,
+        snapshot: async () => {
+            rollbackAfterConfigure = await createSourceSetupRollback(input.args.projectDir);
+            return rollbackAfterConfigure;
+        },
+        configure: async () => {
+            configureCount += 1;
+            if (latestChoice.kind === 'existing' && configureCount === 1) {
+                await ensureSourceAdapterEnabled(input.args.projectDir, input.source);
+                return 'configured';
+            }
+            const project = await loadKtxProject({ projectDir: input.args.projectDir });
+            const currentConnection = project.config.connections[latestConnectionId] ?? latestConnection;
+            const useAlreadyPromptedArgs = configureCount === 1 && latestChoice.kind !== 'existing';
+            const sourceArgs = useAlreadyPromptedArgs && latestChoice.kind !== 'existing'
+                ? latestChoice.args
+                : input.args.inputMode === 'disabled'
+                    ? sourceArgsFromExistingConnection({
+                        args: input.args,
+                        source: input.source,
+                        connectionId: latestConnectionId,
+                        connection: currentConnection,
+                    })
+                    : await promptForInteractiveSource(sourceArgsFromExistingConnection({
+                        args: input.args,
+                        source: input.source,
+                        connectionId: latestConnectionId,
+                        connection: currentConnection,
+                    }), input.source, input.prompts, input.io, {
+                        pickNotionRootPages: input.deps.pickNotionRootPages,
+                        discoverMetabaseDatabases: input.deps.discoverMetabaseDatabases,
+                    }, latestConnectionId, input.deps.testGitRepo, input.deps.discoverMetabaseDatabases);
+            if (sourceArgs === 'back') {
+                return 'back';
+            }
+            latestConnectionId = sourceArgs.sourceConnectionId ?? latestConnectionId;
+            latestConnection = buildConnection(input.source, sourceArgs);
+            latestChoice =
+                latestChoice.kind === 'new'
+                    ? { kind: 'new', args: sourceArgs }
+                    : { kind: 'edited', connectionId: latestConnectionId, args: sourceArgs };
+            await writeSourceConnection(input.args.projectDir, latestConnectionId, latestConnection, sourceAdapter(input.source), input.io);
+            return 'configured';
+        },
+        validate: () => validateSourceConnectionAndMapping({
+            args: input.args,
+            source: input.source,
+            connectionId: latestConnectionId,
+            connection: latestConnection,
+            prompts: input.prompts,
+            io: input.io,
+            deps: input.deps,
+        }),
+    });
+    if (outcome !== 'ready') {
+        return { status: outcome };
+    }
     if (input.args.runInitialSourceIngest) {
         const ingestResult = await runInitialSourceIngestWithRecovery({
             args: input.args,
-            connectionId,
+            connectionId: latestConnectionId,
             io: input.io,
             prompts: input.prompts,
             deps: input.deps,
         });
         if (ingestResult === 'failed') {
-            await rollback?.();
+            await rollbackAfterConfigure?.();
             return { status: 'failed' };
         }
         if (ingestResult === 'back') {
-            await rollback?.();
+            await rollbackAfterConfigure?.();
             return { status: 'back' };
         }
     }
     else {
-        input.io.stdout.write(`│  Context source ${connectionId} saved. It will be built during the context build step.\n`);
+        input.io.stdout.write(`│  Context source ${latestConnectionId} saved. It will be built during the context build step.\n`);
     }
-    return { status: 'ready', connectionId };
+    return { status: 'ready', connectionId: latestConnectionId };
 }
 export async function runKtxSetupSourcesStep(args, io, deps = {}) {
     try {
@@ -1579,8 +1649,13 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                     returnToSourceSelection = true;
                     break;
                 }
-                if (!readyConnectionIds.includes(choiceResult.connectionId)) {
-                    readyConnectionIds.push(choiceResult.connectionId);
+                if (choiceResult.status === 'skip') {
+                    continue;
+                }
+                if (choiceResult.status === 'ready') {
+                    if (!readyConnectionIds.includes(choiceResult.connectionId)) {
+                        readyConnectionIds.push(choiceResult.connectionId);
+                    }
                 }
             }
             if (returnToSourceSelection) {
@@ -1640,8 +1715,13 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                         if (choiceResult.status === 'back') {
                             continue;
                         }
-                        if (!readyConnectionIds.includes(choiceResult.connectionId)) {
-                            readyConnectionIds.push(choiceResult.connectionId);
+                        if (choiceResult.status === 'skip') {
+                            continue;
+                        }
+                        if (choiceResult.status === 'ready') {
+                            if (!readyConnectionIds.includes(choiceResult.connectionId)) {
+                                readyConnectionIds.push(choiceResult.connectionId);
+                            }
                         }
                         continue;
                     }

package/dist/setup.js

@@ -6,7 +6,7 @@ import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { loadKtxProject } from './context/project/project.js';
 import { readKtxSetupState } from './context/project/setup-config.js';
 import { getKtxCliPackageInfo } from './cli-runtime.js';
-import { formatSetupNextStepLines } from './next-steps.js';
+import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
 import { resolveProjectRuntimeRequirements } from './runtime-requirements.js';
@@ -16,7 +16,7 @@ import { runKtxSetupDatabasesStep, } from './setup-databases.js';
 import { runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
 import { isKtxSetupLlmConfigReady, runKtxSetupAnthropicModelStep, } from './setup-models.js';
 import { runKtxSetupProjectStep } from './setup-project.js';
-import { isKtxPreAgentSetupReady, isKtxSetupReady, runKtxSetupReadyChangeMenu, } from './setup-ready-menu.js';
+import { classifyKtxSetupCompletion, runKtxSetupReadyMenu, setupHasContextTargets, } from './setup-ready-menu.js';
 import { runKtxSetupSourcesStep } from './setup-sources.js';
 import { runKtxSetupRuntimeStep, } from './setup-runtime.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
@@ -47,6 +47,7 @@ async function recordSetupStep(input) {
             step: input.step,
             outcome: setupTelemetryOutcome(input.status),
             durationMs: Math.max(0, performance.now() - input.startedAt),
+            ...(input.errorDetail ? { errorDetail: input.errorDetail } : {}),
         },
     });
 }
@@ -286,9 +287,6 @@ function setupStatusReady(status) {
         status.sources.every((source) => source.ready) &&
         status.runtime.ready);
 }
-function setupHasContextTargets(status) {
-    return status.databases.length > 0 || status.sources.length > 0;
-}
 function setupContextReady(status) {
     return status.context.ready;
 }
@@ -371,14 +369,22 @@ async function runKtxSetupInner(args, io, deps = {}) {
         const currentStatus = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
         let readyAction;
         if (args.inputMode !== 'disabled' && !agentsRequested) {
-            if (isKtxSetupReady(currentStatus)) {
-                readyAction = (await runKtxSetupReadyChangeMenu(currentStatus, deps.readyMenuDeps)).action;
-                if (readyAction === 'exit')
+            const completion = classifyKtxSetupCompletion(currentStatus);
+            if (completion === 'ready') {
+                setupUi.note(formatNextStepLines().join('\n'), 'ktx is ready', io);
+                const choice = (await runKtxSetupReadyMenu(currentStatus, deps.readyMenuDeps)).action;
+                if (choice === 'exit')
                     return 0;
+                readyAction = choice;
+            }
+            else if (completion === 'needs-context') {
+                // Config is done; skip the re-walk and land straight on the build prompt.
+                readyAction = 'context';
             }
-            else if (isKtxPreAgentSetupReady(currentStatus)) {
+            else if (completion === 'needs-agents') {
                 readyAction = 'agents';
             }
+            // 'incomplete' → readyAction stays undefined → run the full setup walk.
         }
         const runOnly = readyAction;
         const agentOnlySetup = agentsRequested || runOnly === 'agents';
@@ -467,6 +473,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 const databaseResult = await databasesRunner({
                     projectDir: projectResult.projectDir,
                     inputMode: args.inputMode,
+                    yes: args.yes,
+                    cliVersion: args.cliVersion,
+                    runtimeInstallPolicy: setupRuntimeInstallPolicy(args),
                     ...(args.databaseDrivers ? { databaseDrivers: args.databaseDrivers } : {}),
                     ...(args.databaseConnectionIds ? { databaseConnectionIds: args.databaseConnectionIds } : {}),
                     ...(args.databaseConnectionId ? { databaseConnectionId: args.databaseConnectionId } : {}),
@@ -565,6 +574,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 startedAt: stepStartedAt,
                 io,
                 cliVersion: args.cliVersion,
+                ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
             });
             if (stepResult.status === 'failed') {
                 return 1;
@@ -589,7 +599,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }
             if (step === 'context' && stepResult.status !== 'ready') {
                 if (shouldRunAgents && args.skipAgents !== true) {
-                    return 0;
+                    // Context isn't built, so skip agent install — but still reach the
+                    // completion screen, which states readiness and points at `ktx ingest`.
+                    break setupLoop;
                 }
             }
             forcePromptSteps.delete(step);

package/dist/status-project.d.ts

@@ -62,6 +62,16 @@ type ClaudeCodeAuthProbe = (input: {
     ok: false;
     message: string;
 }>;
+type CodexAuthProbe = (input: {
+    projectDir: string;
+    model: string;
+}) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    fix: string;
+}>;
 interface LocalStatsIngestPerConnection {
     connectionId: string;
     adapter: string;
@@ -135,6 +145,7 @@ export interface BuildProjectStatusOptions {
     env?: NodeJS.ProcessEnv;
     queryHistoryReadinessProbe?: HistoricSqlReadinessProbe;
     claudeCodeAuthProbe?: ClaudeCodeAuthProbe;
+    codexAuthProbe?: CodexAuthProbe;
     configIssues?: KtxConfigIssue[];
     fast?: boolean;
     useSpinner?: boolean;

package/dist/status-project.js

@@ -1,6 +1,8 @@
 import { stat as statAsync, readdir as readdirAsync } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
+import { CODEX_ISOLATION_WARNING, CODEX_ISOLATION_WARNING_FIX, } from './context/llm/codex-isolation.js';
+import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { isQueryHistoryEnabled, queryHistoryDialectForConnection, } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { historicSqlProbeCatalogName, runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
@@ -49,6 +51,18 @@ async function buildLlmStatus(config, options) {
             fix: 'Run: ktx setup (choose an LLM provider)',
         };
     }
+    // The runtime (resolveModelSlots) hard-requires llm.models.default for every
+    // non-none backend; without it ingest/scan/memory throw. Report that here so
+    // status never marks a project ready that the runtime would refuse to run.
+    if (!model || model.trim().length === 0) {
+        return {
+            backend,
+            model,
+            status: 'fail',
+            detail: `llm.models.default is required for backend "${backend}"`,
+            fix: 'Set llm.models.default in ktx.yaml, then rerun `ktx status` (or rerun `ktx setup`).',
+        };
+    }
     if (backend === 'anthropic') {
         const ref = config.provider.anthropic?.api_key;
         const resolved = resolveRef(ref, env);
@@ -90,7 +104,7 @@ async function buildLlmStatus(config, options) {
         };
     }
     if (backend === 'claude-code') {
-        const modelName = model ?? 'sonnet';
+        const modelName = model;
         if (options.fast === true) {
             return {
                 backend,
@@ -117,6 +131,34 @@ async function buildLlmStatus(config, options) {
             fix: 'Authenticate Claude Code locally with the Claude Code CLI, then rerun `ktx status`.',
         };
     }
+    if (backend === 'codex') {
+        const modelName = model;
+        if (options.fast === true) {
+            return {
+                backend,
+                model: modelName,
+                status: 'skipped',
+                detail: 'auth probe skipped (--fast)',
+            };
+        }
+        const probe = options.codexAuthProbe ?? runCodexAuthProbe;
+        const auth = await withSpinner(options.useSpinner === true, 'Probing Codex authentication', () => probe({ projectDir: options.projectDir, model: modelName }));
+        if (auth.ok) {
+            return {
+                backend,
+                model: modelName,
+                status: 'ok',
+                detail: 'local Codex session authenticated',
+            };
+        }
+        return {
+            backend,
+            model: modelName,
+            status: 'fail',
+            detail: auth.message,
+            fix: auth.fix,
+        };
+    }
     return { backend, model, status: 'warn', detail: 'unknown LLM backend' };
 }
 function buildEmbeddingsStatus(config, env) {
@@ -378,6 +420,12 @@ function buildWarnings(config, connections, llm, embeddings) {
             fix: formatClaudeCodePromptCachingFix(),
         });
     }
+    if (llm.backend === 'codex') {
+        warnings.push({
+            message: CODEX_ISOLATION_WARNING,
+            fix: CODEX_ISOLATION_WARNING_FIX,
+        });
+    }
     return warnings;
 }
 function buildVerdict(llm, embeddings, connections, queryHistory, warnings) {
@@ -625,6 +673,7 @@ export async function buildProjectStatus(project, options = {}) {
         projectDir: project.projectDir,
         env,
         claudeCodeAuthProbe: options.claudeCodeAuthProbe,
+        codexAuthProbe: options.codexAuthProbe,
         fast: options.fast,
         useSpinner: options.useSpinner,
     });