@voybio/ace-swarm 2.4.0 → 2.4.2

package/dist/cli.js

@@ -2,9 +2,9 @@
 import { ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, DEFAULTS_ROOT, PACKAGE_ROOT, WORKSPACE_ROOT, fileExists, getAllMcpServerConfigSnippets, getMcpClientInstallHint, getMcpServerConfigSnippet, wsPath, } from "./helpers.js";
 import { refreshAstgrepIndex } from "./astgrep-index.js";
 import { scanWorkspaceDelta } from "./index-store.js";
-import { startStdioServer } from "./server.js";
+import { startHermesShadowStdioServer, startStdioServer } from "./server.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
-import { waitForPendingStatusEventMirrors } from "./status-events.js";
+import { appendStatusEventSafe, waitForPendingStatusEventMirrors } from "./status-events.js";
 import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
 import { HostFileMaterializer } from "./store/materializers/host-file-materializer.js";
 import { openStore } from "./store/ace-packed-store.js";
@@ -12,18 +12,24 @@ import { DiscoveryRepository } from "./store/repositories/discovery-repository.j
 import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 import { getWorkspaceStorePath, readStoreBlobSync, readStoreJsonSync, } from "./store/store-snapshot.js";
 import { ensureCanonicalWorkspaceStore } from "./store/workspace-store-paths.js";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
 import { runTui } from "./tui/index.js";
-import { buildOpenAiCompatibleBaseUrl, buildProviderDoctorCommands, defaultModelForProvider, discoverProviderContext, isLocalLlmProvider, normalizeLocalBaseUrl, normalizeProvider, scanLocalModelRuntimes, } from "./tui/provider-discovery.js";
+import { buildOpenAiCompatibleBaseUrl, buildProviderDoctorCommands, defaultModelForProvider, discoverProviderContext, isLocalLlmProvider, normalizeLocalBaseUrl, normalizeLlamaCppHfModelName, normalizeProvider, scanLocalModelRuntimes, } from "./tui/provider-discovery.js";
 import { diagnoseChatRuntimeConfig, OpenAICompatibleClient, } from "./tui/openai-compatible.js";
