@openpalm/lib 0.11.0-beta.9 → 0.11.0-rc.18

package/src/control-plane/migrations.ts

@@ -0,0 +1,423 @@
+/**
+ * On-disk layout migration harness.
+ *
+ * `stack.env` carries `OP_LAYOUT_VERSION` — the authoritative marker of the
+ * home-directory layout schema. `ensureMigrated()` runs BEFORE any state
+ * validation (createState/resolveRuntimeFiles assume the current layout), so it
+ * must resolve its own paths rather than take a built ControlPlaneState.
+ *
+ * Contract (the fail-safe invariant):
+ *   - Fast path: if the layout is already current, return immediately — no lock,
+ *     no backup, zero overhead on routine updates.
+ *   - Otherwise: acquire the install lock, take a FULL-HOME backup first, and
+ *     abort the whole upgrade if the backup fails (never migrate without a
+ *     verified safety copy).
+ *   - Migrations are COPY-ONLY / additive (never delete the old layout), so a
+ *     mid-run failure leaves the home fully recoverable.
+ *   - The OP_LAYOUT_VERSION bump is the LAST step (the commit point); a crash
+ *     before it just re-runs next time (idempotent).
+ *   - On failure, throw MigrationError carrying the backup path + recovery
+ *     guidance for the CLI/UI to surface.
+ */
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync,
+  readdirSync, statSync, chmodSync, cpSync,
+} from "node:fs";
+import { join } from "node:path";
+import { parse as yamlParse } from "yaml";
+import {
+  resolveOpenPalmHome, resolveDataDir, resolveStackDir, resolveStashDir, resolveConfigDir,
+} from "./home.js";
+import { acquireInstallLock, releaseInstallLock } from "./install-lock.js";
+import { backupOpenPalmHome } from "./backup.js";
+import { upsertEnvValue } from "./env.js";
+
+export const LAYOUT_VERSION_KEY = "OP_LAYOUT_VERSION";
+/** Bump when the on-disk layout changes and add a Migration to MIGRATIONS. */
+export const CURRENT_LAYOUT_VERSION = 1;
+
+const ADDON_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+export interface MigrationReport {
+  migrated: boolean;
+  from: number;
+  to: number;
+  applied: string[];
+  backupDir: string | null;
+  notes: string[];
+}
+
+export class MigrationError extends Error {
+  constructor(
+    message: string,
+    readonly guidance: string,
+    readonly backupDir: string | null,
+  ) {
+    super(message);
+    this.name = "MigrationError";
+  }
+}
+
+interface MigrationCtx {
+  homeDir: string;
+  dataDir: string;
+  stackDir: string;
+  stashDir: string;
+  configDir: string;
+  dryRun: boolean;
+  log: (m: string) => void;
+  notes: string[];
+}
+
+interface Migration {
+  from: number;
+  to: number;
+  describe: string;
+  apply(ctx: MigrationCtx): void;
+  verify(ctx: MigrationCtx): void;
+}
+
+// ── Layout-version read/write (stack.env is the single source of truth) ───────
+
+function stackEnvFile(stashDir: string): string {
+  return join(stashDir, "env", "stack.env");
+}
+
+/**
+ * Resolve the current on-disk layout version.
+ *   - explicit OP_LAYOUT_VERSION in knowledge/env/stack.env wins
+ *   - else a top-level `vault/` directory ⇒ 0.10.x layout (version 0)
+ *   - else assume the current layout (a pre-marker 0.11 install) — caller stamps it
+ */
+function readLayoutVersion(ctx: { homeDir: string; stashDir: string }): number {
+  const envPath = stackEnvFile(ctx.stashDir);
+  if (existsSync(envPath)) {
+    for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+      const m = line.match(/^OP_LAYOUT_VERSION=(\d+)\s*$/);
+      if (m) return Number(m[1]);
+    }
+  }
+  if (existsSync(join(ctx.homeDir, "vault"))) return 0;
+  return CURRENT_LAYOUT_VERSION;
+}
+
+function stampLayoutVersion(stashDir: string, version: number): void {
+  const envPath = stackEnvFile(stashDir);
+  if (!existsSync(envPath)) return; // nothing to stamp; not a usable install
+  const next = upsertEnvValue(readFileSync(envPath, "utf-8"), LAYOUT_VERSION_KEY, String(version));
+  writeFileSync(envPath, next);
+}
+
+// ── helpers (non-destructive: copy, never delete the source) ──────────────────
+
+function ensureDir(ctx: MigrationCtx, dir: string): void {
+  if (ctx.dryRun) { ctx.log(`[dry-run] mkdir ${rel(ctx, dir)}`); return; }
+  mkdirSync(dir, { recursive: true });
+  try { chmodSync(dir, 0o700); } catch { /* Windows / best-effort */ }
+}
+
+function rel(ctx: MigrationCtx, p: string): string {
+  return p.startsWith(ctx.homeDir) ? p.slice(ctx.homeDir.length + 1) : p;
+}
+
+/** Copy src→dest; skip if dest exists; chmod 600. Returns true if copied. */
+function copyIfAbsent(ctx: MigrationCtx, src: string, dest: string): boolean {
+  if (!existsSync(src)) return false;
+  if (existsSync(dest)) { ctx.log(`skip (exists): ${rel(ctx, dest)}`); return false; }
+  if (ctx.dryRun) { ctx.log(`[dry-run] copy ${rel(ctx, src)} -> ${rel(ctx, dest)}`); return true; }
+  cpSync(src, dest, { recursive: true });
+  try { if (statSync(dest).isFile()) chmodSync(dest, 0o600); } catch { /* best-effort */ }
+  ctx.log(`copied: ${rel(ctx, src)} -> ${rel(ctx, dest)}`);
+  return true;
+}
+
+function writeFile600(ctx: MigrationCtx, path: string, content: string): void {
+  if (ctx.dryRun) { ctx.log(`[dry-run] write ${rel(ctx, path)}`); return; }
+  writeFileSync(path, content);
+  try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+}
+
+// ── Migration 0 → 1: 0.10.x `vault/` layout → 0.11.0 knowledge/ layout ────────
+
+const SECRET_KEY_RE = /(_API_KEY|_TOKEN|_SECRET|_PASSWORD)$/;
+const CONFIG_KEY_RE = /^(OP_CAP_|SYSTEM_LLM_|EMBEDDING_)/;
+
+function migrate010to011(ctx: MigrationCtx): void {
+  const vault = join(ctx.homeDir, "vault");
+  const newEnv = join(ctx.stashDir, "env");
+  const newSecrets = join(ctx.stashDir, "secrets");
+  ensureDir(ctx, newEnv);
+  ensureDir(ctx, newSecrets);
+
+  // user.env → knowledge/env/user.env
+  copyIfAbsent(ctx, join(vault, "user", "user.env"), join(newEnv, "user.env"));
+
+  // stack.env transform → knowledge/env/stack.env
+  const srcStack = join(vault, "stack", "stack.env");
+  const destStack = join(newEnv, "stack.env");
+  if (existsSync(srcStack) && !existsSync(destStack)) {
+    const kept: string[] = [];
+    const removed: string[] = [];
+    for (const line of readFileSync(srcStack, "utf-8").split("\n")) {
+      if (line === "" || line.startsWith("#")) { kept.push(line); continue; }
+      const eq = line.indexOf("=");
+      const key = eq >= 0 ? line.slice(0, eq) : line;
+      const val = eq >= 0 ? line.slice(eq + 1) : "";
+      if (key === "OP_UI_LOGIN_PASSWORD") {
+        writeFile600(ctx, join(newSecrets, "op_ui_login_password"), val + "\n");
+        ctx.log("extracted OP_UI_LOGIN_PASSWORD -> knowledge/secrets/op_ui_login_password");
+      } else if (key === "OP_ADMIN_PORT") {
+        kept.push(`OP_HOST_UI_PORT=${val}`);
+        ctx.log("renamed OP_ADMIN_PORT -> OP_HOST_UI_PORT");
+      } else if (key === "OP_ADMIN_OPENCODE_PORT" || key === "OP_GUARDIAN_PORT") {
+        ctx.log(`dropped removed var: ${key}`);
+      } else if (key.startsWith("TTS_") || key.startsWith("STT_")) {
+        kept.push(`OP_${key}=${val}`);
+        ctx.log(`renamed ${key} -> OP_${key}`);
+      } else if (CONFIG_KEY_RE.test(key) || SECRET_KEY_RE.test(key)) {
+        removed.push(line);
+        ctx.log(`quarantined: ${key}`);
+      } else {
+        kept.push(line);
+      }
+    }
+    writeFile600(ctx, destStack, kept.join("\n") + "\n");
+    if (removed.length > 0) {
+      writeFile600(ctx, join(newEnv, "stack.env.removed-secrets.bak"), removed.join("\n") + "\n");
+      ctx.notes.push(
+        "Secret/capability keys were removed from stack.env (saved to knowledge/env/stack.env.removed-secrets.bak) — re-enter provider keys via the Connections tab and LLM config via config/akm/config.json; do not put them back in stack.env.",
+      );
+    }
+  }
+
+  // provider creds (best-effort) + service secrets
+  if (copyIfAbsent(ctx, join(vault, "stack", "auth.json"), join(newSecrets, "auth.json"))) {
+    ctx.notes.push("Copied auth.json best-effort — verify providers in the Connections tab and re-add any that are missing (the OpenCode auth format changed).");
+  }
+  const servicesDir = join(vault, "stack", "services");
+  if (existsSync(servicesDir)) {
+    for (const name of readdirSync(servicesDir)) {
+      copyIfAbsent(ctx, join(servicesDir, name), join(newSecrets, name));
+    }
+  }
+
+  // channel HMAC secrets: split CHANNEL_<NAME>_SECRET into per-secret files
+  const guardianEnv = join(vault, "stack", "guardian.env");
+  if (existsSync(guardianEnv)) {
+    for (const line of readFileSync(guardianEnv, "utf-8").split("\n")) {
+      const m = line.match(/^CHANNEL_(.+)_SECRET=(.*)$/);
+      if (!m) continue;
+      const name = m[1].toLowerCase();
+      if (!ADDON_NAME_RE.test(name)) continue;
+      const dest = join(newSecrets, `channel_${name}_secret`);
+      if (existsSync(dest)) { ctx.log(`skip (exists): knowledge/secrets/channel_${name}_secret`); continue; }
+      writeFile600(ctx, dest, m[2] + "\n");
+      ctx.log(`channel secret: ${m[1]} -> knowledge/secrets/channel_${name}_secret`);
+    }
+  }
+
+  // user credential files mounted into the assistant at /etc/openpalm
+  for (const n of ["apprise.yaml", "apprise.conf", "gcloud-credentials.json"]) {
+    copyIfAbsent(ctx, join(vault, "user", n), join(newSecrets, n));
+  }
+  for (const d of [".gws", ".gcloud", ".mgc"]) {
+    copyIfAbsent(ctx, join(vault, "user", d), join(newSecrets, d));
+  }
+
+  // Leave a README in the retained legacy vault/ explaining that it is now a
+  // recovery copy and how to remove it safely once 0.11.x is confirmed working.
+  writeVaultReadme(ctx, vault);
+
+  // Addon enablement: stack.yml is removed in 0.11.0. Convert any addons[] from
+  // a legacy stack.yml (config/stack.yml or config/stack/stack.yml) into
+  // OP_ENABLED_ADDONS in stack.env. Do NOT create stack.yml.
+  const addons = readLegacyStackYmlAddons(ctx);
+  if (addons.length > 0) {
+    const envPath = stackEnvFile(ctx.stashDir);
+    if (ctx.dryRun) {
+      ctx.log(`[dry-run] set OP_ENABLED_ADDONS=${addons.join(",")}`);
+    } else if (existsSync(envPath)) {
+      writeFile600(ctx, envPath, upsertEnvValue(readFileSync(envPath, "utf-8"), "OP_ENABLED_ADDONS", addons.join(",")));
+      ctx.log(`set OP_ENABLED_ADDONS=${addons.join(",")}`);
+    }
+  }
+}
+
+const VAULT_README = `# This \`vault/\` directory is from OpenPalm 0.10.x — it is now a RECOVERY COPY
+
+OpenPalm 0.11.0 changed the on-disk layout. The upgrade **copied** everything out
+of this \`vault/\` directory into the new locations and left these originals here,
+untouched, as a safety net:
+
+- \`vault/user/user.env\`        → \`knowledge/env/user.env\`
+- \`vault/stack/stack.env\`       → \`knowledge/env/stack.env\` (transformed)
+- \`vault/stack/guardian.env\`    → \`knowledge/secrets/channel_<name>_secret\`
+- \`vault/stack/services/*\`      → \`knowledge/secrets/\`
+- \`vault/stack/auth.json\`       → \`knowledge/secrets/auth.json\` (best-effort)
+- other user credential files   → \`knowledge/secrets/\`
+
+A full backup of your home was also taken under \`data/backups/\` before migrating.
+
+Nothing in 0.11.x reads this directory anymore. You can delete it once you have
+confirmed the new version works.
+
+## How to remove it safely
+
+1. Confirm 0.11.x is healthy: the stack starts (\`openpalm status\`), you can sign
+   in to the UI, your providers are connected (Connections tab), and your
+   channels still work.
+2. Spot-check that your data is in the new layout:
+   - \`knowledge/env/stack.env\` and \`knowledge/env/user.env\` look right
+   - your secrets are under \`knowledge/secrets/\` (login password, channel
+     secrets, \`auth.json\`, etc.)
+   - if \`knowledge/env/stack.env.removed-secrets.bak\` exists, re-enter those
+     provider keys (Connections) and LLM config (\`config/akm/config.json\`) — do
+     not put secrets back into \`stack.env\`.
+3. Only then remove this directory. Prefer your OS trash (reversible):
+   - Linux:   \`gio trash ~/.openpalm/vault\`  (or \`trash-put ~/.openpalm/vault\`)
+   - macOS:   \`trash ~/.openpalm/vault\`
+   - Windows: delete \`%USERPROFILE%\\.openpalm\\vault\` (sends to Recycle Bin)
+   - Last resort (irreversible): \`rm -rf ~/.openpalm/vault\`
+
+If anything looks wrong, do NOT delete this directory — restore from it or from
+\`data/backups/\`. Full guide: docs/operations/upgrade-0.10-to-0.11.md
+`;
+
+/** Drop a safe-removal README into the retained legacy vault/ (skip if present). */
+function writeVaultReadme(ctx: MigrationCtx, vault: string): void {
+  const dest = join(vault, "README.md");
+  if (existsSync(dest)) { ctx.log("skip (exists): vault/README.md"); return; }
+  if (ctx.dryRun) { ctx.log("[dry-run] write vault/README.md (safe-removal guide)"); return; }
+  writeFileSync(dest, VAULT_README);
+  ctx.log("wrote vault/README.md (safe-removal guide)");
+}
+
+/** Extract a validated addons[] list from any legacy stack.yml, or []. */
+function readLegacyStackYmlAddons(ctx: MigrationCtx): string[] {
+  for (const p of [join(ctx.configDir, "stack.yml"), join(ctx.stackDir, "stack.yml")]) {
+    if (!existsSync(p)) continue;
+    try {
+      const raw = yamlParse(readFileSync(p, "utf-8")) as { addons?: unknown };
+      if (Array.isArray(raw?.addons)) {
+        return [...new Set(raw.addons.filter((v): v is string => typeof v === "string" && ADDON_NAME_RE.test(v)))].sort();
+      }
+    } catch { /* ignore unparseable */ }
+  }
+  return [];
+}
+
+const MIGRATIONS: Migration[] = [
+  {
+    from: 0,
+    to: 1,
+    describe: "0.10.x vault/ layout → 0.11.0 knowledge/ layout",
+    apply: migrate010to011,
+    verify(ctx) {
+      // The migration must have produced a usable 0.11 stack.env (unless a
+      // dry-run, where nothing was written).
+      if (ctx.dryRun) return;
+      if (!existsSync(stackEnvFile(ctx.stashDir))) {
+        throw new Error("post-migration check failed: knowledge/env/stack.env is missing");
+      }
+    },
+  },
+];
+
+// ── Public entry point ────────────────────────────────────────────────────────
+
+const RECOVERY_GUIDANCE =
+  "Your original files were left untouched and a full backup was taken first. " +
+  "To recover, restore the backup (see docs/operations/backup-restore.md) or run " +
+  "the standalone migrator with --dry-run (scripts/migrate-0.10-to-0.11.sh / .ps1). " +
+  "Full guide: docs/operations/upgrade-0.10-to-0.11.md";
+
+/**
+ * Ensure the home directory is migrated to the current layout. Safe to call at
+ * the top of any upgrade/install entry point. Resolves its own paths (must run
+ * before createState, which assumes the current layout).
+ */
+export function ensureMigrated(opts: { homeDir?: string; dryRun?: boolean; log?: (m: string) => void } = {}): MigrationReport {
+  const homeDir = opts.homeDir ?? resolveOpenPalmHome();
+  const dryRun = opts.dryRun ?? false;
+  const log = opts.log ?? (() => {});
+  const stashDir = resolveStashDir();
+  const ctxBase = {
+    homeDir,
+    dataDir: resolveDataDir(),
+    stackDir: resolveStackDir(),
+    stashDir,
+    configDir: resolveConfigDir(),
+    dryRun,
+    log,
+    notes: [] as string[],
+  };
+
+  const from = readLayoutVersion(ctxBase);
+  const empty: MigrationReport = { migrated: false, from, to: from, applied: [], backupDir: null, notes: [] };
+
+  // Fast path: already current → just ensure the marker is stamped, no lock/backup.
+  if (from >= CURRENT_LAYOUT_VERSION) {
+    if (!dryRun) stampLayoutVersion(stashDir, CURRENT_LAYOUT_VERSION);
+    return { ...empty, to: CURRENT_LAYOUT_VERSION };
+  }
+
+  const pending = MIGRATIONS
+    .filter((m) => m.from >= from && m.to <= CURRENT_LAYOUT_VERSION)
+    .sort((a, b) => a.from - b.from);
+  if (pending.length === 0) {
+    if (!dryRun) stampLayoutVersion(stashDir, CURRENT_LAYOUT_VERSION);
+    return { ...empty, to: CURRENT_LAYOUT_VERSION };
+  }
+
+  let lock: ReturnType<typeof acquireInstallLock> = null;
+  let backupDir: string | null = null;
+  try {
+    // Mutual exclusion + backup gate: never migrate without a verified safety
+    // copy. Any failure here aborts with no changes made.
+    if (!dryRun) {
+      try {
+        mkdirSync(ctxBase.dataDir, { recursive: true });
+      } catch (e) {
+        throw new MigrationError(`Could not prepare the data directory: ${e instanceof Error ? e.message : String(e)}`, RECOVERY_GUIDANCE, null);
+      }
+      lock = acquireInstallLock(ctxBase.dataDir);
+      if (!lock) {
+        throw new MigrationError("Another install/upgrade is in progress.", RECOVERY_GUIDANCE, null);
+      }
+      log("Taking a full backup before migrating…");
+      try {
+        backupDir = backupOpenPalmHome(homeDir);
+      } catch (e) {
+        throw new MigrationError(`Could not create a safety backup; upgrade aborted (no changes made): ${e instanceof Error ? e.message : String(e)}`, RECOVERY_GUIDANCE, null);
+      }
+      if (!backupDir) {
+        throw new MigrationError("Could not create a safety backup; upgrade aborted (no changes made).", RECOVERY_GUIDANCE, null);
+      }
+      log(`Backup: ${backupDir}`);
+    }
+
+    const applied: string[] = [];
+    const notes: string[] = [];
+    for (const m of pending) {
+      const ctx: MigrationCtx = { ...ctxBase, notes };
+      log(`Migrating layout ${m.from} → ${m.to}: ${m.describe}`);
+      m.apply(ctx);
+      m.verify(ctx);
+      applied.push(`${m.from}->${m.to}`);
+    }
+
+    // Commit point: bump the layout version LAST.
+    if (!dryRun) stampLayoutVersion(stashDir, CURRENT_LAYOUT_VERSION);
+
+    return { migrated: true, from, to: CURRENT_LAYOUT_VERSION, applied, backupDir, notes };
+  } catch (e) {
+    if (e instanceof MigrationError) throw e;
+    throw new MigrationError(
+      `Migration failed: ${e instanceof Error ? e.message : String(e)}`,
+      RECOVERY_GUIDANCE,
+      backupDir,
+    );
+  } finally {
+    releaseInstallLock(lock);
+  }
+}

