@openpalm/lib 0.11.0-beta.3 → 0.11.0-beta.6

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

@@ -24,11 +24,12 @@ import {
   getAddonProfiles,
   getAddonProfileSelection,
   setAddonProfileSelection,
-  enableAddon,
-  disableAddonByName,
   setAddonEnabled,
   installAutomationFromRegistry,
   uninstallAutomation,
+  getAddonProfileAvailability,
+  annotateAddonProfileAvailability,
+  __addonAvailabilityTestHooks,
 } from "./registry.js";
 
 // ── Validation Tests ─────────────────────────────────────────────────
@@ -309,10 +310,11 @@ describe("materialized registry catalog", () => {
 
     materializeRegistryCatalog(sourceRoot);
 
-    expect(enableAddon(process.env.OP_HOME!, 'chat')).toEqual({ ok: true });
+    const stackDir = join(process.env.OP_HOME!, 'config', 'stack');
+    expect(setAddonEnabled(process.env.OP_HOME!, stackDir, 'chat', true)).toMatchObject({ ok: true });
     expect(existsSync(join(process.env.OP_HOME!, 'config', 'stack', 'addons', 'chat', 'compose.yml'))).toBe(true);
 
-    expect(disableAddonByName(process.env.OP_HOME!, 'chat')).toEqual({ ok: true });
+    expect(setAddonEnabled(process.env.OP_HOME!, stackDir, 'chat', false)).toMatchObject({ ok: true });
     expect(existsSync(join(process.env.OP_HOME!, 'config', 'stack', 'addons', 'chat'))).toBe(false);
   });
 
@@ -478,3 +480,131 @@ describe("materialized registry catalog", () => {
     expect(existsSync(join(stashDir, 'tasks', 'cleanup.md'))).toBe(false);
   });
 });
