@openpalm/lib 0.11.0-beta.8 → 0.11.0-rc.1

package/src/control-plane/akm-user-env.ts

@@ -0,0 +1,167 @@
+/// <reference types="bun-types" />
+/**
+ * akm `env:user` helpers.
+ *
+ * The user-managed environment file lives at `${OP_HOME}/knowledge/env/user.env`
+ * and is the canonical home for user-managed configuration (LLM provider keys,
+ * owner info, and any other user-set values). It maps to the akm `env` asset
+ * type (ref `env:user`): a whole `.env` file that akm loads wholesale via
+ * `akm env run env:user` / `akm env path env:user`. The assistant entrypoint
+ * sources this file directly at startup.
+ *
+ * akm (>= 0.8.0) no longer manages individual env entries — the file owner edits
+ * it and akm loads it as a unit. OpenPalm therefore owns the file directly:
+ * writes/deletes are plain atomic .env edits (mode 0600), no akm subprocess.
+ * Values are shell-quoted on write so the entrypoint can `source` the file
+ * safely; `parseEnvFile` (dotenv) unquotes them on read.
+ *
+ * `stack.env` and `knowledge/secrets/` are operator-managed and NOT part of
+ * this file; service secrets are granted as Compose secret files.
+ *
+ * Layout:
+ *   knowledge/     — AKM_STASH_DIR: asset content (skills, env, secrets, agents)
+ *   data/akm/      — akm operational cache and data
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseEnvFile, upsertEnvValue, removeEnvKey } from "./env.js";
+import type { ControlPlaneState } from "./types.js";
+
+/**
+ * Quote a value so the written line is interpreted IDENTICALLY by a POSIX shell
+ * `source` (the assistant entrypoint does `set -a; . user.env`) and by dotenv
+ * (akm `env run` / OpenPalm's `parseEnvFile`).
+ *
+ * The shared `quoteEnvValue` (env.ts) is tuned for dotenv/compose only: it
+ * leaves values with internal spaces bare (`OWNER=Ada Lovelace`) and uses
+ * double-quote+backslash escaping — both of which a shell `source` mis-parses
+ * (word-splitting, `&`/`$` interpretation). POSIX single-quoting is the one
+ * encoding both agree on: everything inside `'...'` is literal in shell AND in
+ * dotenv. Simple token-shaped values are written bare for readability; anything
+ * else is single-quoted, with embedded single quotes closed/escaped/reopened
+ * the POSIX way (`'\''`).
+ */
+function quoteForUserEnv(value: string): string {
+  if (value === "") return "";
+  // Bare-safe: characters that need no quoting in either shell or dotenv.
+  if (/^[A-Za-z0-9_./:@%+,=-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** akm ref for the user-managed environment file. */
+export const AKM_USER_ENV_REF = "env:user";
+
+const ENV_DIR_MODE = 0o700;
+const ENV_FILE_MODE = 0o600;
+
+/**
+ * Build the env that points akm at the shared OpenPalm stash. We mirror the
+ * layout that the assistant container uses (see
+ * `.openpalm/config/stack/core.compose.yml`) so host-side and container-side
+ * runs resolve to the same files.
+ *
+ * Host-side runs use the same explicit directories as the assistant container:
+ * config in config/akm, cache in data/akm/cache, and durable data in
+ * data/akm/data. Used by automation execution (`executeAutomation`).
+ */
+export function buildAkmEnv(state: ControlPlaneState): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    AKM_STASH_DIR: state.stashDir,
+    AKM_CONFIG_DIR: `${state.configDir}/akm`,
+    AKM_CACHE_DIR: `${state.dataDir}/akm/cache`,
+    AKM_DATA_DIR: `${state.dataDir}/akm/data`,
+  };
+}
+
+/** The four XDG-base akm env vars that MUST be set together (akm 0.8.0). */
+export const AKM_ENV_KEYS = ["AKM_STASH_DIR", "AKM_CONFIG_DIR", "AKM_CACHE_DIR", "AKM_DATA_DIR"] as const;
+
+/**
+ * Guard (I-6): every OpenPalm-internal `akm` spawn MUST set all four AKM_* dirs
+ * explicitly. Partially overriding them lets akm fall back to the operator's
+ * GLOBAL ~/.config/akm / ~/.local/share/akm for the unset families — the
+ * documented forensic hazard (akm setup writing the global config regardless of
+ * AKM_STASH_DIR). We check the keys are present as OWN properties of the env
+ * object passed to akm, not merely inherited from process.env (process.env may
+ * carry the operator's global AKM_STASH_DIR, which is exactly what must NOT be
+ * relied upon). `buildAkmEnv` satisfies this by construction.
+ */
+export function assertAkmEnvComplete(env: NodeJS.ProcessEnv): void {
+  const missing = AKM_ENV_KEYS.filter((k) => !env[k] || !String(env[k]).trim());
+  if (missing.length > 0) {
+    throw new Error(
+      `Refusing to spawn akm without all four AKM_* dirs set: missing ${missing.join(", ")}. ` +
+        `Use buildAkmEnv(state) — a partial set lets akm write the operator's global config.`,
+    );
+  }
+}
+
+/**
+ * Canonical akm `env:user` file path for a control-plane state.
+ *
+ * Deterministic: akm (>= 0.8.0) materializes env files at
+ * `${AKM_STASH_DIR}/env/<name>.env`, and `state.stashDir` is the stash root.
+ * Returns the path regardless of whether the file currently exists.
+ */
+export function userEnvPathSync(state: ControlPlaneState): string {
+  return `${state.stashDir}/env/user.env`;
+}
+
+/**
+ * Ensure the user env file exists and return its absolute path.
+ *
+ * Pure filesystem — no akm subprocess. Returns immediately when the file is
+ * already provisioned (the steady state — read paths pay no extra syscalls).
+ * Otherwise creates `knowledge/env/` (0700) and an empty `user.env` (0600).
+ */
+export function ensureAkmUserEnv(state: ControlPlaneState): string {
+  const envPath = userEnvPathSync(state);
+  if (existsSync(envPath)) return envPath;
+
+  mkdirSync(dirname(envPath), { recursive: true, mode: ENV_DIR_MODE });
+  writeFileSync(envPath, "", { mode: ENV_FILE_MODE });
+  chmodSync(envPath, ENV_FILE_MODE);
+  return envPath;
+}
+
+/**
+ * Write a single key/value into the user env file (`env:user`).
+ *
+ * The value is shell-quoted before it is written so the assistant entrypoint
+ * can `source` the file without word-splitting on spaces or special
+ * characters. `ensureAkmUserEnv` guarantees the file exists; `chmodSync`
+ * keeps it 0600. Throws on filesystem errors so callers can surface the error.
+ */
+export function writeUserEnvKey(state: ControlPlaneState, key: string, value: string): void {
+  const path = ensureAkmUserEnv(state);
+  writeFileSync(path, upsertEnvValue(readFileSync(path, "utf-8"), key, quoteForUserEnv(value)));
+  chmodSync(path, ENV_FILE_MODE);
+}
+
+/**
+ * Remove a key from the user env file (`env:user`). Idempotent: removing an
+ * absent key rewrites the file unchanged. Throws on filesystem errors.
+ */
+export function deleteUserEnvKey(state: ControlPlaneState, key: string): void {
+  const path = ensureAkmUserEnv(state);
+  writeFileSync(path, removeEnvKey(readFileSync(path, "utf-8"), key));
+  chmodSync(path, ENV_FILE_MODE);
+}
+
+/**
+ * Read the user-managed env namespace. Returns `{}` when the file does not
+ * exist yet. Pure sync — no subprocess.
+ */
+export function readUserEnvSync(state: ControlPlaneState): Record<string, string> {
+  return readUserEnvFile(userEnvPathSync(state));
+}
+
+/**
+ * Return the parsed contents of a user env file (public API used by the admin
+ * UI list endpoint). `parseEnvFile` returns `{}` for a missing or unreadable
+ * file (it backs up corrupt files internally), so no extra guards are needed.
+ */
+export function readUserEnvFile(envPath: string): Record<string, string> {
+  return parseEnvFile(envPath);
+}

package/src/control-plane/backup.ts

@@ -8,20 +8,29 @@ function timestampDirName(now = new Date()): string {
 /**
  * Create a durable backup snapshot of the current OP_HOME contents.
  *
- * The backup is written under OP_HOME/backups/<timestamp>/ and excludes the
- * backups directory itself to avoid recursive copies.
+ * The backup is written under OP_HOME/data/backups/<timestamp>/ and excludes
+ * existing backups to avoid recursive copies.
  */
 export function backupOpenPalmHome(homeDir: string): string | null {
   if (!existsSync(homeDir)) return null;
 
-  const backupDir = join(homeDir, "backups", timestampDirName());
+  const backupDir = join(homeDir, "data", "backups", timestampDirName());
   mkdirSync(backupDir, { recursive: true });
 
   let copiedAny = false;
   for (const entry of readdirSync(homeDir, { withFileTypes: true })) {
-    if (entry.name === "backups") continue;
-
     const sourcePath = join(homeDir, entry.name);
+    if (entry.name === "data") {
+      const dataTarget = join(backupDir, entry.name);
+      mkdirSync(dataTarget, { recursive: true });
+      for (const dataEntry of readdirSync(sourcePath, { withFileTypes: true })) {
+        if (dataEntry.name === "backups") continue;
+        cpSync(join(sourcePath, dataEntry.name), join(dataTarget, dataEntry.name), { recursive: true });
+        copiedAny = true;
+      }
+      continue;
+    }
+
     const targetPath = join(backupDir, entry.name);
     cpSync(sourcePath, targetPath, { recursive: true });
     copiedAny = true;

package/src/control-plane/channels.ts

@@ -1,7 +1,7 @@
 /**
  * Channel validation, discovery, and allowlist checks for the OpenPalm control plane.
  */
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parse as yamlParse } from "yaml";
 import type { ChannelInfo } from "./types.js";
@@ -16,6 +16,43 @@ function isValidChannelName(name: string): boolean {
   return CHANNEL_NAME_RE.test(name);
 }
 
+function addonComposePaths(homeDir: string): string[] {
+  const paths: string[] = [];
+
+  for (const name of ['channels.compose.yml', 'services.compose.yml', 'custom.compose.yml']) {
+    const composePath = `${homeDir}/config/stack/${name}`;
+    if (existsSync(composePath)) paths.push(composePath);
+  }
+
+  return paths;
+}
+
+function channelNamesFromCompose(composePath: string): string[] {
+  try {
+    const content = readFileSync(composePath, "utf-8");
+    const doc = yamlParse(content);
+    if (typeof doc !== "object" || doc === null) return [];
+    const services = (doc as Record<string, unknown>).services;
+    if (typeof services !== "object" || services === null) return [];
+
+    const names: string[] = [];
+    for (const [svcName, svcDef] of Object.entries(services as Record<string, unknown>)) {
+      if (typeof svcDef !== "object" || svcDef === null) continue;
+      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="))) names.push(svcName);
+        } else if ("CHANNEL_NAME" in (env as Record<string, unknown>)) {
+          names.push(svcName);
+        }
+      }
+    }
+    return names;
+  } catch {
+    return [];
+  }
+}
+
 // ── Channel Discovery ─────────────────────────────────────────────────
 
 /**
@@ -51,7 +88,8 @@ export function isChannelAddon(composePath: string): boolean {
 }
 
 /**
- * Discover installed channels by scanning stack/addons/ for channel addons.
+ * Discover installed channels from explicit first-party addon state plus
+ * custom stack/addons/ overlays.
  * A channel addon is identified by compose-derived truth: its compose.yml
  * defines services with a CHANNEL_NAME environment variable.
  *
@@ -62,20 +100,8 @@ export function isChannelAddon(composePath: string): boolean {
  */
 export function discoverChannels(configDir: string): ChannelInfo[] {
   const homeDir = dirname(configDir);
-  const addonsDir = `${homeDir}/config/stack/addons`;
-  if (!existsSync(addonsDir)) return [];
-
-  const entries = readdirSync(addonsDir, { withFileTypes: true });
-  return entries
-    .filter((entry) => {
-      if (!entry.isDirectory()) return false;
-      const composePath = `${addonsDir}/${entry.name}/compose.yml`;
-      return existsSync(composePath) && isChannelAddon(composePath);
-    })
-    .map((entry) => ({
-      name: entry.name,
-      ymlPath: `${addonsDir}/${entry.name}/compose.yml`,
-    }))
+  return addonComposePaths(homeDir)
+    .flatMap((composePath) => channelNamesFromCompose(composePath).map((name) => ({ name, ymlPath: composePath })))
     .filter((ch) => isValidChannelName(ch.name));
 }
 
@@ -84,8 +110,8 @@ export function discoverChannels(configDir: string): ChannelInfo[] {
 /**
  * Check if a service name is allowed. Core services are always allowed.
  * Addon services are allowed if they appear as a compose service defined in
- * any addon compose file under stack/addons/. This is compose-derived: the
- * actual compose content is checked, not directory naming conventions.
+ * any active addon compose file. This is compose-derived: the actual compose
+ * content is checked, not directory naming conventions.
  */
 export function isAllowedService(value: string, configDir?: string): boolean {
   if (!value || !value.trim() || value !== value.toLowerCase()) return false;
@@ -93,14 +119,8 @@ export function isAllowedService(value: string, configDir?: string): boolean {
 
   if (configDir) {
     const homeDir = dirname(configDir);
-    const addonsDir = `${homeDir}/config/stack/addons`;
-    if (!existsSync(addonsDir)) return false;
-
-    // Check if any addon compose.yml defines this service name (YAML-parsed)
-    for (const entry of readdirSync(addonsDir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const composePath = `${addonsDir}/${entry.name}/compose.yml`;
-      if (!existsSync(composePath)) continue;
+    // Check if any active addon compose.yml defines this service name (YAML-parsed)
+    for (const composePath of addonComposePaths(homeDir)) {
       try {
         const content = readFileSync(composePath, "utf-8");
         const doc = yamlParse(content);
@@ -120,14 +140,13 @@ export function isAllowedService(value: string, configDir?: string): boolean {
 
 /**
  * Check if a channel name is valid and installed.
- * Accepts any channel with a compose.yml in stack/addons/<name>/.
+ * Accepts enabled first-party channels and custom channel overlays.
  */
 export function isValidChannel(value: string, configDir?: string): boolean {
   if (!value || !value.trim()) return false;
   if (!isValidChannelName(value)) return false;
   if (configDir) {
-    const homeDir = dirname(configDir);
-    return existsSync(`${homeDir}/config/stack/addons/${value}/compose.yml`);
+    return discoverChannels(configDir).some((channel) => channel.name === value);
   }
   return false;
 }

package/src/control-plane/cleanup-guardrails.test.ts

@@ -112,7 +112,7 @@ describe("guardrail: compose preflight before mutation", () => {
     // Verify composePreflight is imported
     expect(lifecycleTs).toContain("composePreflight");
     // Verify preflight appears BEFORE snapshot in the source
-    const preflightIdx = lifecycleTs.indexOf("composePreflight({ files, envFiles })");
+    const preflightIdx = lifecycleTs.indexOf("composePreflight({ files, envFiles, profiles })");
     const snapshotIdx = lifecycleTs.indexOf("snapshotCurrentState(state)");
     expect(preflightIdx).toBeGreaterThan(0);
     expect(snapshotIdx).toBeGreaterThan(0);

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

@@ -18,10 +18,9 @@ function makeState(overrides: Partial<ControlPlaneState> = {}): ControlPlaneStat
   return {
     homeDir: tempDir,
     configDir,
-    stashDir: join(tempDir, "stash"),
+    stashDir: join(tempDir, "knowledge"),
     workspaceDir: join(tempDir, "workspace"),
-    cacheDir: join(tempDir, "cache"),
-    stateDir: join(tempDir, "state"),
+    dataDir: join(tempDir, "data"),
     stackDir: join(configDir, "stack"),
     services: {},
     artifacts: { compose: "" },
@@ -36,26 +35,24 @@ function seedCoreCompose(): void {
   writeFileSync(join(stackDir, "core.compose.yml"), "services: {}");
 }
 
-function seedEnvFiles(files: { stack?: boolean; guardian?: boolean } = {}): void {
-  const stackDir = join(tempDir, "config", "stack");
+function seedEnvFiles(files: { stack?: boolean } = {}): void {
   if (files.stack) {
-    mkdirSync(stackDir, { recursive: true });
-    writeFileSync(join(stackDir, "stack.env"), "KEY=val");
-  }
-  if (files.guardian) {
-    mkdirSync(stackDir, { recursive: true });
-    writeFileSync(join(stackDir, "guardian.env"), "CHANNEL_CHAT_SECRET=abc");
+    const envDir = join(tempDir, "knowledge", "env");
+    mkdirSync(envDir, { recursive: true });
+    writeFileSync(join(envDir, "stack.env"), "KEY=val");
   }
 }
 
 function seedAddon(name: string): void {
-  const addonDir = join(tempDir, "config", "stack", "addons", name);
-  mkdirSync(addonDir, { recursive: true });
-  writeFileSync(join(addonDir, "compose.yml"), "services: {}");
+  const stackDir = join(tempDir, "config", "stack");
+  mkdirSync(stackDir, { recursive: true });
+  writeFileSync(join(stackDir, "channels.compose.yml"), `services:\n  ${name}:\n    profiles: [\"addon.${name}\"]\n    image: test\n`);
+  writeFileSync(join(stackDir, "stack.yml"), `version: 2\naddons:\n  - ${name}\n`);
 }
 
 beforeEach(() => {
   tempDir = mkdtempSync(join(tmpdir(), "compose-args-test-"));
+  process.env.OP_HOME = tempDir;
 });
 
 afterEach(() => {
@@ -73,27 +70,37 @@ describe("buildComposeOptions", () => {
     expect(opts.files[0]).toContain("core.compose.yml");
   });
 
-  it("includes addon overlays when compose files are present in stack/addons", () => {
+  it("includes fixed channel compose and profile from stack.yml", () => {
     seedCoreCompose();
     seedAddon("chat");
 
     const state = makeState();
     const opts = buildComposeOptions(state);
     expect(opts.files).toHaveLength(2);
-    expect(opts.files[1]).toContain("chat");
+    expect(opts.files[1]).toContain("channels.compose.yml");
+    expect(opts.profiles).toContain("addon.chat");
+  });
+
+  it("includes the user custom compose file", () => {
+    seedCoreCompose();
+    const stackDir = join(tempDir, "config", "stack");
+    writeFileSync(join(stackDir, "custom.compose.yml"), "services: {}");
+
+    const state = makeState();
+    const opts = buildComposeOptions(state);
+    expect(opts.files).toHaveLength(2);
+    expect(opts.files[1]).toContain("custom.compose.yml");
   });
 
   it("returns env files in correct order", () => {
-    // Note: vault/user/user.env is no longer a
-    // compose env_file. The runtime env file list is: stack.env, guardian.env.
-    // Even when a legacy user.env is present on disk, it is intentionally
-    // excluded from the compose args.
-    seedEnvFiles({ stack: true, guardian: true });
+    // The runtime --env-file list is knowledge/env/stack.env only. The user env
+    // (knowledge/env/user.env) is sourced by the assistant entrypoint, not a
+    // compose env_file.
+    seedEnvFiles({ stack: true });
     const state = makeState();
     const opts = buildComposeOptions(state);
-    expect(opts.envFiles).toHaveLength(2);
+    expect(opts.envFiles).toHaveLength(1);
     expect(opts.envFiles[0]).toContain("stack.env");
-    expect(opts.envFiles[1]).toContain("guardian.env");
   });
 
   it("excludes missing env files", () => {
@@ -115,6 +122,38 @@ describe("buildComposeCliArgs", () => {
     expect(args[1]).toBe("openpalm");
   });
 
+  it("uses OP_PROJECT_NAME from stack.env", () => {
+    seedCoreCompose();
+    seedEnvFiles({ stack: true });
+    writeFileSync(join(tempDir, "knowledge", "env", "stack.env"), "OP_PROJECT_NAME=openpalm-test\n");
+    const state = makeState();
+    const args = buildComposeCliArgs(state);
+    expect(args[0]).toBe("--project-name");
+    expect(args[1]).toBe("openpalm-test");
+  });
+
+  it("uses canonical voice and ollama profile ids", () => {
+    seedCoreCompose();
+    seedEnvFiles({ stack: true });
+    writeFileSync(join(tempDir, "knowledge", "env", "stack.env"), "OP_VOICE_PROFILE=addon.voice.cuda\nOP_OLLAMA_PROFILE=addon.ollama.cpu\n");
+    const state = makeState();
+    const args = buildComposeCliArgs(state);
+    expect(args).toContain("addon.voice.cuda");
+    expect(args).toContain("addon.ollama.cpu");
+  });
+
+  it("ignores non-canonical addon profile ids", () => {
+    seedCoreCompose();
+    seedEnvFiles({ stack: true });
+    writeFileSync(join(tempDir, "knowledge", "env", "stack.env"), "OP_VOICE_PROFILE=not-canonical\nOP_OLLAMA_PROFILE=also-not-canonical\n");
+    const state = makeState();
+    const args = buildComposeCliArgs(state);
+    expect(args).not.toContain("not-canonical");
+    expect(args).not.toContain("also-not-canonical");
+    expect(args).not.toContain("addon.voice.cuda");
+    expect(args).not.toContain("addon.ollama.cpu");
+  });
+
   it("includes -f flags for compose files", () => {
     seedCoreCompose();
     const state = makeState();
@@ -125,18 +164,16 @@ describe("buildComposeCliArgs", () => {
   });
 
   it("includes --env-file flags for env files that exist", () => {
-    // Note: vault/user/user.env is no longer
-    // listed in the compose env_file set. Only stack.env and guardian.env
-    // (when present) are passed via --env-file.
+    // Only knowledge/env/stack.env is passed via --env-file.
     seedCoreCompose();
-    seedEnvFiles({ stack: true, guardian: true });
+    seedEnvFiles({ stack: true });
     const state = makeState();
     const args = buildComposeCliArgs(state);
     const envFileIndices = args.reduce<number[]>((acc, arg, i) => {
       if (arg === "--env-file") acc.push(i);
       return acc;
     }, []);
-    expect(envFileIndices).toHaveLength(2);
+    expect(envFileIndices).toHaveLength(1);
   });
 
   it("does not include --env-file for missing files", () => {
@@ -146,7 +183,7 @@ describe("buildComposeCliArgs", () => {
     expect(args).not.toContain("--env-file");
   });
 
-  it("includes addon overlays in -f flags", () => {
+  it("includes fixed channel compose in -f flags", () => {
     seedCoreCompose();
     seedAddon("chat");
 
@@ -157,6 +194,6 @@ describe("buildComposeCliArgs", () => {
       return acc;
     }, []);
     expect(fFlags).toHaveLength(2);
-    expect(fFlags[1]).toContain("chat");
+    expect(fFlags[1]).toContain("channels.compose.yml");
   });
 });

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

@@ -10,44 +10,99 @@ import type { ControlPlaneState } from "./types.js";
 import { buildComposeFileList } from "./lifecycle.js";
 import { buildEnvFiles } from "./config-persistence.js";
 import { resolveComposeProjectName } from "./docker.js";
+import { parseEnvFile } from "./env.js";
+import { canonicalAddonProfileSelection } from "./profile-ids.js";
+import { listStackSpecAddons } from "./stack-spec.js";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
 export type ComposeOptions = {
   files: string[];
   envFiles: string[];
+  profiles: string[];
 };
 
+// ── Profile Resolution ───────────────────────────────────────────────────
+
+/**
+ * Resolve active Docker Compose profiles from the stack env.
+ * Reads OP_VOICE_PROFILE and OP_OLLAMA_PROFILE (addon hardware profiles).
+ * Returns deduplicated, non-empty profile strings.
+ */
+export function resolveActiveProfiles(state: ControlPlaneState): string[] {
+  const profiles: string[] = [];
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
+  let env: Record<string, string> = {};
+  if (existsSync(stackEnvPath)) {
+    env = parseEnvFile(stackEnvPath);
+    for (const profile of (env.COMPOSE_PROFILES ?? '').split(',')) {
+      const trimmed = profile.trim();
+      if (trimmed) profiles.push(trimmed);
+    }
+    const voiceProfile = canonicalAddonProfileSelection('voice', env.OP_VOICE_PROFILE ?? '');
+    if (voiceProfile) profiles.push(voiceProfile);
+    const ollamaProfile = canonicalAddonProfileSelection('ollama', env.OP_OLLAMA_PROFILE ?? '');
+    if (ollamaProfile) profiles.push(ollamaProfile);
+  }
+
+  for (const addon of listStackSpecAddons(state.stackDir)) {
+    if (addon === 'voice') {
+      profiles.push(canonicalAddonProfileSelection('voice', env.OP_VOICE_PROFILE ?? '') || 'addon.voice.cpu');
+    } else if (addon === 'ollama') {
+      profiles.push(canonicalAddonProfileSelection('ollama', env.OP_OLLAMA_PROFILE ?? '') || 'addon.ollama.cpu');
+    } else {
+      profiles.push(`addon.${addon}`);
+    }
+  }
+
+  return [...new Set(profiles)];
+}
+
 // ── Builders ─────────────────────────────────────────────────────────────
 
 /**
- * Build the compose file and env file lists for a given state.
- * Returns the resolved files and env files for use with docker.ts functions.
- *
- * Note: env files are already filtered to only existing paths by
- * `buildEnvFiles()` in config-persistence.ts.
+ * Build the compose file, env file, and profile lists for a given state.
+ * Returns the resolved values for use with docker.ts functions.
  */
 export function buildComposeOptions(state: ControlPlaneState): ComposeOptions {
   return {
     files: buildComposeFileList(state),
     envFiles: buildEnvFiles(state),
+    profiles: resolveActiveProfiles(state),
   };
 }
 
 /**
  * Build the full docker compose CLI argument array for a given state.
  *
- * Returns: ['--project-name', 'openpalm', '-f', file1, '-f', file2, '--env-file', env1, ...]
+ * Returns: ['--project-name', 'openpalm', '-f', file1, '-f', file2, '--env-file', env1, '--profile', addon.voice.cpu, ...]
  *
  * Only includes env files that exist on disk.
  */
 export function buildComposeCliArgs(state: ControlPlaneState): string[] {
-  const { files, envFiles } = buildComposeOptions(state);
+  const { files, envFiles, profiles } = buildComposeOptions(state);
 
   return [
     "--project-name",
-    resolveComposeProjectName(),
+    resolveComposeProjectName(collectEnvOverrides(envFiles)),
     ...files.flatMap((f) => ["-f", f]),
     ...envFiles.filter((f) => existsSync(f)).flatMap((f) => ["--env-file", f]),
+    ...profiles.flatMap((p) => ["--profile", p]),
   ];
 }
+
+// ── Run Script ───────────────────────────────────────────────────────────
+
+/**
+ * Convert an absolute path to a ${OP_HOME}-relative shell expression.
+ * E.g. "/home/user/.openpalm/config/stack/core.compose.yml"
+ *   → "${OP_HOME}/config/stack/core.compose.yml"
+ */
+function collectEnvOverrides(envFiles: string[]): Record<string, string> {
+  const overrides: Record<string, string> = {};
+  for (const envFile of envFiles) {
+    Object.assign(overrides, parseEnvFile(envFile));
+  }
+  return overrides;
+}
+