@openpalm/lib 0.11.0-rc.3 → 0.11.0

package/package.json

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

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

@@ -47,7 +47,9 @@ function seedAddon(name: string): void {
   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`);
+  const envDir = join(tempDir, "knowledge", "env");
+  mkdirSync(envDir, { recursive: true });
+  writeFileSync(join(envDir, "stack.env"), `OP_ENABLED_ADDONS=${name}\n`);
 }
 
 beforeEach(() => {
@@ -70,7 +72,7 @@ describe("buildComposeOptions", () => {
     expect(opts.files[0]).toContain("core.compose.yml");
   });
 
-  it("includes fixed channel compose and profile from stack.yml", () => {
+  it("includes fixed channel compose and profile from OP_ENABLED_ADDONS", () => {
     seedCoreCompose();
     seedAddon("chat");
 

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

@@ -10,9 +10,8 @@ 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 { parseEnvFile, parseEnabledAddons } from "./env.js";
 import { canonicalAddonProfileSelection } from "./profile-ids.js";
-import { listStackSpecAddons } from "./stack-spec.js";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -45,7 +44,7 @@ export function resolveActiveProfiles(state: ControlPlaneState): string[] {
     if (ollamaProfile) profiles.push(ollamaProfile);
   }
 
-  for (const addon of listStackSpecAddons(state.stackDir)) {
+  for (const addon of parseEnabledAddons(env.OP_ENABLED_ADDONS)) {
     if (addon === 'voice') {
       profiles.push(canonicalAddonProfileSelection('voice', env.OP_VOICE_PROFILE ?? '') || 'addon.voice.cpu');
     } else if (addon === 'ollama') {

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

@@ -14,7 +14,8 @@ import { ensureSecret } from './secrets-files.js';
 import type { ControlPlaneState, ArtifactMeta } from "./types.js";
 import { listEnabledAddonIds } from "./registry.js";
 import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
-import { SPEC_DEFAULTS } from "./stack-spec.js";
+import { SPEC_DEFAULTS } from "./defaults.js";
+import { CURRENT_LAYOUT_VERSION } from "./migrations.js";
 
 import {
   readCoreCompose,
@@ -128,6 +129,12 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
     `OP_IMAGE_TAG=${DEFAULT_IMAGE_TAG}`,
     "",
+    "# ── Layout (on-disk schema version; managed by the migration harness) ──",
+    `OP_LAYOUT_VERSION=${CURRENT_LAYOUT_VERSION}`,
+    "",
+    "# ── Enabled addons (comma-separated; managed via the Add-ons UI / CLI) ──",
+    "OP_ENABLED_ADDONS=",
+    "",
     "# ── Ports (38XX range) ──────────────────────────────────────────────",
     "# Guardian is network-only (no host port) — channels reach it via",
     "# http://guardian:8080 over the channel_lan Docker network.",

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

@@ -56,18 +56,25 @@ export function ensureOpenCodeSystemConfig(): void {
 
 const REPO = "itlackey/openpalm";
 
-function resolveAssetVersion(): string {
-  if (process.env.OP_ASSET_VERSION) return process.env.OP_ASSET_VERSION;
-  try {
-    const pkgJson = JSON.parse(
-      readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf-8")
+// The version to download assets for is ALWAYS passed in by the caller (the
+// upgrade flow resolves the canonical platform tag — the newest published
+// `openpalm/assistant` Docker tag, e.g. "v0.11.0-rc.6" — and threads it here).
+// This module intentionally does NOT resolve the version itself: no env var, no
+// `import.meta.url` package.json read (which breaks when the lib is bundled into
+// the UI/electron), and never a silent "main" fallback (main's asset layout can
+// differ from a released install). Bundler-agnostic by construction.
+
+function normalizeAssetRef(version: string): string {
+  const v = version.trim();
+  if (!v) {
+    throw new Error(
+      "Cannot download OpenPalm stack assets: no version provided. " +
+      "The caller must pass the target release tag (e.g. \"v0.11.0-rc.6\")."
     );
-    return `v${pkgJson.version}`;
-  } catch {
-    return "main";
   }
+  // GitHub release/raw refs are `vX.Y.Z`; accept a bare semver and add the `v`.
+  return /^\d/.test(v) ? `v${v}` : v;
 }
-const VERSION = resolveAssetVersion();
 
 // Persona files (openpalm.md, system.md), stash seeds, and user-editable config
 // files are intentionally NOT in this list. They are seeded once (never
@@ -85,9 +92,9 @@ const SEEDED_ASSETS: { relPath: string; githubFilename: string }[] = [
   { relPath: "config/stack/custom.compose.yml", githubFilename: ".openpalm/config/stack/custom.compose.yml" },
 ];
 
-async function downloadAsset(filename: string): Promise<string> {
-  const releaseUrl = `https://github.com/${REPO}/releases/download/${VERSION}/${filename}`;
-  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${VERSION}/${filename}`;
+async function downloadAsset(filename: string, version: string): Promise<string> {
+  const releaseUrl = `https://github.com/${REPO}/releases/download/${version}/${filename}`;
+  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${version}/${filename}`;
 
   for (const url of [releaseUrl, rawUrl]) {
     try {
@@ -97,19 +104,20 @@ async function downloadAsset(filename: string): Promise<string> {
       // try next URL
     }
   }
-  throw new Error(`Failed to download ${filename} from GitHub (tried release and raw URLs for version "${VERSION}")`);
+  throw new Error(`Failed to download ${filename} from GitHub (tried release and raw URLs for version "${version}")`);
 }
 
-export async function refreshCoreAssets(): Promise<{
+export async function refreshCoreAssets(version: string): Promise<{
   backupDir: string | null;
   updated: string[];
 }> {
+  const ref = normalizeAssetRef(version);
   const homeDir = resolveOpenPalmHome();
   const updated: string[] = [];
   let backupDir: string | null = null;
 
   for (const asset of MANAGED_ASSETS) {
-    const freshContent = await downloadAsset(asset.githubFilename);
+    const freshContent = await downloadAsset(asset.githubFilename, ref);
     const targetPath = join(homeDir, asset.relPath);
 
     if (existsSync(targetPath)) {
@@ -135,7 +143,7 @@ export async function refreshCoreAssets(): Promise<{
   for (const asset of SEEDED_ASSETS) {
     const targetPath = join(homeDir, asset.relPath);
     if (existsSync(targetPath)) continue;
-    const freshContent = await downloadAsset(asset.githubFilename);
+    const freshContent = await downloadAsset(asset.githubFilename, ref);
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, freshContent);
     updated.push(asset.relPath);

package/src/control-plane/defaults.ts

@@ -0,0 +1,16 @@
+/**
+ * Stack defaults (ports + image). Formerly in stack-spec.ts; kept after the
+ * stack.yml removal because these are the canonical fallback values used when a
+ * key is absent from stack.env.
+ */
+export const SPEC_DEFAULTS = {
+  ports: {
+    assistant: 3800,
+    hostUi: 3880,
+    assistantSsh: 2222,
+  },
+  image: {
+    namespace: "openpalm",
+    tag: "latest",
+  },
+} as const;

package/src/control-plane/env.ts

@@ -82,6 +82,21 @@ export function upsertEnvValue(content: string, key: string, value: string): str
   return `${content}${suffix}${line}\n`;
 }
 
+/** Addon name shape (matches the former stack.yml validation). */
+export const ADDON_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+/**
+ * Parse the `OP_ENABLED_ADDONS` stack.env value (comma-separated) into a
+ * validated, de-duplicated, sorted list of addon ids. Replaces the former
+ * stack.yml `addons[]` array as the authoritative enabled-addon record.
+ */
+export function parseEnabledAddons(value: string | undefined): string[] {
+  if (!value) return [];
+  return [...new Set(
+    value.split(',').map((v) => v.trim()).filter((v) => ADDON_NAME_RE.test(v)),
+  )].sort();
+}
+
 export const RELEASE_TAG_REGEX = /^v?\d+\.\d+\.\d+(?:[-+](?:[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*))?$/;
 
 /**

package/src/control-plane/home.ts

@@ -3,11 +3,11 @@
  *
  * Single ~/.openpalm/ root:
  *   config/    — user-editable config + system config files (akm/)
- *   config/stack/ — compose runtime + stack config (stack.env, stack.yml, auth.json, fixed compose files)
+ *   config/stack/ — fixed compose files (no stack.env/secrets/stack.yml)
  *   data/      — persistent service data, logs, backups, rollback
- *   knowledge/ — akm knowledge (env, secrets, tasks)
+ *   knowledge/ — akm knowledge (env, secrets, tasks); env/stack.env is the
+ *                authoritative stack composition + versions record
  *   workspace/ — shared assistant work area
- *   config/stack/ — compose runtime assets + stack config (stack.env, stack.yml)
  */
 import { mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";

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

@@ -26,7 +26,6 @@ import {
 } from "./setup.js";
 import type { SetupSpec, SetupConnection } from "./setup.js";
 import type { ControlPlaneState } from "./types.js";
-import { STACK_SPEC_FILENAME, readStackSpec } from "./stack-spec.js";
 import { readSecret } from './secrets-files.js';
 
 // ── Helpers ──────────────────────────────────────────────────────────────
@@ -313,11 +312,6 @@ describe("Existing Install", () => {
       })
     );
 
-    // stack.yml is just a version marker now
-    const specAfterSecond = readStackSpec(stackDir);
-    expect(specAfterSecond).not.toBeNull();
-    expect(specAfterSecond!.version).toBe(2);
-
     const auth = JSON.parse(readFileSync(join(homeDir, "knowledge", "secrets", "auth.json"), "utf-8"));
     expect(auth.groq.key).toBe("gsk-test-key-456");
   });
@@ -426,12 +420,6 @@ describe("Broken/Corrupt State", () => {
     }
   });
 
-  // Scenario 13: Missing stack.yml returns null
-  it("readStackSpec returns null when stack.yml missing", () => {
-    const spec = readStackSpec(stackDir);
-    expect(spec).toBeNull();
-  });
-
   // Scenario 14: knowledge/tasks dir missing (performSetup should recreate it via ensureHomeDirs)
   it("performSetup creates missing subdirectories", async () => {
     // Seed the minimal env files first
@@ -453,16 +441,6 @@ describe("Broken/Corrupt State", () => {
     expect(existsSync(join(homeDir, "knowledge", "tasks"))).toBe(true);
   });
 
-  // Scenario 15: openpalm.yaml with old version
-  it("readStackSpec returns null for version 1 spec", () => {
-    writeFileSync(
-      join(stackDir, STACK_SPEC_FILENAME),
-      "version: 1\nconnections: []\n"
-    );
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).toBeNull();
-  });
 });
 
 // =====================================================================
@@ -562,10 +540,6 @@ describe("Setup Input Variations", () => {
 
     const result = await performSetup(input);
     expect(result.ok).toBe(true);
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
   });
 
   // Scenario 21: Multiple providers map to correct env vars
@@ -626,12 +600,9 @@ describe("performSetup end-to-end artifacts", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  it("writes stack.yml and readStackSpec returns v2", async () => {
+  it("does not create a stack.yml (addon state lives in stack.env)", async () => {
     await performSetup(makeValidSpec());
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
+    expect(existsSync(join(stackDir, "stack.yml"))).toBe(false);
   });
 
   it("writes akm config with embedding dims from setup spec", async () => {

package/src/control-plane/lifecycle.ts

@@ -216,7 +216,9 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
 }
 
 export async function applyUpgrade(
-  state: ControlPlaneState
+  state: ControlPlaneState,
+  /** Release tag whose stack assets to fetch (e.g. "v0.11.0-rc.6"). Caller-supplied. */
+  version: string
 ): Promise<{
   backupDir: string | null;
   updated: string[];
@@ -225,7 +227,7 @@ export async function applyUpgrade(
   const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
-    const { backupDir, updated } = await refreshCoreAssets();
+    const { backupDir, updated } = await refreshCoreAssets(version);
     const restarted = await reconcileCore(state, {});
     return { backupDir, updated, restarted };
   } finally {
@@ -269,7 +271,9 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
     const tagResult = await updateStackEnvToLatestImageTag(state);
     imageTag = tagResult.tag;
     namespace = tagResult.namespace;
-    upgradeResult = await applyUpgrade(state);
+    // The resolved platform tag IS the version whose stack assets we fetch —
+    // keeps compose files and images in lockstep.
+    upgradeResult = await applyUpgrade(state, imageTag);
   } catch (e) {
     // Restore stack.env on failure
     if (originalStackEnv !== null) {
@@ -308,7 +312,7 @@ export async function applyTagChange(state: ControlPlaneState, tag: string): Pro
   const stackEnvPath = `${state.stashDir}/env/stack.env`;
   const currentContent = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
   writeFileSync(stackEnvPath, mergeEnvContent(currentContent, { OP_IMAGE_TAG: tag }, { uncomment: true }));
-  const upgradeResult = await applyUpgrade(state);
+  const upgradeResult = await applyUpgrade(state, tag);
   return {
     imageTag: tag,
     namespace: "openpalm",

package/src/control-plane/migrations.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ensureMigrated, MigrationError, CURRENT_LAYOUT_VERSION } from "./migrations.js";
+
+// The harness resolves all paths from OP_HOME; point it at a synthetic 0.10 home.
+let home: string;
+let prevOpHome: string | undefined;
+
+function seed010(h: string): void {
+  mkdirSync(join(h, "vault", "user"), { recursive: true });
+  mkdirSync(join(h, "vault", "stack", "services"), { recursive: true });
+  mkdirSync(join(h, "config"), { recursive: true });
+  mkdirSync(join(h, "data"), { recursive: true });
+  writeFileSync(join(h, "vault", "user", "user.env"), "MY_PREF=hello\n");
+  writeFileSync(
+    join(h, "vault", "stack", "stack.env"),
+    [
+      "# system env",
+      "OP_HOME=/x/.openpalm",
+      "OP_ADMIN_PORT=9000",
+      "OPENAI_API_KEY=sk-secret123",
+      "OP_CAP_LLM_MODEL=gpt-4",
+      "TTS_VOICE=alloy",
+      "OP_UI_LOGIN_PASSWORD=hunter2",
+      "OP_ASSISTANT_PORT=3800",
+      "",
+    ].join("\n"),
+  );
+  writeFileSync(
+    join(h, "vault", "stack", "guardian.env"),
+    "CHANNEL_DISCORD_SECRET=disc-abc\nCHANNEL_SLACK_SECRET=slack-xyz\n",
+  );
+  writeFileSync(join(h, "vault", "stack", "services", "some.secret"), "svc-val\n");
+  writeFileSync(join(h, "vault", "user", "apprise.yaml"), "urls:\n  - mailto://x\n");
+  writeFileSync(join(h, "config", "stack.yml"), "version: 1\ncapabilities:\n  llm: openai\n");
+}
+
+/** Sorted top-level entry names under a directory. */
+function entries(dir: string): string[] {
+  return readdirSync(dir).sort();
+}
+
+beforeEach(() => {
+  prevOpHome = process.env.OP_HOME;
+  home = mkdtempSync(join(tmpdir(), "op-migrate-"));
+  process.env.OP_HOME = home;
+});
+
+afterEach(() => {
+  if (prevOpHome === undefined) delete process.env.OP_HOME;
+  else process.env.OP_HOME = prevOpHome;
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("ensureMigrated 0.10 → 0.11", () => {
+  it("migrates the vault layout, backs up, and stamps the layout version", () => {
+    seed010(home);
+    const report = ensureMigrated();
+
+    expect(report.migrated).toBe(true);
+    expect(report.from).toBe(0);
+    expect(report.to).toBe(CURRENT_LAYOUT_VERSION);
+    expect(report.backupDir).toBeTruthy();
+    expect(existsSync(report.backupDir!)).toBe(true);
+
+    const stackEnv = readFileSync(join(home, "knowledge", "env", "stack.env"), "utf-8");
+    expect(stackEnv).toContain("OP_HOST_UI_PORT=9000"); // renamed
+    expect(stackEnv).toContain("OP_TTS_VOICE=alloy");    // prefixed
+    expect(stackEnv).toContain("OP_ASSISTANT_PORT=3800"); // kept
+    expect(stackEnv).toContain(`OP_LAYOUT_VERSION=${CURRENT_LAYOUT_VERSION}`); // commit
+    expect(stackEnv).not.toContain("OPENAI_API_KEY");    // quarantined
+    expect(stackEnv).not.toContain("OP_CAP_LLM_MODEL");  // quarantined
+
+    expect(readFileSync(join(home, "knowledge", "env", "stack.env.removed-secrets.bak"), "utf-8"))
+      .toContain("OPENAI_API_KEY=sk-secret123");
+    expect(readFileSync(join(home, "knowledge", "secrets", "op_ui_login_password"), "utf-8").trim())
+      .toBe("hunter2");
+    expect(readFileSync(join(home, "knowledge", "secrets", "channel_discord_secret"), "utf-8").trim())
+      .toBe("disc-abc");
+    expect(readFileSync(join(home, "knowledge", "secrets", "channel_slack_secret"), "utf-8").trim())
+      .toBe("slack-xyz");
+    expect(existsSync(join(home, "knowledge", "secrets", "some.secret"))).toBe(true);
+    expect(existsSync(join(home, "knowledge", "secrets", "apprise.yaml"))).toBe(true);
+    // stack.yml is removed in 0.11.0 — the migration must NOT create one.
+    expect(existsSync(join(home, "config", "stack", "stack.yml"))).toBe(false);
+    expect(readFileSync(join(home, "knowledge", "env", "user.env"), "utf-8")).toContain("MY_PREF=hello");
+
+    // Non-destructive: originals untouched.
+    expect(existsSync(join(home, "vault", "stack", "stack.env"))).toBe(true);
+  });
+
+  it("ends with exactly the expected 0.11 directories and every datum in its proper location", () => {
+    seed010(home);
+    ensureMigrated();
+
+    // Only the expected top-level directories exist. The legacy vault/ is
+    // intentionally retained (copy-only recovery copy); nothing stray is created.
+    expect(entries(home)).toEqual(["config", "data", "knowledge", "vault"]);
+
+    // knowledge/ holds exactly the env + secrets stores.
+    expect(entries(join(home, "knowledge"))).toEqual(["env", "secrets"]);
+
+    // Every migrated datum landed in its proper 0.11 location — no missing, no extra.
+    expect(entries(join(home, "knowledge", "env"))).toEqual([
+      "stack.env",
+      "stack.env.removed-secrets.bak",
+      "user.env",
+    ]);
+    expect(entries(join(home, "knowledge", "secrets"))).toEqual([
+      "apprise.yaml",
+      "channel_discord_secret",
+      "channel_slack_secret",
+      "op_ui_login_password",
+      "some.secret",
+    ]);
+
+    // The full backup landed under data/backups (and nowhere else top-level).
+    expect(existsSync(join(home, "data", "backups"))).toBe(true);
+
+    // The retained vault/ carries a safe-removal README.
+    expect(existsSync(join(home, "vault", "README.md"))).toBe(true);
+
+    // Nothing leaked into a wrong place: no 0.11 secrets under knowledge/env,
+    // and no plaintext login password left inside the migrated stack.env.
+    expect(existsSync(join(home, "knowledge", "env", "op_ui_login_password"))).toBe(false);
+    expect(readFileSync(join(home, "knowledge", "env", "stack.env"), "utf-8"))
+      .not.toContain("hunter2");
+  });
+
+  it("migrates a minimal home (only stack.env) without creating stray files", () => {
+    mkdirSync(join(home, "vault", "stack"), { recursive: true });
+    mkdirSync(join(home, "data"), { recursive: true });
+    writeFileSync(
+      join(home, "vault", "stack", "stack.env"),
+      "OP_IMAGE_TAG=0.10.2\nOP_ASSISTANT_PORT=3800\n",
+    );
+    const report = ensureMigrated();
+    expect(report.migrated).toBe(true);
+
+    // env/ has only stack.env — no user.env, no removed-secrets.bak (there were
+    // no secrets/cap keys to quarantine).
+    expect(entries(join(home, "knowledge", "env"))).toEqual(["stack.env"]);
+    // secrets/ exists (created) but is empty — nothing to migrate.
+    expect(entries(join(home, "knowledge", "secrets"))).toEqual([]);
+    const stackEnv = readFileSync(join(home, "knowledge", "env", "stack.env"), "utf-8");
+    expect(stackEnv).toContain("OP_IMAGE_TAG=0.10.2");
+    expect(stackEnv).toContain(`OP_LAYOUT_VERSION=${CURRENT_LAYOUT_VERSION}`);
+  });
+
+  it("does not write a removed-secrets.bak when stack.env has no secret/cap keys", () => {
+    mkdirSync(join(home, "vault", "stack"), { recursive: true });
+    mkdirSync(join(home, "data"), { recursive: true });
+    writeFileSync(join(home, "vault", "stack", "stack.env"), "OP_ASSISTANT_PORT=3800\n");
+    ensureMigrated();
+    expect(existsSync(join(home, "knowledge", "env", "stack.env.removed-secrets.bak"))).toBe(false);
+  });
+
+  it("writes a safe-removal README into the retained vault/", () => {
+    seed010(home);
+    ensureMigrated();
+    const readme = readFileSync(join(home, "vault", "README.md"), "utf-8");
+    // It explains what the directory is and how to remove it safely.
+    expect(readme).toContain("RECOVERY COPY");
+    expect(readme).toContain("How to remove it safely");
+    expect(readme).toContain("gio trash");
+    expect(readme).toContain("data/backups");
+    // The original migrated files are still present (README is additive only).
+    expect(existsSync(join(home, "vault", "stack", "stack.env"))).toBe(true);
+  });
+
+  it("dry-run does not write the vault README", () => {
+    seed010(home);
+    ensureMigrated({ dryRun: true });
+    expect(existsSync(join(home, "vault", "README.md"))).toBe(false);
+  });
+
+  it("does not clobber a pre-existing vault/README.md", () => {
+    seed010(home);
+    writeFileSync(join(home, "vault", "README.md"), "user's own notes\n");
+    ensureMigrated();
+    expect(readFileSync(join(home, "vault", "README.md"), "utf-8")).toBe("user's own notes\n");
+  });
+
+  it("converts addons[] from a nested config/stack/stack.yml too", () => {
+    seed010(home);
+    rmSync(join(home, "config", "stack.yml"), { force: true });
+    mkdirSync(join(home, "config", "stack"), { recursive: true });
+    writeFileSync(join(home, "config", "stack", "stack.yml"), "version: 2\naddons:\n  - voice\n");
+    ensureMigrated();
+    expect(readFileSync(join(home, "knowledge", "env", "stack.env"), "utf-8"))
+      .toContain("OP_ENABLED_ADDONS=voice");
+  });
+
+  it("normalizes channel secret names to lowercase and skips invalid ones", () => {
+    mkdirSync(join(home, "vault", "stack"), { recursive: true });
+    mkdirSync(join(home, "data"), { recursive: true });
+    writeFileSync(join(home, "vault", "stack", "stack.env"), "OP_ASSISTANT_PORT=3800\n");
+    writeFileSync(
+      join(home, "vault", "stack", "guardian.env"),
+      // valid (mixed case → lowercase), and an invalid name with a space (skipped).
+      "CHANNEL_Discord_SECRET=abc\nCHANNEL_BAD NAME_SECRET=nope\n",
+    );
+    ensureMigrated();
+    expect(existsSync(join(home, "knowledge", "secrets", "channel_discord_secret"))).toBe(true);
+    expect(entries(join(home, "knowledge", "secrets"))).toEqual(["channel_discord_secret"]);
+  });
+
+  it("preserves user-edited destination files (copy-only, skip-if-exists)", () => {
+    seed010(home);
+    // Simulate a partially-migrated home where the user already has a user.env.
+    mkdirSync(join(home, "knowledge", "env"), { recursive: true });
+    writeFileSync(join(home, "knowledge", "env", "user.env"), "MY_PREF=edited-by-user\n");
+    ensureMigrated();
+    // The existing destination must NOT be clobbered by the vault copy.
+    expect(readFileSync(join(home, "knowledge", "env", "user.env"), "utf-8"))
+      .toContain("edited-by-user");
+  });
+
+  it("copies auth.json best-effort and surfaces a verify-providers note", () => {
+    seed010(home);
+    writeFileSync(join(home, "vault", "stack", "auth.json"), '{"openai":{"type":"api"}}');
+    const report = ensureMigrated();
+    expect(existsSync(join(home, "knowledge", "secrets", "auth.json"))).toBe(true);
+    expect(report.notes.join(" ")).toContain("auth.json");
+  });
+
+  it("converts a legacy stack.yml addons[] into OP_ENABLED_ADDONS", () => {
+    seed010(home);
+    writeFileSync(join(home, "config", "stack.yml"), "version: 2\naddons:\n  - voice\n  - discord\n");
+    ensureMigrated();
+    const stackEnv = readFileSync(join(home, "knowledge", "env", "stack.env"), "utf-8");
+    expect(stackEnv).toContain("OP_ENABLED_ADDONS=discord,voice");
+    expect(existsSync(join(home, "config", "stack", "stack.yml"))).toBe(false);
+  });
+
+  it("is idempotent — a second run is a no-op", () => {
+    seed010(home);
+    ensureMigrated();
+    const second = ensureMigrated();
+    expect(second.migrated).toBe(false);
+    expect(second.to).toBe(CURRENT_LAYOUT_VERSION);
+  });
+
+  it("dry-run writes nothing", () => {
+    seed010(home);
+    const report = ensureMigrated({ dryRun: true });
+    expect(report.migrated).toBe(true);
+    expect(existsSync(join(home, "knowledge", "env", "stack.env"))).toBe(false);
+    expect(report.backupDir).toBeNull();
+  });
+
+  it("aborts (no changes) when the backup cannot be created", () => {
+    seed010(home);
+    // Make data/ a file so backupOpenPalmHome's mkdir of data/backups fails.
+    rmSync(join(home, "data"), { recursive: true, force: true });
+    writeFileSync(join(home, "data"), "not a dir");
+    expect(() => ensureMigrated()).toThrow(MigrationError);
+    expect(existsSync(join(home, "knowledge", "env", "stack.env"))).toBe(false);
+  });
+
+  it("treats an already-0.11 home (no vault) as current and stamps it", () => {
+    mkdirSync(join(home, "knowledge", "env"), { recursive: true });
+    writeFileSync(join(home, "knowledge", "env", "stack.env"), "OP_IMAGE_TAG=0.11.0\n");
+    const report = ensureMigrated();
+    expect(report.migrated).toBe(false);
+    expect(report.to).toBe(CURRENT_LAYOUT_VERSION);
+    expect(readFileSync(join(home, "knowledge", "env", "stack.env"), "utf-8"))
+      .toContain(`OP_LAYOUT_VERSION=${CURRENT_LAYOUT_VERSION}`);
+  });
+});