package/src/control-plane/opencode-client.ts

@@ -2,7 +2,7 @@
  * Shared OpenCode REST API client.
  *
  * Factory function that returns typed accessors for an OpenCode server
- * at a configurable base URL. Used by both the admin (container) and
+ * at a configurable base URL. Used by both the admin UI (host process) and
  * CLI (host subprocess) to talk to OpenCode.
  */
 

package/src/control-plane/paths.ts

@@ -5,78 +5,93 @@
  * When the directory layout changes, update this file only.
  *
  * Layout:
- *   config/        — user-editable config + system config files (auth.json, akm/)
- *   config/stack/  — compose runtime + stack config (stack.env, guardian.env, stack.yml, addons/)
- *   cache/         — regenerable/semi-persistent data (akm cache, guardian cache, rollback)
- *   state/         — persistent service data (assistant, admin, guardian, logs, backups, registry)
- *   stash/         — akm knowledge (skills, vaults, agents)
+ *   config/        — user-editable config + system config files (akm/)
+ *   config/stack/  — fixed compose files only (stack.env, secrets, auth.json live under knowledge/; no stack.yml)
+ *   data/          — persistent service data, logs, backups, rollback
+ *   knowledge/     — akm knowledge (skills, env, secrets, agents)
  *   workspace/     — shared work area
  */
