@openpalm/lib 0.11.1 → 0.11.2-rc.2

package/package.json

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

package/src/control-plane/docker.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  detectExistingProject,
+  isProjectOurs,
+  resolveComposeProjectName,
+} from "./docker.js";
+
+describe("isProjectOurs (ours-vs-foreign decision)", () => {
+  it("treats a matching working_dir as ours", () => {
+    expect(isProjectOurs("/home/me/.openpalm", "/home/me/.openpalm")).toBe(true);
+  });
+
+  it("treats a different working_dir as foreign", () => {
+    expect(isProjectOurs("/home/other/.openpalm", "/home/me/.openpalm")).toBe(false);
+  });
+
+  it("treats an empty/unknown working_dir as ours (reconcile, don't refuse)", () => {
+    expect(isProjectOurs("", "/home/me/.openpalm")).toBe(true);
+    expect(isProjectOurs("   ", "/home/me/.openpalm")).toBe(true);
+  });
+
+  it("ignores surrounding whitespace on the label", () => {
+    expect(isProjectOurs("  /home/me/.openpalm \n", "/home/me/.openpalm")).toBe(true);
+  });
+});
+
+describe("detectExistingProject", () => {
+  // Use a project name that cannot possibly match any running container so the
+  // result is deterministic whether or not a docker daemon is present:
+  //  - docker error (no daemon)      → { exists:false }
+  //  - docker ok, no matching label  → { exists:false }
+  const ghostName = `openpalm-detect-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+  it("returns exists:false when no project matches (or docker is unavailable)", async () => {
+    const result = await detectExistingProject({
+      projectName: ghostName,
+      expectedWorkingDir: "/nonexistent/op_home",
+    });
+    expect(result.exists).toBe(false);
+    expect(result.isOurs).toBe(false);
+    expect(result.workingDir).toBe("");
+  });
+});
+
+describe("resolveComposeProjectName", () => {
+  const saved = process.env.OP_PROJECT_NAME;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.OP_PROJECT_NAME;
+    else process.env.OP_PROJECT_NAME = saved;
+  });
+
+  it("defaults to openpalm", () => {
+    delete process.env.OP_PROJECT_NAME;
+    delete process.env.COMPOSE_PROJECT_NAME;
+    expect(resolveComposeProjectName({})).toBe("openpalm");
+  });
+
+  it("honors OP_PROJECT_NAME from overrides first", () => {
+    expect(resolveComposeProjectName({ OP_PROJECT_NAME: "openpalm-dev" })).toBe("openpalm-dev");
+  });
+});

package/src/control-plane/docker.ts

@@ -51,6 +51,83 @@ export function resolveComposeProjectName(envOverrides: Record<string, string> =
   );
 }
 
+/**
+ * Result of probing the Docker daemon for an existing compose project that
+ * shares our project name.
+ *
+ * - `exists`   — at least one running container carries the project label.
+ * - `isOurs`   — those containers were launched from THIS install's working
+ *                dir (compose working_dir label === expectedWorkingDir). When
+ *                true the caller should reconcile in place (up --force-recreate).
+ *                When false a DIFFERENT OpenPalm install (e.g. dev vs host) owns
+ *                the name and the caller must refuse.
+ * - `workingDir` — the working_dir label read off the first container, for
+ *                error messages. Empty string when unknown.
+ */
+export type ExistingProject = {
+  exists: boolean;
+  isOurs: boolean;
+  workingDir: string;
+};
+
+/**
+ * Decide whether a running compose project (identified by its
+ * `com.docker.compose.project.working_dir` label) is OURS — i.e. was launched
+ * from this install's working dir. An empty/unknown label can't prove foreign,
+ * so it counts as ours (reconcile rather than wrongly refuse a redeploy).
+ *
+ * Pure decision split out from detectExistingProject so the ours-vs-foreign
+ * rule is unit-testable without a Docker daemon.
+ */
+export function isProjectOurs(workingDirLabel: string, expectedWorkingDir: string): boolean {
+  const label = workingDirLabel.trim();
+  return label === "" || label === expectedWorkingDir;
+}
+
+/**
+ * Probe the Docker daemon for a running compose project that shares
+ * `projectName`. Decides ours-vs-foreign by comparing the project's
+ * `com.docker.compose.project.working_dir` label against `expectedWorkingDir`
+ * (the install's OP_HOME / compose context).
+ *
+ * Returns `{ exists:false }` on any docker error (daemon down, no permission) —
+ * detection is best-effort and never blocks the caller; a real failure surfaces
+ * later through composeUp.
+ */
+export function detectExistingProject(opts: {
+  projectName: string;
+  expectedWorkingDir: string;
+}): Promise<ExistingProject> {
+  const none: ExistingProject = { exists: false, isOurs: false, workingDir: "" };
+  return new Promise((resolve) => {
+    execFile(
+      "docker",
+      ["ps", "-q", "--filter", `label=com.docker.compose.project=${opts.projectName}`],
+      { timeout: 10_000 },
+      (err, stdout) => {
+        if (err) return resolve(none);
+        const ids = stdout.toString().trim().split(/\s+/).filter(Boolean);
+        if (ids.length === 0) return resolve(none);
+        execFile(
+          "docker",
+          [
+            "inspect",
+            "--format",
+            '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}',
+            ids[0],
+          ],
+          { timeout: 10_000 },
+          (err2, stdout2) => {
+            if (err2) return resolve({ exists: true, isOurs: false, workingDir: "" });
+            const workingDir = stdout2.toString().trim();
+            resolve({ exists: true, isOurs: isProjectOurs(workingDir, opts.expectedWorkingDir), workingDir });
+          },
+        );
+      },
+    );
+  });
+}
+
 /** Check if Docker is available */
 export async function checkDocker(): Promise<DockerResult> {
   return new Promise((resolve) => {
@@ -172,7 +249,21 @@ export async function composeUp(
   if (options.forceRecreate) args.push("--force-recreate");
   if (options.removeOrphans) args.push("--remove-orphans");
   if (options.services?.length) args.push(...options.services);
-  return run(args, undefined, 300_000, collectEnvOverrides(options.envFiles));
+  return run(args, undefined, composeUpTimeoutMs(), collectEnvOverrides(options.envFiles));
+}
+
+/**
+ * Timeout budget for `compose up`. A first install extracts multi-GB images
+ * (voice CUDA ~7.6 GB) onto slow disks; the previous hard 5-minute cap
+ * SIGTERM-killed the start mid-extraction and surfaced as an empty/opaque
+ * error. Default 30 min, override with OP_COMPOSE_UP_TIMEOUT_MS. Kept bounded
+ * (never removed) so a genuinely hung start still eventually fails.
+ */
+function composeUpTimeoutMs(): number {
+  const raw = process.env.OP_COMPOSE_UP_TIMEOUT_MS?.trim();
+  const parsed = raw ? Number(raw) : NaN;
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return 30 * 60_000;
 }
 
 /**
@@ -184,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);
@@ -193,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/hardware-detect.ts

@@ -11,7 +11,7 @@ import { createLogger } from "../logger.js";
 
 const logger = createLogger("hardware-detect");
 
-export type GpuVendor = "nvidia" | "amd" | "unknown";
+export type GpuVendor = "nvidia" | "amd" | "apple" | "unknown";
 
 export type GpuInfo = {
   vendor: GpuVendor;
@@ -27,6 +27,8 @@ type GpuProbe = {
   args: string[];
   /** Pure parser: tool stdout -> detected GPUs. Must not throw. */
   parse: (stdout: string) => GpuInfo[];
+  /** Optional gate — when present and false, the probe is skipped entirely. */
+  enabled?: boolean;
 };
 
 /** Parse `nvidia-smi --query-gpu=name,memory.total --format=csv,noheader,nounits`. */
@@ -68,6 +70,25 @@ export function parseRocmSmi(stdout: string): GpuInfo[] {
   return out;
 }
 
+/**
+ * Parse `sysctl -n hw.memsize hw.model` (two lines: total bytes, then model id)
+ * into an Apple-Silicon GpuInfo. `hw.memsize` is UNIFIED memory shared between
+ * CPU and GPU, carried here as vramMb for informational display only — callers
+ * must NOT treat it like discrete VRAM (see setup-recommendation). Pure; never throws.
+ */
+export function parseAppleSilicon(stdout: string): GpuInfo[] {
+  const lines = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length === 0) return [];
+  const bytes = Number.parseInt(lines[0] ?? "", 10);
+  if (!Number.isFinite(bytes) || bytes <= 0) return [];
+  const vramMb = Math.round(bytes / (1024 * 1024));
+  const model = lines[1] && lines[1].length > 0 ? lines[1] : "arm64";
+  return [{ vendor: "apple", name: `Apple Silicon (${model})`, vramMb }];
+}
+
 const GPU_PROBES: GpuProbe[] = [
   {
     vendor: "nvidia",
@@ -81,6 +102,16 @@ const GPU_PROBES: GpuProbe[] = [
     args: ["--showmeminfo", "vram", "--showproductname", "--json"],
     parse: parseRocmSmi,
   },
+  {
+    // Apple Silicon Macs expose no nvidia-smi/rocm-smi. Probe macOS sysctl for
+    // unified-memory size + model id. Gated to darwin/arm64 so it never runs (and
+    // never spawns a missing binary) on Linux/Intel.
+    vendor: "apple",
+    command: "sysctl",
+    args: ["-n", "hw.memsize", "hw.model"],
+    parse: parseAppleSilicon,
+    enabled: process.platform === "darwin" && process.arch === "arm64",
+  },
 ];
 
 function run(command: string, args: string[], timeoutMs = 3_000): Promise<string | null> {
@@ -100,6 +131,7 @@ export async function detectGpu(): Promise<GpuInfo | null> {
   const found: GpuInfo[] = [];
   await Promise.all(
     GPU_PROBES.map(async (probe) => {
+      if (probe.enabled === false) return;
       const stdout = await run(probe.command, probe.args);
       if (stdout === null) return;
       try {

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

@@ -5,7 +5,7 @@ import {
   MIN_LOCAL_GPU_VRAM_MB,
   type SetupRecommendationInput,
 } from "./setup-recommendation.js";
-import { parseNvidiaSmi, parseRocmSmi, type GpuInfo } from "./hardware-detect.js";
+import { parseNvidiaSmi, parseRocmSmi, parseAppleSilicon, type GpuInfo } from "./hardware-detect.js";
 
 const base: SetupRecommendationInput = { cloudProviders: [], hostProviders: [], gpu: null };
 const gpu = (vendor: GpuInfo["vendor"], vramMb: number, name = "Test GPU"): GpuInfo => ({ vendor, name, vramMb });
@@ -53,6 +53,39 @@ describe("recommendSetup", () => {
     expect(r.action).toBe("connect-manually");
   });
 
+  test("darwin + apple GPU + no provider -> connect-manually (NOT enable-ollama), Mac-tailored alert", () => {
+    const r = recommendSetup({ ...base, platform: "darwin", gpu: gpu("apple", 65536, "Apple Silicon (Mac15,7)") });
+    expect(r.action).toBe("connect-manually");
+    expect(r.action).not.toBe("enable-ollama");
+    if (r.action === "connect-manually") {
+      expect(r.alert).toContain("macOS");
+      expect(r.alert).toContain("Metal");
+      expect(r.alert.toLowerCase()).toContain("ollama");
+    }
+  });
+
+  test("darwin + apple GPU never selects cuda/rocm (no in-stack enable)", () => {
+    // Even with huge unified memory, darwin+apple must not enable in-stack ollama.
+    const r = recommendSetup({ ...base, platform: "darwin", gpu: gpu("apple", 131072) });
+    expect(r.action).not.toBe("enable-ollama");
+  });
+
+  test("darwin + host ollama running -> still use-host-providers (wins over apple guidance)", () => {
+    const r = recommendSetup({
+      ...base,
+      platform: "darwin",
+      hostProviders: [{ provider: "ollama", url: "http://localhost:11434" }],
+      gpu: gpu("apple", 65536),
+    });
+    expect(r.action).toBe("use-host-providers");
+  });
+
+  test("linux + nvidia >= threshold -> still enable-ollama cuda (unchanged)", () => {
+    const r = recommendSetup({ ...base, platform: "linux", gpu: gpu("nvidia", 24576) });
+    expect(r.action).toBe("enable-ollama");
+    if (r.action === "enable-ollama") expect(r.profileVariant).toBe("cuda");
+  });
+
   test("no cloud, no host, no GPU -> connect-manually", () => {
     const r = recommendSetup(base);
     expect(r.action).toBe("connect-manually");
@@ -60,14 +93,108 @@ 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, unknown->cpu", () => {
+  test("nvidia->cuda, amd->rocm, apple->cpu, unknown->cpu", () => {
     expect(gpuToProfileVariant(gpu("nvidia", 8192))).toBe("cuda");
     expect(gpuToProfileVariant(gpu("amd", 8192))).toBe("rocm");
+    expect(gpuToProfileVariant(gpu("apple", 65536))).toBe("cpu");
     expect(gpuToProfileVariant(gpu("unknown", 8192))).toBe("cpu");
   });
 });
 
+describe("parseAppleSilicon", () => {
+  test("parses hw.memsize bytes -> MiB + vendor apple + model name", () => {
+    const stdout = `${16 * 1024 * 1024 * 1024}\nMac15,7\n`;
+    const out = parseAppleSilicon(stdout);
+    expect(out).toEqual([{ vendor: "apple", name: "Apple Silicon (Mac15,7)", vramMb: 16384 }]);
+  });
+  test("missing model line -> falls back to arm64", () => {
+    const out = parseAppleSilicon(`${8 * 1024 * 1024 * 1024}\n`);
+    expect(out[0]?.vendor).toBe("apple");
+    expect(out[0]?.name).toBe("Apple Silicon (arm64)");
+    expect(out[0]?.vramMb).toBe(8192);
+  });
+  test("garbage / empty -> []", () => {
+    expect(parseAppleSilicon("")).toEqual([]);
+    expect(parseAppleSilicon("not-a-number\nMac15,7")).toEqual([]);
+  });
+});
+
 describe("parseNvidiaSmi", () => {
   test("parses name + VRAM (MiB), handles commas in name", () => {
     const out = parseNvidiaSmi("NVIDIA GeForce RTX 4090, 24564\nNVIDIA A100, 81920\n");

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

@@ -18,6 +18,10 @@ export const MIN_LOCAL_GPU_VRAM_MB = 8 * 1024;
 const VENDOR_PROFILE_VARIANT: Record<GpuVendor, "cuda" | "rocm" | "cpu"> = {
   nvidia: "cuda",
   amd: "rocm",
+  // The in-stack Ollama container on a Mac is a Linux container with no Metal
+  // access, so it can only ever run CPU. (On darwin apple GPUs are routed to
+  // host-Ollama guidance and never reach enable-ollama — see recommendSetup.)
+  apple: "cpu",
   unknown: "cpu",
 };
 
@@ -34,6 +38,23 @@ export type SetupRecommendationInput = {
   hostProviders: DetectedHostProvider[];
   /** Best detected GPU, or null. */
   gpu: GpuInfo | null;
+  /**
+   * Host platform. Defaults to `process.platform` when omitted, but the decision
+   * logic only reads this field (never `process.*`) so the function stays pure.
+   * On darwin the in-stack Linux Ollama can't reach the Mac's Metal GPU, so an
+   * 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 =
@@ -56,18 +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. capable GPU (>= threshold)    -> enable in-stack Ollama.
- *  4. 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",
@@ -78,6 +121,22 @@ export function recommendSetup(input: SetupRecommendationInput): SetupRecommenda
     };
   }
 
+  // macOS: the in-stack Ollama is a Linux container with no access to the Mac's
+  // Metal GPU, so enabling it would silently fall back to slow CPU. When the Mac
+  // has an Apple-Silicon GPU and nothing is connected yet, steer the user to a
+  // native host Ollama (which DOES use Metal) via connect-manually — reusing the
+  // existing action avoids a new wizard branch (chosen for minimal UI impact).
+  if (platform === "darwin" && gpu && gpu.vendor === "apple") {
+    return {
+      action: "connect-manually",
+      alert:
+        "No AI provider was detected. On macOS, fast local models need Ollama running " +
+        "natively (it uses your Apple Silicon / Metal GPU) — the bundled in-stack Ollama " +
+        "runs in Linux and cannot reach Metal. Install Ollama for macOS (https://ollama.com/download), " +
+        "or connect a provider on the next step.",
+    };
+  }
+
   if (gpu && gpu.vramMb >= MIN_LOCAL_GPU_VRAM_MB) {
     return {
       action: "enable-ollama",

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";
 
@@ -260,10 +261,11 @@ export {
 } from "./control-plane/lifecycle.js";
 
 // ── Docker ──────────────────────────────────────────────────────────────
-export type { DockerResult } from "./control-plane/docker.js";
+export type { DockerResult, ExistingProject } from "./control-plane/docker.js";
 export {
   checkDocker,
   checkDockerCompose,
+  detectExistingProject,
   resolveComposeProjectName,
   composePreflight,
   composeUp,
@@ -299,7 +301,7 @@ export { detectLocalProviders } from "./control-plane/model-runner.js";
 
 // ── Hardware detection + setup recommendation ───────────────────────────
 export type { GpuInfo, GpuVendor } from "./control-plane/hardware-detect.js";
-export { detectGpu, parseNvidiaSmi, parseRocmSmi } from "./control-plane/hardware-detect.js";
+export { detectGpu, parseNvidiaSmi, parseRocmSmi, parseAppleSilicon } from "./control-plane/hardware-detect.js";
 export type {
   DetectedHostProvider,
   SetupRecommendation,