@openpalm/lib 0.11.0-beta.10 → 0.11.0-beta.13

package/README.md

@@ -21,7 +21,7 @@ Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
 ## Important context
 
 - Some filenames still use legacy names like `staging`; those modules now support the direct-write compose model
-- `config/` is user-owned, `config/stack/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
+- `config/` is user-owned, `knowledge/env/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
 - New reusable control-plane logic belongs here, not duplicated in consumers
 
 ## Main module areas

package/package.json

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

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

@@ -0,0 +1,113 @@
+/**
+ * Tests for the akm user-env helpers (`env:user`).
+ *
+ * akm (>= 0.8.0) no longer manages individual env entries, so OpenPalm owns the
+ * `knowledge/env/user.env` file directly. Writes/deletes are plain atomic .env
+ * edits — no akm subprocess — so these tests run everywhere (no akm-on-PATH gate).
+ */
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ensureAkmUserEnv,
+  readUserEnvSync,
+  writeUserEnvKey,
+  deleteUserEnvKey,
+  userEnvPathSync,
+  AKM_USER_ENV_REF,
+} from "./akm-user-env.js";
+import type { ControlPlaneState } from "./types.js";
+
+function makeState(homeDir: string): ControlPlaneState {
+  return {
+    homeDir,
+    configDir: join(homeDir, "config"),
+    stashDir: join(homeDir, "knowledge"),
+    workspaceDir: join(homeDir, "workspace"),
+    dataDir: join(homeDir, "data"),
+    stackDir: join(homeDir, "config", "stack"),
+    services: {},
+    artifacts: { compose: "" },
+    artifactMeta: [],
+  };
+}
+
+describe("akm user-env helpers", () => {
+  let homeDir: string;
+  let state: ControlPlaneState;
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), "openpalm-akm-env-"));
+    state = makeState(homeDir);
+    mkdirSync(state.stashDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it("ensureAkmUserEnv creates env/user.env (mode 0600) and returns its path", () => {
+    const path = ensureAkmUserEnv(state);
+    expect(path).toBe(userEnvPathSync(state));
+    expect(path).toBe(join(state.stashDir, "env", "user.env"));
+    expect(existsSync(path)).toBe(true);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+  });
+
+  it("writeUserEnvKey upserts a key, readUserEnvSync reads it back", () => {
+    writeUserEnvKey(state, "TOKEN", "secret-9988");
+    expect(readUserEnvSync(state).TOKEN).toBe("secret-9988");
+
+    // Upsert replaces in place rather than appending a duplicate.
+    writeUserEnvKey(state, "TOKEN", "rotated");
+    const parsed = readUserEnvSync(state);
+    expect(parsed.TOKEN).toBe("rotated");
+    const lines = readFileSync(userEnvPathSync(state), "utf-8").split("\n").filter((l) => l.startsWith("TOKEN="));
+    expect(lines.length).toBe(1);
+  });
+
+  it("writeUserEnvKey single-quotes values with spaces/special chars (shell-source-safe, dotenv round-trips)", () => {
+    writeUserEnvKey(state, "TOKEN", "sk-simple123");
+    writeUserEnvKey(state, "OWNER", "Ada Lovelace");
+    writeUserEnvKey(state, "URL", "https://x.example/p?a=1&b=2");
+    writeUserEnvKey(state, "NOTE", "a#b$c");
+
+    // dotenv round-trip (what akm env run / the admin endpoint parse).
+    const parsed = readUserEnvSync(state);
+    expect(parsed.OWNER).toBe("Ada Lovelace");
+    expect(parsed.URL).toBe("https://x.example/p?a=1&b=2");
+    expect(parsed.NOTE).toBe("a#b$c");
+
+    // Raw lines: simple tokens stay bare; anything with spaces/shell-meta is
+    // POSIX single-quoted so the entrypoint's `set -a; . user.env` is safe
+    // (no word-splitting, no `&`/`$` interpretation, no injection).
+    const raw = readFileSync(userEnvPathSync(state), "utf-8");
+    expect(raw).toContain("TOKEN=sk-simple123\n");
+    expect(raw).toContain("OWNER='Ada Lovelace'\n");
+    expect(raw).toContain("URL='https://x.example/p?a=1&b=2'\n");
+  });
+
+  it("deleteUserEnvKey removes only the named key", () => {
+    writeUserEnvKey(state, "TOKEN_A", "value-a");
+    writeUserEnvKey(state, "TOKEN_B", "value-b");
+    deleteUserEnvKey(state, "TOKEN_A");
+    const parsed = readUserEnvSync(state);
+    expect(parsed.TOKEN_A).toBeUndefined();
+    expect(parsed.TOKEN_B).toBe("value-b");
+  });
+
+  it("deleteUserEnvKey is idempotent on a missing key", () => {
+    expect(() => deleteUserEnvKey(state, "NEVER_SET_KEY")).not.toThrow();
+  });
+
+  it("readUserEnvSync returns {} when no file exists yet", () => {
+    expect(readUserEnvSync(state)).toEqual({});
+  });
+});
+
+describe("AKM_USER_ENV_REF", () => {
+  it("exports the canonical akm ref string", () => {
+    expect(AKM_USER_ENV_REF).toBe("env:user");
+  });
+});

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

@@ -0,0 +1,144 @@
+/// <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/admin containers use (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`,
+  };
+}
+
+/**
+ * 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

@@ -2,12 +2,13 @@
  * Tests for canonical compose argument builder.
  */
 import { describe, it, expect, beforeEach, afterEach } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
   buildComposeOptions,
   buildComposeCliArgs,
+  writeRunScript,
 } from "./compose-args.js";
 import type { ControlPlaneState } from "./types.js";
 
@@ -18,10 +19,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 +36,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 +71,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 +123,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 +165,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 +184,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 +195,27 @@ describe("buildComposeCliArgs", () => {
       return acc;
     }, []);
     expect(fFlags).toHaveLength(2);
-    expect(fFlags[1]).toContain("chat");
+    expect(fFlags[1]).toContain("channels.compose.yml");
+  });
+});
+
+// ── writeRunScript ───────────────────────────────────────────────────────
+
+describe("writeRunScript", () => {
+  it("sources stack.env and writes resolved profile args", () => {
+    seedCoreCompose();
+    seedEnvFiles({ stack: true });
+    const state = makeState();
+
+    writeRunScript(state);
+
+    const script = readFileSync(join(tempDir, "run.sh"), "utf-8");
+    expect(script).toContain("set -a");
+    expect(script).toContain('OP_HOME="${OP_HOME:-$SCRIPT_DIR}"');
+    expect(script).toContain('source "${OP_HOME}/knowledge/env/stack.env"');
+    expect(script).toContain('profile_args=()');
+    expect(script).toContain('docker compose --project-name "${OP_PROJECT_NAME:-${COMPOSE_PROJECT_NAME:-openpalm}}"');
+    expect(script).not.toContain('--profile ${OP_VOICE_PROFILE}');
+    expect(script).not.toContain('--profile ${OP_OLLAMA_PROFILE}');
   });
 });