+import { dirname, basename } from "node:path";
 import type { ControlPlaneState } from "./types.js";
 
 // ── Config directory — user + system config ─────────────────────────────────
 
-/** OpenCode auth token store */
-export const authJsonPath          = (s: ControlPlaneState): string => `${s.configDir}/auth.json`;
-/** akm setup config directory (AKM_CONFIG_DIR) */
+/**
+ * OpenCode auth token store. Provider credentials are sensitive, so they live
+ * under knowledge/secrets/ (out of config/stack/) and are bind-mounted into
+ * every OpenCode-based container (assistant + guardian).
+ */
+export const authJsonPath          = (s: ControlPlaneState): string => `${s.stashDir}/secrets/auth.json`;
+/** akm config directory mounted at /etc/akm */
 export const akmConfigDir          = (s: ControlPlaneState): string => `${s.configDir}/akm`;
-/** akm setup config file (written by admin on capability save) */
+/** akm setup config file (written by the admin UI AKM action and CLI install) */
 export const akmConfigPath         = (s: ControlPlaneState): string => `${s.configDir}/akm/config.json`;
 export const tasksDir              = (s: ControlPlaneState): string => `${s.stashDir}/tasks`;
 export const assistantConfigDir    = (s: ControlPlaneState): string => `${s.configDir}/assistant`;
