@voybio/ace-swarm 0.2.3 → 0.2.4

package/README.md

@@ -2,24 +2,25 @@
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.
 
-`ace-swarm` provides Claude Code, Codex, Cursor, VS Code, and local-model workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `.agents/ACE/ace-state.ace` — so the workspace keeps one source of truth instead of a forest of generated state files.
+`ace-swarm` provides Claude Code, Codex, Cursor, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `.agents/ACE/ace-state.ace` — so the workspace keeps one source of truth instead of a forest of generated state files.
 
-Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For local models, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
+Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For provider-backed runs, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
 
 ## ACE Manifesto
 
 - Agent work should survive restarts, handoffs, and review.
 - Handoffs should be typed, evidence-linked, and validated.
 - Shared workflow state should live in the workspace, not only in chat history.
-- Local models should get the same structure and observability as hosted models.
+- ACE-Orchestrator is the default entrypoint, and every provider can delegate through the full agent set.
+- Provider-backed runs should get the same structure and observability.
 - Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.ace`.
 
-### Serving local models
+### Serving model providers
 
-ACE provides local models with the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.
+ACE provides model providers with the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.
 
-- `ace init --llm ollama` or `ace init --llm llama.cpp` records a local runtime profile in the store.
-- `ace doctor` discovers the endpoint, checks the selected model, and keeps the runtime honest.
+- `ace init --llm <provider>` records the selected runtime profile in the store.
+- `ace doctor` validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
 - `ace mcp` and `ace tui` expose the same workspace truth to the host, the terminal, and the model.
 
 ## Why This Exists Now
@@ -28,7 +29,7 @@ Frontier models are getting more capable and more restricted at the same time. P
 
 - Claude Code proved the terminal-native agent loop.
 - OpenAI connectors and MCP widened the tool surface.
-- Ollama and llama.cpp keep local models in play.
+- Ollama and llama.cpp keep local runtimes in play.
 - MCP remains the common protocol surface across clients and runtimes.
 
 ACE sits underneath that stack. It does not compete with the host you already use. It provides that host with a durable local runtime.
@@ -128,6 +129,15 @@ ace mcp
 
 If you already have a local runtime running, `ace doctor --scan` will probe common Ollama and llama.cpp endpoints and write the selected profile back into the store.
 
+Hosted provider path with Codex:
+
+```bash
+npx -y ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
+export OPENAI_API_KEY=...
+ace doctor --llm codex --model gpt-5
+ace mcp
+```
+
 ## What Bootstrap Writes
 
 ACE bootstrap is intentionally contained. The store is authoritative at `.agents/ACE/ace-state.ace`; only a few host-facing files land in the workspace when requested.
@@ -205,8 +215,8 @@ In that setup, the host remains the interface. ACE becomes the state contract un
 
 Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap.
 
-- `ace init --llm ollama` or `ace init --llm llama.cpp` seeds the profile inside `.agents/ACE/ace-state.ace`.
-- `ace doctor` verifies that the selected runtime is reachable and configured.
+- `ace init --llm <provider>` seeds the profile inside `.agents/ACE/ace-state.ace`.
+- `ace doctor` verifies that the selected runtime is configured and, when possible, reachable.
 - `ace tui` can talk to either local runtime and surface the same workspace state the MCP server sees.
 - The ACE model bridge gives local runs tool selection, execution flow, and persisted state instead of a fragile one-shot chat loop.
 
@@ -236,7 +246,7 @@ If you want local agents with memory, evidence, and handoff discipline, this is
 | `ace turnkey [options]`                     | project the store-backed host surface              |
 | `ace mcp` / `ace serve`                     | start the MCP server over stdio                   |
 | `ace tui [options]`                         | open the terminal operator surface                |
-| `ace doctor [options]`                      | validate local-model readiness                    |
+| `ace doctor [options]`                      | validate ACE runtime readiness                    |
 | `ace mcp-config [--client <name>|--all]`    | print baked client snippets for optional install  |
 | `ace paths`                                 | show resolved package and workspace paths         |
 +---------------------------------------------+---------------------------------------------------+

package/assets/.agents/ACE/ACE-Init/AGENTS.md

@@ -1,9 +1,15 @@
 ---
 name: ACE-Init
 description: Bootstrap-only initializer that materializes ACE state, validates readiness, and hands control to ACE-Orchestrator.
-target: vscode, codex
+target: vscode, codex, claude, cursor, antigravity, copilot, gemini
 tools:
   - vscode
+  - codex
+  - claude
+  - cursor
+  - antigravity
+  - copilot
+  - gemini
   - execute
   - read
   - edit

package/assets/.agents/ACE/orchestrator/AGENTS.md

@@ -1,11 +1,14 @@
 ---
 name: ACE-Orchestrator
 description: Global flow-orchestration contract for routing venture, UX, and engineering work across swarm and composable agents.
-target: vscode, codex
+target: vscode, codex, claude, cursor, antigravity, copilot, gemini
 tools:
   - vscode
   - codex
   - claude
+  - cursor
+  - antigravity
+  - copilot
   - gemini
   - execute
   - read

package/dist/cli.js

@@ -13,7 +13,8 @@ import { DiscoveryRepository } from "./store/repositories/discovery-repository.j
 import { getWorkspaceStorePath, readStoreBlobSync, readStoreJsonSync, } from "./store/store-snapshot.js";
 import { readFileSync } from "node:fs";
 import { runTui } from "./tui/index.js";
-import { buildOpenAiCompatibleBaseUrl, DEFAULT_LLAMA_CPP_MODEL, DEFAULT_OLLAMA_MODEL, discoverProviderContext, normalizeLocalBaseUrl, scanLocalModelRuntimes, } from "./tui/provider-discovery.js";
+import { buildOpenAiCompatibleBaseUrl, buildProviderDoctorCommands, defaultModelForProvider, discoverProviderContext, isLocalLlmProvider, normalizeLocalBaseUrl, normalizeProvider, scanLocalModelRuntimes, } from "./tui/provider-discovery.js";
+import { diagnoseChatRuntimeConfig, OpenAICompatibleClient, } from "./tui/openai-compatible.js";
 function printHelp() {
     console.log(`ACE Swarm CLI
 
@@ -23,7 +24,7 @@ Usage:
   ace tui [options]            Launch interactive TUI dashboard
   ace init [options]           Bootstrap the ACE store into current workspace
   ace turnkey [options]        Project minimal workspace bootstrap stubs from the ACE store
-  ace doctor [options]         Validate local LLM + MCP readiness
+  ace doctor [options]         Validate ACE runtime + MCP readiness
   ace mcp-config [options]     Print global/client MCP config snippet(s) from store
   ace preconfig                Write .mcp-config/ bundle for all supported clients to workspace root
   ace paths                    Show resolved package/workspace paths
@@ -40,15 +41,15 @@ Options for init:
   --force                      Overwrite scaffolded files if they already exist
   --mcp-config                 Also write .vscode/mcp.json workspace bridge
   --client-config-bundle       Also write minimal workspace host stubs (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md)
-  --llm <provider>             ollama|llama.cpp
-  --model <name>               Model name for local provider
-  --base-url <url>             Local runtime base URL override
+  --llm <provider>             ollama|llama.cpp|codex|claude|gemini|copilot|...
+  --model <name>               Model name for the selected provider
+  --base-url <url>             Runtime base URL override (local or OpenAI-compatible)
   --ollama-url <url>           Legacy alias for --base-url
 
 Options for doctor:
-  --llm <provider>             ollama|llama.cpp (default: auto from ${ACE_ROOT_REL}/ace-state.ace)
+  --llm <provider>             ollama|llama.cpp|codex|claude|gemini|copilot|... (default: auto from ${ACE_ROOT_REL}/ace-state.ace)
   --model <name>               Model name override
