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

package/README.md

@@ -3,6 +3,8 @@
 Shared control-plane library for OpenPalm.
 CLI, admin, and scheduler use this package so stack behavior stays consistent.
 
+> **Bun required.** This package ships TypeScript source and relies on Bun's native TS execution. It does not compile to JavaScript and is not compatible with Node.js.
+
 The current model is direct-write over `~/.openpalm/` plus native Docker Compose.
 Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.0-beta.3",
+  "version": "0.11.0-beta.6",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "scripts": {
     "test": "bun test"
   },

package/src/control-plane/akm-vault.ts

@@ -244,7 +244,11 @@ export async function deleteAkmVaultKey(
   const vaultPath = await ensureAkmUserVault(state, env);
   if (!vaultPath) return false;
   try {
-    await execAkm(["vault", "unset", AKM_USER_VAULT_REF, key], env);
+    // --yes: newer akm versions require explicit confirmation for any
+    // destructive operation in non-interactive mode. Without this flag
+    // the command exits with NON_INTERACTIVE_REQUIRES_YES and our
+    // delete looks like a hard failure instead of an idempotent unset.
+    await execAkm(["vault", "unset", "--yes", AKM_USER_VAULT_REF, key], env);
   } catch (err) {
     // `unset` of a missing key is a benign no-op; many akm versions exit 0
     // anyway. If akm hard-fails (non-zero, non-empty stderr) we surface it.

package/src/control-plane/channels.ts

@@ -19,9 +19,11 @@ function isValidChannelName(name: string): boolean {
 // ── Channel Discovery ─────────────────────────────────────────────────
 
 /**
- * Check if a compose file defines a channel service (has CHANNEL_NAME or GUARDIAN_URL).
- * This is compose-derived: we parse the actual compose content rather than
- * relying on filename patterns or directory naming conventions.
+ * Check if a compose file defines a channel service (has CHANNEL_NAME).
+ * Compose-derived: we parse the actual compose content rather than rely on
+ * filename or directory naming conventions. (GUARDIAN_URL used to be a
+ * fallback signal — it's been removed since channels-sdk now hardcodes the
+ * in-network guardian URL.)
  */
 export function isChannelAddon(composePath: string): boolean {
   try {
@@ -36,9 +38,9 @@ export function isChannelAddon(composePath: string): boolean {
       const env = (svcDef as Record<string, unknown>).environment;
       if (typeof env === "object" && env !== null) {
         if (Array.isArray(env)) {
-          if (env.some((e: unknown) => typeof e === "string" && (e.startsWith("CHANNEL_NAME=") || e.startsWith("GUARDIAN_URL=")))) return true;
+          if (env.some((e: unknown) => typeof e === "string" && e.startsWith("CHANNEL_NAME="))) return true;
         } else {
-          if ("CHANNEL_NAME" in (env as Record<string, unknown>) || "GUARDIAN_URL" in (env as Record<string, unknown>)) return true;
+          if ("CHANNEL_NAME" in (env as Record<string, unknown>)) return true;
         }
       }
     }
@@ -51,7 +53,7 @@ export function isChannelAddon(composePath: string): boolean {
 /**
  * Discover installed channels by scanning stack/addons/ for channel addons.
  * A channel addon is identified by compose-derived truth: its compose.yml
- * defines services with CHANNEL_NAME or GUARDIAN_URL environment variables.
+ * defines services with a CHANNEL_NAME environment variable.
  *
  * Non-channel addons (admin, ollama, etc.) are excluded.
  *

package/src/control-plane/compose-args.test.ts

@@ -6,7 +6,6 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
-  COMPOSE_PROJECT_NAME,
   buildComposeOptions,
   buildComposeCliArgs,
 } from "./compose-args.js";
@@ -63,14 +62,6 @@ afterEach(() => {
   rmSync(tempDir, { recursive: true, force: true });
 });
 
-// ── COMPOSE_PROJECT_NAME ─────────────────────────────────────────────────
-
-describe("COMPOSE_PROJECT_NAME", () => {
-  it("is 'openpalm'", () => {
-    expect(COMPOSE_PROJECT_NAME).toBe("openpalm");
-  });
-});
-
 // ── buildComposeOptions ──────────────────────────────────────────────────
 
 describe("buildComposeOptions", () => {

package/src/control-plane/compose-args.ts

@@ -11,10 +11,6 @@ import { buildComposeFileList } from "./lifecycle.js";
 import { buildEnvFiles } from "./config-persistence.js";
 import { resolveComposeProjectName } from "./docker.js";
 
-// ── Constants ────────────────────────────────────────────────────────────
-
-export const COMPOSE_PROJECT_NAME = "openpalm";
-
 // ── Types ────────────────────────────────────────────────────────────────
 
 export type ComposeOptions = {

package/src/control-plane/config-persistence.ts

@@ -12,6 +12,7 @@ import { parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
 import type { ControlPlaneState, ArtifactMeta } from "./types.js";
 import { isChannelAddon } from "./channels.js";
 import { listEnabledAddonIds } from "./registry.js";
+import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
 
 import {
   readCoreCompose,
@@ -69,6 +70,19 @@ export function writeSystemEnv(state: ControlPlaneState): void {
     OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
   };
 
+  // Backfill OP_UID/OP_GID when the existing stack.env was written by an
+  // older code path that hard-coded 1000, or when the file was created
+  // with missing/zero values. We only override when the current value is
+  // missing or zero — an operator who manually set OP_UID=2000 (e.g.
+  // because they're running on a host with a non-1000 service account)
+  // must not be silently changed.
+  const parsed = parseEnvFile(systemEnvPath);
+  const ids = resolveOperatorIds(state.homeDir);
+  if (ids) {
+    if (!hasUsableOperatorId(parsed, "OP_UID")) adminManaged.OP_UID = String(ids.uid);
+    if (!hasUsableOperatorId(parsed, "OP_GID")) adminManaged.OP_GID = String(ids.gid);
+  }
+
   const content = mergeEnvContent(base, adminManaged, {
     sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
   });
@@ -77,8 +91,13 @@ export function writeSystemEnv(state: ControlPlaneState): void {
 }
 
 function generateFallbackSystemEnv(state: ControlPlaneState): string {
-  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
-  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
+  // Operator UID/GID — auto-detect from OP_HOME owner (or process UID).
+  // Skipped on Windows where containers run in WSL2 and OP_UID has no
+  // meaning on the host process.
+  const ids = resolveOperatorIds(state.homeDir);
+  const idLines: string[] = ids
+    ? [`OP_UID=${ids.uid}`, `OP_GID=${ids.gid}`]
+    : [];
 
   return [
     "# OpenPalm — System Configuration (managed by CLI/admin)",
@@ -92,18 +111,18 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     "",
     "# ── Paths ──────────────────────────────────────────────────────────",
     `OP_HOME=${state.homeDir}`,
-    `OP_UID=${uid}`,
-    `OP_GID=${gid}`,
+    ...idLines,
     "",
     "# ── Images ──────────────────────────────────────────────────────────",
     `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
     `OP_IMAGE_TAG=${DEFAULT_IMAGE_TAG}`,
     "",
     "# ── Ports (38XX range) ──────────────────────────────────────────────",
+    "# Guardian is network-only (no host port) — channels reach it via",
+    "# http://guardian:8080 over the channel_lan Docker network.",
     `OP_ASSISTANT_PORT=3800`,
     `OP_ADMIN_PORT=3880`,
     `OP_ADMIN_OPENCODE_PORT=3881`,
-    `OP_GUARDIAN_PORT=3899`,
     ""
   ].join("\n");
 }
@@ -126,8 +145,21 @@ export function discoverStackOverlays(stackDir: string): string[] {
       .filter((e) => e.isDirectory())
       .sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
-      const addonCompose = `${addonsDir}/${entry.name}/compose.yml`;
-      if (existsSync(addonCompose)) files.push(addonCompose);
+      const dir = `${addonsDir}/${entry.name}`;
+      // Pick up compose.yml plus any compose.<variant>.yml sibling
+      // overlays (e.g. compose.cdi.yml generated by /admin/voice on
+      // CDI hosts). Stable sort: compose.yml first, then siblings
+      // alphabetically, so the base file's keys are the defaults and
+      // overlays merge on top in deterministic order.
+      const overlays = readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && /^compose(\.[A-Za-z0-9_-]+)?\.ya?ml$/.test(e.name))
+        .map((e) => e.name)
+        .sort((a, b) => {
+          if (a === "compose.yml" || a === "compose.yaml") return -1;
+          if (b === "compose.yml" || b === "compose.yaml") return 1;
+          return a.localeCompare(b);
+        });
+      for (const name of overlays) files.push(`${dir}/${name}`);
     }
   }
 
@@ -225,7 +257,7 @@ export function writeChannelSecrets(stackDir: string, secrets: Record<string, st
  * (e.g. `/var/run/docker.sock`) are left alone.
  */
 export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
-  const composeFiles = discoverStackOverlays(`${state.homeDir}/stack`);
+  const composeFiles = discoverStackOverlays(state.stackDir);
   if (composeFiles.length === 0) return;
 
   const envVars: Record<string, string> = {
@@ -281,9 +313,13 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
 export function writeRuntimeFiles(
   state: ControlPlaneState
 ): void {
-  // Write core compose to config/stack/
+  // Write core compose to config/stack/ only on first install —
+  // refreshCoreAssets() is the canonical writer on update.
   mkdirSync(state.stackDir, { recursive: true });
-  writeFileSync(`${state.stackDir}/core.compose.yml`, state.artifacts.compose);
+  const composePath = `${state.stackDir}/core.compose.yml`;
+  if (!existsSync(composePath)) {
+    writeFileSync(composePath, state.artifacts.compose);
+  }
 
   // Load persisted channel HMAC secrets from guardian.env,
   // then generate new ones for new channel addons.

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

@@ -11,6 +11,7 @@
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveStateDir, resolveOpenPalmHome, resolveBackupsDir, resolveStashDir } from "./home.js";
 import { createLogger } from "../logger.js";
 import { sha256 } from "./crypto.js";
@@ -80,15 +81,26 @@ export function seedStashAssets(seeds: Record<string, string>): string[] {
 // ── Asset Refresh (GitHub download) ──────────────────────────────────
 
 const REPO = "itlackey/openpalm";
-const VERSION = process.env.OP_ASSET_VERSION ?? "main";
 
-// Stash seeds are intentionally NOT in this list — they use seedStashAssets()
-// which never overwrites existing files (user edits win on re-install).
+function resolveAssetVersion(): string {
+  if (process.env.OP_ASSET_VERSION) return process.env.OP_ASSET_VERSION;
+  try {
+    const pkgJson = JSON.parse(
+      readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf-8")
+    );
+    return `v${pkgJson.version}`;
+  } catch {
+    return "main";
+  }
+}
+const VERSION = resolveAssetVersion();
+
+// Persona files (openpalm.md, system.md) and stash seeds are intentionally NOT
+// in this list — they are user-customizable and use seedAssistantPersonaFiles()
+// / seedStashAssets() which never overwrite existing files (user edits win).
 const MANAGED_ASSETS: { relPath: string; githubFilename: string }[] = [
-  { relPath: "config/stack/core.compose.yml",        githubFilename: ".openpalm/config/stack/core.compose.yml" },
-  { relPath: "config/assistant/opencode.jsonc",      githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
-  { relPath: "config/assistant/openpalm.md",         githubFilename: ".openpalm/config/assistant/openpalm.md" },
-  { relPath: "config/assistant/system.md",           githubFilename: ".openpalm/config/assistant/system.md" },
+  { relPath: "config/stack/core.compose.yml",   githubFilename: ".openpalm/config/stack/core.compose.yml" },
+  { relPath: "config/assistant/opencode.jsonc", githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
 ];
 
 async function downloadAsset(filename: string): Promise<string> {
@@ -139,3 +151,32 @@ export async function refreshCoreAssets(): Promise<{
 
   return { backupDir, updated };
 }
+
+// ── Assistant Persona File Seeding ────────────────────────────────────
+
+/**
+ * Seed assistant persona files (openpalm.md, system.md) into OP_HOME.
+ *
+ * Idempotent: **never overwrites** an existing file — user edits always
+ * win. This preserves the "config/ is user-owned" contract: persona files
+ * are seeded once on first install and never touched again on update.
+ *
+ * `seeds` maps relative path keys (e.g. `"config/assistant/openpalm.md"`)
+ * to file content. Each file is written to `resolveOpenPalmHome()/<relPath>`
+ * only if the file does not already exist.
+ *
+ * Returns the list of relative paths that were actually written (empty on
+ * re-run when every seed already exists on disk).
+ */
+export function seedAssistantPersonaFiles(seeds: Record<string, string>): string[] {
+  const homeDir = resolveOpenPalmHome();
+  const written: string[] = [];
+  for (const [relPath, content] of Object.entries(seeds)) {
+    const targetPath = join(homeDir, relPath);
+    if (existsSync(targetPath)) continue;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, content);
+    written.push(relPath);
+  }
+  return written;
+}

package/src/control-plane/docker.ts

@@ -295,26 +295,37 @@ export async function composeLogs(
   return run(args, undefined);
 }
 
+// 60-minute pull timeout. Voice addon ships a ~2.4 GB image (CPU) /
+// ~7.6 GB (CUDA); on a 1-2 Mbps home connection these legitimately take
+// 30+ minutes. The previous 5-min cap silently killed pulls mid-stream
+// on first install, surfacing as an opaque "pull failed". The wizard's
+// retry layer wraps this, so an actually-hung pull is bounded by the
+// outer retry budget; this just gives any progressing pull room to
+// finish on slow connections.
+const PULL_TIMEOUT_MS = 60 * 60_000;
+
 /**
  * Pull image for a single service.
  */
 export async function composePullService(
   service: string,
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<DockerResult> {
   await runPreflight(options);
   const args = buildComposeArgs(options);
+  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("pull", service);
-  return run(args, undefined, 300_000, collectEnvOverrides(options.envFiles));
+  return run(args, undefined, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }
 
 export async function composePull(
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<DockerResult> {
   await runPreflight(options);
   const args = buildComposeArgs(options);
+  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("pull");
-  return run(args, undefined, 300_000, collectEnvOverrides(options.envFiles));
+  return run(args, undefined, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }
 
 /**

package/src/control-plane/install-edge-cases.test.ts

@@ -142,8 +142,8 @@ function seedMinimalEnvFiles(): void {
       "GROQ_API_KEY=",
       "MISTRAL_API_KEY=",
       "GOOGLE_API_KEY=",
-      "OWNER_NAME=",
-      "OWNER_EMAIL=",
+      "OP_OWNER_NAME=",
+      "OP_OWNER_EMAIL=",
       "",
     ].join("\n")
   );
@@ -187,7 +187,7 @@ describe("Fresh Install", () => {
     // API keys and owner info are seeded in state/stack.env.
     const stackContent = readFileSync(join(stackDir, "stack.env"), "utf-8");
     expect(stackContent).toContain("OPENAI_API_KEY=");
-    expect(stackContent).toContain("OWNER_NAME=");
+    expect(stackContent).toContain("OP_OWNER_NAME=");
   });
 
   // Scenario 2: isSetupComplete returns false before setup

package/src/control-plane/lifecycle.ts

@@ -25,7 +25,7 @@ import { refreshCoreAssets } from "./core-assets.js";
 import { isSetupComplete } from "./setup-status.js";
 import { snapshotCurrentState } from "./rollback.js";
 import { checkDocker, composePreflight, composePull, composeUp, composeConfigServices, resolveComposeProjectName } from "./docker.js";
-import { acquireLock, releaseLock } from "./lock.js";
+import { acquireInstallLock, releaseInstallLock } from "./install-lock.js";
 import { listEnabledAddonIds } from "./registry.js";
 
 const IMAGE_NAMESPACE_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
@@ -125,7 +125,8 @@ async function reconcileCore(
 }
 
 export async function applyInstall(state: ControlPlaneState): Promise<void> {
-  const lock = acquireLock(state.homeDir, "install");
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
     await reconcileCore(state, { activateServices: true });
     // Pre-create host-side volume mount targets as the current user so
@@ -133,25 +134,27 @@ export async function applyInstall(state: ControlPlaneState): Promise<void> {
     // non-root containers).
     ensureComposeVolumeTargets(state);
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
 export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted: string[] }> {
-  const lock = acquireLock(state.homeDir, "update");
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
     return { restarted: await reconcileCore(state, {}) };
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
 export async function applyUninstall(state: ControlPlaneState): Promise<{ stopped: string[] }> {
-  const lock = acquireLock(state.homeDir, "uninstall");
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
     return { stopped: await reconcileCore(state, { deactivateServices: true }) };
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
@@ -218,13 +221,14 @@ export async function applyUpgrade(
   updated: string[];
   restarted: string[];
 }> {
-  const lock = acquireLock(state.homeDir, "upgrade");
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
     const { backupDir, updated } = await refreshCoreAssets();
     const restarted = await reconcileCore(state, {});
     return { backupDir, updated, restarted };
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 

package/src/control-plane/operator-ids.test.ts

@@ -0,0 +1,130 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
+
+let tempDir = "";
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "openpalm-opids-"));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("resolveOperatorIds", () => {
+  test("returns the homeDir's owner when it exists and is non-root", () => {
+    // A mkdtemp directory is owned by the current process — neither
+    // root (in any reasonable test env) nor a hard-coded 1000.
+    const expected = statSync(tempDir);
+    const ids = resolveOperatorIds(tempDir);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    expect(ids!.uid).toBe(expected.uid);
+    expect(ids!.gid).toBe(expected.gid);
+  });
+
+  test("falls back to process UID when homeDir does not exist", () => {
+    const missing = join(tempDir, "does-not-exist");
+    const ids = resolveOperatorIds(missing);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    // process.getuid is guaranteed on POSIX runtimes used by this test
+    expect(ids!.uid).toBe(process.getuid!());
+    expect(ids!.gid).toBe(process.getgid!());
+  });
+
+  test("never returns 0 (root) — falls back to process UID when homeDir is root-owned", () => {
+    // We can't easily chown a dir to root without root. Instead, exercise
+    // the branch via a faked statSync output: build a path that triggers
+    // the "owner is 0, prefer process UID" code path by ensuring real
+    // tempDir owner is the process UID and asserting the result for a
+    // missing path matches process UID (already covered above). The
+    // explicit 0-check is enforced by the implementation; this test
+    // documents that the function never *returns* 0 for any of the
+    // exercised inputs in a non-root test process.
+    const ids = resolveOperatorIds(tempDir);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    expect(ids!.uid).toBeGreaterThan(0);
+    expect(ids!.gid).toBeGreaterThan(0);
+  });
+
+  test("returns null when BOTH homeDir owner and process UID/GID are 0 (root install on root-owned OP_HOME)", () => {
+    if (process.platform === "win32") {
+      // win32 short-circuits before any of this logic
+      expect(resolveOperatorIds(tempDir)).toBeNull();
+      return;
+    }
+
+    // Stub process.getuid / getgid to simulate running as root. On Linux,
+    // `/` is owned by uid=0 gid=0, so passing "/" gives us a root-owned
+    // homeDir. Combined with the stubbed process IDs, this hits the
+    // "both signals are root" branch that previously returned {0,0}.
+    const origGetuid = process.getuid;
+    const origGetgid = process.getgid;
+    try {
+      (process as unknown as { getuid: () => number }).getuid = () => 0;
+      (process as unknown as { getgid: () => number }).getgid = () => 0;
+      // Sanity-check the assumption that "/" is root-owned in this env
+      // before relying on it as a fixture. On macOS / Linux CI runners
+      // this holds; if a future weird env breaks it, the assertion
+      // surfaces clearly rather than producing a confusing pass.
+      const rootStat = statSync("/");
+      expect(rootStat.uid).toBe(0);
+      expect(rootStat.gid).toBe(0);
+
+      const ids = resolveOperatorIds("/");
+      expect(ids).toBeNull();
+    } finally {
+      (process as unknown as { getuid: typeof origGetuid }).getuid = origGetuid;
+      (process as unknown as { getgid: typeof origGetgid }).getgid = origGetgid;
+    }
+  });
+
+  test("returns null on win32", () => {
+    // This test is informational; on non-win32 it doesn't run the win32
+    // branch. The check is left here for documentation and runs as a
+    // no-op assertion on POSIX.
+    if (process.platform === "win32") {
+      expect(resolveOperatorIds(tempDir)).toBeNull();
+    } else {
+      // No-op: confirms the test compiles and the helper is callable.
+      expect(typeof resolveOperatorIds).toBe("function");
+    }
+  });
+});
+
+describe("hasUsableOperatorId", () => {
+  test("returns true for positive numeric values", () => {
+    expect(hasUsableOperatorId({ OP_UID: "1000" }, "OP_UID")).toBe(true);
+    expect(hasUsableOperatorId({ OP_GID: "501" }, "OP_GID")).toBe(true);
+  });
+
+  test("returns false for missing key", () => {
+    expect(hasUsableOperatorId({}, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for empty string", () => {
+    expect(hasUsableOperatorId({ OP_UID: "" }, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for zero", () => {
+    expect(hasUsableOperatorId({ OP_UID: "0" }, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for non-numeric garbage", () => {
+    expect(hasUsableOperatorId({ OP_UID: "abc" }, "OP_UID")).toBe(false);
+  });
+});

package/src/control-plane/operator-ids.ts

@@ -0,0 +1,89 @@
+/**
+ * Operator UID/GID detection for stack.env.
+ *
+ * Container processes that bind-mount host paths (voice models, addon
+ * caches, etc.) run as `${OP_UID}:${OP_GID}`. If those values are wrong,
+ * the container can't write to the mounted volume and the install
+ * silently degrades (model downloads stall, healthchecks time out).
+ *
+ * Detection strategy (Linux/macOS):
+ *   1. Stat OP_HOME. If it exists and is owned by a non-root user,
+ *      prefer that owner — operator may have created OP_HOME under a
+ *      different account than the one running install (e.g. sudo
+ *      install for a service user).
+ *   2. Otherwise fall back to the process's real UID/GID.
+ *   3. Never return 0 (root). Running install as root is allowed but
+ *      the container must run as the operator, not root.
+ *
+ * Returns `null` on Windows (containers run in WSL2's Linux; OP_UID
+ * has no meaning on the win32 host process itself).
+ */
+import { statSync } from "node:fs";
+
+export type OperatorIds = { uid: number; gid: number };
+
+/**
+ * Resolve the operator's UID/GID for stack.env.
+ * Returns null on Windows or when neither homeDir owner nor process
+ * UID/GID is available (e.g. process.getuid undefined on some runtimes).
+ */
+export function resolveOperatorIds(homeDir: string): OperatorIds | null {
+  if (process.platform === "win32") return null;
+
+  const processUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  const processGid = typeof process.getgid === "function" ? process.getgid() : undefined;
+
+  let ownerUid: number | undefined;
+  let ownerGid: number | undefined;
+  try {
+    const st = statSync(homeDir);
+    ownerUid = st.uid;
+    ownerGid = st.gid;
+  } catch {
+    // homeDir may not exist yet during a first-time install — that's fine,
+    // we fall through to the process IDs below.
+  }
+
+  // Prefer the homeDir owner when it's a non-root user (the operator may
+  // have created OP_HOME under a different account than the one running
+  // install — e.g. an admin running `sudo openpalm install` on behalf of
+  // a service account).
+  const uid =
+    ownerUid !== undefined && ownerUid !== 0
+      ? ownerUid
+      : processUid !== undefined && processUid !== 0
+        ? processUid
+        : ownerUid; // last resort: homeDir owner even if 0, or undefined
+
+  const gid =
+    ownerGid !== undefined && ownerGid !== 0
+      ? ownerGid
+      : processGid !== undefined && processGid !== 0
+        ? processGid
+        : ownerGid;
+
+  if (uid === undefined || gid === undefined) return null;
+
+  // Final guard: never return 0 (root). This happens when BOTH the OP_HOME
+  // owner AND the process UID are root (e.g. `sudo openpalm install` on a
+  // freshly-created root-owned OP_HOME, common in CI builds and Docker-based
+  // installer flows). Returning null causes the caller to skip writing
+  // OP_UID/OP_GID to stack.env, and compose's `${OP_UID:-1000}` default
+  // kicks in — container runs as 1000:1000, which is the sane fallback
+  // when no real operator can be detected.
+  if (uid === 0 || gid === 0) return null;
+
+  return { uid, gid };
+}
+
+/**
+ * Returns true if the parsed stack.env already has a usable
+ * (non-zero, numeric) operator ID for the given key.
+ * Operator may have hand-set OP_UID/OP_GID; respect that.
+ */
+export function hasUsableOperatorId(parsed: Record<string, string>, key: "OP_UID" | "OP_GID"): boolean {
+  const raw = parsed[key];
+  if (!raw) return false;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0;
+}