@voybio/ace-swarm 0.2.3 → 0.2.5

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/assets/.agents/skills/eval-harness/SKILL.md

@@ -173,6 +173,20 @@ Confidence: <score>% (<label>)
 
 ---
 
+## Validation Surface
+
+- Run this skill against at least one known-pass baseline and one known-fail fixture before trusting a promotion decision.
+- Validation command example: execute the configured eval harness runner and confirm deterministic suite counts in `agent-state/EVAL_REPORT.md`.
+
+---
+
+## Portability Notes
+
+- Keep this skill vendor-neutral: it should work across Codex, Claude, Cursor, and Antigravity runtimes.
+- Avoid provider-specific assumptions in suite execution or report parsing; rely on ACE artifacts as the source of truth.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/handoff-lint/SKILL.md

@@ -132,6 +132,20 @@ Also use when:
 
 ---
 
+## Validation Surface
+
+- Run this check with one valid and one intentionally broken handoff payload to verify deterministic PASS/FAIL behavior.
+- Validation command example: execute the handoff lint path used by the runtime and confirm schema, route, and evidence checks all emit rule-level outcomes.
+
+---
+
+## Portability Notes
+
+- Keep lint output schema and rule IDs stable so different clients can consume results uniformly.
+- Do not depend on provider-specific behavior; handoff validation must rely only on ACE artifacts and schemas.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/incident-commander/SKILL.md

@@ -156,6 +156,20 @@ No incident closure without ALL of:
 
 ---
 
+## Validation Surface
+
+- Run an incident simulation with synthetic `GATE_FAILED` events and verify severity classification, owner assignment, and timeline reconstruction are deterministic.
+- Validation command example: replay a known event stream and confirm `global-state/INCIDENTS.md` and `agent-state/INCIDENT_TIMELINE.md` contain matching evidence-linked rows.
+
+---
+
+## Portability Notes
+
+- Incident lifecycle states and emitted event names must remain stable across clients.
+- Keep the protocol provider-agnostic: all decisions should be derivable from ACE state artifacts and event logs.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/memory-curator/SKILL.md

@@ -161,6 +161,20 @@ Generated: <ISO8601>
 
 ---
 
+## Validation Surface
+
+- Run this skill on a fixture with known duplicates and contradictions, then verify the reconciliation report counts match expected values.
+- Validation command example: execute memory curation and confirm no source logs are modified while `MEMORY_INDEX.md` updates with provenance links.
+
+---
+
+## Portability Notes
+
+- Preserve schema and section labels so downstream consumers can parse curated memory artifacts consistently.
+- Keep curation logic independent of model/provider specifics; evidence linkage is the portable contract.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/release-sentry/SKILL.md

@@ -160,6 +160,20 @@ Reason: <one sentence>
 
 ---
 
+## Validation Surface
+
+- Validate this skill with one known-pass and one known-fail release packet to confirm gate outcomes are deterministic.
+- Validation command example: run release sentry checks and verify `RELEASE_DECISION.md` always includes explicit gate evidence rows.
+
+---
+
+## Portability Notes
+
+- Keep decision enums and gate names stable so any client can consume release outputs consistently.
+- Avoid provider-specific assumptions; release readiness must be computed from ACE artifacts only.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/risk-quant/SKILL.md

@@ -158,6 +158,20 @@ Every risk in `RISKS.md` must contain these fields:
 
 ---
 
+## Validation Surface
+
+- Run this skill against a fixture risk set with expected probability-impact scores and verify computed tiers match exactly.
+- Validation command example: execute risk quantification and confirm HIGH/CRITICAL entries always include owner, mitigation, and verification condition.
+
+---
+
+## Portability Notes
+
+- Keep scoring scales and tier thresholds explicit and stable across clients.
+- Quantification must remain vendor-neutral and based on ACE state artifacts, not model-specific behavior.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/schema-forge/SKILL.md

@@ -151,6 +151,20 @@ Use when:
 
 ---
 
+## Validation Surface
+
+- Validate schema updates against both old and new sample payload fixtures before promoting contract changes.
+- Validation command example: run JSON-schema validation for backward and forward compatibility samples and record results in `EVIDENCE_LOG.md`.
+
+---
+
+## Portability Notes
+
+- Preserve stable schema IDs, version fields, and migration metadata so any ACE client can consume updates.
+- Keep evolution rules provider-agnostic; compatibility decisions must be artifact-driven, not model-driven.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/state-auditor/SKILL.md