-  --base-url <url>             Local runtime base URL override
+  --base-url <url>             Runtime base URL override
   --ollama-url <url>           Legacy alias for --base-url
   --scan                       Probe common local Ollama + llama.cpp endpoints when URL is unset
 
@@ -92,14 +93,14 @@ function readBaseUrlFlag(args) {
 }
 function parseLlmOptions(args) {
     const profile = readLlmProfile();
-    const selected = readFlagValue(args, "--llm")?.trim().toLowerCase() ?? profile?.provider?.trim().toLowerCase();
+    const selected = normalizeProvider(readFlagValue(args, "--llm")?.trim() ?? profile?.provider?.trim());
     if (!selected)
         return {};
     if (!ALL_LLM_PROVIDERS.includes(selected)) {
         throw new Error(`Unsupported LLM provider: ${selected}`);
     }
     const provider = selected;
-    const defaultModel = provider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL;
+    const defaultModel = defaultModelForProvider(provider);
     const llmModel = readFlagValue(args, "--model")?.trim() || profile?.model || defaultModel;
     const llmBaseUrl = readBaseUrlFlag(args) ?? normalizeLocalBaseUrl(profile?.base_url);
     return {
@@ -123,30 +124,17 @@ async function writeLlmProfile(profile) {
                 payload.default_api_key = "ollama";
             }
         }
-        const doctorCommands = profile.provider === "ollama"
-            ? [
-                "ollama serve",
-                `ollama pull ${profile.model}`,
-                ...(profile.baseUrl ? [`curl -s ${profile.baseUrl}/api/tags`] : []),
-            ]
-            : [
-                "# Start llama-server separately, for example:",
-                "# llama-server -m /path/to/model.gguf --port 8080",
-                ...(profile.baseUrl ? [`curl -s ${buildOpenAiCompatibleBaseUrl(profile.baseUrl)}/models`] : []),
-            ];
+        const doctorCommands = buildProviderDoctorCommands(profile.provider, profile.model, profile.baseUrl);
         const store = await openStore(storePath);
         try {
             await store.setJSON("state/runtime/llm_profile", payload);
             await store.setBlob("state/runtime/doctor_checks.md", [
-                `# ACE + ${profile.provider} Doctor Checks`,
+                `# ACE + ${profile.provider} Runtime Checks`,
                 "",
-                "Run these commands to verify local-model readiness:",
+                "Run these commands to verify ACE runtime readiness:",
                 "",
                 "```bash",
                 ...doctorCommands,
-                profile.baseUrl
-                    ? `ace doctor --llm ${profile.provider} --model ${profile.model} --base-url ${profile.baseUrl}`
-                    : `ace doctor --llm ${profile.provider} --model ${profile.model} --scan`,
                 "```",
                 "",
             ].join("\n"));
@@ -202,7 +190,7 @@ async function runInit(args, mode = "init") {
         includeClientConfigBundle,
         llm: llm.llmProvider ?? undefined,
         model: llm.llmModel ?? undefined,
-        ollamaUrl: llm.llmBaseUrl ?? undefined,
+        baseUrl: llm.llmBaseUrl ?? undefined,
     });
     const astIndex = refreshAstgrepIndex({
         scope: ".",
@@ -237,7 +225,10 @@ async function runInit(args, mode = "init") {
     if (llm.llmProvider) {
         console.log(`LLM provider: ${llm.llmProvider}`);
         console.log(`Model: ${llm.llmModel}`);
-        console.log(`Base URL: ${llm.llmBaseUrl ?? "(not set; run ace doctor --scan or pass --base-url)"}`);
+        console.log(`Base URL: ${llm.llmBaseUrl ??
+            (isLocalLlmProvider(llm.llmProvider)
+                ? "(not set; run ace doctor --scan or pass --base-url)"
+                : "(not set; provider defaults or env may still apply)")}`);
         console.log(`LLM profile path: ${storeResult.storePath}#state/runtime/llm_profile`);
     }
     if (storeResult.materialized.length > 0) {
@@ -324,7 +315,6 @@ async function listLocalRuntimeModels(provider, baseUrl) {
 async function runDoctor(args) {
     const llm = parseLlmOptions(args);
     const checks = [];
-    const shouldScan = args.includes("--scan") || !llm.llmBaseUrl;
     const mcpConfigPaths = [wsPath(".vscode", "mcp.json")];
     const hasWorkspaceMcpConfig = mcpConfigPaths.some((path) => fileExists(path));
     const hasStoredMcpConfig = ALL_MCP_CLIENTS.some((client) => typeof readStoredMcpSnippet(client) === "string");
@@ -345,11 +335,12 @@ async function runDoctor(args) {
         ok: hasProfile,
         detail: hasProfile
             ? profilePath
-            : `Missing ${ACE_ROOT_REL}/ace-state.ace#state/runtime/llm_profile. Run \`ace init --llm ollama\` or \`ace doctor --scan\`.`,
+            : `Missing ${ACE_ROOT_REL}/ace-state.ace#state/runtime/llm_profile. Run \`ace init --llm <provider>\` or \`ace doctor --scan\` for a local runtime.`,
     });
     let provider = llm.llmProvider;
     let model = llm.llmModel;
     let baseUrl = llm.llmBaseUrl;
+    const shouldScan = args.includes("--scan") || (!provider && !baseUrl) || (isLocalLlmProvider(provider) && !baseUrl);
     if (shouldScan) {
         const scanned = await scanLocalModelRuntimes({
             workspaceRoot: WORKSPACE_ROOT,
@@ -361,7 +352,7 @@ async function runDoctor(args) {
         if (chosen) {
             provider = chosen.provider ?? provider;
             baseUrl = baseUrl ?? chosen.baseUrl;
-            model = model || chosen.models[0] || (provider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL);
+            model = model || chosen.models[0] || defaultModelForProvider(provider);
             checks.push({
                 name: "Runtime endpoint discovered",
                 ok: true,
@@ -369,7 +360,7 @@ async function runDoctor(args) {
             });
             const writtenProfilePath = await writeLlmProfile({
                 provider: provider ?? chosen.provider,
-                model: model ?? (provider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL),
+                model: model ?? defaultModelForProvider(provider ?? chosen.provider),
                 baseUrl,
             });
             checks.push({
@@ -387,19 +378,19 @@ async function runDoctor(args) {
         }
     }
     if (!provider) {
-        throw new Error(`No local runtime provider configured. Use --llm <provider>, bootstrap one into ${ACE_ROOT_REL}/ace-state.ace#state/runtime/llm_profile, or run \`ace doctor --scan\`.`);
+        throw new Error(`No runtime provider configured. Use --llm <provider>, bootstrap one into ${ACE_ROOT_REL}/ace-state.ace#state/runtime/llm_profile, or run \`ace doctor --scan\` for a local runtime.`);
     }
     if (!model) {
-        model = provider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL;
+        model = defaultModelForProvider(provider);
     }
-    if (!baseUrl) {
+    if (isLocalLlmProvider(provider) && !baseUrl) {
         checks.push({
             name: "Base URL configured",
             ok: false,
             detail: "No local runtime base URL is configured. Pass --base-url or run `ace doctor --scan` to discover one.",
         });
         const failed = checks.filter((check) => !check.ok);
-        console.log("ACE Doctor Report (local runtime)");
+        console.log("ACE Doctor Report");
         console.log(`Workspace: ${WORKSPACE_ROOT}`);
         console.log(`Provider: ${provider}`);
         console.log(`Model: ${model}`);
@@ -415,48 +406,94 @@ async function runDoctor(args) {
         return;
     }
     let modelNames = [];
-    try {
-        modelNames = await listLocalRuntimeModels(provider, baseUrl);
+    if (isLocalLlmProvider(provider)) {
+        try {
+            modelNames = await listLocalRuntimeModels(provider, baseUrl);
+            checks.push({
+                name: "Runtime endpoint reachable",
+                ok: true,
+                detail: provider === "ollama"
+                    ? `${baseUrl}/api/tags responded with ${modelNames.length} models`
+                    : `${buildOpenAiCompatibleBaseUrl(baseUrl)}/models responded with ${modelNames.length} models`,
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: "Runtime endpoint reachable",
+                ok: false,
+                detail: `${baseUrl} request failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        const hasModel = modelNames.includes(model);
+        await recordDiscoveryProfile({
+            provider,
+            baseUrl: baseUrl,
+            models: modelNames,
+            selectedModel: model,
+            available: modelNames.length > 0,
+        });
         checks.push({
-            name: "Runtime endpoint reachable",
-            ok: true,
+            name: provider === "ollama" ? "Requested model installed" : "Requested model served",
+            ok: hasModel,
             detail: provider === "ollama"
-                ? `${baseUrl}/api/tags responded with ${modelNames.length} models`
-                : `${buildOpenAiCompatibleBaseUrl(baseUrl)}/models responded with ${modelNames.length} models`,
+                ? hasModel
+                    ? `${model} found`
+                    : `${model} missing (run: ollama pull ${model})`
+                : hasModel
+                    ? `${model} found`
+                    : `${model} not reported by llama.cpp (available: ${modelNames.join(", ") || "none"})`,
         });
     }
-    catch (error) {
+    else {
+        const diagnosis = diagnoseChatRuntimeConfig(provider, model, baseUrl ? { baseUrl } : undefined);
         checks.push({
-            name: "Runtime endpoint reachable",
-            ok: false,
-            detail: `${baseUrl} request failed: ${error instanceof Error ? error.message : String(error)}`,
+            name: "Runtime config ready",
+            ok: diagnosis.ok,
+            detail: diagnosis.message,
         });
+        if (diagnosis.ok) {
+            try {
+                const client = new OpenAICompatibleClient({
+                    providerConfigs: baseUrl ? { [provider]: { baseUrl } } : undefined,
+                });
+                modelNames = await client.listModels(provider);
+                checks.push({
+                    name: "Provider endpoint reachable",
+                    ok: true,
+                    detail: `${provider} /models responded with ${modelNames.length} models`,
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: "Provider endpoint reachable",
+                    ok: false,
+                    detail: `${provider} model listing failed: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+            if (modelNames.length > 0) {
+                const requestedModel = provider === "copilot" ? model.replace(/^copilot\//, "") : model;
+                const hasModel = modelNames.includes(requestedModel);
+                checks.push({
+                    name: "Requested model available",
+                    ok: hasModel,
+                    detail: hasModel
+                        ? `${requestedModel} found`
+                        : `${requestedModel} not reported by ${provider} (available: ${modelNames.join(", ") || "none"})`,
+                });
+            }
+        }
     }
-    const hasModel = modelNames.includes(model);
-    await recordDiscoveryProfile({
-        provider,
-        baseUrl,
-        models: modelNames,
-        selectedModel: model,
-        available: modelNames.length > 0,
-    });
-    checks.push({
-        name: provider === "ollama" ? "Requested model installed" : "Requested model served",
-        ok: hasModel,
-        detail: provider === "ollama"
-            ? hasModel
-                ? `${model} found`
-                : `${model} missing (run: ollama pull ${model})`
-            : hasModel
-                ? `${model} found`
-                : `${model} not reported by llama.cpp (available: ${modelNames.join(", ") || "none"})`,
-    });
     const failed = checks.filter((check) => !check.ok);
-    console.log("ACE Doctor Report (local runtime)");
+    console.log("ACE Doctor Report");
     console.log(`Workspace: ${WORKSPACE_ROOT}`);
     console.log(`Provider: ${provider}`);
     console.log(`Model: ${model}`);
-    console.log(`Base URL: ${baseUrl}`);
+    if (isLocalLlmProvider(provider)) {
+        console.log(`Base URL: ${baseUrl}`);
+    }
+    else if (baseUrl) {
+        console.log(`Base URL override: ${baseUrl}`);
+    }
     console.log("");
     for (const check of checks) {
         const status = check.ok ? "PASS" : "FAIL";

package/dist/helpers.d.ts

@@ -22,7 +22,7 @@ export declare const ACE_HOST_CLAUDE_REL = "CLAUDE.md";
 export declare const ACE_HOST_CURSOR_RULES_REL = ".cursorrules";
 export declare const ALL_MCP_CLIENTS: readonly ["codex", "vscode", "claude", "cursor", "antigravity"];
 export type McpClient = (typeof ALL_MCP_CLIENTS)[number];
-export declare const ALL_LLM_PROVIDERS: readonly ["ollama", "llama.cpp"];
+export declare const ALL_LLM_PROVIDERS: readonly ["ollama", "llama.cpp", "codex", "claude", "gemini", "copilot"];
 export type LlmProvider = (typeof ALL_LLM_PROVIDERS)[number];
 export declare const ALL_AGENTS: readonly ["orchestrator", "vos", "ui", "coders", "astgrep", "skeptic", "ops", "research", "spec", "builder", "qa", "docs", "memory", "security", "observability", "eval", "release"];
 export type AgentRole = (typeof ALL_AGENTS)[number];

package/dist/helpers.js

@@ -9,7 +9,7 @@ import { buildHostInstructionText } from "./ace-server-instructions.js";
 import { isInside, normalizeRelPath } from "./shared.js";
 import { getWorkspaceStorePath, listStoreKeysSync, parseVirtualStorePath, readStoreBlobSync, readVirtualStorePathSync, toVirtualStorePath, } from "./store/store-snapshot.js";
 import { isOperationalArtifactPath, operationalArtifactKey, writeStoreBlobSync, writeOperationalArtifactSync, } from "./store/store-artifacts.js";
-import { buildOpenAiCompatibleBaseUrl, DEFAULT_LLAMA_CPP_MODEL, DEFAULT_OLLAMA_MODEL, normalizeLocalBaseUrl, } from "./tui/provider-discovery.js";
+import { buildProviderDoctorCommands, buildOpenAiCompatibleBaseUrl, defaultModelForProvider, normalizeLocalBaseUrl, normalizeProvider, } from "./tui/provider-discovery.js";
 export { isInside, isReadError, normalizeRelPath, looksLikeSwarmHandoffPath } from "./shared.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -128,7 +128,14 @@ export const ALL_MCP_CLIENTS = [
     "cursor",
     "antigravity",
 ];
-export const ALL_LLM_PROVIDERS = ["ollama", "llama.cpp"];
+export const ALL_LLM_PROVIDERS = [
+    "ollama",
+    "llama.cpp",
+    "codex",
+    "claude",
+    "gemini",
+    "copilot",
+];
 export const ALL_AGENTS = [
     "orchestrator",
     "vos",
@@ -1325,10 +1332,11 @@ export function bootstrapAceWorkspace(options = {}) {
     const projectName = options.projectName?.trim() || "ACE Project";
     const includeMcpConfig = options.includeMcpConfig ?? true;
     const includeClientConfigBundle = options.includeClientConfigBundle ?? true;
-    const llmProvider = options.llmProvider;
+    const normalizedProvider = normalizeProvider(options.llmProvider);
+    const llmProvider = normalizedProvider;
     const llmModel = options.llmModel?.trim() ||
         options.ollamaModel?.trim() ||
-        (llmProvider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL);
+        defaultModelForProvider(llmProvider);
     const llmBaseUrl = normalizeLocalBaseUrl(options.llmBaseUrl ?? options.ollamaBaseUrl);
     if (llmProvider && !ALL_LLM_PROVIDERS.includes(llmProvider)) {
         throw new Error(`Unsupported llmProvider: ${llmProvider}`);
@@ -1654,12 +1662,14 @@ export function bootstrapAceWorkspace(options = {}) {
             ...(llmProvider
                 ? [
                     "",
-                    "## Local Model Profile",
+                    "## LLM Runtime Profile",
                     `- \`${ACE_LLM_ROOT_REL}/llm-profile.json\` (generated for ${llmProvider})`,
-                    `- \`${ACE_LLM_ROOT_REL}/doctor-checks.md\` (commands to verify local runtime)`,
+                    `- \`${ACE_LLM_ROOT_REL}/doctor-checks.md\` (commands to verify provider runtime)`,
                     llmBaseUrl
                         ? `- Run \`ace doctor --llm ${llmProvider} --model ${llmModel} --base-url ${llmBaseUrl}\``
-                        : `- Run \`ace doctor --llm ${llmProvider} --model ${llmModel} --scan\` to discover a local endpoint`,
+                        : llmProvider === "ollama" || llmProvider === "llama.cpp"
+                            ? `- Run \`ace doctor --llm ${llmProvider} --model ${llmModel} --scan\` to discover a local endpoint`
+                            : `- Run \`ace doctor --llm ${llmProvider} --model ${llmModel}\` after exporting the provider credentials`,
                 ]
                 : []),
         ].join("\n"), result, force);
@@ -1678,27 +1688,14 @@ export function bootstrapAceWorkspace(options = {}) {
             }
         }
         writeIfMissingOrForced(wsPath(".ace", "llm-profile.json"), JSON.stringify(profilePayload, null, 2), result, force);
-        const doctorCommands = llmProvider === "ollama"
-            ? [
-                "ollama serve",
-                `ollama pull ${llmModel}`,
-                ...(llmBaseUrl ? [`curl -s ${llmBaseUrl}/api/tags`] : []),
-            ]
-            : [
-                "# Start llama-server separately, for example:",
-                "# llama-server -m /path/to/model.gguf --port 8080",
-                ...(llmBaseUrl ? [`curl -s ${buildOpenAiCompatibleBaseUrl(llmBaseUrl)}/models`] : []),
-            ];
+        const doctorCommands = buildProviderDoctorCommands(llmProvider, llmModel, llmBaseUrl);
         writeIfMissingOrForced(wsPath(".ace", "doctor-checks.md"), [
-            `# ACE + ${llmProvider} Doctor Checks`,
+            `# ACE + ${llmProvider} Runtime Checks`,
             "",
-            "Run these commands to verify local-model readiness:",
+            "Run these commands to verify ACE runtime readiness:",
             "",
             "```bash",
             ...doctorCommands,
-            llmBaseUrl
-                ? `ace doctor --llm ${llmProvider} --model ${llmModel} --base-url ${llmBaseUrl}`
-                : `ace doctor --llm ${llmProvider} --model ${llmModel} --scan`,
             "```",
             "",
             `MCP is still configured separately via \`${ACE_VSCODE_ROOT_REL}/mcp.json\` or \`${ACE_BUNDLE_ROOT_REL}/*\`.`,

package/dist/local-model-runtime.js

@@ -1,6 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { ROLE_ENUM, scoreDomains } from "./shared.js";
+import { ROLE_ENUM } from "./shared.js";
 import { resolveWorkspaceRoot } from "./helpers.js";
 import { executeAceInternalTool } from "./ace-internal-tools.js";
 import { ModelBridge } from "./model-bridge.js";
@@ -28,61 +27,17 @@ function normalizeRoleCandidate(input) {
         ? candidate
         : undefined;
 }
-function parseRoleFromRoutingSummary(summary) {
-    const match = summary.match(/\*\*Primary Swarm Agent\(s\):\*\*\s*([^\n]+)/i);
-    if (!match?.[1])
-        return undefined;
-    const firstAgent = match[1]
-        .split(",")
-        .map((entry) => entry.trim())
-        .find(Boolean);
-    return normalizeRoleCandidate(firstAgent);
-}
-function hasAlignedTaskContract(workspaceRoot) {
-    const required = [
-        "agent-state/TASK.md",
-        "agent-state/SCOPE.md",
-        "agent-state/QUALITY_GATES.md",
-        "agent-state/HANDOFF.json",
-    ];
-    return required.every((relativePath) => {
-        const absolute = resolve(workspaceRoot, relativePath);
-        if (!existsSync(absolute))
-            return false;
-        return readFileSync(absolute, "utf-8").trim().length > 0;
-    });
+function fallbackRoleForTask() {
+    return "orchestrator";
 }
-function fallbackRoleForTask(task, workspaceRoot) {
-    if (!hasAlignedTaskContract(workspaceRoot)) {
-        return "orchestrator";
-    }
-    const { domain } = scoreDomains(task);
-    switch (domain) {
-        case "engineering":
-            return "coders";
-        case "venture":
-            return "vos";
-        case "ux":
-            return "ui";
-        default:
-            return "orchestrator";
-    }
-}
-async function resolveRole(task, workspaceRoot, sessionId, requestedRole) {
+async function resolveRole(task, sessionId, requestedRole) {
     const explicitRole = normalizeRoleCandidate(requestedRole);
     if (explicitRole) {
         return { role: explicitRole, routingSummary: undefined };
     }
     const routing = await executeAceInternalTool("route_task", { description: task, domain: "unknown" }, sessionId);
     const routingSummary = extractTextContent(routing);
-    const routedRole = parseRoleFromRoutingSummary(routingSummary);
-    const fallbackRole = fallbackRoleForTask(task, workspaceRoot);
-    return {
-        role: routedRole && !(routedRole === "orchestrator" && fallbackRole !== "orchestrator")
-            ? routedRole
-            : fallbackRole,
-        routingSummary,
-    };
+    return { role: fallbackRoleForTask(), routingSummary };
 }
 function resolveTier(requested, provider, model, role) {
     if (requested && requested !== "auto")
@@ -152,7 +107,7 @@ export async function runLocalModelTask(options) {
         ollamaUrl: options.ollamaUrl,
     });
     const bridge = new ModelBridge(options.clients ?? createDefaultModelBridgeClients(runtime));
-    const { role, routingSummary } = await resolveRole(options.task, runtime.workspaceRoot, undefined, options.role);
+    const { role, routingSummary } = await resolveRole(options.task, undefined, options.role);
     const tier = resolveTier(options.tier, runtime.provider, runtime.model, role);
     const result = await bridge.run({
         task: options.task,

package/dist/store/bootstrap-store.d.ts

@@ -24,6 +24,7 @@ export interface BootstrapOptions {
     mcpServerPath?: string;
     llm?: string;
     model?: string;
+    baseUrl?: string;
     ollamaUrl?: string;
 }
 export interface BootstrapResult {

package/dist/store/bootstrap-store.js

@@ -27,7 +27,7 @@ import { ProjectionManager } from "./materializers/projection-manager.js";
 import { TodoSyncer } from "./materializers/todo-syncer.js";
 import { OPERATIONAL_ARTIFACT_REL_PATHS, operationalArtifactKey, } from "./store-artifacts.js";
 import { STORE_VERSION } from "./types.js";
-import { DEFAULT_LLAMA_CPP_MODEL, DEFAULT_OLLAMA_MODEL, } from "../tui/provider-discovery.js";
+import { buildProviderDoctorCommands, defaultModelForProvider, normalizeLocalBaseUrl, normalizeProvider, } from "../tui/provider-discovery.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function getAssetsRoot() {
     // Resolve relative to this file's location in the installed package
@@ -40,45 +40,32 @@ function getAssetsRoot() {
 async function applyLlmRuntimeConfig(store, opts) {
     if (!opts.llm)
         return;
-    const configuredModel = opts.model ?? (opts.llm === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL);
+    const provider = normalizeProvider(opts.llm) ?? opts.llm;
+    const configuredModel = opts.model ?? defaultModelForProvider(provider);
+    const configuredBaseUrl = normalizeLocalBaseUrl(opts.baseUrl ?? opts.ollamaUrl);
     const profilePayload = {
-        provider: opts.llm,
+        provider,
         model: configuredModel,
         generated_at: new Date().toISOString(),
     };
-    if (opts.ollamaUrl) {
-        profilePayload.base_url = opts.ollamaUrl;
-        if (opts.llm === "ollama") {
-            profilePayload.api_compat_base_url = opts.ollamaUrl.endsWith("/v1")
-                ? opts.ollamaUrl
-                : `${opts.ollamaUrl}/v1`;
+    if (configuredBaseUrl) {
+        profilePayload.base_url = configuredBaseUrl;
+        if (provider === "ollama") {
+            profilePayload.api_compat_base_url = configuredBaseUrl.endsWith("/v1")
+                ? configuredBaseUrl
+                : `${configuredBaseUrl}/v1`;
             profilePayload.default_api_key = "ollama";
         }
     }
     await store.setJSON("state/runtime/llm_profile", profilePayload);
-    const doctorCommands = opts.llm === "ollama"
-        ? [
-            "ollama serve",
-            `ollama pull ${configuredModel}`,
-            ...(opts.ollamaUrl ? [`curl -s ${opts.ollamaUrl}/api/tags`] : []),
-        ]
-        : [
-            "# Start llama-server separately, for example:",
-            "# llama-server -m /path/to/model.gguf --port 8080",
-            ...(opts.ollamaUrl
-                ? [`curl -s ${opts.ollamaUrl.endsWith("/v1") ? opts.ollamaUrl : `${opts.ollamaUrl}/v1`}/models`]
-                : []),
-        ];
+    const doctorCommands = buildProviderDoctorCommands(provider, configuredModel, configuredBaseUrl);
     await store.setBlob("state/runtime/doctor_checks.md", [
-        `# ACE + ${opts.llm} Doctor Checks`,
+        `# ACE + ${provider} Runtime Checks`,
         "",
-        "Run these commands to verify local-model readiness:",
+        "Run these commands to verify ACE runtime readiness:",
         "",
         "```bash",
         ...doctorCommands,
-        opts.ollamaUrl
-            ? `ace doctor --llm ${opts.llm} --model ${configuredModel} --base-url ${opts.ollamaUrl}`
-            : `ace doctor --llm ${opts.llm} --model ${configuredModel} --scan`,
         "```",
         "",
     ].join("\n"));

package/dist/tools-agent.js

@@ -52,25 +52,6 @@ function extractToolTextContent(result) {
         .filter(Boolean)
         .join("\n");
 }
-function normalizeRoleCandidate(input) {
-    if (!input)
-        return undefined;
-    const normalized = input.trim().toLowerCase().replace(/^ace-/, "").replace(/[^a-z0-9]+/g, "");
-    const candidate = normalized === "coder" ? "coders" : normalized;
-    return ROLE_ENUM.options.includes(candidate)
-        ? candidate
-        : undefined;
-}
-function parseRoleFromRoutingSummary(summary) {
-    const match = summary.match(/\*\*Primary Swarm Agent\(s\):\*\*\s*([^\n]+)/i);
-    if (!match?.[1])
-        return undefined;
-    const firstAgent = match[1]
-        .split(",")
-        .map((entry) => entry.trim())
-        .find(Boolean);
-    return normalizeRoleCandidate(firstAgent);
-}
 function mapRoleToTaskType(role) {
     switch (role) {
         case "vos":
@@ -91,9 +72,8 @@ function extractHandoffId(text) {
     return lineMatch?.[1];
 }
 async function buildOrchestratorSteps(task, sessionId) {
-    const routing = await executeAceInternalTool("route_task", { description: task, domain: "unknown" }, sessionId);
-    const routedRole = parseRoleFromRoutingSummary(extractToolTextContent(routing)) ?? "orchestrator";
-    return [{ role: routedRole, task }];
+    void sessionId;
+    return [{ role: "orchestrator", task }];
 }
 function appendUniqueNote(target, note) {
     if (!target.includes(note)) {
@@ -566,9 +546,9 @@ export function registerAgentTools(server) {
             ],
         };
     });
-    server.tool("run_local_model", "Offload a governed ACE subtask to a local model bridge and return the result", {
-        task: z.string().describe("Task to execute with the local ACE model bridge"),
-        role: ROLE_ENUM.optional().describe("Optional ACE role; defaults to route_task"),
+    server.tool("run_local_model", "Offload a governed ACE subtask to the provider-backed ACE bridge and return the result", {
+        task: z.string().describe("Task to execute with the ACE model bridge"),
+        role: ROLE_ENUM.optional().describe("Optional ACE role; defaults to orchestrator"),
         max_turns: z
             .number()
             .int()
@@ -582,15 +562,15 @@ export function registerAgentTools(server) {
         provider: z
             .string()
             .optional()
-            .describe("Optional provider override; otherwise discovered from local runtime context"),
+            .describe("Optional provider override; otherwise discovered from workspace/runtime context"),
         model: z
             .string()
             .optional()
-            .describe("Optional model override; otherwise discovered from local runtime context"),
+            .describe("Optional model override; otherwise discovered from workspace/runtime context"),
         base_url: z
             .string()
             .optional()
-            .describe("Optional local runtime base URL override"),
+            .describe("Optional provider base URL override"),
         ollama_url: z
             .string()
             .optional()
@@ -621,7 +601,7 @@ export function registerAgentTools(server) {
                 {
                     type: "text",
                     text: [
-                        "## Local Model Run",
+                        "## Delegated Run",
                         `- role: ${delegated.role}`,
                         `- provider: ${delegated.runtime.provider}`,
                         `- model: ${delegated.runtime.model}`,
@@ -655,7 +635,7 @@ export function registerAgentTools(server) {
             ],
         };
     });
-    server.tool("run_orchestrator", "Execute a supervised plan via model bridge child runs; when steps are omitted, auto-planning falls back to a single route_task-derived step", {
+    server.tool("run_orchestrator", "Execute a supervised plan via model bridge child runs; when steps are omitted, the plan starts with ACE-Orchestrator", {
         task: z.string().describe("The task to decompose and execute"),
         steps: z
             .array(z.object({
@@ -675,7 +655,7 @@ export function registerAgentTools(server) {
                 .describe("Optional ACE tool allowlist for the step"),
         }))
             .optional()
-            .describe("Pre-defined steps; if omitted, the orchestrator derives a single routed step"),
+            .describe("Pre-defined steps; if omitted, the orchestrator starts with a single ACE-Orchestrator step"),
         execution_mode: z
             .enum(["sequential", "scheduled"])
             .optional()
@@ -689,15 +669,15 @@ export function registerAgentTools(server) {
         provider: z
             .string()
             .optional()
-            .describe("Optional provider override; otherwise discovered from local runtime context"),
+            .describe("Optional provider override; otherwise discovered from workspace/runtime context"),
         model: z
             .string()
             .optional()
-            .describe("Optional model override; otherwise discovered from local runtime context"),
+            .describe("Optional model override; otherwise discovered from workspace/runtime context"),
         base_url: z
             .string()
             .optional()
-            .describe("Optional local runtime base URL override"),
+            .describe("Optional provider base URL override"),
         ollama_url: z
             .string()
             .optional()
@@ -715,7 +695,7 @@ export function registerAgentTools(server) {
             ollamaUrl: ollama_url,
         });
         const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
-        const planSource = Array.isArray(steps) && steps.length > 0 ? "explicit_steps" : "route_task_single_step";
+        const planSource = Array.isArray(steps) && steps.length > 0 ? "explicit_steps" : "orchestrator_default_step";
         const planSteps = Array.isArray(steps) && steps.length > 0
             ? steps
             : await buildOrchestratorSteps(task, sessionId);
@@ -840,8 +820,8 @@ export function registerAgentTools(server) {
                     text: JSON.stringify({
                         runtime,
                         plan_source: planSource,
-                        planning_note: planSource === "route_task_single_step"
-                            ? "Auto-planning currently falls back to a single route_task-derived step. Pass explicit steps for multi-step orchestration."
+                        planning_note: planSource === "orchestrator_default_step"
+                            ? "Auto-planning currently starts with ACE-Orchestrator. Pass explicit steps for multi-step orchestration."
                             : null,
                         plan: supervised.plan,
                         step_summaries,

package/dist/tools-framework.js

@@ -4,9 +4,9 @@
  */
 import { z } from "zod";
 import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
-import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, safeRead, safeWrite, withFileLock, wsPath, } from "./helpers.js";
+import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, safeRead, safeWrite, withFileLock, wsPath, } from "./helpers.js";
 import { getRoleTitle, MCP_CLIENT_ENUM, scoreDomains, } from "./shared.js";
-import { DEFAULT_LLAMA_CPP_MODEL, DEFAULT_OLLAMA_MODEL, } from "./tui/provider-discovery.js";
+import { defaultModelForProvider, } from "./tui/provider-discovery.js";
 import { refreshAstgrepIndex } from "./astgrep-index.js";
 import { scanWorkspaceDelta } from "./index-store.js";
 import { getOrRefreshKanbanSnapshot } from "./kanban.js";
@@ -289,7 +289,7 @@ export function registerFrameworkTools(server) {
         }
         const routingMap = {
             venture: {
-                swarm_agents: ["vos"],
+                swarm_agents: ["orchestrator"],
                 subagents: [
                     "astgrep",
                     "research",
@@ -298,11 +298,11 @@ export function registerFrameworkTools(server) {
                     "skeptic",
                     "ops",
                 ],
-                pipeline: "VOS -> UI -> Coders (as needed) with composable Research/Spec/Skeptic/Ops support",
-                prompt: "ace-vos",
+                pipeline: "Orchestrator -> VOS/UI/Coders as needed with composable Research/Spec/Skeptic/Ops support",
+                prompt: "ace-orchestrator",
             },
             ux: {
-                swarm_agents: ["ui"],
+                swarm_agents: ["orchestrator"],
                 subagents: [
                     "astgrep",
                     "research",
@@ -313,11 +313,11 @@ export function registerFrameworkTools(server) {
                     "skeptic",
                     "ops",
                 ],
-                pipeline: "UI -> Coders with composable Spec/Builder/QA and Skeptic/Ops sidecars",
-                prompt: "ace-ui",
+                pipeline: "Orchestrator -> UI/Coders with composable Spec/Builder/QA and Skeptic/Ops sidecars",
+                prompt: "ace-orchestrator",
             },
             engineering: {
-                swarm_agents: ["coders"],
+                swarm_agents: ["orchestrator"],
                 subagents: [
                     "astgrep",
                     "spec",
@@ -331,8 +331,8 @@ export function registerFrameworkTools(server) {
                     "skeptic",
                     "ops",
                 ],
-                pipeline: "Coders with composable Spec -> Builder -> QA -> Docs and Skeptic/Ops guards",
-                prompt: "ace-coders",
+                pipeline: "Orchestrator -> Coders with composable Spec -> Builder -> QA -> Docs and Skeptic/Ops guards",
+                prompt: "ace-orchestrator",
             },
             mixed: {
                 swarm_agents: ["orchestrator"],
@@ -486,7 +486,8 @@ export function registerFrameworkTools(server) {
                         `**Primary Swarm Agent(s):** ${activeRoute.swarm_agents
                             .map((agent) => `ACE-${getRoleTitle(agent)}`)
                             .join(", ")}`,
-                        "**Hierarchy Rule:** Top-level routing stays locked to ACE-Orchestrator, ACE-VOS, ACE-UI, or ACE-Coders. Composable agents are delegated specialists, not peer replacements.",
+                        "**Default Entry Agent:** ACE-Orchestrator",
+                        "**Hierarchy Rule:** Top-level work starts with ACE-Orchestrator. VOS, UI, and Coders are delegated specialists, not peer replacements.",
                         `**Preflight Owner:** ACE-Orchestrator`,
                         `**Task Contract:** ${taskContract.ok ? "aligned" : "attention required"}`,
                         `**Composable Subagents (Universal):** ${[...COMPOSABLE_AGENTS].join(", ")}`,
@@ -523,7 +524,7 @@ export function registerFrameworkTools(server) {
         };
     });
     // ── Bootstrap ─────────────────────────────────────────────────────
-    server.tool("bootstrap_state", "Bootstrap ACE framework files (state, tasks, instructions, skills, scripts, MCP configs, optional local LLM profile)", {
+    server.tool("bootstrap_state", "Bootstrap ACE framework files (state, tasks, instructions, skills, scripts, MCP configs, optional runtime profile)", {
         project_name: z
             .string()
             .optional()
@@ -541,18 +542,28 @@ export function registerFrameworkTools(server) {
             .optional()
             .describe("Write minimal workspace host stubs (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md)"),
         llm_provider: z
-            .enum(["ollama", "llama.cpp"])
+            .enum(ALL_LLM_PROVIDERS)
+            .optional()
+            .describe("Optional LLM runtime provider to scaffold"),
+        llm_model: z
+            .string()
+            .optional()
+            .describe("Model name for generated runtime profile"),
+        llm_base_url: z
+            .string()
             .optional()
-            .describe("Optional local LLM profile provider to scaffold"),
+            .describe("Runtime base URL for generated provider profile"),
         ollama_model: z
             .string()
             .optional()
-            .describe("Model name for generated local profile (legacy field name kept for compatibility)"),
+            .describe("Legacy alias for llm_model"),
         ollama_base_url: z
             .string()
             .optional()
-            .describe("Local runtime base URL for generated profile (legacy field name kept for compatibility)"),
-    }, async ({ project_name, force, include_mcp_config, include_client_config_bundle, llm_provider, ollama_model, ollama_base_url, }) => {
+            .describe("Legacy alias for llm_base_url"),
+    }, async ({ project_name, force, include_mcp_config, include_client_config_bundle, llm_provider, llm_model, llm_base_url, ollama_model, ollama_base_url, }) => {
+        const resolvedLlmModel = llm_model ?? ollama_model;
+        const resolvedLlmBaseUrl = llm_base_url ?? ollama_base_url;
         // Store-first bootstrap — initializes ace-state.ace, bakes host bundles into store,
         // and optionally materializes minimal workspace stubs.
         const storeResult = await bootstrapStoreWorkspace({
@@ -562,8 +573,8 @@ export function registerFrameworkTools(server) {
             includeMcpConfig: include_mcp_config,
             includeClientConfigBundle: include_client_config_bundle,
             llm: llm_provider ?? undefined,
-            model: ollama_model ?? undefined,
-            ollamaUrl: ollama_base_url ?? undefined,
+            model: resolvedLlmModel ?? undefined,
+            baseUrl: resolvedLlmBaseUrl ?? undefined,
         });
         const astIndex = refreshAstgrepIndex({
             scope: ".",
@@ -601,8 +612,8 @@ export function registerFrameworkTools(server) {
                 materialized: storeResult.materialized.length,
                 force: Boolean(force),
                 llm_provider: llm_provider ?? null,
-                llm_model: ollama_model ?? null,
-                llm_base_url: ollama_base_url ?? null,
+                llm_model: resolvedLlmModel ?? null,
+                llm_base_url: resolvedLlmBaseUrl ?? null,
                 indexed_files: delta.snapshot.file_count,
                 index_truncated: delta.truncated,
                 ast_index_scope: astIndex.scope,
@@ -645,10 +656,13 @@ export function registerFrameworkTools(server) {
                         ...(llm_provider
                             ? [
                                 "",
-                                "## Local LLM Profile",
+                                "## LLM Runtime Profile",
                                 `- provider: ${llm_provider}`,
-                                `- model: ${ollama_model ?? (llm_provider === "llama.cpp" ? DEFAULT_LLAMA_CPP_MODEL : DEFAULT_OLLAMA_MODEL)}`,
-                                `- base_url: ${ollama_base_url ?? "discover via ace doctor --scan or set explicitly"}`,
+                                `- model: ${resolvedLlmModel ?? defaultModelForProvider(llm_provider)}`,
+                                `- base_url: ${resolvedLlmBaseUrl ??
+                                    (llm_provider === "ollama" || llm_provider === "llama.cpp"
+                                        ? "discover via ace doctor --scan or set explicitly"
+                                        : "optional; use provider defaults or set explicitly")}`,
                                 `- profile_path: ${storeResult.storePath}#state/runtime/llm_profile`,
                                 `- doctor_path: ${storeResult.storePath}#state/runtime/doctor_checks.md`,
                             ]

package/dist/tui/index.js

@@ -17,7 +17,7 @@ import { OpenAICompatibleClient, diagnoseChatRuntimeConfig, } from "./openai-com
 import { detectColorLevel, write, cursor, screen, fg, style } from "./renderer.js";
 import { ALL_AGENTS, WORKSPACE_ROOT } from "../helpers.js";
 import { backfillHandoffsIntoScheduler } from "../tools-handoff.js";
-import { DEFAULT_OLLAMA_MODEL, inferProviderFromModel, normalizeLocalBaseUrl, } from "./provider-discovery.js";
+import { DEFAULT_OLLAMA_MODEL, defaultModelForProvider, inferProviderFromModel, normalizeLocalBaseUrl, } from "./provider-discovery.js";
 import { resolveAceStateLayout } from "../ace-state-resolver.js";
 import { withLocalModelRuntimeRepository, } from "../store/repositories/local-model-runtime-repository.js";
 const DASHBOARD_CONTROLS = ["provider", "model", "chat", "logs", "refresh"];
@@ -56,7 +56,7 @@ export class AceTui {
         const workspaceRoot = options.workspaceRoot ?? WORKSPACE_ROOT;
         this.workspaceRoot = workspaceRoot;
         this.provider = this.normalizeProvider(options.provider ?? inferProviderFromModel(options.model) ?? "ollama") ?? "ollama";
-        this.model = (options.model ?? DEFAULT_OLLAMA_MODEL).trim();
+        this.model = (options.model ?? defaultModelForProvider(this.provider)).trim();
         // Initialize modules
         const colorLevel = detectColorLevel();
         for (const [provider, baseUrl] of Object.entries(options.providerBaseUrls ?? {})) {
@@ -758,7 +758,7 @@ export class AceTui {
             this.model = DEFAULT_OLLAMA_MODEL;
         }
         else {
-            this.model = `${this.provider}/default`;
+            this.model = defaultModelForProvider(this.provider);
         }
         this.config.set("model", this.model);
         this.telemetry.setModel(this.model);

package/dist/tui/local-model-contract.js

@@ -28,24 +28,8 @@ function extractStatusField(statusRaw, label) {
     const match = statusRaw.match(pattern);
     return match?.[1] ? clip(oneLine(match[1])) : undefined;
 }
-function determineRole(task, preferredRole) {
-    const lowered = task.toLowerCase();
-    if (preferredRole && preferredRole !== "orchestrator") {
-        return preferredRole;
-    }
-    if (/\b(doc|docs|readme|changelog|guide)\b/.test(lowered))
-        return "docs";
-    if (/\b(test|qa|verify|regression|assert|review)\b/.test(lowered))
-        return "qa";
-    if (/\b(ui|design|layout|ux|css|frontend)\b/.test(lowered))
-        return "ui";
-    if (/\b(research|investigate|compare|audit|analyze|analysis)\b/.test(lowered))
-        return "research";
-    if (/\b(spec|schema|contract|interface)\b/.test(lowered))
-        return "spec";
-    if (/\b(build|implement|fix|patch|code|refactor|wire|edit)\b/.test(lowered))
-        return "coders";
-    return "orchestrator";
+function determineRole(preferredRole) {
+    return preferredRole?.trim() || "orchestrator";
 }
 export function shouldSynthesizeShortPlan(task) {
     const lowered = task.toLowerCase();
@@ -103,17 +87,15 @@ export function buildAcePreflightPacket(input) {
                 ? "thin"
                 : "healthy";
     const preflightState = blockers.length > 0 ? "blocked" : warnings.length > 0 || blockedByStatus ? "attention_required" : "ready";
-    const recommendedRole = determineRole(input.task, input.preferredRole);
+    const recommendedRole = determineRole(input.preferredRole);
     const synthesize = shouldSynthesizeShortPlan(input.task);
     const recommendedNextAction = preflightState === "blocked"
         ? "validate_framework"
         : synthesize
             ? "run_orchestrator"
-            : quartetHealth !== "healthy"
-                ? "recall_context"
-                : recommendedRole === "orchestrator"
-                    ? "route_task"
-                    : "recall_context";
+            : recommendedRole === "orchestrator"
+                ? "run_orchestrator"
+                : "recall_context";
     return {
         session_id: input.sessionId,
         workspace_root: input.workspaceRoot,
@@ -154,7 +136,7 @@ export function buildStartupNudge(preflight, ledger) {
     const text = action === "validate_framework"
         ? "ACE state is incomplete. Run validate_framework before free-form execution."
         : action === "run_orchestrator"
-            ? "This looks multi-step. Prefer run_orchestrator over a single free-form reply."
+            ? "Start with run_orchestrator so ACE-Orchestrator can route the work."
             : action === "route_task"
                 ? "Role selection is still ambiguous. Route the task before deeper work."
                 : "Load ACE context first with recall_context before deeper work.";

package/dist/tui/provider-discovery.d.ts

@@ -14,6 +14,8 @@
  */
 export declare const DEFAULT_OLLAMA_MODEL = "llama3.1:8b";
 export declare const DEFAULT_LLAMA_CPP_MODEL = "local-model";
+export declare const LOCAL_LLM_PROVIDERS: readonly ["ollama", "llama.cpp"];
+export type LocalLlmProvider = (typeof LOCAL_LLM_PROVIDERS)[number];
 export interface ProviderDiscoveryOptions {
     workspaceRoot: string;
     cliProvider?: string;
@@ -53,6 +55,10 @@ export declare function normalizeProvider(input: string | undefined): string | u
 export declare function normalizeLocalBaseUrl(url: string | undefined): string | undefined;
 export declare function buildOpenAiCompatibleBaseUrl(baseUrl: string): string;
 export declare function inferProviderFromModel(model: string | undefined): string | undefined;
+export declare function isLocalLlmProvider(providerInput: string | undefined): providerInput is LocalLlmProvider;
+export declare function defaultModelForProvider(providerInput: string | undefined): string;
+export declare function providerEnvPrefix(providerInput: string | undefined): string;
+export declare function buildProviderDoctorCommands(providerInput: string | undefined, modelInput: string | undefined, baseUrlInput?: string): string[];
 export declare function parseJsoncLoose(raw: string): unknown;
 export declare function discoverProviderContext(options: ProviderDiscoveryOptions): ProviderDiscoveryResult;
 export declare function scanLocalModelRuntimes(options?: LocalRuntimeScanOptions): Promise<LocalRuntimeScanResult>;

package/dist/tui/provider-discovery.js

@@ -18,7 +18,14 @@ import { join, resolve } from "node:path";
 import { readStoreJsonSync } from "../store/store-snapshot.js";
 export const DEFAULT_OLLAMA_MODEL = "llama3.1:8b";
 export const DEFAULT_LLAMA_CPP_MODEL = "local-model";
-const LOCAL_RUNTIME_PROVIDER_PREFERENCE = ["ollama", "llama.cpp"];
+const DEFAULT_HOSTED_MODELS = {
+    codex: "gpt-5",
+    claude: "claude-3-7-sonnet",
+    gemini: "gemini-2.5-pro",
+    copilot: "copilot/gpt-5-mini",
+};
+export const LOCAL_LLM_PROVIDERS = ["ollama", "llama.cpp"];
+const LOCAL_RUNTIME_PROVIDER_PREFERENCE = LOCAL_LLM_PROVIDERS;
 const PROVIDER_PREFERENCE = [
     ...LOCAL_RUNTIME_PROVIDER_PREFERENCE,
     "codex",
@@ -95,12 +102,69 @@ export function inferProviderFromModel(model) {
     }
     return undefined;
 }
-function defaultModelForProvider(provider) {
-    if (provider === "ollama")
+export function isLocalLlmProvider(providerInput) {
+    const provider = normalizeProvider(providerInput);
+    return provider === "ollama" || provider === "llama.cpp";
+}
+export function defaultModelForProvider(providerInput) {
+    const provider = normalizeProvider(providerInput);
+    if (provider === "ollama" || !provider)
         return DEFAULT_OLLAMA_MODEL;
     if (provider === "llama.cpp")
         return DEFAULT_LLAMA_CPP_MODEL;
-    return `${provider}/default`;
+    return DEFAULT_HOSTED_MODELS[provider] ?? DEFAULT_HOSTED_MODELS.codex;
+}
+export function providerEnvPrefix(providerInput) {
+    const provider = normalizeProvider(providerInput);
+    if (!provider)
+        return "LLM";
+    if (provider === "llama.cpp")
+        return "LLAMA_CPP";
+    return provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+export function buildProviderDoctorCommands(providerInput, modelInput, baseUrlInput) {
+    const provider = normalizeProvider(providerInput) ?? "ollama";
+    const model = modelInput?.trim() || defaultModelForProvider(provider);
+    const baseUrl = normalizeLocalBaseUrl(baseUrlInput);
+    if (provider === "ollama") {
+        return [
+            "ollama serve",
+            `ollama pull ${model}`,
+            ...(baseUrl ? [`curl -s ${baseUrl}/api/tags`] : []),
+            baseUrl
+                ? `ace doctor --llm ${provider} --model ${model} --base-url ${baseUrl}`
+                : `ace doctor --llm ${provider} --model ${model} --scan`,
+        ];
+    }
+    if (provider === "llama.cpp") {
+        return [
+            "# Start llama-server separately, for example:",
+            "# llama-server -m /path/to/model.gguf --port 8080",
+            ...(baseUrl ? [`curl -s ${buildOpenAiCompatibleBaseUrl(baseUrl)}/models`] : []),
+            baseUrl
+                ? `ace doctor --llm ${provider} --model ${model} --base-url ${baseUrl}`
+                : `ace doctor --llm ${provider} --model ${model} --scan`,
+        ];
+    }
+    if (provider === "codex") {
+        return [
+            "export OPENAI_API_KEY=<token>",
+            ...(baseUrl ? [`export OPENAI_BASE_URL=${baseUrl}`] : []),
+            `ace doctor --llm ${provider} --model ${model}${baseUrl ? ` --base-url ${baseUrl}` : ""}`,
+        ];
+    }
+    if (provider === "copilot") {
+        return [
+            "gh auth login  # or export GITHUB_TOKEN=<token>",
+            `ace doctor --llm ${provider} --model ${model}`,
+        ];
+    }
+    const prefix = providerEnvPrefix(provider);
+    return [
+        `export ${prefix}_BASE_URL=${baseUrl ?? "<openai-compatible-base-url>"}`,
+        `export ${prefix}_API_KEY=<token>`,
+        `ace doctor --llm ${provider} --model ${model}${baseUrl ? ` --base-url ${baseUrl}` : ""}`,
+    ];
 }
 function looksLikeModel(value) {
     const v = value.trim().toLowerCase();
@@ -326,6 +390,8 @@ export function discoverProviderContext(options) {
         process.env.LLM_MODEL?.trim() ||
         undefined;
     const envGenericBaseUrl = normalizeLocalBaseUrl(process.env.ACE_TUI_BASE_URL ?? process.env.ACE_LLM_BASE_URL ?? process.env.LLM_BASE_URL);
+    const openAiBaseUrl = normalizeLocalBaseUrl(process.env.OPENAI_BASE_URL);
+    const genericBaseUrl = envGenericBaseUrl ?? openAiBaseUrl;
     const cliProvider = normalizeProvider(options.cliProvider);
     const cliModel = options.cliModel?.trim() || undefined;
     const cliBaseUrl = normalizeLocalBaseUrl(options.cliBaseUrl ?? options.cliOllamaUrl);
@@ -355,9 +421,18 @@ export function discoverProviderContext(options) {
                 inferProviderFromModel(profileModel);
     }
     if (!provider) {
-        provider = "ollama";
-        if (settingHints.length > 0) {
-            notes.push("runtime_default=ollama (VS Code model hints are discovery-only)");
+        const genericOpenAiSignals = Boolean(genericBaseUrl) ||
+            Boolean(process.env.OPENAI_API_KEY?.trim()) ||
+            Boolean(process.env.CODEX_API_KEY?.trim());
+        if (genericOpenAiSignals) {
+            provider = "codex";
+            notes.push("runtime_default=codex (generic OpenAI-compatible env detected)");
+        }
+        else {
+            provider = "ollama";
+            if (settingHints.length > 0) {
+                notes.push("runtime_default=ollama (VS Code model hints are discovery-only)");
+            }
         }
     }
     setProviderBaseUrl(providerBaseUrls, profileProvider, profileBaseUrl);
@@ -366,8 +441,8 @@ export function discoverProviderContext(options) {
     if (!providerBaseUrls.has(provider) && cliBaseUrl) {
         providerBaseUrls.set(provider, cliBaseUrl);
     }
-    if (!providerBaseUrls.has(provider) && envGenericBaseUrl) {
-        providerBaseUrls.set(provider, envGenericBaseUrl);
+    if (!providerBaseUrls.has(provider) && genericBaseUrl) {
+        providerBaseUrls.set(provider, genericBaseUrl);
     }
     if (!providerBaseUrls.has(provider) && profileBaseUrl && profileProvider === provider) {
         providerBaseUrls.set(provider, profileBaseUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voybio/ace-swarm",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "ACE Framework MCP server and CLI — single-file ACEPACK state, local-model serving, agent orchestration, and host compliance enforcement.",
   "type": "module",
   "main": "dist/index.js",