+
+// ── Host capability probes ───────────────────────────────────────────
+
+describe("getAddonProfileAvailability", () => {
+  beforeEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  afterEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  it("returns available:true for the cpu profile (no host requirements)", async () => {
+    const result = await getAddonProfileAvailability({ id: 'cpu' });
+    expect(result.available).toBe(true);
+    expect(result.reason).toBeUndefined();
+  });
+
+  it("returns available:true for unknown profile ids (no host-side gating)", async () => {
+    const result = await getAddonProfileAvailability({ id: 'something-else' });
+    expect(result.available).toBe(true);
+  });
+
+  it("caches the result across calls (probe runs only once)", async () => {
+    const a = await getAddonProfileAvailability({ id: 'cpu' });
+    const b = await getAddonProfileAvailability({ id: 'cpu' });
+    expect(a).toBe(b); // same reference — cached
+  });
+
+  it("probes cuda: returns available:false on a host with no NVIDIA runtime / CDI", async () => {
+    // This test runs on CI/dev machines without GPUs. We don't mock execFile;
+    // we just assert the contract: when neither signal is present, the
+    // reason mentions nvidia-container-toolkit. If a future GPU host runs
+    // this test, the assertion still tolerates the success case.
+    const result = await getAddonProfileAvailability({ id: 'cuda' });
+    if (!result.available) {
+      expect(result.reason).toContain('NVIDIA');
+    } else {
+      // Host genuinely has the runtime registered — accept it.
+      expect(result.reason).toBeUndefined();
+    }
+  });
+
+  it("probes rocm: returns available:false when /dev/kfd is missing", async () => {
+    const result = await getAddonProfileAvailability({ id: 'rocm' });
+    if (!result.available) {
+      expect(result.reason).toContain('ROCm');
+    } else {
+      expect(result.reason).toBeUndefined();
+    }
+  });
+
+  it("probes rocm: when devices exist, reports unpublished image distinctly from missing-device case", async () => {
+    // On a host without /dev/kfd, we hit the device-missing branch and
+    // get the "devices not present" copy. On a ROCm host, we'd fall
+    // through to the manifest-inspect probe and (until 0.11.0-rocm6
+    // ships) get the "image not published yet" copy. Both must mention
+    // ROCm so operator-facing copy stays consistent.
+    const result = await getAddonProfileAvailability({ id: 'rocm' });
+    if (!result.available && existsSync('/dev/kfd') && existsSync('/dev/dri')) {
+      expect(result.reason).toMatch(/image not published|CPU profile/i);
+    }
+    if (!result.available && !(existsSync('/dev/kfd') && existsSync('/dev/dri'))) {
+      expect(result.reason).toMatch(/devices not present/i);
+    }
+  });
+});
+
+describe("execFileNoThrow (ENOENT capture)", () => {
+  it("captures ENOENT for a missing binary as 'spawn <cmd> ENOENT' stderr", async () => {
+    const result = await __addonAvailabilityTestHooks.execFileNoThrow(
+      '/nonexistent/path/to/openpalm-test-no-such-binary-zzz',
+      ['--help'],
+      2_000,
+    );
+    expect(result.ok).toBe(false);
+    expect(result.stderr).toMatch(/ENOENT/);
+    // When the binary is "docker", the synthetic stderr becomes
+    // `spawn docker ENOENT: command not found` — that string matches the
+    // translateDockerError regex `/spawn .*docker.*ENOENT/i` so the
+    // operator gets actionable copy instead of "unknown error (no stderr)".
+    expect(result.stderr).toMatch(/spawn\s+\S*\s*ENOENT/);
+  });
+
+  it("formats ENOENT for `docker` so translateDockerError can match it", async () => {
+    // Use an absolute path that we know doesn't exist so the test is
+    // deterministic regardless of whether docker is installed on the host.
+    const result = await __addonAvailabilityTestHooks.execFileNoThrow(
+      'docker-not-installed-zzz',
+      ['info'],
+      2_000,
+    );
+    expect(result.ok).toBe(false);
+    expect(result.stderr).toBe('spawn docker-not-installed-zzz ENOENT: command not found');
+  });
+});
+
+describe("annotateAddonProfileAvailability", () => {
+  beforeEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  afterEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  it("decorates each profile with available + optional reason", async () => {
+    const out = await annotateAddonProfileAvailability([
+      { id: 'cpu', services: ['voice'], label: 'CPU', default: true },
+      { id: 'rocm', services: ['voice-rocm'], label: 'AMD' },
+    ]);
+    expect(out).toHaveLength(2);
+    expect(out[0]?.id).toBe('cpu');
+    expect(out[0]?.available).toBe(true);
+    // Preserves original fields.
+    expect(out[0]?.label).toBe('CPU');
+    expect(out[0]?.default).toBe(true);
+    expect(out[1]?.id).toBe('rocm');
+    expect(typeof out[1]?.available).toBe('boolean');
+  });
+
+  it("does not mutate the input array", async () => {
+    const input = [{ id: 'cpu', services: ['voice'] }];
+    const before = JSON.parse(JSON.stringify(input));
+    await annotateAddonProfileAvailability(input);
+    expect(input).toEqual(before);
+  });
+});

package/src/control-plane/registry.ts

