@openpalm/lib 0.10.2 → 0.11.0-beta.2

package/README.md

@@ -19,7 +19,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, `vault/stack/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
+- `config/` is user-owned, `config/stack/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
@@ -30,7 +30,7 @@ Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
 | `control-plane/env` and `control-plane/secrets` | Read, merge, and patch env files |
 | `control-plane/lifecycle` and `control-plane/docker` | Compose operations and stack lifecycle helpers |
 | `control-plane/channels` and `control-plane/components` | Addon discovery and install/uninstall logic |
-| `control-plane/memory-config` | Memory service configuration helpers |
+| `control-plane/provider-models` | Provider model discovery helpers |
 | `control-plane/scheduler` | Automation parsing and scheduler helpers |
 | `logger` | Shared structured logger |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.10.2",
+  "version": "0.11.0-beta.2",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",
@@ -23,8 +23,12 @@
     "directory": "packages/lib"
   },
   "dependencies": {
-    "croner": "^9.0.0",
-    "dotenv": "^16.4.7",
+    "dotenv": "^17.4.2",
+    "tar": "^7.5.15",
     "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/tar": "^7.0.87",
+    "bun-types": "^1.3.14"
   }
 }

package/src/control-plane/admin-token.ts

@@ -0,0 +1,73 @@
+/**
+ * Admin token file management.
+ *
+ * Token lives at {homeDir}/state/admin/token, mode 0600.
+ * - ensureAdminToken: idempotent — skips write if file already exists and is non-empty.
+ * - rotateAdminToken: overwrites unconditionally. Only called by `openpalm admin rotate-token`.
+ *
+ * Windows note: chmodSync(path, 0o600) is a no-op on Windows.
+ * NFS/CIFS warning: mode bits are ignored on network shares. ensureAdminToken warns via console.
+ */
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+function getAdminStateDir(homeDir: string): string {
+  return join(homeDir, "state", "admin");
+}
+
+function generateToken(): string {
+  return randomBytes(32).toString("hex");
+}
+
+/**
+ * Ensure an admin token file exists at {homeDir}/state/admin/token.
+ * Idempotent: if the file already exists and is non-empty, returns the existing token.
+ * Creates the directory if necessary. Sets mode 0600 (no-op on Windows).
+ *
+ * @param homeDir  The OP_HOME directory (e.g. ~/.openpalm)
+ * @returns        The admin token (new or existing)
+ */
+export function ensureAdminToken(homeDir: string): string {
+  const dir = getAdminStateDir(homeDir);
+  mkdirSync(dir, { recursive: true });
+
+  const tokenPath = join(dir, "token");
+
+  if (existsSync(tokenPath)) {
+    const existing = readFileSync(tokenPath, "utf8").trim();
+    if (existing.length > 0) return existing;
+  }
+
+  const token = generateToken();
+  writeFileSync(tokenPath, token, { encoding: "utf8", mode: 0o600 });
+  try {
+    // Some platforms require a separate chmod call to enforce the mode.
+    chmodSync(tokenPath, 0o600);
+  } catch {
+    // Windows — ignore silently
+  }
+  return token;
+}
+
+/**
+ * Rotate the admin token. Overwrites the token file unconditionally.
+ * Only call this from `openpalm admin rotate-token`.
+ *
+ * @param homeDir  The OP_HOME directory
+ * @returns        The new admin token
+ */
+export function rotateAdminToken(homeDir: string): string {
+  const dir = getAdminStateDir(homeDir);
+  mkdirSync(dir, { recursive: true });
+
+  const tokenPath = join(dir, "token");
+  const token = generateToken();
+  writeFileSync(tokenPath, token, { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(tokenPath, 0o600);
+  } catch {
+    // Windows — ignore silently
+  }
+  return token;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Tests for the akm vault helpers. The vault helpers spawn `akm vault set
+ * <ref> <key>` and feed the secret VALUE on stdin (akm-cli >= 0.8.0).
+ *
+ * Tests gate on the akm CLI being on PATH so the suite stays green in
+ * environments without akm installed.
+ */
+import { describe, expect, it, beforeEach, afterEach, mock } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  ensureAkmUserVault,
+  readAkmUserVaultFile,
+  writeAkmVaultKey,
+  deleteAkmVaultKey,
+  AKM_USER_VAULT_REF,
+} from "./akm-vault.js";
+import type { ControlPlaneState } from "./types.js";
+
+function makeState(homeDir: string): ControlPlaneState {
+  return {
+    homeDir,
+    configDir: join(homeDir, "config"),
+    stashDir: join(homeDir, "stash"),
+    workspaceDir: join(homeDir, "workspace"),
+    cacheDir: join(homeDir, "cache"),
+    stateDir: join(homeDir, "state"),
+    stackDir: join(homeDir, "stack"),
+    services: {},
+    artifacts: { compose: "" },
+    artifactMeta: [],
+  };
+}
+
+function hasAkmCli(): boolean {
+  try {
+    execFileSync("akm", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const AKM_AVAILABLE = hasAkmCli();
+
+
+describe("writeAkmVaultKey", () => {
+  let homeDir: string;
+  let state: ControlPlaneState;
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), "openpalm-akm-write-"));
+    state = makeState(homeDir);
+    mkdirSync(state.stashDir, { recursive: true });
+    mkdirSync(`${state.stateDir}/cache/akm`, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it.skipIf(!AKM_AVAILABLE)("writes a key via `akm vault set` (stdin mode, no argv leak)", async () => {
+    const value = "argv-free-secret-9988";
+    const ok = await writeAkmVaultKey(state, "TOKEN", value);
+    expect(ok).toBe(true);
+
+    const vaultPath = await ensureAkmUserVault(state);
+    expect(vaultPath).not.toBeNull();
+    if (vaultPath) {
+      const stored = readAkmUserVaultFile(vaultPath);
+      expect(stored.TOKEN).toBe(value);
+    }
+  });
+
+  it.skipIf(!AKM_AVAILABLE)("deleteAkmVaultKey removes a key via `akm vault unset`", async () => {
+    await writeAkmVaultKey(state, "TOKEN_A", "value-a");
+    await writeAkmVaultKey(state, "TOKEN_B", "value-b");
+
+    const ok = await deleteAkmVaultKey(state, "TOKEN_A");
+    expect(ok).toBe(true);
+
+    const vaultPath = await ensureAkmUserVault(state);
+    if (vaultPath) {
+      const stored = readAkmUserVaultFile(vaultPath);
+      expect(stored.TOKEN_A).toBeUndefined();
+      expect(stored.TOKEN_B).toBe("value-b");
+    }
+  });
+
+  it.skipIf(!AKM_AVAILABLE)("deleteAkmVaultKey is idempotent on a missing key", async () => {
+    // Deleting a key that was never set should not throw — `akm vault unset`
+    // either exits 0 or emits a "not found" message we tolerate.
+    const ok = await deleteAkmVaultKey(state, "NEVER_SET_KEY");
+    expect(ok).toBe(true);
+  });
+});
+
+
+describe("AKM_USER_VAULT_REF", () => {
+  it("exports the canonical akm ref string", () => {
+    expect(AKM_USER_VAULT_REF).toBe("vault:user");
+  });
+});

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

@@ -0,0 +1,307 @@
+/// <reference types="bun-types" />
+/**
+ * akm `vault:user` helpers.
+ *
+ * The akm-cli vault store at `${OP_HOME}/stash/vaults/user.env` is the
+ * canonical home for user-managed environment secrets. The assistant
+ * entrypoint sources this file directly at startup.
+ *
+ * `stack.env` and `guardian.env` are operator-managed and NOT mirrored
+ * into akm — mirroring them would break guardian's HMAC env_file
+ * hot-reload contract.
+ *
+ * SECURITY: every write into the akm vault is performed by spawning
+ * `akm vault set <ref> <key>` with the secret VALUE delivered via stdin
+ * (akm-cli >= 0.8.0). Values never appear in argv, so they cannot leak
+ * through `/proc/<pid>/cmdline`. The matching delete path uses
+ * `akm vault unset <ref> <key>` which is naturally argv-safe.
+ *
+ * Layout:
+ *   stash/         — AKM_STASH_DIR: asset content (skills, vaults, knowledge, agents)
+ *   state/akm/     — AKM_DATA_DIR / AKM_STATE_DIR / AKM_CONFIG_DIR: operational metadata
+ *   cache/akm/     — AKM_CACHE_DIR: regenerable registry artifacts
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { parseEnvFile } from "./env.js";
+import { createLogger } from "../logger.js";
+import type { ControlPlaneState } from "./types.js";
+
+const execFile = promisify(execFileCb);
+const logger = createLogger("akm-vault");
+
+export const AKM_USER_VAULT_REF = "vault:user";
+
+/**
+ * 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 vault file.
+ *
+ * AKM_CONFIG_DIR lives in config/ (alongside stack.env, auth.json) so
+ * operators can inspect and version-control akm setup alongside other config.
+ * AKM_CACHE_DIR lives in cache/ since registry index and downloaded artifacts
+ * are regenerable and should not be indexed alongside stash assets.
+ */
+export function buildAkmEnv(state: ControlPlaneState): NodeJS.ProcessEnv {
+  const akmOperational = `${state.stateDir}/akm`;
+  return {
+    ...process.env,
+    AKM_STASH_DIR: state.stashDir,
+    AKM_CONFIG_DIR: `${state.configDir}/akm`,
+    AKM_DATA_DIR: `${akmOperational}/data`,
+    AKM_STATE_DIR: `${akmOperational}/state`,
+    AKM_CACHE_DIR: `${state.cacheDir}/akm`,
+  };
+}
+
+/**
+ * Per-invocation timeout (ms) for every akm subprocess we launch. The CLI is
+ * a local binary and these probes (`--version`, `vault create`, `vault path`,
+ * `vault set/unset`) complete in well under a second on a healthy host;
+ * anything longer means akm is wedged or unreachable. Bounding the call
+ * keeps `mirrorUserVaultToAkm` truly best-effort: a stuck akm binary cannot
+ * block install/upgrade.
+ *
+ * Why a wall-clock race instead of execFile's built-in `timeout` option:
+ * node's `child_process.execFile` in Bun is implemented on top of `Bun.spawn`,
+ * and its `timeout` option only fires once stdout/stderr are wired up. Test
+ * suites that stub `Bun.spawn` (e.g. `packages/cli/src/main.test.ts`
+ * `mockDockerCli`) return a fake child whose stdout never closes, so neither
+ * the underlying promise nor the timeout option ever resolves. A simple
+ * `Promise.race` against an unref'd setTimeout converts that failure mode
+ * into a fast rejection that `akmAvailable` swallows as "akm not on PATH",
+ * without changing behaviour on real hosts.
+ */
+const AKM_EXEC_TIMEOUT_MS = 2_000;
+
+/**
+ * Race a promise against an unref'd setTimeout. If the timeout fires first,
+ * reject with `<label> timed out after <ms>ms`. The timer is always cleared
+ * in `finally` so it never keeps the event loop alive past resolution. The
+ * unref means the timer alone won't block process exit — the surrounding
+ * subprocess work owns the liveness.
+ */
+function raceWithTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    timer.unref?.();
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+
+async function execAkm(args: string[], env: NodeJS.ProcessEnv): Promise<{ stdout: string; stderr: string }> {
+  return raceWithTimeout(
+    execFile("akm", args, { env }),
+    AKM_EXEC_TIMEOUT_MS,
+    `akm ${args[0] ?? "?"}`,
+  );
+}
+
+async function akmAvailable(env: NodeJS.ProcessEnv): Promise<boolean> {
+  try {
+    await execAkm(["--version"], env);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the absolute path of the akm vault file, creating the vault if
+ * missing. Callers that have already built the akm env (via `buildAkmEnv`)
+ * can pass it in to avoid rebuilding — the result is identical either way.
+ */
+export async function ensureAkmUserVault(
+  state: ControlPlaneState,
+  env: NodeJS.ProcessEnv = buildAkmEnv(state),
+): Promise<string | null> {
+  if (!(await akmAvailable(env))) {
+    return null;
+  }
+  try {
+    // `vault create` accepts only the ref on argv — no secret material crosses
+    // the process boundary here.
+    await execAkm(["vault", "create", AKM_USER_VAULT_REF], env);
+  } catch (err) {
+    // `create` is documented as a no-op when the vault already exists, but
+    // some build channels emit a non-zero exit. Probe `path` to distinguish
+    // a real failure from "already exists".
+    logger.debug("akm vault create returned non-zero", {
+      ref: AKM_USER_VAULT_REF,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+  try {
+    const { stdout } = await execAkm(["vault", "path", AKM_USER_VAULT_REF], env);
+    const path = stdout.trim();
+    return path.length > 0 ? path : null;
+  } catch (err) {
+    logger.warn("akm vault path failed", {
+      ref: AKM_USER_VAULT_REF,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}
+
+/**
+ * Spawn `akm vault set <ref> <key>` and feed the secret VALUE via stdin.
+ * The value never crosses argv, so it cannot leak through
+ * `/proc/<pid>/cmdline`. Bounded by AKM_EXEC_TIMEOUT_MS — a stuck akm
+ * binary cannot block the calling install/upgrade flow.
+ */
+async function akmVaultSetViaStdin(
+  ref: string,
+  key: string,
+  value: string,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  // We use Bun.spawn directly because it supports an in-memory stdin pipe
+  // (a buffer/string stream) without dragging in an extra dependency, and
+  // because akm-cli on >= 0.8.0 reads the value from stdin when no
+  // positional `<value>` is provided. (The CLI silently switched stdin to
+  // the default in commit c50f9f4; explicit `--stdin` is still accepted
+  // for older binaries — but since we pin akm-cli >= 0.8.0-rc2 across all
+  // images via Dockerfile ARGs, the implicit form is enough.)
+  const child = Bun.spawn(["akm", "vault", "set", ref, key], {
+    env,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // Feed the secret. `child.stdin` is a FileSink in Bun — write+end then
+  // wait for exit. We don't use `await child.stdin.end(value)` because
+  // some Bun versions return undefined here; explicit write+end is portable.
+  if (child.stdin) {
+    // child.stdin is typed as FileSink in Bun
+    const sink = child.stdin as { write: (data: string) => unknown; end: () => unknown };
+    sink.write(value);
+    sink.end();
+  }
+
+  // Wall-clock bound — mirror of the execAkm pattern. On timeout we also
+  // SIGKILL the child so the orphaned subprocess doesn't outlive us.
+  let exitCode: number;
+  try {
+    exitCode = await raceWithTimeout(
+      child.exited,
+      AKM_EXEC_TIMEOUT_MS,
+      `akm vault set ${key}`,
+    );
+  } catch (err) {
+    try { child.kill(); } catch { /* best-effort */ }
+    throw err;
+  }
+
+  if (exitCode !== 0) {
+    const stderrText = child.stderr ? await new Response(child.stderr).text() : "";
+    throw new Error(`akm vault set ${key} failed (exit ${exitCode}): ${stderrText.trim()}`);
+  }
+}
+
+/**
+ * Write a single key/value into the akm `vault:user` store via
+ * `akm vault set <ref> <key>` with the value delivered on stdin.
+ *
+ * Returns `true` on success, `false` when akm is unavailable or the vault
+ * could not be ensured. Throws on akm subprocess failures (non-zero exit
+ * with a captured stderr, or wall-clock timeout) so callers can surface
+ * the real error instead of silently dropping the write.
+ */
+export async function writeAkmVaultKey(
+  state: ControlPlaneState,
+  key: string,
+  value: string,
+): Promise<boolean> {
+  // Build env once and thread it through both the ensure step and the
+  // subsequent `akm vault set`. Avoids a redundant `buildAkmEnv` call.
+  const env = buildAkmEnv(state);
+  const vaultPath = await ensureAkmUserVault(state, env);
+  if (!vaultPath) return false;
+  await akmVaultSetViaStdin(AKM_USER_VAULT_REF, key, value, env);
+  return true;
+}
+
+/**
+ * Remove a key from the akm `vault:user` store via `akm vault unset`.
+ * The key name is a normal identifier and crosses argv only — secret
+ * values are never involved. Returns `true` if the operation completed
+ * (whether or not the key was present), `false` when akm is unavailable.
+ */
+export async function deleteAkmVaultKey(
+  state: ControlPlaneState,
+  key: string,
+): Promise<boolean> {
+  // Build env once and pass it into ensureAkmUserVault so we don't pay
+  // for two `buildAkmEnv` calls on a single delete.
+  const env = buildAkmEnv(state);
+  const vaultPath = await ensureAkmUserVault(state, env);
+  if (!vaultPath) return false;
+  try {
+    await execAkm(["vault", "unset", 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.
+    const message = err instanceof Error ? err.message : String(err);
+    // Heuristic: tolerate "not found" / "no such" messages so re-running
+    // delete on an already-deleted key stays idempotent for callers.
+    if (/not\s*found|no\s+such|does\s+not\s+exist/i.test(message)) {
+      logger.debug("akm vault unset reported missing key", { key, message });
+      return true;
+    }
+    throw err;
+  }
+  return true;
+}
+
+/**
+ * Synchronously resolve the canonical akm `vault:user` file path for a given
+ * control-plane state. Used by sync read paths (e.g. plaintext secret backend
+ * `list`/`exists`) that cannot await `ensureAkmUserVault`.
+ *
+ * The path is deterministic: `buildAkmEnv` pins `AKM_STASH_DIR` to
+ * `state.stashDir`, and akm-cli (>= 0.8.0) materializes vault files
+ * at `${AKM_STASH_DIR}/vaults/<ref>.env`.
+ *
+ * Returns the path string regardless of whether the file currently exists —
+ * callers should `existsSync` if presence matters.
+ */
+export function akmUserVaultPathSync(state: ControlPlaneState): string {
+  return `${state.stashDir}/vaults/user.env`;
+}
+
+/**
+ * Read the user-managed env namespace from the akm `vault:user` store.
+ *
+ * Returns `{}` when the vault file does not exist yet. Pure sync — no subprocess spawn.
+ */
+export function readUserVaultSync(state: ControlPlaneState): Record<string, string> {
+  const akmPath = akmUserVaultPathSync(state);
+  if (existsSync(akmPath)) {
+    return readAkmUserVaultFile(akmPath);
+  }
+  return {};
+}
+
+/** Return the parsed contents of the akm vault file (public API used by admin UI list endpoint). */
+export function readAkmUserVaultFile(vaultPath: string): Record<string, string> {
+  if (!existsSync(vaultPath)) return {};
+  try {
+    return parseEnvFile(vaultPath);
+  } catch {
+    // Fallback: hand-parse if dotenv chokes (e.g. file with stray BOM).
+    const raw = readFileSync(vaultPath, "utf-8");
+    const out: Record<string, string> = {};
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (m) out[m[1]] = m[2];
+    }
+    return out;
+  }
+}

package/src/control-plane/channels.ts

@@ -60,7 +60,7 @@ export function isChannelAddon(composePath: string): boolean {
  */
 export function discoverChannels(configDir: string): ChannelInfo[] {
   const homeDir = dirname(configDir);
-  const addonsDir = `${homeDir}/stack/addons`;
+  const addonsDir = `${homeDir}/config/stack/addons`;
   if (!existsSync(addonsDir)) return [];
 
   const entries = readdirSync(addonsDir, { withFileTypes: true });
@@ -91,7 +91,7 @@ export function isAllowedService(value: string, configDir?: string): boolean {
 
   if (configDir) {
     const homeDir = dirname(configDir);
-    const addonsDir = `${homeDir}/stack/addons`;
+    const addonsDir = `${homeDir}/config/stack/addons`;
     if (!existsSync(addonsDir)) return false;
 
     // Check if any addon compose.yml defines this service name (YAML-parsed)
@@ -125,7 +125,7 @@ export function isValidChannel(value: string, configDir?: string): boolean {
   if (!isValidChannelName(value)) return false;
   if (configDir) {
     const homeDir = dirname(configDir);
-    return existsSync(`${homeDir}/stack/addons/${value}/compose.yml`);
+    return existsSync(`${homeDir}/config/stack/addons/${value}/compose.yml`);
   }
   return false;
 }

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

@@ -149,17 +149,16 @@ describe("guardrail: compose-derived service discovery", () => {
   });
 });
 
-// ── Guardrail 5: Env schema paths are correct ──────────────────────────
+// ── Guardrail 5: No varlock or .env.schema references in validate.ts ───
 
-describe("guardrail: env schema validation paths", () => {
-  test("validate.ts uses correct nested vault schema paths", () => {
+describe("guardrail: validate.ts is varlock-free", () => {
+  test("validate.ts does not import child_process or read .env.schema", () => {
     const validateTs = readFileSync(join(LIB_CONTROL_PLANE_DIR, "validate.ts"), "utf-8");
-    // Must use nested paths
-    expect(validateTs).toContain("vaultDir}/user/user.env.schema");
-    expect(validateTs).toContain("vaultDir}/stack/stack.env.schema");
-    // Must NOT use flat paths
-    expect(validateTs).not.toContain("vaultDir}/user.env.schema");
-    expect(validateTs).not.toContain("vaultDir}/system.env.schema");
+    // Post-#391: validation is key-presence only — no schema files, no binary.
+    expect(validateTs).not.toContain("node:child_process");
+    expect(validateTs).not.toContain("execFile");
+    expect(validateTs).not.toContain("VARLOCK_BIN");
+    expect(validateTs).not.toContain(".env.schema");
   });
 });
 

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

@@ -15,47 +15,42 @@ import type { ControlPlaneState } from "./types.js";
 let tempDir: string;
 
 function makeState(overrides: Partial<ControlPlaneState> = {}): ControlPlaneState {
+  const configDir = join(tempDir, "config");
   return {
-    adminToken: "test",
-    assistantToken: "test",
-    setupToken: "test",
     homeDir: tempDir,
-    configDir: join(tempDir, "config"),
-    vaultDir: join(tempDir, "vault"),
-    dataDir: join(tempDir, "data"),
-    logsDir: join(tempDir, "logs"),
+    configDir,
+    stashDir: join(tempDir, "stash"),
+    workspaceDir: join(tempDir, "workspace"),
     cacheDir: join(tempDir, "cache"),
+    stateDir: join(tempDir, "state"),
+    stackDir: join(configDir, "stack"),
     services: {},
     artifacts: { compose: "" },
     artifactMeta: [],
-    audit: [],
     ...overrides,
   };
 }
 
 function seedCoreCompose(): void {
-  const stackDir = join(tempDir, "stack");
+  const stackDir = join(tempDir, "config", "stack");
   mkdirSync(stackDir, { recursive: true });
   writeFileSync(join(stackDir, "core.compose.yml"), "services: {}");
 }
 
-function seedEnvFiles(files: { stack?: boolean; user?: boolean; guardian?: boolean } = {}): void {
+function seedEnvFiles(files: { stack?: boolean; guardian?: boolean } = {}): void {
+  const stackDir = join(tempDir, "config", "stack");
   if (files.stack) {
-    mkdirSync(join(tempDir, "vault", "stack"), { recursive: true });
-    writeFileSync(join(tempDir, "vault", "stack", "stack.env"), "KEY=val");
-  }
-  if (files.user) {
-    mkdirSync(join(tempDir, "vault", "user"), { recursive: true });
-    writeFileSync(join(tempDir, "vault", "user", "user.env"), "SECRET=val");
+    mkdirSync(stackDir, { recursive: true });
+    writeFileSync(join(stackDir, "stack.env"), "KEY=val");
   }
   if (files.guardian) {
-    mkdirSync(join(tempDir, "vault", "stack"), { recursive: true });
-    writeFileSync(join(tempDir, "vault", "stack", "guardian.env"), "CHANNEL_CHAT_SECRET=abc");
+    mkdirSync(stackDir, { recursive: true });
+    writeFileSync(join(stackDir, "guardian.env"), "CHANNEL_CHAT_SECRET=abc");
   }
 }
 
 function seedAddon(name: string): void {
-  const addonDir = join(tempDir, "stack", "addons", name);
+  const addonDir = join(tempDir, "config", "stack", "addons", name);
   mkdirSync(addonDir, { recursive: true });
   writeFileSync(join(addonDir, "compose.yml"), "services: {}");
 }
@@ -98,13 +93,16 @@ describe("buildComposeOptions", () => {
   });
 
   it("returns env files in correct order", () => {
-    seedEnvFiles({ stack: true, user: true, guardian: true });
+    // 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 });
     const state = makeState();
     const opts = buildComposeOptions(state);
-    expect(opts.envFiles).toHaveLength(3);
+    expect(opts.envFiles).toHaveLength(2);
     expect(opts.envFiles[0]).toContain("stack.env");
-    expect(opts.envFiles[1]).toContain("user.env");
-    expect(opts.envFiles[2]).toContain("guardian.env");
+    expect(opts.envFiles[1]).toContain("guardian.env");
   });
 
   it("excludes missing env files", () => {
@@ -136,8 +134,11 @@ 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.
     seedCoreCompose();
-    seedEnvFiles({ stack: true, user: true });
+    seedEnvFiles({ stack: true, guardian: true });
     const state = makeState();
     const args = buildComposeCliArgs(state);
     const envFileIndices = args.reduce<number[]>((acc, arg, i) => {