+/** Guardian OpenCode global config dir — bind-mounted at /etc/opencode */
+export const guardianConfigDir     = (s: ControlPlaneState): string => `${s.configDir}/guardian`;
 
 // ── Config/stack directory — compose runtime + stack config ─────────────────
 
-/** System env: capabilities, secrets, tokens */
-export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stackDir}/stack.env`;
-/** Guardian HMAC channel secrets */
-export const guardianEnvPath       = (s: ControlPlaneState): string => `${s.stackDir}/guardian.env`;
-/** Stack spec: capability assignments */
-export const stackSpecFilePath     = (s: ControlPlaneState): string => `${s.stackDir}/stack.yml`;
-
-// ── Cache directory — regenerable/semi-persistent ───────────────────────────
+/**
+ * System env: non-secret runtime configuration (the Compose `--env-file`).
+ * Lives under knowledge/env/ alongside the user env file (akm `env:stack`).
+ */
+export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stashDir}/env/stack.env`;
+/**
+ * Resolve the OP_HOME root from a stackDir. Normally `<home>/config/stack`;
+ * falls back to the stackDir itself for callers/tests that pass a home-shaped
+ * dir. Mirrors `resolveHomeDirFromStackDir` in secrets-files.ts so the env and
+ * secret dirs resolve consistently from the same input.
+ */
+const homeFromStackDir = (stackDir: string): string =>
+  basename(stackDir) === "stack" && basename(dirname(stackDir)) === "config"
+    ? dirname(dirname(stackDir))
+    : stackDir;
 