+import { runShellCommand } from "./runtime-command.js";
+import { resolveHermesLaunchProfile } from "./hermes/launch-profile.js";
 function printHelp() {
     console.log(`ACE Swarm CLI
 
 Usage:
   ace mcp                      Start MCP server over stdio
+  ace mcp-shadow --tools <csv> Start filtered Hermes-local MCP shadow server over stdio
   ace serve                    Alias for mcp
   ace tui [options]            Launch interactive TUI dashboard
   ace init [options]           Bootstrap the ACE store into current workspace
+  ace connect [provider]       Register a live local runtime or hosted provider in the store
   ace turnkey [options]        Project minimal workspace bootstrap stubs from the ACE store
   ace doctor [options]         Validate ACE runtime + MCP readiness
   ace cache [options]          Cache ACE artifacts into ace-state.ace and optionally clean projections
@@ -37,6 +43,16 @@ Options for tui:
   --model <name>               Model name override (defaults from profile/settings discovery)
   --base-url <url>             Local runtime base URL override
   --ollama-url <url>           Legacy alias for --base-url
+  --engine <name>              direct|hermes_local execution engine
+  --hermes                     Alias for --engine hermes_local
+  --hermes-root <path>         User-supplied Hermes checkout/import root
+  --hermes-python <path>       User-supplied Python executable with Hermes deps
+  --hermes-uv-project <path>   Optional uv project root for operator-managed Hermes
+  --hermes-command-json <json> Advanced command array override for Hermes Python
+  
+  Hermes is optional and user-supplied. \`ace tui\` and \`ace doctor\` only resolve
+  Hermes when you pass \`--hermes\` / \`--engine hermes_local\` or set the matching
+  Hermes environment variables.
 
 Options for init:
   --project <name>             Project name stored in agent-state/ace-state.ace metadata
@@ -48,12 +64,25 @@ Options for init:
   --base-url <url>             Runtime base URL override (local or OpenAI-compatible)
   --ollama-url <url>           Legacy alias for --base-url
 
+Options for connect:
+  llama-server|llama-cli       Optional launcher name for llama.cpp HF runtimes
+  --hf <repo>                  Hugging Face model repo or local model identifier
+  --model <name>               Alias for --hf when you already know the model name
+  --base-url <url>             OpenAI-compatible endpoint for the live runtime
+  --provider <name>            Explicit provider override when not using a launcher alias
+
 Options for doctor:
   --llm <provider>             ollama|llama.cpp|codex|claude|gemini|copilot|... (default: auto from agent-state/ace-state.ace)
   --model <name>               Model name 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
+  --hermes                     Also run optional Hermes-local readiness checks
+  --hermes-root <path>         User-supplied Hermes checkout/import root (or ACE_HERMES_ROOT)
+  --hermes-python <path>       User-supplied Python executable (or HERMES_PYTHON)
+  --hermes-uv-project <path>   Optional uv project root for operator-managed Hermes
+  --hermes-command-json <json> Advanced command array override for Hermes Python
+  --repair-ollama              Opt-in: run ollama pull <model> when doctor finds a missing Ollama model
 
 Options for cache:
   --dry-run                    Preview what would be cached and cleaned (no writes/deletes)
@@ -63,6 +92,11 @@ Options for mcp-config:
   --client <name>              codex|vscode|copilot|claude|cursor|antigravity
   --all                        Print all client snippets for optional global install
 
+Hermes environment:
+  ACE_HERMES_ROOT              User-supplied Hermes checkout/import root
+  HERMES_PYTHON                User-supplied Python with Hermes dependencies
+  ACE_HERMES_UV_PROJECT        Optional operator-managed uv project root
+
 preconfig writes .mcp-config/ at the workspace root with ready-to-use config files for every
 supported MCP client plus a root .mcp.json for GitHub Copilot CLI. Run once after ace init.
 Each file includes the install hint for its client.
@@ -77,6 +111,180 @@ function readFlagValue(args, flag) {
         return undefined;
     return args[index + 1];
 }
+async function runCommandArray(command, args, options) {
+    const [bin, ...prefixArgs] = command;
+    if (!bin)
+        return { ok: false, stdout: "", stderr: "", detail: "empty command array" };
+    return await new Promise((resolveCommand) => {
+        const child = spawn(bin, [...prefixArgs, ...args], {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+        }, options.timeoutMs ?? 5000);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            resolveCommand({ ok: false, stdout, stderr, detail: error.message });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            resolveCommand({
+                ok: code === 0,
+                stdout,
+                stderr,
+                detail: code === 0 ? "exit 0" : `exit ${code}; ${stderr.slice(0, 300)}`,
+            });
+        });
+    });
+}
+function mcpFrame(payload) {
+    const body = JSON.stringify(payload);
+    return `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`;
+}
+async function probeHermesShadowMcp(cliPath, toolAllowlist) {
+    return await new Promise((resolveProbe, rejectProbe) => {
+        const child = spawn(process.execPath, [cliPath, "mcp-shadow", "--tools", toolAllowlist.join(",")], {
+            cwd: PACKAGE_ROOT,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            rejectProbe(new Error(`shadow MCP probe timed out${stderr ? `: ${stderr.slice(0, 200)}` : ""}`));
+        }, 2500);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            if (stdout.includes('"tools"') && stdout.includes(toolAllowlist[0] ?? "")) {
+                clearTimeout(timeout);
+                child.kill("SIGTERM");
+                resolveProbe(`shadow MCP initialize/tools-list probe succeeded; tools=${toolAllowlist.join(",")}`);
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            rejectProbe(error);
+        });
+        child.on("close", () => {
+            clearTimeout(timeout);
+            if (stdout.includes('"tools"') && stdout.includes(toolAllowlist[0] ?? "")) {
+                resolveProbe(`shadow MCP initialize/tools-list probe succeeded; tools=${toolAllowlist.join(",")}`);
+            }
+            else {
+                rejectProbe(new Error(`shadow MCP probe did not return tools/list${stderr ? `: ${stderr.slice(0, 200)}` : ""}`));
+            }
+        });
+        child.stdin.write(mcpFrame({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "ace-doctor", version: "0.0.0" },
+            },
+        }));
+        child.stdin.write(mcpFrame({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
+        child.stdin.write(mcpFrame({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }));
+    });
+}
+async function appendHermesLocalReadinessChecks(checks, profile) {
+    const hermesRoot = profile.hermes_root;
+    const workerPath = profile.worker_path;
+    const cliPath = resolve(PACKAGE_ROOT, "dist", "cli.js");
+    const toolAllowlist = ["get_all_agents_summary"];
+    checks.push({
+        name: "Hermes launch profile",
+        ok: true,
+        detail: `source=${profile.source}; mode=${profile.mode}; command=${JSON.stringify(profile.command)}; hermes_root=${profile.hermes_root ?? "not configured"}`,
+    });
+    checks.push({
+        name: "Hermes worker packaged",
+        ok: existsSync(workerPath),
+        detail: existsSync(workerPath)
+            ? workerPath
+            : `Missing ${workerPath}; run npm run build.`,
+    });
+    checks.push({
+        name: "Hermes checkout import root",
+        ok: Boolean(hermesRoot &&
+            existsSync(resolve(hermesRoot, "run_agent.py")) &&
+            existsSync(resolve(hermesRoot, "tools", "mcp_tool.py"))),
+        detail: hermesRoot && existsSync(resolve(hermesRoot, "run_agent.py"))
+            ? hermesRoot
+            : "ACE does not install Hermes. Set ACE_HERMES_ROOT or pass --hermes-root to a Hermes checkout.",
+    });
+    const pythonResolves = await runCommandArray(profile.command, ["-c", "import sys; print(sys.executable)"], {
+        cwd: PACKAGE_ROOT,
+        timeoutMs: 5000,
+    });
+    checks.push({
+        name: "Hermes Python command",
+        ok: pythonResolves.ok,
+        detail: pythonResolves.ok ? `${JSON.stringify(profile.command)} -> ${pythonResolves.stdout.trim()}` : pythonResolves.detail,
+    });
+    const importEnv = {
+        ...process.env,
+        PYTHONPATH: [hermesRoot, process.env.PYTHONPATH].filter(Boolean).join(":"),
+    };
+    const importResult = hermesRoot
+        ? await runCommandArray(profile.command, ["-c", "from run_agent import AIAgent; print(AIAgent.__name__)"], {
+            cwd: hermesRoot,
+            env: importEnv,
+            timeoutMs: 5000,
+        })
+        : { ok: false, detail: "Hermes root not configured", stdout: "", stderr: "" };
+    checks.push({
+        name: "Hermes Python imports",
+        ok: importResult.ok,
+        detail: importResult.ok ? "run_agent.AIAgent import ok" : importResult.detail,
+    });
+    checks.push({
+        name: "ACE shadow MCP command",
+        ok: existsSync(cliPath),
+        detail: existsSync(cliPath)
+            ? JSON.stringify([process.execPath, cliPath, "mcp-shadow", "--tools", toolAllowlist.join(",")])
+            : `Missing ${cliPath}; run npm run build.`,
+    });
+    if (existsSync(cliPath)) {
+        try {
+            checks.push({
+                name: "ACE shadow MCP handshake",
+                ok: true,
+                detail: await probeHermesShadowMcp(cliPath, toolAllowlist),
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: "ACE shadow MCP handshake",
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    else {
+        checks.push({
+            name: "ACE shadow MCP handshake",
+            ok: false,
+            detail: `Cannot probe shadow MCP until ${cliPath} exists; run npm run build.`,
+        });
+    }
+}
 function readLlmProfile() {
     const storeProfile = readStoreJsonSync(WORKSPACE_ROOT, "state/runtime/llm_profile") ??
         readStoreJsonSync(WORKSPACE_ROOT, "state/runtime/llm-profile");
@@ -98,6 +306,29 @@ function readLlmProfile() {
 function readBaseUrlFlag(args) {
     return normalizeLocalBaseUrl(readFlagValue(args, "--base-url") ?? readFlagValue(args, "--ollama-url"));
 }
+function readConnectModelFlag(args) {
+    return (readFlagValue(args, "--hf") ??
+        readFlagValue(args, "-hf") ??
+        readFlagValue(args, "--model"))?.trim();
+}
+function parseConnectArgs(args) {
+    const firstToken = args[0];
+    const hasLauncher = Boolean(firstToken && !firstToken.startsWith("-"));
+    const launcher = hasLauncher ? firstToken?.trim().toLowerCase() : undefined;
+    const providerOverride = normalizeProvider(readFlagValue(args, "--provider")?.trim());
+    const provider = providerOverride ??
+        (launcher === "llama-server" || launcher === "llama-cli" ? "llama.cpp" : providerOverride);
+    const rawModel = readConnectModelFlag(args);
+    const model = provider === "llama.cpp" ? normalizeLlamaCppHfModelName(rawModel) ?? rawModel : rawModel;
+    const baseUrl = readBaseUrlFlag(args);
+    const launcherCommand = hasLauncher ? args.join(" ").trim() : undefined;
+    return {
+        provider: provider,
+        model,
+        baseUrl,
+        launcherCommand,
+    };
+}
 function parseLlmOptions(args) {
     const profile = readLlmProfile();
     const selected = normalizeProvider(readFlagValue(args, "--llm")?.trim() ?? profile?.provider?.trim());
@@ -107,8 +338,11 @@ function parseLlmOptions(args) {
         throw new Error(`Unsupported LLM provider: ${selected}`);
     }
     const provider = selected;
-    const defaultModel = defaultModelForProvider(provider);
-    const llmModel = readFlagValue(args, "--model")?.trim() || profile?.model || defaultModel;
+    const explicitModel = readFlagValue(args, "--model")?.trim();
+    const profileModel = profile?.model?.trim();
+    const llmModel = explicitModel ||
+        profileModel ||
+        (provider === "ollama" ? defaultModelForProvider(provider) : undefined);
     const llmBaseUrl = readBaseUrlFlag(args) ?? normalizeLocalBaseUrl(profile?.base_url);
     return {
         llmProvider: provider,
@@ -121,9 +355,11 @@ async function writeLlmProfile(profile) {
     await withStoreWriteCoordinator(storePath, async () => {
         const payload = {
             provider: profile.provider,
-            model: profile.model,
             generated_at: new Date().toISOString(),
         };
+        if (profile.model) {
+            payload.model = profile.model;
+        }
         if (profile.baseUrl) {
             payload.base_url = profile.baseUrl;
             if (profile.provider === "ollama") {
@@ -131,6 +367,9 @@ async function writeLlmProfile(profile) {
                 payload.default_api_key = "ollama";
             }
         }
+        if (profile.launcherCommand) {
+            payload.launch_command = profile.launcherCommand;
+        }
         const doctorCommands = buildProviderDoctorCommands(profile.provider, profile.model, profile.baseUrl);
         const store = await openStore(storePath);
         try {
@@ -153,6 +392,40 @@ async function writeLlmProfile(profile) {
     }, { operation_label: "writeLlmProfile" });
     return `${storePath}#state/runtime/llm_profile`;
 }
+async function runConnect(args) {
+    const parsed = parseConnectArgs(args);
+    if (!parsed.provider) {
+        throw new Error("ace connect expects a provider or launcher command. Try `ace connect llama-server -hf <model> --base-url http://127.0.0.1:8080`.");
+    }
+    if (!ALL_LLM_PROVIDERS.includes(parsed.provider)) {
+        throw new Error(`Unsupported LLM provider: ${parsed.provider}`);
+    }
+    if (isLocalLlmProvider(parsed.provider) && !parsed.model) {
+        throw new Error("ace connect for local runtimes requires an explicit model. Pass `--hf <repo>` or `--model <name>`.");
+    }
+    const storeResult = await bootstrapStoreWorkspace({
+        workspaceRoot: WORKSPACE_ROOT,
+        llm: parsed.provider,
+        model: parsed.model,
+        baseUrl: parsed.baseUrl,
+        includeMcpConfig: false,
+        includeClientConfigBundle: false,
+        launcherCommand: parsed.launcherCommand,
+    });
+    console.log("ACE connect complete");
+    console.log(`Workspace: ${WORKSPACE_ROOT}`);
+    console.log(`Store: ${storeResult.storePath}`);
+    console.log(`Provider: ${parsed.provider}`);
+    console.log(`Model: ${parsed.model ?? "(not set)"}`);
+    console.log(`Base URL: ${parsed.baseUrl ?? "(not set)"}`);
+    if (parsed.launcherCommand) {
+        console.log(`Launcher: ${parsed.launcherCommand}`);
+    }
+    console.log(`Profile path: ${storeResult.storePath}#state/runtime/llm_profile`);
+    for (const warning of storeResult.warnings) {
+        console.warn(`  [store] ${warning}`);
+    }
+}
 async function recordDiscoveryProfile(input) {
     const storePath = getWorkspaceStorePath(WORKSPACE_ROOT);
     await withStoreWriteCoordinator(storePath, async () => {
@@ -296,6 +569,13 @@ async function listLocalRuntimeModels(provider, baseUrl) {
             headers: { Accept: "application/json" },
         });
         if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            if (response.status >= 500 && /unable to load model/i.test(text)) {
+                const error = new Error(`${response.status} ${response.statusText}: ollama_model_load_error. ` +
+                    `Suggested remediation: run ollama pull <model> or ace doctor --repair-ollama.`);
+                error.reason_code = "ollama_model_load_error";
+                throw error;
+            }
             throw new Error(`${response.status} ${response.statusText}`);
         }
         const payload = (await response.json().catch(() => ({})));
@@ -321,6 +601,7 @@ async function listLocalRuntimeModels(provider, baseUrl) {
 }
 async function runDoctor(args) {
     const llm = parseLlmOptions(args);
+    const repairOllama = args.includes("--repair-ollama");
     const checks = [];
     const mcpConfigPaths = [wsPath(".vscode", "mcp.json")];
     const hasWorkspaceMcpConfig = mcpConfigPaths.some((path) => fileExists(path));
@@ -347,7 +628,9 @@ async function runDoctor(args) {
     let provider = llm.llmProvider;
     let model = llm.llmModel;
     let baseUrl = llm.llmBaseUrl;
-    const shouldScan = args.includes("--scan") || (!provider && !baseUrl) || (isLocalLlmProvider(provider) && !baseUrl);
+    const shouldScan = args.includes("--scan") ||
+        (!provider && !baseUrl) ||
+        (isLocalLlmProvider(provider) && (!baseUrl || !model));
     if (shouldScan) {
         const scanned = await scanLocalModelRuntimes({
             workspaceRoot: WORKSPACE_ROOT,
@@ -359,7 +642,7 @@ async function runDoctor(args) {
         if (chosen) {
             provider = chosen.provider ?? provider;
             baseUrl = baseUrl ?? chosen.baseUrl;
-            model = model || chosen.models[0] || defaultModelForProvider(provider);
+            model = model || chosen.models[0];
             checks.push({
                 name: "Runtime endpoint discovered",
                 ok: true,
@@ -367,7 +650,7 @@ async function runDoctor(args) {
             });
             const writtenProfilePath = await writeLlmProfile({
                 provider: provider ?? chosen.provider,
-                model: model ?? defaultModelForProvider(provider ?? chosen.provider),
+                model,
                 baseUrl,
             });
             checks.push({
@@ -388,6 +671,30 @@ async function runDoctor(args) {
         throw new Error(`No runtime provider configured. Use --llm <provider>, bootstrap one into agent-state/ace-state.ace#state/runtime/llm_profile, or run \`ace doctor --scan\` for a local runtime.`);
     }
     if (!model) {
+        if (isLocalLlmProvider(provider)) {
+            checks.push({
+                name: "Runtime model configured",
+                ok: false,
+                detail: "No local runtime model is configured yet. Run `ace connect` with a user-supplied HF model or run `ace doctor --scan` after the runtime is up.",
+            });
+            const failed = checks.filter((check) => !check.ok);
+            console.log("ACE Doctor Report");
+            console.log(`Workspace: ${WORKSPACE_ROOT}`);
+            console.log(`Provider: ${provider}`);
+            console.log("Model: (not set)");
+            if (baseUrl) {
+                console.log(`Base URL: ${baseUrl}`);
+            }
+            console.log("");
+            for (const check of checks) {
+                const status = check.ok ? "PASS" : "FAIL";
+                console.log(`- [${status}] ${check.name}: ${check.detail}`);
+            }
+            if (failed.length > 0) {
+                process.exitCode = 1;
+            }
+            return;
+        }
         model = defaultModelForProvider(provider);
     }
     if (isLocalLlmProvider(provider) && !baseUrl) {
@@ -425,6 +732,23 @@ async function runDoctor(args) {
             });
         }
         catch (error) {
+            const reasonCode = typeof error === "object" && error !== null && "reason_code" in error
+                ? String(error.reason_code)
+                : undefined;
+            if (reasonCode === "ollama_model_load_error") {
+                await appendStatusEventSafe({
+                    source_module: "capability-ops",
+                    event_type: "OLLAMA_MODEL_LOAD_ERROR",
+                    status: "blocked",
+                    summary: `Ollama model-load error for ${model}: ${error instanceof Error ? error.message : String(error)}`,
+                    objective_id: "ollama-doctor",
+                    payload: {
+                        reason_code: "ollama_model_load_error",
+                        model,
+                        base_url: baseUrl,
+                    },
+                }).catch(() => undefined);
+            }
             checks.push({
                 name: "Runtime endpoint reachable",
                 ok: false,
@@ -450,6 +774,44 @@ async function runDoctor(args) {
                     ? `${model} found`
                     : `${model} not reported by llama.cpp (available: ${modelNames.join(", ") || "none"})`,
         });
+        if (provider === "ollama" && !hasModel && repairOllama) {
+            const repair = await runShellCommand(`ollama pull ${model}`, {
+                cwd: WORKSPACE_ROOT,
+                timeout_ms: 10 * 60_000,
+            });
+            await appendRunLedgerEntrySafe({
+                tool: "doctor",
+                category: repair.exit_code === 0 ? "info" : "regression",
+                message: `Opt-in Ollama repair attempted for ${model}`,
+                artifacts: [],
+                metadata: {
+                    reason_code: "ollama_model_load_error",
+                    model,
+                    exit_code: repair.exit_code,
+                    timed_out: repair.timed_out,
+                },
+            }).catch(() => undefined);
+            await appendStatusEventSafe({
+                source_module: "capability-ops",
+                event_type: "OLLAMA_REPAIR_ATTEMPTED",
+                status: repair.exit_code === 0 ? "done" : "fail",
+                summary: `Opt-in Ollama repair attempted for ${model}`,
+                objective_id: "ollama-doctor",
+                payload: {
+                    reason_code: "ollama_model_load_error",
+                    model,
+                    exit_code: repair.exit_code,
+                    timed_out: repair.timed_out,
+                },
+            }).catch(() => undefined);
+            checks.push({
+                name: "Ollama model repair attempted",
+                ok: repair.exit_code === 0,
+                detail: repair.exit_code === 0
+                    ? `ollama pull ${model} completed`
+                    : `ollama pull ${model} failed with exit ${repair.exit_code}: ${repair.stderr || repair.stdout || "no output"}`,
+            });
+        }
     }
     else {
         const diagnosis = diagnoseChatRuntimeConfig(provider, model, baseUrl ? { baseUrl } : undefined);
@@ -490,6 +852,25 @@ async function runDoctor(args) {
             }
         }
     }
+    if (isLocalLlmProvider(provider) && args.includes("--hermes")) {
+        try {
+            const hermesProfile = resolveHermesLaunchProfile({
+                workspaceRoot: WORKSPACE_ROOT,
+                cliHermesRoot: readFlagValue(args, "--hermes-root"),
+                cliHermesPython: readFlagValue(args, "--hermes-python"),
+                cliHermesUvProject: readFlagValue(args, "--hermes-uv-project"),
+                cliHermesCommandJson: readFlagValue(args, "--hermes-command-json"),
+            });
+            await appendHermesLocalReadinessChecks(checks, hermesProfile);
+        }
+        catch (error) {
+            checks.push({
+                name: "Hermes launch profile",
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     const failed = checks.filter((check) => !check.ok);
     console.log("ACE Doctor Report");
     console.log(`Workspace: ${WORKSPACE_ROOT}`);
@@ -576,11 +957,32 @@ async function main() {
         await startStdioServer();
         return;
     }
+    if (command === "mcp-shadow") {
+        const shadowArgs = args.slice(1);
+        const tools = (readFlagValue(shadowArgs, "--tools") ?? "")
+            .split(",")
+            .map((tool) => tool.trim())
+            .filter(Boolean);
+        await startHermesShadowStdioServer(tools);
+        return;
+    }
     if (command === "tui") {
         const tuiArgs = args.slice(1);
         const cliProvider = readFlagValue(tuiArgs, "--provider")?.trim() ||
             readFlagValue(tuiArgs, "--llm")?.trim();
         const cliModel = readFlagValue(tuiArgs, "--model")?.trim();
+        const cliEngine = readFlagValue(tuiArgs, "--engine")?.trim() ||
+            (tuiArgs.includes("--hermes") ? "hermes_local" : undefined);
+        const normalizedCliEngine = cliEngine?.toLowerCase().replace(/-/g, "_");
+        const hermesLaunchProfile = normalizedCliEngine === "hermes_local"
+            ? resolveHermesLaunchProfile({
+                workspaceRoot: WORKSPACE_ROOT,
+                cliHermesRoot: readFlagValue(tuiArgs, "--hermes-root"),
+                cliHermesPython: readFlagValue(tuiArgs, "--hermes-python"),
+                cliHermesUvProject: readFlagValue(tuiArgs, "--hermes-uv-project"),
+                cliHermesCommandJson: readFlagValue(tuiArgs, "--hermes-command-json"),
+            })
+            : undefined;
         const cliBaseUrl = readBaseUrlFlag(tuiArgs);
         const discovered = discoverProviderContext({
             workspaceRoot: WORKSPACE_ROOT,
@@ -588,14 +990,78 @@ async function main() {
             cliModel,
             cliBaseUrl,
         });
+        const needsLocalScan = isLocalLlmProvider(discovered.provider) &&
+            (!discovered.baseUrl || !discovered.model || discovered.model === defaultModelForProvider(discovered.provider));
+        const runtime = needsLocalScan
+            ? await scanLocalModelRuntimes({
+                workspaceRoot: WORKSPACE_ROOT,
+                preferredProvider: discovered.provider,
+                explicitBaseUrl: discovered.baseUrl,
+            })
+            : undefined;
+        const scanned = runtime?.candidates.find((candidate) => candidate.provider === discovered.provider) ??
+            runtime?.candidates[0];
+        const resolvedTui = scanned?.models[0]
+            ? {
+                ...discovered,
+                model: scanned.models[0],
+                baseUrl: discovered.baseUrl ?? scanned.baseUrl,
+                providerBaseUrls: {
+                    ...discovered.providerBaseUrls,
+                    [scanned.provider]: discovered.baseUrl ?? scanned.baseUrl,
+                },
+            }
+            : discovered;
+        // Merge any persisted discovery records from the workspace store so recent `ace doctor`
+        // results are reflected immediately in the TUI startup options.
+        try {
+            const store = await openStore(getWorkspaceStorePath(WORKSPACE_ROOT), { readOnly: true });
+            try {
+                const discoveryRepo = new DiscoveryRepository(store);
+                const stored = await discoveryRepo.listAll();
+                const mergedProviders = new Set(resolvedTui.providers ?? []);
+                const mergedModelsByProvider = { ...(resolvedTui.modelsByProvider ?? {}) };
+                const mergedProviderBaseUrls = { ...(resolvedTui.providerBaseUrls ?? {}) };
+                for (const p of stored) {
+                    if (!p || !p.provider)
+                        continue;
+                    const prov = String(p.provider).trim();
+                    if (!prov)
+                        continue;
+                    mergedProviders.add(prov);
+                    if (Array.isArray(p.models) && p.models.length > 0) {
+                        const existing = new Set(mergedModelsByProvider[prov] ?? []);
+                        for (const m of p.models)
+                            if (typeof m === "string" && m.trim())
+                                existing.add(m.trim());
+                        mergedModelsByProvider[prov] = [...existing].sort((a, b) => a.localeCompare(b));
+                    }
+                    if (p.endpoint && typeof p.endpoint === "string") {
+                        mergedProviderBaseUrls[prov] = p.endpoint;
+                    }
+                }
+                resolvedTui.providers = [...mergedProviders].sort((a, b) => a.localeCompare(b));
+                resolvedTui.modelsByProvider = { ...(resolvedTui.modelsByProvider ?? {}), ...mergedModelsByProvider };
+                resolvedTui.providerBaseUrls = { ...(resolvedTui.providerBaseUrls ?? {}), ...mergedProviderBaseUrls };
+            }
+            finally {
+                await store.close();
+            }
+        }
+        catch (err) {
+            // Non-fatal — continue with discovered defaults if store read fails.
+            console.warn(`Could not merge discovery records into TUI startup: ${err instanceof Error ? err.message : String(err)}`);
+        }
         await runTui({
-            provider: discovered.provider,
-            model: discovered.model,
-            providers: discovered.providers,
-            modelsByProvider: discovered.modelsByProvider,
-            baseUrl: discovered.baseUrl,
-            ollamaUrl: discovered.ollamaUrl,
-            providerBaseUrls: discovered.providerBaseUrls,
+            provider: resolvedTui.provider,
+            engine: cliEngine,
+            hermesLaunchProfile,
+            model: resolvedTui.model,
+            providers: resolvedTui.providers,
+            modelsByProvider: resolvedTui.modelsByProvider,
+            baseUrl: resolvedTui.baseUrl,
+            ollamaUrl: resolvedTui.ollamaUrl,
+            providerBaseUrls: resolvedTui.providerBaseUrls,
             workspaceRoot: WORKSPACE_ROOT,
         });
         return;
@@ -604,6 +1070,10 @@ async function main() {
         await runInit(args.slice(1), "init");
         return;
     }
+    if (command === "connect") {
+        await runConnect(args.slice(1));
+        return;
+    }
     if (command === "turnkey") {
         await runInit(args.slice(1), "turnkey");
         return;