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

package/src/control-plane/lifecycle.ts

@@ -8,25 +8,23 @@ import {
   resolveConfigDir,
   resolveStashDir,
   resolveWorkspaceDir,
-  resolveCacheDir,
-  resolveStateDir,
+  resolveDataDir,
   resolveStackDir,
 } from "./home.js";
-import { ensureSecrets } from "./secrets.js";
+import { ensureSecrets, readStackSecretEnv } from "./secrets.js";
 import {
   resolveRuntimeFiles,
   writeRuntimeFiles,
-  buildEnvFiles,
   discoverStackOverlays,
   ensureComposeVolumeTargets,
 } from "./config-persistence.js";
-import { readStackSpec } from "./stack-spec.js";
 import { refreshCoreAssets } from "./core-assets.js";
 import { isSetupComplete } from "./setup-status.js";
 import { snapshotCurrentState } from "./rollback.js";
 import { checkDocker, composePreflight, composePull, composeUp, composeConfigServices, resolveComposeProjectName } from "./docker.js";
+import { buildComposeOptions } from "./compose-args.js";
 import { acquireInstallLock, releaseInstallLock } from "./install-lock.js";
-import { listEnabledAddonIds } from "./registry.js";
+import { getAddonServiceNames, listEnabledAddonIds } from "./registry.js";
 
 const IMAGE_NAMESPACE_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
 const SEMVER_TAG_RE = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