-export const akmCacheDir           = (s: ControlPlaneState): string => `${s.cacheDir}/akm`;
-export const guardianCacheDir      = (s: ControlPlaneState): string => `${s.cacheDir}/guardian`;
-export const rollbackDir           = (s: ControlPlaneState): string => `${s.cacheDir}/rollback`;
+/**
+ * Same as `stackEnvPath` but resolved from a `stackDir` for the few callers
+ * that only have the stack dir, not full state.
+ */
+export const stackEnvPathFromStackDir = (stackDir: string): string => `${homeFromStackDir(stackDir)}/knowledge/env/stack.env`;
 
-// ── State directory — persistent service data ───────────────────────────────
+// ── Operational state directories ───────────────────────────────────────────
 
-export const assistantServiceDir   = (s: ControlPlaneState): string => `${s.stateDir}/assistant`;
-export const adminServiceDir       = (s: ControlPlaneState): string => `${s.stateDir}/admin`;
-export const guardianServiceDir    = (s: ControlPlaneState): string => `${s.stateDir}/guardian`;
-export const guardianStashDir      = (s: ControlPlaneState): string => `${s.stateDir}/guardian/stash`;
-export const guardianAkmDir        = (s: ControlPlaneState): string => `${s.stateDir}/guardian/akm`;
-/** Shared akm operational data (data/, state/ — NOT config, which lives in config/akm/) */
-export const akmStateDir           = (s: ControlPlaneState): string => `${s.stateDir}/akm`;
-export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.cacheDir}/akm/tasks/logs/${id}`;
-export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.cacheDir}/akm/tasks/logs`;
-export const logsDir               = (s: ControlPlaneState): string => `${s.stateDir}/logs`;
+export const akmCacheDir           = (s: ControlPlaneState): string => `${s.dataDir}/akm/cache`;
+export const rollbackDir           = (s: ControlPlaneState): string => `${s.dataDir}/rollback`;
+export const logsDir               = (s: ControlPlaneState): string => `${s.dataDir}/logs`;
 /**
  * Guardian's own audit log of channel ingress (HMAC verify, replay, rate
  * limit). Phase 6 of the auth/proxy refactor removed the OpenPalm-side
  * `admin-audit.jsonl` — OpenCode session logs are the audit trail for
  * chat + tool activity.
  */