@@ -5,7 +5,7 @@
  * Install seeds it once; refresh replaces it explicitly.
  */
 import { cpSync, existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { execFile, execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
@@ -84,7 +84,7 @@ export type RegistryCatalogVerification = {
   automationCount: number;
 };
 
-export type MutationResult = { ok: true } | { ok: false; error: string };
+type MutationResult = { ok: true } | { ok: false; error: string };
 export type AddonMutationResult = (
   | { ok: true; enabled: boolean; changed: boolean; services: string[] }
   | { ok: false; error: string }
@@ -346,8 +346,224 @@ export type AddonProfile = {
   label?: string;
   requires?: string;
   default?: boolean;
+  /**
+   * Whether the host can run this profile.
+   *
+   * Populated by `getAddonProfileAvailability()`. When the value is missing
+   * (e.g. older catalogs), callers should treat the profile as available.
+   */
+  available?: boolean;
+  /** Human-readable reason when `available === false`. */
+  reason?: string;
 };
 
+// ── Host capability probes ─────────────────────────────────────────────
+
+export type AddonProfileAvailability = { available: boolean; reason?: string };
+
+const HOST_PROBE_TIMEOUT_MS = 2_000;
+
+// Process-lifetime cache. Hardware presence does not change while the UI
+// server is running, so probing once is enough.
+const availabilityCache = new Map<string, AddonProfileAvailability>();
+
+/**
+ * Reset the host-capability cache. Test-only — not exported.
+ */
+function _resetAvailabilityCacheForTests(): void {
+  availabilityCache.clear();
+}
+
+// Exported under a deliberately ugly name so test files can reach it.
+export const __addonAvailabilityTestHooks = {
+  reset: _resetAvailabilityCacheForTests,
+  /**
+   * Test-only: exposes the internal exec wrapper so tests can verify
+   * ENOENT (missing binary) is surfaced as actionable stderr that the
+   * docker-error translator can recognise.
+   */
+  execFileNoThrow: (cmd: string, args: string[], timeoutMs: number) =>
+    execFileNoThrow(cmd, args, timeoutMs),
+};
+
+function execFileNoThrow(
+  cmd: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (error, stdout, stderr) => {
+      // ENOENT (binary missing) surfaces here with no stderr — child_process
+      // never gets to exec the program. Inject a synthetic stderr that
+      // matches the translateDockerError ENOENT regex so callers get
+      // actionable copy instead of "unknown error (no stderr)".
+      let mergedStderr = stderr?.toString() ?? '';
+      const code = (error as NodeJS.ErrnoException | null)?.code;
+      if (code && !mergedStderr) {
+        if (code === 'ENOENT') {
+          mergedStderr = `spawn ${cmd} ENOENT: command not found`;
+        } else {
+          mergedStderr = `spawn ${cmd} ${code}`;
+        }
+      }
+      resolve({
+        ok: !error,
+        stdout: stdout?.toString() ?? '',
+        stderr: mergedStderr,
+      });
+    });
+  });
+}
+
+/**
+ * Compute the openpalm/voice image ref for a given GPU variant, matching
+ * the substitution chain in the addon compose file:
+ *   ${OP_IMAGE_NAMESPACE:-openpalm}/voice:${OP_VOICE_IMAGE_TAG:-${OP_IMAGE_TAG:-v0.11.0}-<variant>}
+ */
+function voiceImageRef(variant: 'cpu' | 'cu121' | 'rocm6'): string {
+  const namespace = process.env.OP_IMAGE_NAMESPACE?.trim() || 'openpalm';
+  const explicit = process.env.OP_VOICE_IMAGE_TAG?.trim();
+  if (explicit) return `${namespace}/voice:${explicit}`;
+  const baseTag = process.env.OP_IMAGE_TAG?.trim() || 'v0.11.0';
+  return `${namespace}/voice:${baseTag}-${variant}`;
+}
+
+/**
+ * `docker manifest inspect <ref>` returns 0 only when the registry can
+ * resolve a manifest for that ref. We use it as the cheap "is this image
+ * actually published?" check — no pull required. The retry handles
+ * transient registry hiccups. Timeout is short because the manifest blob
+ * is a few KB.
+ */
+async function dockerManifestExists(imageRef: string): Promise<boolean> {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const res = await execFileNoThrow(
+      'docker',
+      ['manifest', 'inspect', imageRef],
+      5_000,
+    );
+    if (res.ok) return true;
+    // If docker itself is missing (ENOENT), retrying won't help.
+    if (/ENOENT/.test(res.stderr)) return false;
+  }
+  return false;
+}
+
+async function probeCuda(): Promise<AddonProfileAvailability> {
+  // Two acceptance signals:
+  //   1. `docker info` reports an `nvidia` runtime (toolkit installed +
+  //      `nvidia-ctk runtime configure --runtime=docker` was run).
+  //   2. `/etc/cdi/nvidia.yaml` exists (CDI-mode daemon with a generated
+  //      spec). We don't require the runtime in this case — the route's
+  //      CDI fallback can switch the compose to driver:cdi.
+  try {
+    if (existsSync('/etc/cdi/nvidia.yaml')) return { available: true };
+  } catch {
+    // existsSync only throws on path-syntax issues; ignore and probe docker.
+  }
+
+  const result = await execFileNoThrow(
+    'docker',
+    ['info', '--format', '{{json .Runtimes}}'],
+    HOST_PROBE_TIMEOUT_MS,
+  );
+  if (result.ok && result.stdout.includes('"nvidia"')) {
+    return { available: true };
+  }
+  return {
+    available: false,
+    reason: 'NVIDIA runtime not registered. Install nvidia-container-toolkit or enable CDI.',
+  };
+}
+
+async function probeRocm(): Promise<AddonProfileAvailability> {
+  // Hardware gate: ROCm needs both the KFD char device and the GPU DRI nodes.
+  let devicesPresent = false;
+  try {
+    devicesPresent = existsSync('/dev/kfd') && existsSync('/dev/dri');
+  } catch {
+    devicesPresent = false;
+  }
+  if (!devicesPresent) {
+    return {
+      available: false,
+      reason: 'AMD ROCm devices not present on this host.',
+    };
+  }
+
+  // Image gate: the openpalm/voice:*-rocm6 image isn't published yet, so
+  // even on a fully-functional ROCm host the compose-up would fail with a
+  // manifest-unknown pull error. Refuse the profile until the image lands.
+  const imageRef = voiceImageRef('rocm6');
+  const published = await dockerManifestExists(imageRef);
+  if (!published) {
+    return {
+      available: false,
+      reason: 'AMD ROCm image not published yet. Check back in a future release or use the CPU profile.',
+    };
+  }
+  return { available: true };
+}
+
+/**
+ * Probe the host for the capabilities required by an addon profile.
+ *
+ * Results are cached for the lifetime of the process — hardware doesn't
+ * change while the UI server runs. All probes use execFile (no shell)
+ * and never throw: errors collapse to `{ available: false, reason }`.
+ *
+ * Unknown profile ids default to `available: true` so unrelated addons
+ * (e.g. a future "high-mem" profile that doesn't probe hardware) keep
+ * working without code changes here.
+ */
+export async function getAddonProfileAvailability(
+  profile: Pick<AddonProfile, 'id'>,
+): Promise<AddonProfileAvailability> {
+  const cacheKey = profile.id;
+  const cached = availabilityCache.get(cacheKey);
+  if (cached) return cached;
+
+  let result: AddonProfileAvailability;
+  try {
+    if (profile.id === 'cpu') {
+      result = { available: true };
+    } else if (profile.id === 'cuda') {
+      result = await probeCuda();
+    } else if (profile.id === 'rocm') {
+      result = await probeRocm();
+    } else {
+      // Unknown profile id — assume available; caller is responsible for
+      // labelling profiles that need host capability gating.
+      result = { available: true };
+    }
+  } catch (err) {
+    // Belt-and-braces: any unexpected throw collapses to unavailable.
+    const reason = err instanceof Error ? err.message : String(err);
+    result = { available: false, reason: `probe failed: ${reason}` };
+  }
+
+  availabilityCache.set(cacheKey, result);
+  return result;
+}
+
+/**
+ * Decorate a list of profiles with `available`/`reason` based on the host
+ * capability probes. Returns a fresh array; does not mutate inputs.
+ */
+export async function annotateAddonProfileAvailability(
+  profiles: AddonProfile[],
+): Promise<AddonProfile[]> {
+  const results = await Promise.all(
+    profiles.map(async (p) => {
+      const a = await getAddonProfileAvailability(p);
+      const annotated: AddonProfile = { ...p, available: a.available };
+      if (a.reason) annotated.reason = a.reason;
+      return annotated;
+    }),
+  );
+  return results;
+}
+
 function readAddonProfiles(composePath: string): AddonProfile[] {
   if (!existsSync(composePath)) return [];
 
@@ -452,7 +668,7 @@ export function setAddonProfileSelection(stackDir: string, name: string, profile
   patchSecretsEnvFile(stackDir, { [profileEnvKey(name)]: trimmed });
 }
 
-export function enableAddon(homeDir: string, name: string): MutationResult {
+function enableAddon(homeDir: string, name: string): MutationResult {
   try {
     copyAddonFromRegistry(homeDir, name);
     // Pre-create the addon services directory so Docker doesn't create it as root
@@ -463,7 +679,7 @@ export function enableAddon(homeDir: string, name: string): MutationResult {
   }
 }
 
-export function disableAddonByName(homeDir: string, name: string): MutationResult {
+function disableAddonByName(homeDir: string, name: string): MutationResult {
   try {
     removeEnabledAddon(homeDir, name);
     return { ok: true };

package/src/control-plane/secrets.ts

@@ -14,8 +14,8 @@ const logger = createLogger("secrets");
 /** Keys whose values are shown unmasked in the UI (not secrets). */
 export const PLAIN_CONFIG_KEYS = new Set([
   "OPENAI_BASE_URL",
-  "OWNER_NAME",
-  "OWNER_EMAIL",
+  "OP_OWNER_NAME",
+  "OP_OWNER_EMAIL",
 ]);
 
 
@@ -91,8 +91,8 @@ function ensureSystemSecrets(state: ControlPlaneState): void {
       "LMSTUDIO_API_KEY=",
       "",
       "# ── Owner ────────────────────────────────────────────────────────────",
-      `OWNER_NAME=${process.env.OWNER_NAME ?? ""}`,
-      `OWNER_EMAIL=${process.env.OWNER_EMAIL ?? ""}`,
+      `OP_OWNER_NAME=${process.env.OP_OWNER_NAME ?? ""}`,
+      `OP_OWNER_EMAIL=${process.env.OP_OWNER_EMAIL ?? ""}`,
       "",
     ].join("\n");
     const content = mergeEnvContent(header, updates);

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

@@ -218,15 +218,15 @@ describe("buildSecretsFromSetup", () => {
   it("sets owner info when provided", () => {
     const spec = makeValidSpec();
     const secrets = buildSecretsFromSetup(spec.connections, spec.owner);
-    expect(secrets.OWNER_NAME).toBe("Test User");
-    expect(secrets.OWNER_EMAIL).toBe("test@example.com");
+    expect(secrets.OP_OWNER_NAME).toBe("Test User");
+    expect(secrets.OP_OWNER_EMAIL).toBe("test@example.com");
   });
 
   it("omits owner info when empty", () => {
     const spec = makeValidSpec({ owner: { name: "", email: "" } });
     const secrets = buildSecretsFromSetup(spec.connections, spec.owner);
-    expect(secrets.OWNER_NAME).toBeUndefined();
-    expect(secrets.OWNER_EMAIL).toBeUndefined();
+    expect(secrets.OP_OWNER_NAME).toBeUndefined();
+    expect(secrets.OP_OWNER_EMAIL).toBeUndefined();
   });
 
   it("does NOT include provider API keys in stack.env updates", () => {
@@ -367,8 +367,8 @@ describe("performSetup", () => {
         "GROQ_API_KEY=",
         "MISTRAL_API_KEY=",
         "GOOGLE_API_KEY=",
-        "OWNER_NAME=",
-        "OWNER_EMAIL=",
+        "OP_OWNER_NAME=",
+        "OP_OWNER_EMAIL=",
         "",
       ].join("\n")
     );

package/src/control-plane/setup.ts

@@ -17,12 +17,11 @@ import { acquireInstallLock, releaseInstallLock, type InstallLockHandle } from "
 import {
   ensureSecrets,
   updateSecretsEnv,
-  updateSystemSecretsEnv,
+  patchSecretsEnvFile,
   ensureOpenCodeConfig,
   readStackEnv,
   writeAuthJsonProviderKeys,
 } from "./secrets.js";
-import { ensureOpenCodeSystemConfig } from "./core-assets.js";
 import { createState } from "./lifecycle.js";
 import { writeStackSpec } from "./stack-spec.js";
 import { writeVoiceVars } from "./spec-to-env.js";
@@ -98,8 +97,8 @@ export function buildSecretsFromSetup(
   const updates: Record<string, string> = {};
   const ownerName = (owner?.name?.trim() ?? "").replace(/[\r\n\0]/g, "").slice(0, 200);
   const ownerEmail = (owner?.email?.trim() ?? "").replace(/[\r\n\0]/g, "").slice(0, 200);
-  if (ownerName) updates.OWNER_NAME = ownerName;
-  if (ownerEmail) updates.OWNER_EMAIL = ownerEmail;
+  if (ownerName) updates.OP_OWNER_NAME = ownerName;
+  if (ownerEmail) updates.OP_OWNER_EMAIL = ownerEmail;
   void connections;
   return updates;
 }
@@ -227,7 +226,7 @@ export async function performSetup(
         }
       }
       updateSecretsEnv(state, updates);
-      updateSystemSecretsEnv(state, buildSystemSecretsFromSetup(security.uiLoginPassword, existingSystemEnv));
+      patchSecretsEnvFile(state.stackDir, buildSystemSecretsFromSetup(security.uiLoginPassword, existingSystemEnv));
       // Provider API keys land in OpenCode's auth.json (bind-mounted into
       // the assistant container) — never in stack.env.
       writeAuthJsonProviderKeys(state, providerKeys);
@@ -311,7 +310,6 @@ export async function performSetup(
       }
 
       ensureOpenCodeConfig();
-      ensureOpenCodeSystemConfig();
 
       // Seed default automation into the AKM stash. Idempotent — existing files
       // are left alone so user edits survive re-install and upgrade.

package/src/control-plane/spec-to-env.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { deriveSystemEnvFromSpec, writeVoiceVars } from "./spec-to-env.js";
@@ -25,7 +25,11 @@ describe("deriveSystemEnvFromSpec", () => {
   test("produces default port values", () => {
     const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
     expect(result.OP_ASSISTANT_PORT).toBe("3800");
-    expect(result.OP_GUARDIAN_PORT).toBe("3899");
+  });
+
+  test("does not emit OP_GUARDIAN_PORT (guardian is network-only, no host mapping)", () => {
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    expect(result.OP_GUARDIAN_PORT).toBeUndefined();
   });
 
   test("does not include the retired memory service port", () => {
@@ -45,6 +49,18 @@ describe("deriveSystemEnvFromSpec", () => {
     expect(result.OP_OLLAMA_ENABLED).toBeUndefined();
     expect(result.OP_ADMIN_ENABLED).toBeUndefined();
   });
+
+  test("auto-detects OP_UID/OP_GID from the homeDir owner (not hard-coded 1000)", () => {
+    // tempDir is owned by the test process, which on a CI runner or
+    // dev box is typically NOT root and NOT necessarily UID 1000. The
+    // assertion that matters: we read the value off statSync, not a
+    // hard-coded constant.
+    if (process.platform === "win32") return;
+    const expected = statSync(tempDir);
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, tempDir);
+    expect(result.OP_UID).toBe(String(expected.uid));
+    expect(result.OP_GID).toBe(String(expected.gid));
+  });
 });
 
 describe("writeVoiceVars", () => {
@@ -57,9 +73,9 @@ describe("writeVoiceVars", () => {
     }, tempDir);
 
     const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
-    expect(content).toContain("TTS_BASE_URL=https://tts.example.com/v1");
-    expect(content).toContain("TTS_MODEL=tts-1");
-    expect(content).toContain("TTS_VOICE=alloy");
+    expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
+    expect(content).toContain("OP_TTS_MODEL=tts-1");
+    expect(content).toContain("OP_TTS_VOICE=alloy");
   });
 
   test("writes STT vars to stack.env", () => {
@@ -71,9 +87,9 @@ describe("writeVoiceVars", () => {
     }, tempDir);
 
     const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
-    expect(content).toContain("STT_BASE_URL=https://stt.example.com/v1");
-    expect(content).toContain("STT_MODEL=whisper-1");
-    expect(content).toContain("STT_LANGUAGE=en");
+    expect(content).toContain("OP_STT_BASE_URL=https://stt.example.com/v1");
+    expect(content).toContain("OP_STT_MODEL=whisper-1");
+    expect(content).toContain("OP_STT_LANGUAGE=en");
   });
 
   test("creates stack.env if it does not exist", () => {
@@ -84,7 +100,7 @@ describe("writeVoiceVars", () => {
     }, tempDir);
 
     const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
-    expect(content).toContain("TTS_BASE_URL=https://tts.example.com/v1");
+    expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
   });
 
   test("is a no-op when no vars are provided", () => {

package/src/control-plane/spec-to-env.ts

@@ -9,6 +9,7 @@ import type { StackSpec } from "./stack-spec.js";
 import { SPEC_DEFAULTS } from "./stack-spec.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { mergeEnvContent } from "./env.js";
+import { resolveOperatorIds } from "./operator-ids.js";
 
 /**
  * Derive the system.env key-value pairs from the StackSpec.
@@ -18,9 +19,6 @@ export function deriveSystemEnvFromSpec(
   spec: StackSpec,
   homeDir: string,
 ): Record<string, string> {
-  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
-  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
-
   const ports = SPEC_DEFAULTS.ports;
   const image = SPEC_DEFAULTS.image;
 
@@ -28,17 +26,25 @@ export function deriveSystemEnvFromSpec(
 
   // Paths
   result["OP_HOME"] = homeDir;
-  result["OP_UID"] = String(uid);
-  result["OP_GID"] = String(gid);
+
+  // Operator UID/GID — auto-detect from OP_HOME owner (or process UID
+  // as fallback). Skipped on Windows where containers run in WSL2 and
+  // OP_UID has no meaning on the host process.
+  const ids = resolveOperatorIds(homeDir);
+  if (ids) {
+    result["OP_UID"] = String(ids.uid);
+    result["OP_GID"] = String(ids.gid);
+  }
   // Image
   result["OP_IMAGE_NAMESPACE"] = image.namespace;
   result["OP_IMAGE_TAG"] = image.tag;
 
-  // Ports
+  // Ports — only the services that publish to the host. Guardian is
+  // network-only (no host port mapping) so OP_GUARDIAN_PORT is no longer
+  // emitted; channels reach it via Docker DNS at http://guardian:8080.
   result["OP_ASSISTANT_PORT"] = String(ports.assistant);
   result["OP_ADMIN_PORT"] = String(ports.admin);
   result["OP_ADMIN_OPENCODE_PORT"] = String(ports.adminOpencode);
-  result["OP_GUARDIAN_PORT"] = String(ports.guardian);
   result["OP_ASSISTANT_SSH_PORT"] = String(ports.assistantSsh);
 
   void spec; // spec reserved for future use; ports/image come from SPEC_DEFAULTS
@@ -79,20 +85,25 @@ export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void
   const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
   const vars: Record<string, string> = {};
 
+  // OP_ prefix is mandatory: unprefixed TTS_*/STT_* names collide with
+  // other tooling (OpenAI clients, kokoro-fastapi, etc.) commonly set in
+  // operator shells. The UI server only reads OP_-prefixed vars from
+  // process.env, so a leaked host TTS_VOICE can't silently override the
+  // saved selection.
   const { tts, stt } = config;
   if (tts?.enabled !== false) {
-    if (tts?.engine) vars["TTS_ENGINE"] = tts.engine;
-    if (tts?.provider) vars["TTS_PROVIDER"] = tts.provider;
-    if (tts?.baseURL) vars["TTS_BASE_URL"] = tts.baseURL;
-    if (tts?.model) vars["TTS_MODEL"] = tts.model;
-    if (tts?.voice) vars["TTS_VOICE"] = tts.voice;
+    if (tts?.engine) vars["OP_TTS_ENGINE"] = tts.engine;
+    if (tts?.provider) vars["OP_TTS_PROVIDER"] = tts.provider;
+    if (tts?.baseURL) vars["OP_TTS_BASE_URL"] = tts.baseURL;
+    if (tts?.model) vars["OP_TTS_MODEL"] = tts.model;
+    if (tts?.voice) vars["OP_TTS_VOICE"] = tts.voice;
   }
   if (stt?.enabled !== false) {
-    if (stt?.engine) vars["STT_ENGINE"] = stt.engine;
-    if (stt?.provider) vars["STT_PROVIDER"] = stt.provider;
-    if (stt?.baseURL) vars["STT_BASE_URL"] = stt.baseURL;
-    if (stt?.model) vars["STT_MODEL"] = stt.model;
-    if (stt?.language) vars["STT_LANGUAGE"] = stt.language;
+    if (stt?.engine) vars["OP_STT_ENGINE"] = stt.engine;
+    if (stt?.provider) vars["OP_STT_PROVIDER"] = stt.provider;
+    if (stt?.baseURL) vars["OP_STT_BASE_URL"] = stt.baseURL;
+    if (stt?.model) vars["OP_STT_MODEL"] = stt.model;
+    if (stt?.language) vars["OP_STT_LANGUAGE"] = stt.language;
   }
 
   if (Object.keys(vars).length === 0) return;