@@ -37,8 +35,7 @@ export function createState(): ControlPlaneState {
   const configDir = resolveConfigDir();
   const stashDir = resolveStashDir();
   const workspaceDir = resolveWorkspaceDir();
-  const cacheDir = resolveCacheDir();
-  const stateDir = resolveStateDir();
+  const dataDir = resolveDataDir();
   const stackDir = resolveStackDir();
 
   const services: Record<string, "running" | "stopped"> = {};
@@ -51,8 +48,7 @@ export function createState(): ControlPlaneState {
     configDir,
     stashDir,
     workspaceDir,
-    cacheDir,
-    stateDir,
+    dataDir,
     stackDir,
     services,
     artifacts: { compose: "" },
@@ -60,6 +56,7 @@ export function createState(): ControlPlaneState {
   };
 
   ensureSecrets(bootstrapState);
+  Object.assign(process.env, readStackSecretEnv(stackDir));
 
   return bootstrapState;
 }
@@ -74,7 +71,7 @@ async function reconcileCore(
   }
 
   for (const addonName of listEnabledAddonIds(state.homeDir)) {
-    mkdirSync(`${state.stateDir}/${addonName}`, { recursive: true });
+    mkdirSync(`${state.dataDir}/${addonName}`, { recursive: true });
   }
 
   const active: string[] = [];
@@ -89,8 +86,7 @@ async function reconcileCore(
   // Preflight: validate compose merge before mutation.
   // Mandatory when compose files exist and OP_SKIP_COMPOSE_PREFLIGHT is not set.
   // Fails if Docker is unavailable (Docker is required for any compose operation).
-  const files = buildComposeFileList(state);
-  const envFiles = buildEnvFiles(state);
+  const { files, envFiles, profiles } = buildComposeOptions(state);
   if (files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
     const dockerCheck = await checkDocker();
     if (!dockerCheck.ok) {
@@ -99,12 +95,13 @@ async function reconcileCore(
         "Docker must be running before install/update/apply operations."
       );
     }
-    const preflight = await composePreflight({ files, envFiles });
+    const preflight = await composePreflight({ files, envFiles, profiles });
     if (!preflight.ok) {
-      const projectName = resolveComposeProjectName();
+      const projectName = resolveComposeProjectName(Object.assign({}, ...envFiles.map((f) => parseEnvFile(f))));
       const fileArgs = files.flatMap((f) => ["-f", f]).join(" ");
       const envArgs = envFiles.filter(existsSync).flatMap((f) => ["--env-file", f]).join(" ");
-      const resolvedCmd = `docker compose ${fileArgs} --project-name ${projectName} ${envArgs} config --quiet`;
+      const profileArgs = profiles.flatMap((p) => ["--profile", p]).join(" ");
+      const resolvedCmd = `docker compose ${fileArgs} --project-name ${projectName} ${envArgs} ${profileArgs} config --quiet`;
       throw new Error(
         `Compose preflight failed: ${preflight.stderr}\n` +
         `Resolved command: ${resolvedCmd}\n` +
@@ -125,7 +122,7 @@ async function reconcileCore(
 }
 
 export async function applyInstall(state: ControlPlaneState): Promise<void> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     await reconcileCore(state, { activateServices: true });
@@ -139,7 +136,7 @@ export async function applyInstall(state: ControlPlaneState): Promise<void> {
 }
 
 export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted: string[] }> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     return { restarted: await reconcileCore(state, {}) };
@@ -149,7 +146,7 @@ export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted
 }
 
 export async function applyUninstall(state: ControlPlaneState): Promise<{ stopped: string[] }> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     return { stopped: await reconcileCore(state, { deactivateServices: true }) };
@@ -179,7 +176,7 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
   namespace: string;
   tag: string;
 }> {
-  const systemEnvPath = `${state.stackDir}/stack.env`;
+  const systemEnvPath = `${state.stashDir}/env/stack.env`;
   const parsed = parseEnvFile(systemEnvPath);
   const namespace = (parsed.OP_IMAGE_NAMESPACE ?? process.env.OP_IMAGE_NAMESPACE ?? "openpalm").trim().toLowerCase();
 
@@ -187,10 +184,14 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
     throw new Error(`Invalid image namespace in system.env: ${namespace}`);
   }
 
+  // `assistant` is the version-of-record image: all platform images
+  // (assistant, guardian, channel, voice) are published in lockstep under the
+  // same OP_IMAGE_TAG, so its newest tag is the canonical platform version.
+
   let response: Response;
   try {
     response = await fetch(
-      `https://registry.hub.docker.com/v2/repositories/${namespace}/admin/tags?page_size=25&ordering=last_updated`,
+      `https://registry.hub.docker.com/v2/repositories/${namespace}/assistant/tags?page_size=25&ordering=last_updated`,
       { headers: { Accept: "application/json" } }
     );
   } catch (e) {
@@ -215,16 +216,18 @@ 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[];
   restarted: string[];
 }> {
-  const lock = acquireInstallLock(state.stateDir);
+  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 {
@@ -247,15 +250,14 @@ export type UpgradeResult = {
  * Callers handle their own audit logging and admin self-recreation.
  */
 export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeResult> {
-  const files = buildComposeFileList(state);
-  const envFiles = buildEnvFiles(state);
+  const composeOpts = buildComposeOptions(state);
 
   // Compose preflight runs inside `applyUpgrade` -> `reconcileCore`, so we
   // skip the redundant top-level call. Any merge failure aborts before
   // mutation just the same.
 
   // 1. Snapshot stack.env for rollback on failure
-  const stackEnvPath = `${state.stackDir}/stack.env`;
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
   let originalStackEnv: string | null = null;
   try {
     originalStackEnv = readFileSync(stackEnvPath, "utf-8");
@@ -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) {
@@ -278,15 +282,15 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
     throw e;
   }
 
-  // 3. Pull images
-  const pullResult = await composePull({ files, envFiles });
+  // 3. Pull all images (core + addons, including profile-gated voice)
+  const pullResult = await composePull(composeOpts);
   if (!pullResult.ok) {
     throw new Error(`Failed to pull images: ${pullResult.stderr}`);
   }
 
-  // 4. Recreate containers
+  // 4. Recreate containers (includes profiles for voice addon)
   const services = await buildManagedServices(state);
-  const upResult = await composeUp({ files, envFiles, services, removeOrphans: true });
+  const upResult = await composeUp({ ...composeOpts, services, removeOrphans: true });
   if (!upResult.ok) {
     throw new Error(`Images pulled but failed to recreate containers: ${upResult.stderr}`);
   }
@@ -305,10 +309,10 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
  * Used by the admin "set version" action — skips the auto-detect step in performUpgrade.
  */
 export async function applyTagChange(state: ControlPlaneState, tag: string): Promise<UpgradeResult> {
-  const stackEnvPath = `${state.stackDir}/stack.env`;
+  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",
@@ -319,16 +323,15 @@ export async function applyTagChange(state: ControlPlaneState, tag: string): Pro
 }
 
 export function buildComposeFileList(state: ControlPlaneState): string[] {
-  return discoverStackOverlays(state.stackDir);
+  return discoverStackOverlays(state.stackDir, state.homeDir);
 }
 
 export async function buildManagedServices(state: ControlPlaneState): Promise<string[]> {
-  const files = buildComposeFileList(state);
-  const envFiles = buildEnvFiles(state);
+  const composeOpts = buildComposeOptions(state);
 
   // Prefer compose-derived service list when Docker is available
-  if (files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
-    const result = await composeConfigServices({ files, envFiles });
+  if (composeOpts.files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
+    const result = await composeConfigServices(composeOpts);
     if (result.ok && result.services.length > 0) {
       return result.services;
     }
@@ -336,7 +339,9 @@ export async function buildManagedServices(state: ControlPlaneState): Promise<st
 
   // Fallback: static inference from CORE_SERVICES + active addon overlays
   const services: string[] = [...CORE_SERVICES];
-  services.push(...listEnabledAddonIds(state.homeDir));
+  for (const addon of listEnabledAddonIds(state.homeDir)) {
+    services.push(...getAddonServiceNames(state.homeDir, addon));
+  }
   return services;
 }
 

package/src/control-plane/markdown-task.ts

@@ -1,21 +1,18 @@
 /**
- * AKM markdown task parser.
+ * AKM task parser.
  *
- * Task files are markdown with YAML frontmatter. The frontmatter defines the
- * schedule and target; for inline-prompt tasks the markdown body is the prompt.
- *
- * Supported target types:
- *   command  — `command: [...]` YAML array (argv), run via Bun.spawn / akm tasks run
- *   prompt   — `prompt: inline` + markdown body as the prompt text
+ * Task files are YAML documents in knowledge/tasks/. Supported target types:
+ *   command  — `command: [...]` YAML array (argv)
+ *   prompt   — `prompt: <text>` inline prompt text
  *   workflow — `workflow: workflow:<ref>` + optional `params` map
  */
 import { parse as parseYaml } from "yaml";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import type { AutomationConfig } from "./scheduler.js";
 import { createLogger } from "../logger.js";
 
-const logger = createLogger("markdown-task");
+const logger = createLogger("task-file");
 
 // ── Types ─────────────────────────────────────────────────────────────────
 
@@ -35,29 +32,11 @@ export type MarkdownTaskTarget =
   | { kind: "prompt"; profile?: string; body: string }
   | { kind: "workflow"; ref: string; params: Record<string, unknown> };
 
-// ── Frontmatter splitter ──────────────────────────────────────────────────
-
-interface ParsedFile {
-  frontmatter: string;
-  body: string;
-}
-
-function splitFrontmatter(content: string): ParsedFile | null {
-  // Must start with ---
-  if (!content.startsWith("---")) return null;
-  const after = content.slice(3);
-  const end = after.indexOf("\n---");
-  if (end === -1) return null;
-  return {
-    frontmatter: after.slice(0, end).trim(),
-    body: after.slice(end + 4).trim(),
-  };
-}
-
 // ── Parser ────────────────────────────────────────────────────────────────
 
 export function parseMarkdownTask(filePath: string): MarkdownTask | null {
-  const id = filePath.replace(/.*[\\/]/, "").replace(/\.md$/, "");
+  const fileName = basename(filePath);
+  const id = fileName.replace(/\.(?:ya?ml|md)$/, "");
   let raw: string;
   try {
     raw = readFileSync(filePath, "utf-8");
@@ -66,22 +45,17 @@ export function parseMarkdownTask(filePath: string): MarkdownTask | null {
     return null;
   }
 
-  const parts = splitFrontmatter(raw);
-  if (!parts) {
-    logger.warn("task file missing frontmatter delimiters", { filePath });
-    return null;
-  }
-
+  const { frontmatter, body } = splitTaskSource(raw);
   let fm: Record<string, unknown>;
   try {
-    fm = parseYaml(parts.frontmatter) as Record<string, unknown>;
+    const parsed = parseYaml(frontmatter);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      logger.warn("task YAML is not an object", { filePath });
+      return null;
+    }
+    fm = parsed as Record<string, unknown>;
   } catch (err) {
-    logger.warn("failed to parse task frontmatter", { filePath, error: String(err) });
-    return null;
-  }
-
-  if (!fm || typeof fm !== "object") {
-    logger.warn("task frontmatter is not an object", { filePath });
+    logger.warn("failed to parse task YAML", { filePath, error: String(err) });
     return null;
   }
 
@@ -106,19 +80,19 @@ export function parseMarkdownTask(filePath: string): MarkdownTask | null {
     }
     target = { kind: "command", cmd };
   } else if (fm.prompt !== undefined) {
-    if (fm.prompt !== "inline") {
-      // Future: handle asset-ref and file-path prompt sources
-      logger.warn("task 'prompt' supports only 'inline' currently", { filePath });
+    if (typeof fm.prompt !== "string" || !fm.prompt.trim()) {
+      logger.warn("task 'prompt' must be a non-empty string", { filePath });
       return null;
     }
-    if (!parts.body) {
-      logger.warn("prompt:inline task has no markdown body", { filePath });
+    const promptBody = fm.prompt.trim() === "inline" ? body.trim() : fm.prompt.trim();
+    if (!promptBody) {
+      logger.warn("task prompt body is empty", { filePath });
       return null;
     }
     target = {
       kind: "prompt",
       profile: typeof fm.profile === "string" ? fm.profile : undefined,
-      body: parts.body,
+      body: promptBody,
     };
   } else if (fm.workflow !== undefined) {
     if (typeof fm.workflow !== "string") {
@@ -149,13 +123,19 @@ export function parseMarkdownTask(filePath: string): MarkdownTask | null {
   };
 }
 
+function splitTaskSource(raw: string): { frontmatter: string; body: string } {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: raw, body: "" };
+  return { frontmatter: match[1] ?? "", body: match[2] ?? "" };
+}
+
 export function loadMarkdownTasks(stashDir: string): MarkdownTask[] {
   const dir = join(stashDir, "tasks");
   if (!existsSync(dir)) return [];
 
   const tasks: MarkdownTask[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() || (!entry.name.endsWith(".md") && !entry.name.endsWith(".yml") && !entry.name.endsWith(".yaml"))) continue;
     const task = parseMarkdownTask(join(dir, entry.name));
     if (task) tasks.push(task);
   }
@@ -195,6 +175,6 @@ export function taskToAutomationConfig(task: MarkdownTask): AutomationConfig {
       agent,
     },
     on_failure: "log",
-    fileName: `${task.id}.md`,
+    fileName: basename(task.source.path),
   };
 }

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}`);
+  });
+});