-export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.stateDir}/logs/guardian-audit.log`;
-/** One-shot 0.11.0 migration log (OP_UI_TOKEN → OPENCODE_SERVER_PASSWORD, endpoints.json move) */
-export const migration0110LogPath  = (s: ControlPlaneState): string => `${s.stateDir}/logs/migration-0.11.0.log`;
-export const backupsDir            = (s: ControlPlaneState): string => `${s.stateDir}/backups`;
-export const registryDir           = (s: ControlPlaneState): string => `${s.stateDir}/registry`;
-export const registryAddonsDir     = (s: ControlPlaneState): string => `${s.stateDir}/registry/addons`;
-export const registryAutomationsDir = (s: ControlPlaneState): string => `${s.stateDir}/registry/automations`;
-export const secretsDir            = (s: ControlPlaneState): string => `${s.stateDir}/secrets`;
-export const secretProviderPath    = (s: ControlPlaneState): string => `${s.stateDir}/secrets/provider.json`;
-export const secretsIndexPath      = (s: ControlPlaneState): string => `${s.stateDir}/secrets/plaintext-index.json`;
-export const passStoreDir          = (s: ControlPlaneState): string => `${s.stateDir}/secrets/pass-store`;
+export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.dataDir}/logs/guardian-audit.log`;
+export const backupsDir            = (s: ControlPlaneState): string => `${s.dataDir}/backups`;
+
+// ── State directory — persistent service data ───────────────────────────────
 