@@ -161,6 +161,20 @@ Overall: <PASS | WARN | CRITICAL>
 
 ---
 
+## Validation Surface
+
+- Run audits against fixtures with known contradictions to verify deterministic CRITICAL/WARN classification.
+- Validation command example: execute the state audit flow and confirm every checklist row maps to a concrete pass/fail artifact reference.
+
+---
+
+## Portability Notes
+
+- Keep report structure and checklist IDs stable so multiple clients can parse outputs consistently.
+- State drift checks must remain independent of model/provider implementation details.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/agent-state/MODULES/gates/gate-correctness.json

@@ -2,6 +2,6 @@
   "id": "gate-correctness",
   "type": "executable",
   "invariant": "All required tests pass",
-  "command": "cd ace-mcp-server && npm test --silent",
+  "command": "if [ -f ace-mcp-server/package.json ]; then cd ace-mcp-server && npm test --silent; elif [ -f package.json ]; then npm test --silent; else echo 'package.json not found for gate-correctness' && exit 1; fi",
   "evidence_requirement": "Command output snippet with exit code 0"
 }

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,8 @@ 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 cache [options]          Cache ACE artifacts into ace-state.ace and optionally clean projections
   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,18 +42,22 @@ 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
 
+Options for cache:
+  --dry-run                    Preview what would be cached and cleaned (no writes/deletes)
+  --no-clean                   Keep workspace ACE artifacts after caching them into ace-state.ace
+
 Options for mcp-config:
   --client <name>              codex|vscode|claude|cursor|antigravity
   --all                        Print all client snippets for optional global install
@@ -92,14 +98,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 +129,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 +195,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 +230,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 +320,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 +340,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 +357,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 +365,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 +383,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 +411,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";
@@ -643,6 +685,26 @@ async function main() {
         console.log(`Store compacted: ${result.before} → ${result.after} bytes (saved ${savedKb}KB)`);
         return;
     }
+    if (command === "cache") {
+        const { cacheWorkspaceArtifacts } = await import("./store/cache-workspace.js");
+        const dryRun = args.includes("--dry-run");
+        const clean = !args.includes("--no-clean");
+        const result = await cacheWorkspaceArtifacts(WORKSPACE_ROOT, { dryRun, clean });
+        console.log("ACE cache complete");
+        console.log(`Workspace: ${WORKSPACE_ROOT}`);
+        console.log(`Store: ${result.storePath}`);
+        console.log(`Scanned files: ${result.scanned_files}`);
+        console.log(`Cached files: ${result.cached_files}`);
+        console.log(`Kept projected files: ${result.kept_projected_files}`);
+        console.log(`Skipped files: ${result.skipped_files}`);
+        console.log(`Removed files: ${result.removed_files}`);
+        if (result.warnings.length > 0) {
+            console.warn(`Warnings (${result.warnings.length}):`);
+            for (const warning of result.warnings)
+                console.warn(`  ! ${warning}`);
+        }
+        return;
+    }
     if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;

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];
@@ -66,6 +66,7 @@ export interface BootstrapResult {
     skipped: string[];
 }
 export declare function mapAceWorkspaceRelativePath(path: string): string;
+export declare function isProjectedAceWorkspacePath(filePath: string): boolean;
 export declare function acePath(...segments: string[]): string;
 export declare function wsPath(...segments: string[]): string;
 /** Normalize a path for validation: workspace-relative, forward slashes. */
@@ -79,6 +80,7 @@ export declare function fileExists(filePath: string): boolean;
 export declare function resolveWorkspaceWritePath(filePath: string): string;
 export declare function resolveWorkspaceReadPath(filePath: string): string;
 export declare function resolveWorkspaceArtifactPath(filePath: string, mode?: "read" | "write"): string;
+export declare function resolveStoreFallbackKeysForPath(filePath: string): string[];
 export declare function classifyPathSource(path?: string): ArtifactSource;
 /** Safely read a workspace file, returning either text or a not-found/access message. */
 export declare function safeRead(filePath: string): string;