@openpalm/lib 0.11.2-rc.1 → 0.11.2-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.2-rc.1",
+  "version": "0.11.2-rc.3",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",

package/src/control-plane/core-assets.ts

@@ -40,7 +40,22 @@ export function readCoreCompose(): string {
 }
 
 export function readBundledStackAsset(name: string): string {
-  return readFileSync(bundledAssetPath(`config/stack/${name}`), 'utf-8');
+  // The bundled `.openpalm` assets are resolved relative to import.meta.url,
+  // which does not survive bundling into the UI/Electron build (the path lands
+  // outside the packaged app). When OP_HOME is already seeded this fallback is
+  // never reached; when it is NOT (e.g. a fresh Electron first-run) the read
+  // fails. Degrade gracefully to "" so callers (addon profile/service lookups)
+  // return empty rather than throwing a 500 — the live OP_HOME assets are the
+  // source of truth once seeded.
+  try {
+    return readFileSync(bundledAssetPath(`config/stack/${name}`), 'utf-8');
+  } catch (err) {
+    logger.warn('bundled stack asset unavailable (returning empty)', {
+      name,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return '';
+  }
 }
 
 // ── OpenCode System Config ──────────────────────────────────────────

package/src/control-plane/docker.ts

@@ -275,6 +275,11 @@ export async function composeDown(
     profiles?: string[];
     removeVolumes?: boolean;
     envFiles?: string[];
+    // Remove containers for services NOT in the (profile-resolved) compose set.
+    // Needed to clean up a previously-enabled-then-disabled profile-gated addon
+    // (e.g. in-stack Ollama): with its profile now inactive, `down` alone leaves
+    // its stopped container behind because compose no longer "sees" the service.
+    removeOrphans?: boolean;
   }
 ): Promise<DockerResult> {
   await runPreflight(options);
@@ -284,6 +289,7 @@ export async function composeDown(
   const args = buildComposeArgs(options);
   args.push("down");
   if (options.removeVolumes) args.push("-v");
+  if (options.removeOrphans) args.push("--remove-orphans");
   return run(args, undefined);
 }
 

package/src/control-plane/lifecycle.ts

@@ -369,17 +369,32 @@ export function buildComposeFileList(state: ControlPlaneState): string[] {
   return discoverStackOverlays(state.stackDir, state.homeDir);
 }
 
+// Channel addons that require the guardian ingress. Mirrors the profile gate on
+// the guardian service in channels.compose.yml (profiles: addon.{chat,api,
+// discord,slack}) and the built-in channel id list used in registry.ts /
+// config-persistence.ts. Guardian is shared infra for these, not an addon
+// service of its own (getAddonServiceNames deliberately excludes it).
+const CHANNEL_ADDON_IDS = ["api", "chat", "discord", "slack"];
+
 export async function buildManagedServices(state: ControlPlaneState): Promise<string[]> {
   const composeOpts = buildComposeOptions(state);
 
-  // Always force-recreate the core services (assistant + guardian) on upgrade,
-  // regardless of how the service set is discovered. getAddonServiceNames
-  // deliberately EXCLUDES guardian, so a fallback that relied on it alone would
-  // drop guardian from the recreated set when channel profiles are active —
-  // leaving guardian on stale state (issue #450).
-  const services = new Set<string>(CORE_SERVICES);
-
-  // Prefer compose-derived service list when Docker is available
+  // The assistant is the only ALWAYS-on core service. The guardian is channel
+  // ingress — profile-gated to the channel addons in channels.compose.yml, so
+  // with zero channels enabled it is never deployed. Seeding it unconditionally
+  // made the installer health-wait on a guardian that never starts (a ~5-minute
+  // hang when no channel is selected). Add it back ONLY when a channel is
+  // enabled; that also preserves the #450 need to force-recreate guardian on
+  // upgrade when channel profiles ARE active (it is excluded from
+  // getAddonServiceNames, so the fallback below would otherwise drop it).
+  const enabledAddons = listEnabledAddonIds(state.homeDir);
+  const channelsEnabled = enabledAddons.some((a) => CHANNEL_ADDON_IDS.includes(a));
+  const services = new Set<string>(["assistant"]);
+  if (channelsEnabled) services.add("guardian");
+
+  // Prefer compose-derived service list when Docker is available. Resolved with
+  // the active profiles, this already includes guardian iff a channel profile
+  // is active — the explicit add above just guarantees it for the fallback.
   if (composeOpts.files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
     const result = await composeConfigServices(composeOpts);
     if (result.ok && result.services.length > 0) {
@@ -388,8 +403,9 @@ export async function buildManagedServices(state: ControlPlaneState): Promise<st
     }
   }
 
-  // Fallback: static inference from CORE_SERVICES + active addon overlays
-  for (const addon of listEnabledAddonIds(state.homeDir)) {
+  // Fallback: static inference from assistant (+ guardian when channels) +
+  // active addon overlays.
+  for (const addon of enabledAddons) {
     for (const s of getAddonServiceNames(state.homeDir, addon)) services.add(s);
   }
   return [...services];

package/src/control-plane/model-runner.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import { parseOllamaHostEnv } from "./model-runner.js";
+
+describe("parseOllamaHostEnv", () => {
+  // ── null / empty inputs ────────────────────────────────────────────────
+  test("undefined → null", () => {
+    expect(parseOllamaHostEnv(undefined)).toBeNull();
+  });
+
+  test("empty string → null", () => {
+    expect(parseOllamaHostEnv("")).toBeNull();
+  });
+
+  test("whitespace only → null", () => {
+    expect(parseOllamaHostEnv("   ")).toBeNull();
+  });
+
+  // ── garbage ────────────────────────────────────────────────────────────
+  test("/garbage → null", () => {
+    expect(parseOllamaHostEnv("/garbage")).toBeNull();
+  });
+
+  test("has spaces → null", () => {
+    expect(parseOllamaHostEnv("my host:1234")).toBeNull();
+  });
+
+  test("port out of range 0 → null", () => {
+    expect(parseOllamaHostEnv("0")).toBeNull();
+  });
+
+  test("port out of range 99999 → null", () => {
+    expect(parseOllamaHostEnv("99999")).toBeNull();
+  });
+
+  test("invalid host:port (port not numeric) → null", () => {
+    expect(parseOllamaHostEnv("localhost:abc")).toBeNull();
+  });
+
+  // ── bare port ──────────────────────────────────────────────────────────
+  test("bare port '9999' → http://localhost:9999", () => {
+    expect(parseOllamaHostEnv("9999")).toBe("http://localhost:9999");
+  });
+
+  test("bare port '11434' → http://localhost:11434", () => {
+    expect(parseOllamaHostEnv("11434")).toBe("http://localhost:11434");
+  });
+
+  // ── host:port ──────────────────────────────────────────────────────────
+  test("'127.0.0.1:9999' → http://127.0.0.1:9999", () => {
+    expect(parseOllamaHostEnv("127.0.0.1:9999")).toBe("http://127.0.0.1:9999");
+  });
+
+  test("'0.0.0.0:9999' → http://0.0.0.0:9999", () => {
+    expect(parseOllamaHostEnv("0.0.0.0:9999")).toBe("http://0.0.0.0:9999");
+  });
+
+  test("'myhost:1234' → http://myhost:1234", () => {
+    expect(parseOllamaHostEnv("myhost:1234")).toBe("http://myhost:1234");
+  });
+
+  // ── full HTTP URL ──────────────────────────────────────────────────────
+  test("'http://127.0.0.1:9999' → http://127.0.0.1:9999", () => {
+    expect(parseOllamaHostEnv("http://127.0.0.1:9999")).toBe("http://127.0.0.1:9999");
+  });
+
+  test("'http://127.0.0.1:9999/some/path' strips path", () => {
+    // URL.origin includes scheme+host+port, strips path
+    expect(parseOllamaHostEnv("http://127.0.0.1:9999/some/path")).toBe("http://127.0.0.1:9999");
+  });
+
+  // ── HTTPS URL ─────────────────────────────────────────────────────────
+  test("'https://h:443' → https://h:443", () => {
+    // URL.origin suppresses default port 443 for https
+    const result = parseOllamaHostEnv("https://h:443");
+    expect(result).toBe("https://h");
+  });
+
+  test("'https://secure.host:8443' → https://secure.host:8443", () => {
+    expect(parseOllamaHostEnv("https://secure.host:8443")).toBe("https://secure.host:8443");
+  });
+
+  // ── bare hostname ──────────────────────────────────────────────────────
+  test("'localhost' → http://localhost:11434 (default port)", () => {
+    expect(parseOllamaHostEnv("localhost")).toBe("http://localhost:11434");
+  });
+
+  test("'my-host.local' → http://my-host.local:11434", () => {
+    expect(parseOllamaHostEnv("my-host.local")).toBe("http://my-host.local:11434");
+  });
+
+  // ── whitespace trimming ────────────────────────────────────────────────
+  test("leading/trailing whitespace is trimmed", () => {
+    expect(parseOllamaHostEnv("  9999  ")).toBe("http://localhost:9999");
+  });
+});

package/src/control-plane/model-runner.ts

@@ -35,63 +35,193 @@ async function validateOllamaResponse(res: Response): Promise<boolean> {
   }
 }
 
-const LOCAL_PROVIDER_PROBES: { provider: string; probes: ProviderProbe[] }[] = [
-  {
-    provider: "model-runner",
-    probes: [
-      {
-        url: "http://model-runner.docker.internal/engines/v1/models",
-        baseUrl: "http://model-runner.docker.internal/engines",
-      },
-      {
-        url: "http://model-runner.docker.internal:12434/engines/v1/models",
-        baseUrl: "http://model-runner.docker.internal:12434/engines",
-      },
-      {
-        url: "http://host.docker.internal:12434/engines/v1/models",
-        baseUrl: "http://host.docker.internal:12434/engines",
-      },
-      {
-        url: "http://localhost:12434/engines/v1/models",
-        baseUrl: "http://localhost:12434/engines",
-      },
-    ],
-  },
-  {
-    provider: "ollama",
-    probes: [
-      {
-        // In-stack Ollama (compose service on assistant_net)
-        url: "http://ollama:11434/api/tags",
-        baseUrl: "http://ollama:11434",
-        validate: validateOllamaResponse,
-      },
+// ── Env-based URL parsers ────────────────────────────────────────────────
+
+/**
+ * Parse an OLLAMA_HOST env value into a normalized base URL string, or null if
+ * the input is absent/malformed.
+ *
+ * Accepted forms:
+ *   - bare port:                "9999"           → "http://localhost:9999"
+ *   - host:port:                "127.0.0.1:9999" → "http://127.0.0.1:9999"
+ *   - full URL (http/https):    "http://h:9999"  → "http://h:9999"
+ *   - bare hostname:            "localhost"       → "http://localhost:11434"  (default port)
+ *
+ * Returns null for empty string, non-numeric bare tokens that aren't valid
+ * hostnames, and any other garbage.
+ */
+export function parseOllamaHostEnv(raw: string | undefined): string | null {
+  if (!raw || raw.trim() === "") return null;
+  const s = raw.trim();
+
+  // Already a full URL
+  if (s.startsWith("http://") || s.startsWith("https://")) {
+    try {
+      const u = new URL(s);
+      // Must have a usable host
+      if (!u.hostname) return null;
+      // Return origin (scheme + host + port, no path)
+      return u.origin;
+    } catch {
+      return null;
+    }
+  }
+
+  // Bare port number e.g. "9999"
+  if (/^\d+$/.test(s)) {
+    const port = parseInt(s, 10);
+    if (port < 1 || port > 65535) return null;
+    return `http://localhost:${port}`;
+  }
+
+  // host:port e.g. "127.0.0.1:9999" or "myhost:1234"
+  const colonIdx = s.lastIndexOf(":");
+  if (colonIdx > 0) {
+    const host = s.slice(0, colonIdx);
+    const portStr = s.slice(colonIdx + 1);
+    if (!/^\d+$/.test(portStr)) return null;
+    const port = parseInt(portStr, 10);
+    if (port < 1 || port > 65535) return null;
+    // Basic hostname/IP validity — must not contain spaces or slashes
+    if (/[\s/]/.test(host)) return null;
+    return `http://${host}:${port}`;
+  }
+
+  // Bare hostname (no port) — use Ollama's default port
+  // Accept only simple hostname-like tokens (letters, digits, hyphens, dots)
+  if (/^[a-zA-Z0-9._-]+$/.test(s)) {
+    return `http://${s}:11434`;
+  }
+
+  return null;
+}
+
+/**
+ * Parse a bare port env value (e.g. LMSTUDIO_PORT, MODEL_RUNNER_PORT) into an
+ * integer, or null if absent/malformed.
+ */
+function parsePortEnv(raw: string | undefined): number | null {
+  if (!raw || raw.trim() === "") return null;
+  const n = parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n < 1 || n > 65535) return null;
+  return n;
+}
+
+// ── Probe timeout ────────────────────────────────────────────────────────
+
+/**
+ * Probe timeout in milliseconds.
+ *
+ * 5 000 ms is chosen to tolerate slow/loaded machines without blocking the
+ * caller for too long.  Override with OP_LOCAL_PROBE_TIMEOUT_MS (clamped to
+ * a floor of 1 000 ms so the env value can't make probes never-timeout).
+ */
+function getProbeTimeoutMs(): number {
+  const floor = 1000;
+  const envRaw = process.env["OP_LOCAL_PROBE_TIMEOUT_MS"];
+  if (envRaw) {
+    const n = parseInt(envRaw, 10);
+    if (Number.isFinite(n) && n >= floor) return n;
+  }
+  return 5000;
+}
+
+// ── Dynamic probe builders ───────────────────────────────────────────────
+
+/** Build the ordered probe list for model-runner, prepending any env-configured port. */
+function buildModelRunnerProbes(): ProviderProbe[] {
+  const defaults: ProviderProbe[] = [
+    {
+      url: "http://model-runner.docker.internal/engines/v1/models",
+      baseUrl: "http://model-runner.docker.internal/engines",
+    },
+    {
+      url: "http://model-runner.docker.internal:12434/engines/v1/models",
+      baseUrl: "http://model-runner.docker.internal:12434/engines",
+    },
+    {
+      url: "http://host.docker.internal:12434/engines/v1/models",
+      baseUrl: "http://host.docker.internal:12434/engines",
+    },
+    {
+      url: "http://localhost:12434/engines/v1/models",
+      baseUrl: "http://localhost:12434/engines",
+    },
+  ];
+
+  const port = parsePortEnv(process.env["MODEL_RUNNER_PORT"]);
+  if (port !== null) {
+    return [
       {
-        url: "http://host.docker.internal:11434/api/tags",
-        baseUrl: "http://host.docker.internal:11434",
-        validate: validateOllamaResponse,
+        url: `http://localhost:${port}/engines/v1/models`,
+        baseUrl: `http://localhost:${port}/engines`,
       },
+      ...defaults,
+    ];
+  }
+  return defaults;
+}
+
+/** Build the ordered probe list for ollama, prepending any env-configured endpoint. */
+function buildOllamaProbes(): ProviderProbe[] {
+  const defaults: ProviderProbe[] = [
+    {
+      // In-stack Ollama (compose service on assistant_net)
+      url: "http://ollama:11434/api/tags",
+      baseUrl: "http://ollama:11434",
+      validate: validateOllamaResponse,
+    },
+    {
+      url: "http://host.docker.internal:11434/api/tags",
+      baseUrl: "http://host.docker.internal:11434",
+      validate: validateOllamaResponse,
+    },
+    {
+      url: "http://localhost:11434/api/tags",
+      baseUrl: "http://localhost:11434",
+      validate: validateOllamaResponse,
+    },
+  ];
+
+  const base = parseOllamaHostEnv(process.env["OLLAMA_HOST"]);
+  if (base !== null) {
+    return [
       {
-        url: "http://localhost:11434/api/tags",
-        baseUrl: "http://localhost:11434",
+        url: `${base}/api/tags`,
+        baseUrl: base,
         validate: validateOllamaResponse,
       },
-    ],
-  },
-  {
-    provider: "lmstudio",
-    probes: [
-      {
-        url: "http://host.docker.internal:1234/v1/models",
-        baseUrl: "http://host.docker.internal:1234",
-      },
+      ...defaults,
+    ];
+  }
+  return defaults;
+}
+
+/** Build the ordered probe list for lmstudio, prepending any env-configured port. */
+function buildLmStudioProbes(): ProviderProbe[] {
+  const defaults: ProviderProbe[] = [
+    {
+      url: "http://host.docker.internal:1234/v1/models",
+      baseUrl: "http://host.docker.internal:1234",
+    },
+    {
+      url: "http://localhost:1234/v1/models",
+      baseUrl: "http://localhost:1234",
+    },
+  ];
+
+  const port = parsePortEnv(process.env["LMSTUDIO_PORT"] ?? process.env["LM_STUDIO_PORT"]);
+  if (port !== null) {
+    return [
       {
-        url: "http://localhost:1234/v1/models",
-        baseUrl: "http://localhost:1234",
+        url: `http://localhost:${port}/v1/models`,
+        baseUrl: `http://localhost:${port}`,
       },
-    ],
-  },
-];
+      ...defaults,
+    ];
+  }
+  return defaults;
+}
 
 // ── Detection ────────────────────────────────────────────────────────────
 
@@ -100,17 +230,42 @@ const LOCAL_PROVIDER_PROBES: { provider: string; probes: ProviderProbe[] }[] = [
  * Returns results for all providers (available or not) in parallel.
  */
 export async function detectLocalProviders(): Promise<LocalProviderDetection[]> {
+  const probeTimeoutMs = getProbeTimeoutMs();
+
+  const providerProbes = [
+    { provider: "model-runner", probes: buildModelRunnerProbes() },
+    { provider: "ollama", probes: buildOllamaProbes() },
+    { provider: "lmstudio", probes: buildLmStudioProbes() },
+  ];
+
   const results = await Promise.all(
-    LOCAL_PROVIDER_PROBES.map(async ({ provider, probes }) => {
+    providerProbes.map(async ({ provider, probes }) => {
       for (const { url: probeUrl, baseUrl, validate } of probes) {
         try {
           const res = await fetch(probeUrl, {
-            signal: AbortSignal.timeout(3000),
+            signal: AbortSignal.timeout(probeTimeoutMs),
           });
           if (res.ok) {
-            if (validate && !(await validate(res))) {
-              logger.debug("provider probe response failed validation", { provider, url: baseUrl });
-              continue;
+            if (validate) {
+              // Clone so we can read the body for debug logging without consuming it
+              const resForValidate = res.clone();
+              const valid = await validate(res);
+              if (!valid) {
+                // Read a snippet of the body to aid debugging — 500-char cap
+                let bodySnippet = "(unreadable)";
+                try {
+                  const raw = await resForValidate.text();
+                  bodySnippet = raw.slice(0, 500);
+                } catch {
+                  // ignore
+                }
+                logger.debug("provider probe response failed validation", {
+                  provider,
+                  url: probeUrl,
+                  bodySnippet,
+                });
+                continue;
+              }
             }
             logger.debug("detected local provider", { provider, url: baseUrl });
             return { provider, url: baseUrl, available: true };

package/src/control-plane/setup-recommendation.test.ts

@@ -93,6 +93,81 @@ describe("recommendSetup", () => {
   });
 });
 
+describe("hostCredentialCount precedence", () => {
+  test("(a) host-configured + capable GPU + no cloud -> NOT enable-ollama (host wins)", () => {
+    const r = recommendSetup({
+      cloudProviders: [],
+      hostProviders: [],
+      gpu: gpu("nvidia", 24576),
+      hostCredentialCount: 2,
+    });
+    expect(r.action).not.toBe("enable-ollama");
+    expect(r.action).toBe("connect-manually");
+    if (r.action === "connect-manually") {
+      expect(r.alert).toContain("host OpenCode");
+      expect(r.alert).toContain("Import");
+    }
+  });
+
+  test("(b) cloud still wins over host-configured", () => {
+    const r = recommendSetup({
+      cloudProviders: ["openai"],
+      hostProviders: [],
+      gpu: null,
+      hostCredentialCount: 3,
+    });
+    expect(r.action).toBe("use-cloud");
+  });
+
+  test("(c) host-configured beats a running host Ollama (import hint over auto-add)", () => {
+    // When the user has both a running host Ollama AND host OpenCode credentials,
+    // the richer "import your existing setup" guidance wins over the auto-add path.
+    const r = recommendSetup({
+      cloudProviders: [],
+      hostProviders: [{ provider: "ollama", url: "http://localhost:11434" }],
+      gpu: null,
+      hostCredentialCount: 1,
+    });
+    expect(r.action).toBe("connect-manually");
+    expect(r.action).not.toBe("use-host-providers");
+    if (r.action === "connect-manually") expect(r.alert).toContain("host OpenCode");
+  });
+
+  test("host-configured with zero credentials -> falls through to normal rules", () => {
+    // hostCredentialCount: 0 (or absent) must not suppress the normal GPU path.
+    const r = recommendSetup({ ...base, gpu: gpu("nvidia", 24576), hostCredentialCount: 0 });
+    expect(r.action).toBe("enable-ollama");
+  });
+
+  test("host-configured omitted (undefined) -> falls through to normal rules", () => {
+    // No regression: callers that don't pass hostCredentialCount get the old behaviour.
+    const r = recommendSetup({ ...base, gpu: gpu("nvidia", 24576) });
+    expect(r.action).toBe("enable-ollama");
+  });
+
+  test("host-configured + no GPU + no cloud -> connect-manually with import alert", () => {
+    const r = recommendSetup({ ...base, hostCredentialCount: 1 });
+    expect(r.action).toBe("connect-manually");
+    if (r.action === "connect-manually") expect(r.alert).toContain("host OpenCode");
+  });
+
+  test("host-configured + darwin apple GPU -> connect-manually (host wins, not apple guidance)", () => {
+    // Both host-configured and darwin+apple would return connect-manually, but
+    // host-configured takes priority so the alert is the import one, not the Metal one.
+    const r = recommendSetup({
+      ...base,
+      platform: "darwin",
+      gpu: gpu("apple", 65536),
+      hostCredentialCount: 2,
+    });
+    expect(r.action).toBe("connect-manually");
+    if (r.action === "connect-manually") {
+      expect(r.alert).toContain("host OpenCode");
+      expect(r.alert).not.toContain("Metal");
+    }
+  });
+});
+
 describe("gpuToProfileVariant", () => {
   test("nvidia->cuda, amd->rocm, apple->cpu, unknown->cpu", () => {
     expect(gpuToProfileVariant(gpu("nvidia", 8192))).toBe("cuda");

package/src/control-plane/setup-recommendation.ts

@@ -45,6 +45,16 @@ export type SetupRecommendationInput = {
    * apple GPU is routed to host-Ollama guidance instead of enable-ollama.
    */
   platform?: NodeJS.Platform;
+  /**
+   * Number of credentials found in the host user's OpenCode auth.json
+   * (~/.local/share/opencode/auth.json). When > 0 the host OpenCode has
+   * configured providers that should be imported rather than bypassed by
+   * auto-enabling the bundled in-stack Ollama.
+   *
+   * Gathered by the caller via detectHostOpenCode() — kept out of this module
+   * so the function stays pure and unit-testable.
+   */
+  hostCredentialCount?: number;
 };
 
 export type SetupRecommendation =
@@ -67,20 +77,40 @@ const labelHostProviders = (h: DetectedHostProvider[]): string =>
  * Decide what setup should do, given detected providers + hardware.
  *
  * Order (first match wins):
- *  1. cloud provider connected      -> use it.
- *  2. host-local provider running   -> add it, proceed.
- *  3. darwin + apple GPU            -> guide to HOST Ollama (Metal); never in-stack.
- *  4. capable GPU (>= threshold)    -> enable in-stack Ollama.
- *  5. otherwise                     -> ask the user to connect a provider.
+ *  1. cloud provider connected              -> use it.
+ *  2. host OpenCode has credentials         -> steer to import; NEVER auto-enable Ollama.
+ *  3. host-local provider running           -> add it, proceed.
+ *  4. darwin + apple GPU                    -> guide to HOST Ollama (Metal); never in-stack.
+ *  5. capable GPU (>= threshold)            -> enable in-stack Ollama.
+ *  6. otherwise                             -> ask the user to connect a provider.
  */
 export function recommendSetup(input: SetupRecommendationInput): SetupRecommendation {
   const { cloudProviders, hostProviders, gpu } = input;
   const platform = input.platform ?? process.platform;
+  const hostCredentialCount = input.hostCredentialCount ?? 0;
 
   if (cloudProviders.length > 0) {
     return { action: "use-cloud", cloudProviders };
   }
 
+  // A host OpenCode installation with credentials outranks auto-enabling the
+  // bundled in-stack Ollama. The user already has configured providers — they
+  // should import them rather than spin up a new Ollama container. We reuse
+  // the existing `connect-manually` action (already handled by the wizard's
+  // Providers step) with an import-oriented alert so no new wizard branch is
+  // needed. This rule runs BEFORE host-local-provider detection so that even a
+  // running host Ollama does not shadow the richer "import your existing setup"
+  // guidance when host credentials are present.
+  if (hostCredentialCount > 0) {
+    return {
+      action: "connect-manually",
+      alert:
+        "Your host OpenCode installation has configured AI providers. " +
+        "Import them now to use your existing setup — click \"Import from host OpenCode\" " +
+        "on the Providers step, or connect a provider manually.",
+    };
+  }
+
   if (hostProviders.length > 0) {
     return {
       action: "use-host-providers",

package/src/control-plane/upgrade-path.test.ts

@@ -104,10 +104,19 @@ describe("performUpgrade force-recreates managed services (#450)", () => {
     expect(src).toMatch(/composeUp\(\{[^}]*forceRecreate:\s*true/);
   });
 
-  test("buildManagedServices always includes the core services (guardian)", () => {
+  test("buildManagedServices always manages the assistant", () => {
     const src = readFileSync(join(LIB_CONTROL_PLANE_DIR, "lifecycle.ts"), "utf-8");
-    // Guardian comes from CORE_SERVICES and must be seeded into the set
-    // regardless of how the rest of the service list is discovered.
-    expect(src).toContain("new Set<string>(CORE_SERVICES)");
+    // The assistant is the only ALWAYS-on core service in the managed set.
+    expect(src).toContain('new Set<string>(["assistant"])');
+  });
+
+  test("buildManagedServices adds guardian ONLY when a channel addon is enabled", () => {
+    const src = readFileSync(join(LIB_CONTROL_PLANE_DIR, "lifecycle.ts"), "utf-8");
+    // Guardian is channel ingress: profile-gated to the channel addons, so it
+    // must be added conditionally — never unconditionally seeded (that hung the
+    // installer on a guardian that never starts when no channel is enabled).
+    expect(src).toContain("channelsEnabled");
+    expect(src).toMatch(/if \(channelsEnabled\) services\.add\("guardian"\)/);
+    expect(src).not.toContain("new Set<string>(CORE_SERVICES)");
   });
 });

package/src/index.ts

@@ -11,6 +11,7 @@ export {
   LLM_PROVIDERS,
   EMBEDDING_DIMS,
   PROVIDER_KEY_MAP,
+  OLLAMA_DEFAULT_MODELS,
   lookupEmbeddingDims,
 } from "./provider-constants.js";