-// ── Stash directory ─────────────────────────────────────────────────────────
+export const assistantServiceDir   = (s: ControlPlaneState): string => `${s.dataDir}/assistant`;
+export const guardianServiceDir    = (s: ControlPlaneState): string => `${s.dataDir}/guardian`;
+export const guardianAkmDir        = (s: ControlPlaneState): string => `${s.dataDir}/guardian/akm`;
+/** akm durable data — NOT config, which lives in config/akm/ */
+export const akmDataDir            = (s: ControlPlaneState): string => `${s.dataDir}/akm/data`;
+export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.dataDir}/akm/cache/tasks/logs/${id}`;
+export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.dataDir}/akm/cache/tasks/logs`;
+export const secretsDir            = (s: ControlPlaneState): string => `${s.dataDir}/secrets`;
+export const secretProviderPath    = (s: ControlPlaneState): string => `${s.dataDir}/secrets/provider.json`;
+export const secretsIndexPath      = (s: ControlPlaneState): string => `${s.dataDir}/secrets/plaintext-index.json`;
+export const passStoreDir          = (s: ControlPlaneState): string => `${s.dataDir}/secrets/pass-store`;
 
-/** akm vault:user file — lives in the stash */
-export const akmUserVaultPath      = (s: ControlPlaneState): string => `${s.stashDir}/vaults/user.env`;
+// ── Knowledge directory ─────────────────────────────────────────────────────
+// The akm env:user file path (`knowledge/env/user.env`) is owned by
+// `akm-user-env.ts` (`userEnvPathSync`), which also handles its read/write and
+// legacy migration — kept there rather than duplicated as a bare path here.
 
 // ── Stack directory ─────────────────────────────────────────────────────────
 
 export const coreComposePath       = (s: ControlPlaneState): string => `${s.stackDir}/core.compose.yml`;
-export const addonsStackDir        = (s: ControlPlaneState): string => `${s.stackDir}/addons`;
+export const servicesComposePath   = (s: ControlPlaneState): string => `${s.stackDir}/services.compose.yml`;
+export const channelsComposePath   = (s: ControlPlaneState): string => `${s.stackDir}/channels.compose.yml`;
+export const customComposePath     = (s: ControlPlaneState): string => `${s.stackDir}/custom.compose.yml`;
 export const addonComposePath      = (s: ControlPlaneState, name: string): string => `${s.stackDir}/addons/${name}/compose.yml`;

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

@@ -0,0 +1,21 @@
+export type HardwareProfileVariant = 'cpu' | 'cuda' | 'rocm';
+
+const PROFILE_ID_RE = /^addon\.([a-z0-9-]+)(?:\.(cpu|cuda|rocm))?$/;
+
+export function addonProfileId(addon: string, variant: HardwareProfileVariant): string {
+  return `addon.${addon}.${variant}`;
+}
+
+export function resolveHardwareProfileVariant(profileId: string): HardwareProfileVariant | null {
+  return (profileId.match(PROFILE_ID_RE)?.[2] as HardwareProfileVariant | undefined) ?? null;
+}
+
+export function canonicalAddonProfileSelection(addon: string, profile: string): string {
+  const trimmed = profile.trim();
+  if (!trimmed) return '';
+
+  const match = trimmed.match(PROFILE_ID_RE);
+  if (!match || match[1] !== addon) return '';
+
+  return trimmed;
+}

package/src/control-plane/provider-models.ts

@@ -4,7 +4,7 @@
  * Used by the admin capabilities test endpoint and the CLI setup wizard
  * to enumerate the models a configured provider exposes.
  */
-import { readStackEnv } from "./secrets.js";
+import { readStackRuntimeEnv } from "./secrets.js";
 import { PROVIDER_DEFAULT_URLS } from "../provider-constants.js";
 
 /** Static model list for Anthropic (no listing API available). */
@@ -24,7 +24,7 @@ const ANTHROPIC_MODELS = [
  *
  * - Empty input → empty string.
  * - `env:NAME` form → looks up `NAME` in `process.env` first, then falls back
- *   to `config/stack/stack.env` resolved against `stackDir`.
+   *   to `knowledge/secrets/<NAME>` resolved against `stackDir`.
  * - Anything else → returned verbatim (treated as a literal key value).
  */
 function resolveApiKey(apiKeyRef: string, stackDir: string): string {
@@ -34,7 +34,7 @@ function resolveApiKey(apiKeyRef: string, stackDir: string): string {
   const varName = apiKeyRef.slice(4);
   if (process.env[varName]) return process.env[varName]!;
 
-  const secrets = readStackEnv(stackDir);
+  const secrets = readStackRuntimeEnv(stackDir);
   return secrets[varName] ?? "";
 }