@pleri/olam-cli 0.1.11 → 0.1.13

package/dist/index.js

@@ -421,8 +421,8 @@ var init_parseUtil = __esm({
     init_errors();
     init_en();
     makeIssue = (params) => {
-      const { data, path: path32, errorMaps, issueData } = params;
-      const fullPath = [...path32, ...issueData.path || []];
+      const { data, path: path35, errorMaps, issueData } = params;
+      const fullPath = [...path35, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -730,11 +730,11 @@ var init_types = __esm({
     init_parseUtil();
     init_util();
     ParseInputLazyPath = class {
-      constructor(parent, value, path32, key) {
+      constructor(parent, value, path35, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path32;
+        this._path = path35;
         this._key = key;
       }
       get path() {
@@ -4221,7 +4221,7 @@ import YAML from "yaml";
 function bootstrapStepCmd(entry) {
   return typeof entry === "string" ? entry : entry.cmd;
 }
-function refineForbiddenKeys(value, path32, ctx, rejectSource) {
+function refineForbiddenKeys(value, path35, ctx, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
@@ -4229,12 +4229,12 @@ function refineForbiddenKeys(value, path32, ctx, rejectSource) {
     if (FORBIDDEN_KEYS.has(key)) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
-        path: [...path32, key],
+        path: [...path35, key],
         message: `forbidden key "${key}" (prototype-pollution surface)`
       });
       continue;
     }
-    if (rejectSource && path32.length === 0 && key === "source") {
+    if (rejectSource && path35.length === 0 && key === "source") {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: ["source"],
@@ -4244,30 +4244,30 @@ function refineForbiddenKeys(value, path32, ctx, rejectSource) {
     }
     refineForbiddenKeys(
       value[key],
-      [...path32, key],
+      [...path35, key],
       ctx,
       false
     );
   }
 }
-function rejectForbiddenKeys(value, path32, rejectSource) {
+function rejectForbiddenKeys(value, path35, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
   for (const key of Object.keys(value)) {
     if (FORBIDDEN_KEYS.has(key)) {
       throw new Error(
-        `[manifest] ${path32}: forbidden key "${key}" (prototype-pollution surface)`
+        `[manifest] ${path35}: forbidden key "${key}" (prototype-pollution surface)`
       );
     }
     if (rejectSource && key === "source") {
       throw new Error(
-        `[manifest] ${path32}: top-level "source" is loader-stamped \u2014 manifests must not author it`
+        `[manifest] ${path35}: top-level "source" is loader-stamped \u2014 manifests must not author it`
       );
     }
     rejectForbiddenKeys(
       value[key],
-      `${path32}.${key}`,
+      `${path35}.${key}`,
       false
     );
   }
@@ -5208,8 +5208,8 @@ var init_client = __esm({
           throw new Error(`failed to report rate-limit for ${accountId} (HTTP ${res.status})`);
         }
       }
-      async request(method, path32, body, attempt = 0) {
-        const url = `${this.baseUrl}${path32}`;
+      async request(method, path35, body, attempt = 0) {
+        const url = `${this.baseUrl}${path35}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         const headers = {};
@@ -5225,7 +5225,7 @@ var init_client = __esm({
         } catch (err) {
           if (attempt < RETRY_COUNT && isTransient(err)) {
             await sleep(RETRY_BACKOFF_MS * (attempt + 1));
-            return this.request(method, path32, body, attempt + 1);
+            return this.request(method, path35, body, attempt + 1);
           }
           throw err;
         } finally {
@@ -6676,8 +6676,8 @@ var init_provider3 = __esm({
       // -----------------------------------------------------------------------
       // Internal fetch helper
       // -----------------------------------------------------------------------
-      async request(path32, method, body) {
-        const url = `${this.config.workerUrl}${path32}`;
+      async request(path35, method, body) {
+        const url = `${this.config.workerUrl}${path35}`;
         const bearer = await this.config.mintToken();
         const headers = {
           Authorization: `Bearer ${bearer}`
@@ -7790,8 +7790,8 @@ import { execFileSync as execFileSync3 } from "node:child_process";
 import * as fs13 from "node:fs";
 import * as os9 from "node:os";
 import * as path14 from "node:path";
-function expandHome(p, homedir15) {
-  return p.replace(/^~(?=$|\/|\\)/, homedir15());
+function expandHome(p, homedir17) {
+  return p.replace(/^~(?=$|\/|\\)/, homedir17());
 }
 function sanitizeRepoFilename(name) {
   const sanitized = name.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -7812,7 +7812,7 @@ ${stderr}`;
 }
 function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
   const exec = deps.exec ?? ((cmd, args, opts) => execFileSync3(cmd, args, opts));
-  const homedir15 = deps.homedir ?? (() => os9.homedir());
+  const homedir17 = deps.homedir ?? (() => os9.homedir());
   const baselineDir = path14.join(workspacePath, ".olam", "baseline");
   try {
     fs13.mkdirSync(baselineDir, { recursive: true });
@@ -7827,7 +7827,7 @@ function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
     if (!repo.path) continue;
     const filename = `${sanitizeRepoFilename(repo.name)}.diff`;
     const outPath = path14.join(baselineDir, filename);
-    const repoPath = expandHome(repo.path, homedir15);
+    const repoPath = expandHome(repo.path, homedir17);
     if (!fs13.existsSync(repoPath)) {
       writeBaselineFile(outPath, `# repo: ${repo.name}
 # (skipped: path ${repoPath} does not exist)
@@ -11780,6 +11780,61 @@ var init_context = __esm({
   }
 });
 
+// src/registry-allowlist.ts
+var registry_allowlist_exports = {};
+__export(registry_allowlist_exports, {
+  decideAllowlist: () => decideAllowlist,
+  resolveDevboxImageOverride: () => resolveDevboxImageOverride
+});
+function decideAllowlist(input) {
+  const { imageRef, allowCustomRegistry } = input;
+  const allowedByDefault = DEFAULT_ALLOWLIST_PATTERNS.some((re) => re.test(imageRef));
+  if (allowedByDefault) {
+    return {
+      imageRef,
+      allowedByDefault: true,
+      accepted: true,
+      stderrLine: ""
+    };
+  }
+  if (allowCustomRegistry) {
+    return {
+      imageRef,
+      allowedByDefault: false,
+      accepted: true,
+      stderrLine: `Warning: using custom devbox image '${imageRef}'. (--allow-custom-registry was specified.) Verify the source and digest before proceeding.`
+    };
+  }
+  return {
+    imageRef,
+    allowedByDefault: false,
+    accepted: false,
+    stderrLine: `Error: image '${imageRef}' is outside allowed registries (ghcr.io/pleri/*).
+  To override: re-run with --allow-custom-registry
+  Verify the source and digest before doing so.`
+  };
+}
+function resolveDevboxImageOverride(flagValue, env = process.env) {
+  if (flagValue && flagValue.trim().length > 0) {
+    return flagValue.trim();
+  }
+  const envValue = env.OLAM_DEVBOX_IMAGE;
+  if (envValue && envValue.trim().length > 0) {
+    return envValue.trim();
+  }
+  return void 0;
+}
+var DEFAULT_ALLOWLIST_PATTERNS;
+var init_registry_allowlist = __esm({
+  "src/registry-allowlist.ts"() {
+    "use strict";
+    DEFAULT_ALLOWLIST_PATTERNS = [
+      // ghcr.io/pleri/<anything>:<tag> or ghcr.io/pleri/<anything>@sha256:<digest>
+      /^ghcr\.io\/pleri\/[^/\s]+(?::[^\s]+|@sha256:[a-f0-9]+)?$/
+    ];
+  }
+});
+
 // ../core/src/orchestrator/enter.ts
 var enter_exports = {};
 __export(enter_exports, {
@@ -12249,11 +12304,11 @@ var UnknownArchetypeError = class extends Error {
   known;
 };
 var ArchetypeCycleError = class extends Error {
-  constructor(path32) {
+  constructor(path35) {
     super(
-      `Archetype inheritance cycle detected: ${path32.join(" \u2192 ")} \u2192 ${path32[0] ?? "?"}`
+      `Archetype inheritance cycle detected: ${path35.join(" \u2192 ")} \u2192 ${path35[0] ?? "?"}`
     );
-    this.path = path32;
+    this.path = path35;
     this.name = "ArchetypeCycleError";
   }
   path;
@@ -12496,6 +12551,13 @@ function nextCooldownReset(accounts, now = Date.now()) {
 
 // src/commands/auth-status.ts
 init_auth();
+
+// src/exit-codes.ts
+var EXIT_GENERIC_ERROR = 1;
+var EXIT_PLERI_NOT_CONFIGURED = 2;
+var EXIT_AUTH_NEEDS_ATTENTION = 5;
+
+// src/commands/auth-status.ts
 var LOCAL_DATA_DIR = path9.join(os5.homedir(), ".olam", "auth-data");
 function localHHMM(isoStr) {
   const d = new Date(isoStr);
@@ -12572,7 +12634,7 @@ function formatAuthStatus(accounts, now = Date.now()) {
     lines.push(
       resetIso ? pc5.yellow(`Next reset: ${localHHMM(resetIso)}`) : pc5.dim("No reset scheduled")
     );
-    return { output: lines.join("\n"), exitCode: 2 };
+    return { output: lines.join("\n"), exitCode: EXIT_AUTH_NEEDS_ATTENTION };
   }
   return { output: lines.join("\n"), exitCode: 0 };
 }
@@ -13065,10 +13127,10 @@ async function readHostCpToken2() {
   if (!fs19.existsSync(tp)) return null;
   return fs19.readFileSync(tp, "utf-8").trim();
 }
-async function callHostCpProxy(method, worldId, path32, body) {
+async function callHostCpProxy(method, worldId, path35, body) {
   const token = await readHostCpToken2();
   if (!token) return { ok: false, status: 0, error: "no token (host CP not started)" };
-  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path32}`;
+  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path35}`;
   try {
     const headers = {
       Authorization: `Bearer ${token}`
@@ -13679,9 +13741,9 @@ function formatFreshnessWarning(result, image = DEFAULT_DEVBOX_IMAGE) {
     "These source files have changed since the image was built; the",
     "changes will NOT take effect in fresh worlds until you rebuild:"
   ];
-  for (const { path: path32, mtimeMs } of result.newerSources) {
+  for (const { path: path35, mtimeMs } of result.newerSources) {
     const when = new Date(mtimeMs).toISOString();
-    lines.push(`  \u2022 ${path32}  (modified ${when})`);
+    lines.push(`  \u2022 ${path35}  (modified ${when})`);
   }
   lines.push("");
   lines.push("Rebuild with:");
@@ -13841,15 +13903,15 @@ init_context();
 var HOST_CP_URL = "http://127.0.0.1:19000";
 async function readHostCpTokenForCreate() {
   try {
-    const { default: fs28 } = await import("node:fs");
-    const { default: os16 } = await import("node:os");
-    const { default: path32 } = await import("node:path");
-    const tp = path32.join(
-      process.env.OLAM_HOME ?? path32.join(os16.homedir(), ".olam"),
+    const { default: fs31 } = await import("node:fs");
+    const { default: os18 } = await import("node:os");
+    const { default: path35 } = await import("node:path");
+    const tp = path35.join(
+      process.env.OLAM_HOME ?? path35.join(os18.homedir(), ".olam"),
       "host-cp.token"
     );
-    if (!fs28.existsSync(tp)) return null;
-    return fs28.readFileSync(tp, "utf-8").trim();
+    if (!fs31.existsSync(tp)) return null;
+    return fs31.readFileSync(tp, "utf-8").trim();
   } catch {
     return null;
   }
@@ -13858,7 +13920,23 @@ function registerCreate(program2) {
   program2.command("create").description("Create a new development world").option("--name <name>", "World name (required unless --from-prompt is set; auto-derived in that case)").option("--repos <repos...>", "Repos to include (names from .olam/config.yaml; wins over --workspace)").option("--workspace <name>", "Named workspace from the host catalog (~/.olam/workspaces/<name>.yaml)").option("--task <task>", "Initial task to dispatch").option("--branch <branch>", "Override default branch name").option("--plan <file>", "Path to a plan file to inject").option("--no-auth", "Skip auto-injecting host credentials").option("--no-host-cp", 'Suppress the host CP "you might want to start it" hint').option("--auto-codex-review", "Spawn a parallel codex-review lane that critiques main as it works").option("--no-open", "Suppress auto-opening the Host CP UI in the browser on success").option("--rebuild-base", "Rebuild olam-devbox:latest before creating (slow)").option("--no-freshness-check", "Skip the devbox image freshness check").option("--from-prompt <prompt>", "NL prompt \u2192 infer workspace + dispatch (CLI parity for olam_create_from_prompt MCP tool)").option("--keep-after-merge", "Disable auto-destroy when the world's PR merges (useful for inspection/debugging)").option("--carry-uncommitted", "Preserve operator's uncommitted edits in the world's worktree").option(
     "--allow-bootstrap-failure",
     "Treat bootstrap step failures as warnings instead of destroying the world (dogfood escape hatch for cross-repo seed coupling)"
-  ).action(async (opts) => {
+  ).option("--devbox-image <ref>", "Override the default devbox image (full registry/name:tag or @sha256: ref)").option("--allow-custom-registry", "Allow --devbox-image refs outside ghcr.io/pleri/* (logs a warning)").action(async (opts) => {
+    const { resolveDevboxImageOverride: resolveDevboxImageOverride2, decideAllowlist: decideAllowlist2 } = await Promise.resolve().then(() => (init_registry_allowlist(), registry_allowlist_exports));
+    const overrideRef = resolveDevboxImageOverride2(opts.devboxImage);
+    if (overrideRef) {
+      const decision = decideAllowlist2({
+        imageRef: overrideRef,
+        allowCustomRegistry: opts.allowCustomRegistry === true
+      });
+      if (!decision.accepted) {
+        process.stderr.write(decision.stderrLine + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      if (decision.stderrLine) {
+        process.stderr.write(decision.stderrLine + "\n");
+      }
+    }
     let resolvedName = opts.name;
     let resolvedWorkspace = opts.workspace;
     let resolvedRepos = opts.repos;
@@ -14163,12 +14241,12 @@ function defaultNameFromPrompt(prompt) {
 }
 async function readHostCpToken3() {
   try {
-    const { default: fs28 } = await import("node:fs");
-    const { default: os16 } = await import("node:os");
-    const { default: path32 } = await import("node:path");
-    const tp = path32.join(os16.homedir(), ".olam", "host-cp.token");
-    if (!fs28.existsSync(tp)) return null;
-    const raw = fs28.readFileSync(tp, "utf-8").trim();
+    const { default: fs31 } = await import("node:fs");
+    const { default: os18 } = await import("node:os");
+    const { default: path35 } = await import("node:path");
+    const tp = path35.join(os18.homedir(), ".olam", "host-cp.token");
+    if (!fs31.existsSync(tp)) return null;
+    const raw = fs31.readFileSync(tp, "utf-8").trim();
     return raw.length > 0 ? raw : null;
   } catch {
     return null;
@@ -14602,29 +14680,38 @@ import * as fs21 from "node:fs";
 import "node:path";
 import ora4 from "ora";
 init_world_paths();
-function registerCrystallize(program2) {
-  program2.command("crystallize").description("Crystallize thoughts from a world to Pleri Plane").argument("<world>", "World ID").action(async (worldId) => {
+function registerCrystallize(program2, options = {}) {
+  const cmd = program2.command("crystallize").description("Crystallize thoughts from a world to Pleri Plane").argument("<world>", "World ID").action(async (worldId) => {
     const { ctx, error } = await loadContext();
+    if (!ctx && error?.name === "OlamConfigNotFoundError") {
+      process.stderr.write(
+        "warn: crystallize requires PLERI_BASE_URL \u2014 skipping (Olam is not initialised; run `olam init` to set up a PLERI block, then re-run).\n"
+      );
+      process.exitCode = EXIT_PLERI_NOT_CONFIGURED;
+      return;
+    }
     if (!ctx) {
       printError(error?.message ?? "Olam is not configured. Run `olam init` first.");
-      process.exitCode = 1;
+      process.exitCode = EXIT_GENERIC_ERROR;
       return;
     }
     if (!ctx.pleriClient) {
-      printError("Pleri Plane is not configured. Add pleri section to .olam/config.yaml.");
-      process.exitCode = 1;
+      process.stderr.write(
+        "warn: crystallize requires PLERI_BASE_URL \u2014 skipping (no work performed). Configure pleri in .olam/config.yaml or set PLERI_BASE_URL to enable.\n"
+      );
+      process.exitCode = EXIT_PLERI_NOT_CONFIGURED;
       return;
     }
     const world = ctx.worldManager.getWorld(worldId);
     if (!world) {
       printError(`World "${worldId}" not found.`);
-      process.exitCode = 1;
+      process.exitCode = EXIT_GENERIC_ERROR;
       return;
     }
     const thoughtDbPath = getWorldDbPath(world.workspacePath);
     if (!fs21.existsSync(thoughtDbPath)) {
       printError(`No thoughts captured yet for "${worldId}". Run a dispatch first.`);
-      process.exitCode = 1;
+      process.exitCode = EXIT_GENERIC_ERROR;
       return;
     }
     const spinner = ora4("Crystallizing thoughts...").start();
@@ -14682,9 +14769,12 @@ function registerCrystallize(program2) {
     } catch (err) {
       spinner.fail("Crystallization failed");
       printError(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
+      process.exitCode = EXIT_GENERIC_ERROR;
     }
   });
+  if (options.hidden) {
+    cmd._hidden = true;
+  }
 }
 
 // src/commands/pr.ts
@@ -16821,17 +16911,246 @@ function registerPolicyCheck(program2) {
 }
 
 // src/commands/upgrade.ts
+import * as fs24 from "node:fs";
+import * as path28 from "node:path";
+import { spawnSync as spawnSync7 } from "node:child_process";
+import pc15 from "picocolors";
+
+// src/commands/upgrade-lock.ts
 import * as fs22 from "node:fs";
+import * as os13 from "node:os";
 import * as path26 from "node:path";
 import { spawnSync as spawnSync6 } from "node:child_process";
-import pc15 from "picocolors";
+var LOCK_FILE_PATH = path26.join(os13.homedir(), ".olam", ".upgrade.lock");
+var STALE_LOCK_TIMEOUT_MS = 5 * 60 * 1e3;
+function readLockFile(lockPath) {
+  try {
+    if (!fs22.existsSync(lockPath)) return null;
+    const raw = fs22.readFileSync(lockPath, "utf-8").trim();
+    if (raw.length === 0) return null;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid !== "number" || typeof parsed.startTs !== "number") return null;
+    return { pid: parsed.pid, startTs: parsed.startTs };
+  } catch {
+    return null;
+  }
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var PS_UNAVAILABLE = "__ps_unavailable__";
+function getPidCommand(pid) {
+  const result = spawnSync6("ps", ["-p", String(pid), "-o", "comm="], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status === null || result.error !== void 0) return PS_UNAVAILABLE;
+  if (result.status !== 0) return null;
+  const out = result.stdout.trim();
+  return out.length === 0 ? null : out;
+}
+function isOlamUpgradeCommand(comm) {
+  if (!comm) return false;
+  if (comm === PS_UNAVAILABLE) return false;
+  const base = comm.split("/").pop() ?? comm;
+  const stripped = base.replace(/\s*\(.*\)\s*$/, "").trim();
+  return stripped === "node" || stripped === "olam" || stripped === "olam-cli";
+}
+function isStaleLock(content, nowMs = Date.now()) {
+  if (!content) return true;
+  if (nowMs - content.startTs > STALE_LOCK_TIMEOUT_MS) return true;
+  if (!isPidAlive(content.pid)) return true;
+  const comm = getPidCommand(content.pid);
+  if (comm === PS_UNAVAILABLE) return false;
+  if (!isOlamUpgradeCommand(comm)) return true;
+  return false;
+}
+function acquireLock(lockPath = LOCK_FILE_PATH, nowMs = Date.now()) {
+  const dir = path26.dirname(lockPath);
+  fs22.mkdirSync(dir, { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs22.openSync(lockPath, "wx", 420);
+      try {
+        const content = { pid: process.pid, startTs: nowMs };
+        fs22.writeSync(fd, JSON.stringify(content));
+      } finally {
+        fs22.closeSync(fd);
+      }
+      return { acquired: true, lockPath };
+    } catch (err) {
+      const code = err.code;
+      if (code !== "EEXIST") throw err;
+      const existing2 = readLockFile(lockPath);
+      if (isStaleLock(existing2, nowMs)) {
+        try {
+          fs22.unlinkSync(lockPath);
+        } catch (unlinkErr) {
+          const ucode = unlinkErr.code;
+          if (ucode !== "ENOENT") throw unlinkErr;
+        }
+        continue;
+      }
+      return {
+        acquired: false,
+        reason: "live",
+        ...existing2?.pid !== void 0 && { existingPid: existing2.pid },
+        ...existing2?.startTs !== void 0 && { existingStartTs: existing2.startTs }
+      };
+    }
+  }
+  const existing = readLockFile(lockPath);
+  return {
+    acquired: false,
+    reason: "live",
+    ...existing?.pid !== void 0 && { existingPid: existing.pid },
+    ...existing?.startTs !== void 0 && { existingStartTs: existing.startTs }
+  };
+}
+function releaseLock(lockPath = LOCK_FILE_PATH) {
+  try {
+    fs22.unlinkSync(lockPath);
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") throw err;
+  }
+}
+function formatRefusalMessage(result, lockPath = LOCK_FILE_PATH) {
+  const pidStr = result.existingPid !== void 0 ? ` (pid ${result.existingPid})` : "";
+  const lines = [
+    `Upgrade in progress${pidStr}.`,
+    "Wait for the running upgrade to finish, or:",
+    "  - Check progress: olam upgrade --history",
+    `  - If stale (crashed CLI): rm ${lockPath}`
+  ];
+  return lines.join("\n");
+}
+
+// src/commands/upgrade-log.ts
+import * as fs23 from "node:fs";
+import * as os14 from "node:os";
+import * as path27 from "node:path";
+function getUpgradeLogPath() {
+  const home = process.env["HOME"] ?? os14.homedir();
+  return path27.join(home, ".olam", "upgrade.log");
+}
+var UPGRADE_LOG_PATH = getUpgradeLogPath();
+function appendUpgradeLog(row, logPath = getUpgradeLogPath()) {
+  try {
+    fs23.mkdirSync(path27.dirname(logPath), { recursive: true });
+    const line = JSON.stringify(row) + "\n";
+    fs23.appendFileSync(logPath, line, { mode: 420 });
+  } catch (err) {
+    process.stderr.write(
+      `[upgrade-log] failed to append: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+}
+function readUpgradeLog(limit = 10, logPath = getUpgradeLogPath()) {
+  if (!fs23.existsSync(logPath)) return [];
+  let raw;
+  try {
+    raw = fs23.readFileSync(logPath, "utf-8");
+  } catch (err) {
+    process.stderr.write(
+      `[upgrade-log] failed to read: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return [];
+  }
+  const lines = raw.split("\n").filter((l) => l.length > 0);
+  const rows = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    try {
+      const parsed = JSON.parse(line);
+      if (typeof parsed.ts === "string" && typeof parsed.started_at === "number" && typeof parsed.status === "string") {
+        rows.push(parsed);
+      } else {
+        process.stderr.write(`[upgrade-log] skipped malformed row at line ${i + 1}
+`);
+      }
+    } catch {
+      process.stderr.write(`[upgrade-log] skipped corrupt JSON at line ${i + 1}
+`);
+    }
+  }
+  return rows.slice(-Math.max(0, limit));
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  const totalSec = Math.round(ms / 1e3);
+  if (totalSec < 60) return `${totalSec}s`;
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min < 60) return `${min}m${String(sec).padStart(2, "0")}s`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return `${hr}h${String(remMin).padStart(2, "0")}m`;
+}
+function formatHistoryTable(rows) {
+  if (rows.length === 0) {
+    return "No upgrade history yet. Run `olam upgrade` to create your first record.";
+  }
+  const lines = [];
+  lines.push("TIMESTAMP                   SHA       STATUS         DURATION   FAILED-STEP");
+  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  for (const r of rows) {
+    const ts = r.ts.slice(0, 19).replace("T", " ");
+    const sha = r.sha_target.slice(0, 8);
+    const statusIcon = r.status === "success" ? "\u2713 success" : r.status === "rolled_back" ? "\u21A9 rolled_back" : "\u2717 failed";
+    const dur = formatDuration(r.ended_at - r.started_at);
+    const failed = r.failed_step ?? "";
+    lines.push(
+      `${ts.padEnd(28)}${sha.padEnd(10)}${statusIcon.padEnd(15)}${dur.padEnd(11)}${failed}`
+    );
+  }
+  return lines.join("\n");
+}
+function formatHistoryJson(rows) {
+  return rows.map((r) => JSON.stringify(r)).join("\n");
+}
+
+// src/commands/upgrade-history.ts
+function parseHistoryOpts(raw) {
+  const rawLimit = raw.n;
+  const limit = typeof rawLimit === "number" ? rawLimit : typeof rawLimit === "string" ? Number.parseInt(rawLimit, 10) : 10;
+  return {
+    limit: Number.isFinite(limit) && limit > 0 ? limit : 10,
+    json: raw.json === true
+  };
+}
+function handleHistory(opts) {
+  const rows = readUpgradeLog(opts.limit);
+  if (opts.json) {
+    process.stdout.write(formatHistoryJson(rows) + "\n");
+    return;
+  }
+  if (rows.length === 0) {
+    printInfo("Log file", UPGRADE_LOG_PATH);
+    process.stdout.write(formatHistoryTable(rows) + "\n");
+    return;
+  }
+  printInfo("Log file", UPGRADE_LOG_PATH);
+  process.stdout.write(formatHistoryTable(rows) + "\n");
+}
+
+// src/commands/upgrade.ts
+init_auth();
+var AUTH_HEALTH_URL2 = "http://127.0.0.1:9999/health";
 function isNodeModulesInSync(cwd) {
-  const lockPath = path26.join(cwd, "package-lock.json");
-  const markerPath = path26.join(cwd, "node_modules", ".package-lock.json");
-  if (!fs22.existsSync(lockPath) || !fs22.existsSync(markerPath)) return false;
+  const lockPath = path28.join(cwd, "package-lock.json");
+  const markerPath = path28.join(cwd, "node_modules", ".package-lock.json");
+  if (!fs24.existsSync(lockPath) || !fs24.existsSync(markerPath)) return false;
   try {
-    const lockStat = fs22.statSync(lockPath);
-    const markerStat = fs22.statSync(markerPath);
+    const lockStat = fs24.statSync(lockPath);
+    const markerStat = fs24.statSync(markerPath);
     return markerStat.mtimeMs >= lockStat.mtimeMs;
   } catch {
     return false;
@@ -16847,8 +17166,8 @@ function shouldSkipInstall(opts, cwd) {
   return { skip: false };
 }
 function validateRepoRoot(cwd) {
-  const marker = path26.join(cwd, "packages/host-cp/compose.yaml");
-  if (!fs22.existsSync(marker)) {
+  const marker = path28.join(cwd, "packages/host-cp/compose.yaml");
+  if (!fs24.existsSync(marker)) {
     return {
       ok: false,
       error: `Not an olam repo root (expected ${marker}).
@@ -16858,11 +17177,19 @@ Run \`olam upgrade\` from the root of your olam checkout.`
   return { ok: true };
 }
 function parseUpgradeOpts(raw) {
+  const rawN = raw.n;
+  const historyN = typeof rawN === "number" ? rawN : typeof rawN === "string" ? Number.parseInt(rawN, 10) : 10;
   return {
     yes: raw.yes === true,
     skipImage: raw.skipImage === true,
     skipInstall: raw.skipInstall === true,
-    branch: raw.branch ?? null
+    branch: raw.branch ?? null,
+    rollback: raw.rollback === true,
+    force: raw.force === true,
+    noCache: raw.noCache === true,
+    history: raw.history === true,
+    historyN: Number.isFinite(historyN) && historyN > 0 ? historyN : 10,
+    historyJson: raw.json === true
   };
 }
 function extractBundleHash(indexHtml) {
@@ -16872,7 +17199,7 @@ function extractBundleHash(indexHtml) {
 function runStep2(label, cmd, args, opts = {}) {
   const start = Date.now();
   process.stdout.write(`  ${pc15.dim(label.padEnd(34))}`);
-  const result = spawnSync6(cmd, [...args], {
+  const result = spawnSync7(cmd, [...args], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd: opts.cwd ?? process.cwd(),
@@ -16891,7 +17218,7 @@ function runStep2(label, cmd, args, opts = {}) {
   };
 }
 function isGitDirty(cwd) {
-  const result = spawnSync6("git", ["status", "--porcelain"], {
+  const result = spawnSync7("git", ["status", "--porcelain"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd
@@ -16899,13 +17226,194 @@ function isGitDirty(cwd) {
   return (result.stdout ?? "").trim().length > 0;
 }
 function hasGitUpstream(cwd) {
-  const result = spawnSync6("git", ["rev-parse", "--abbrev-ref", "@{u}"], {
+  const result = spawnSync7("git", ["rev-parse", "--abbrev-ref", "@{u}"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd
   });
   return result.status === 0;
 }
+function captureHeadSha(cwd) {
+  const result = spawnSync7("git", ["rev-parse", "HEAD"], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    cwd
+  });
+  if (result.status !== 0) return null;
+  const sha = (result.stdout ?? "").trim();
+  if (!/^[0-9a-f]{40}$/.test(sha)) return null;
+  return sha;
+}
+function abbreviateSha(sha) {
+  return sha.slice(0, 8);
+}
+function imageExists(tag) {
+  try {
+    const result = spawnSync7("docker", ["image", "inspect", "--format", "{{.Id}}", tag], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+function checkRollbackSetExists(plan) {
+  const missing = plan.filter((p) => !imageExists(p.rollback)).map((p) => p.rollback);
+  if (missing.length === 0) return null;
+  return missing.join(", ");
+}
+function smokeImage(image, targetSha) {
+  const createResult = spawnSync7("docker", ["create", "--name", `olam-smoke-${Date.now()}`, image], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (createResult.status !== 0) {
+    return {
+      image,
+      ok: false,
+      bakedSha: null,
+      error: `docker create failed: ${(createResult.stderr ?? "").trim()}`
+    };
+  }
+  const containerId = (createResult.stdout ?? "").trim();
+  const inspectResult = spawnSync7(
+    "docker",
+    ["inspect", "--format", '{{index .Config.Labels "olam_build_sha"}}', image],
+    {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }
+  );
+  if (containerId.length > 0) {
+    spawnSync7("docker", ["rm", "-f", containerId], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+  }
+  if (inspectResult.status !== 0) {
+    return {
+      image,
+      ok: false,
+      bakedSha: null,
+      error: `docker inspect failed: ${(inspectResult.stderr ?? "").trim()}`
+    };
+  }
+  const bakedSha = (inspectResult.stdout ?? "").trim();
+  if (bakedSha.length === 0) {
+    return {
+      image,
+      ok: false,
+      bakedSha: null,
+      error: "olam_build_sha label is missing or empty"
+    };
+  }
+  if (bakedSha !== targetSha) {
+    return {
+      image,
+      ok: false,
+      bakedSha,
+      error: `baked SHA ${abbreviateSha(bakedSha)} \u2260 target SHA ${abbreviateSha(targetSha)}`
+    };
+  }
+  return { image, ok: true, bakedSha };
+}
+var PRODUCTION_SWAP_PLAN = [
+  { transient: "olam-auth:olam-next", canonical: "olam-auth:local", rollback: "olam-auth:olam-rollback" },
+  { transient: "olam-devbox:olam-next", canonical: "olam-devbox:latest", rollback: "olam-devbox:olam-rollback" },
+  { transient: "olam-host-cp:olam-next", canonical: "olam-host-cp:latest", rollback: "olam-host-cp:olam-rollback" }
+];
+function dockerTag(source, dest) {
+  try {
+    const result = spawnSync7("docker", ["tag", source, dest], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    if (result.status === 0 && result.error === void 0) return { ok: true };
+    return {
+      ok: false,
+      error: (result.stderr ?? "").trim() || result.error?.message || "docker tag failed"
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? `spawnSync threw: ${err.message}` : "spawnSync threw"
+    };
+  }
+}
+function performAtomicSwap(plan) {
+  const steps = plan.map((p) => ({
+    image: p.canonical,
+    rollbackSaved: false,
+    canonicalAdvanced: false
+  }));
+  for (let i = 0; i < plan.length; i++) {
+    const p = plan[i];
+    const r = dockerTag(p.canonical, p.rollback);
+    steps[i] = {
+      ...steps[i],
+      rollbackSaved: r.ok,
+      ...r.error !== void 0 && { rollbackError: r.error }
+    };
+  }
+  let advanceFailed = false;
+  let firstFailureIdx = -1;
+  for (let i = 0; i < plan.length; i++) {
+    const p = plan[i];
+    if (advanceFailed) {
+      steps[i] = { ...steps[i], canonicalAdvanced: false };
+      continue;
+    }
+    const r = dockerTag(p.transient, p.canonical);
+    steps[i] = {
+      ...steps[i],
+      canonicalAdvanced: r.ok,
+      ...r.error !== void 0 && { canonicalError: r.error }
+    };
+    if (!r.ok) {
+      advanceFailed = true;
+      firstFailureIdx = i;
+    }
+  }
+  const allAdvanced = steps.every((s) => s.canonicalAdvanced);
+  const noneAdvanced = steps.every((s) => !s.canonicalAdvanced);
+  const partialAdvance = !allAdvanced && !noneAdvanced;
+  const rollbackCoherent = steps.every((s) => s.rollbackSaved);
+  let summary;
+  if (allAdvanced) {
+    const rollbacks = steps.filter((s) => s.rollbackSaved).length;
+    summary = `Swapped ${plan.length} canonical tags; ${rollbacks} :olam-rollback preserved`;
+  } else if (partialAdvance) {
+    const advanced = steps.filter((s) => s.canonicalAdvanced).length;
+    const failedStep = steps[firstFailureIdx];
+    const recoveryHint = rollbackCoherent ? `Run \`olam upgrade --rollback\` to restore coherent prior state.` : `Rollback set INCOHERENT (${steps.filter((s) => s.rollbackSaved).length} of ${plan.length} :olam-rollback tags written). Manual recovery required: inspect images and re-tag canonical from a known-good source.`;
+    summary = `PARTIAL: ${advanced} of ${plan.length} canonical tags advanced before failure on ${failedStep?.image}: ${failedStep?.canonicalError}. ${recoveryHint}`;
+  } else {
+    const failedStep = steps[firstFailureIdx];
+    summary = `Failed on first canonical-advance (${failedStep?.image}): ${failedStep?.canonicalError}. Canonical tags untouched.`;
+  }
+  return {
+    ok: allAdvanced,
+    steps,
+    partialAdvance,
+    rollbackCoherent,
+    summary
+  };
+}
+function performRollbackSwap(plan) {
+  const results = [];
+  for (const p of plan) {
+    const r = dockerTag(p.rollback, p.canonical);
+    results.push({
+      image: p.canonical,
+      ok: r.ok,
+      ...r.error !== void 0 && { error: r.error }
+    });
+  }
+  const allOk = results.every((r) => r.ok);
+  const summary = allOk ? `Rolled back ${plan.length} canonical tags from :olam-rollback` : `PARTIAL rollback: ${results.filter((r) => r.ok).length} of ${plan.length} succeeded; failed: ${results.filter((r) => !r.ok).map((r) => r.image).join(", ")}`;
+  return { ok: allOk, results, summary };
+}
 async function confirm2(message) {
   if (!process.stdin.isTTY) return true;
   const { createInterface: createInterface2 } = await import("node:readline");
@@ -16931,10 +17439,87 @@ async function waitForHealth(timeoutMs = 1e4) {
   }
   return false;
 }
+async function waitForVersionMatch(targetSha, timeoutMs = 6e4, pollIntervalMs = 1e3) {
+  const deadline = Date.now() + timeoutMs;
+  let lastSnapshot = null;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch("http://127.0.0.1:19000/api/version/status", {
+        signal: AbortSignal.timeout(2e3)
+      });
+      if (res.ok) {
+        const snapshot = await res.json();
+        lastSnapshot = snapshot;
+        if (snapshot.hostCp?.running === targetSha && snapshot.authService?.running === targetSha && snapshot.devbox?.running === targetSha) {
+          return { matched: true, snapshot };
+        }
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  return { matched: false, snapshot: lastSnapshot };
+}
+function formatVersionMismatch(targetSha, snapshot) {
+  if (!snapshot) return "No /api/version/status response received within timeout.";
+  const lines = [];
+  for (const [name, comp] of [
+    ["host-cp", snapshot.hostCp],
+    ["auth-service", snapshot.authService],
+    ["devbox", snapshot.devbox]
+  ]) {
+    const match2 = comp?.running === targetSha;
+    lines.push(`  ${match2 ? "\u2713" : "\u2717"} ${name}: running=${abbreviateSha(comp?.running ?? "unknown")} target=${abbreviateSha(targetSha)}`);
+  }
+  return lines.join("\n");
+}
+async function waitForAuthHealthLocal(timeoutMs = 15e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(AUTH_HEALTH_URL2, { signal: AbortSignal.timeout(2e3) });
+      if (res.ok) return true;
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+async function recreateAuthService() {
+  const start = Date.now();
+  try {
+    spawnSync7("docker", ["stop", "olam-auth"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    spawnSync7("docker", ["rm", "olam-auth"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    const controller = new AuthContainerController();
+    controller.start();
+    const healthy = await waitForAuthHealthLocal(15e3);
+    const durationMs = Date.now() - start;
+    if (!healthy) {
+      return {
+        ok: false,
+        durationMs,
+        error: "auth-service /health did not respond within 15s after recreate"
+      };
+    }
+    return { ok: true, durationMs };
+  } catch (err) {
+    return {
+      ok: false,
+      durationMs: Date.now() - start,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
 function readBundleHash(cwd) {
-  const indexPath = path26.join(cwd, "packages/control-plane/public/index.html");
-  if (!fs22.existsSync(indexPath)) return null;
-  return extractBundleHash(fs22.readFileSync(indexPath, "utf-8"));
+  const indexPath = path28.join(cwd, "packages/control-plane/public/index.html");
+  if (!fs24.existsSync(indexPath)) return null;
+  return extractBundleHash(fs24.readFileSync(indexPath, "utf-8"));
 }
 async function handleUpgrade(opts) {
   const cwd = process.cwd();
@@ -16969,6 +17554,142 @@ async function handleUpgrade(opts) {
       return;
     }
   }
+  if (opts.history) {
+    handleHistory(parseHistoryOpts({ n: opts.historyN, json: opts.historyJson }));
+    return;
+  }
+  if (opts.rollback) {
+    return await handleRollback();
+  }
+  const lock = acquireLock();
+  if (!lock.acquired) {
+    printError(formatRefusalMessage(lock, LOCK_FILE_PATH));
+    process.exitCode = 1;
+    return;
+  }
+  let signalReleased = false;
+  const releaseOnSignal = (signal) => {
+    if (signalReleased) return;
+    signalReleased = true;
+    try {
+      releaseLock();
+    } catch {
+    }
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  };
+  process.once("SIGINT", releaseOnSignal);
+  process.once("SIGTERM", releaseOnSignal);
+  const logRow = {
+    started_at: Date.now(),
+    durations_ms: {},
+    sha_target: "",
+    failed_step: null,
+    status: "failed"
+    // default; flipped to 'success' on clean exit
+  };
+  try {
+    await runUpgradeStepsWithLockHeld(opts, cwd, logRow);
+    if (process.exitCode !== 1) logRow.status = "success";
+  } finally {
+    const ended_at = Date.now();
+    const row = {
+      ts: new Date(ended_at).toISOString(),
+      started_at: logRow.started_at,
+      ended_at,
+      sha_target: logRow.sha_target,
+      status: logRow.status,
+      failed_step: logRow.failed_step,
+      durations_ms: logRow.durations_ms
+    };
+    appendUpgradeLog(row);
+    releaseLock();
+    process.removeListener("SIGINT", releaseOnSignal);
+    process.removeListener("SIGTERM", releaseOnSignal);
+  }
+}
+async function handleRollback() {
+  printHeader("olam upgrade --rollback");
+  const missing = checkRollbackSetExists(PRODUCTION_SWAP_PLAN);
+  if (missing !== null) {
+    printError(
+      `No rollback-set available \u2014 missing :olam-rollback tag(s): ${missing}
+
+A rollback-set is created by the FIRST successful \`olam upgrade\`. If this
+is your first install, run \`olam upgrade\` to populate the rollback set.
+If a previous upgrade was incomplete, the rollback set may be partial;
+manually inspect images with \`docker images olam-*:olam-rollback\`.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const lock = acquireLock();
+  if (!lock.acquired) {
+    printError(formatRefusalMessage(lock, LOCK_FILE_PATH));
+    process.exitCode = 1;
+    return;
+  }
+  let signalReleased = false;
+  const releaseOnSignal = (signal) => {
+    if (signalReleased) return;
+    signalReleased = true;
+    try {
+      releaseLock();
+    } catch {
+    }
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  };
+  process.once("SIGINT", releaseOnSignal);
+  process.once("SIGTERM", releaseOnSignal);
+  try {
+    process.stdout.write(`  ${pc15.dim("rollback retag (3 ops)".padEnd(34))}`);
+    const swapStart = Date.now();
+    const swapResult = performRollbackSwap(PRODUCTION_SWAP_PLAN);
+    const swapDur = `${((Date.now() - swapStart) / 1e3).toFixed(1)}s`;
+    process.stdout.write(`${swapResult.ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${swapDur}
+`);
+    if (!swapResult.ok) {
+      printError(`Rollback retag failed: ${swapResult.summary}`);
+      process.exitCode = 1;
+      return;
+    }
+    printInfo("Rollback", swapResult.summary);
+    const cwd = process.cwd();
+    const composeFile = path28.join(cwd, "packages/host-cp/compose.yaml");
+    const authSecret = readAuthSecret2();
+    process.stdout.write(`  ${pc15.dim("docker compose recreate host-cp".padEnd(34))}`);
+    const composeStart = Date.now();
+    const composeResult = runCompose(["up", "-d", "--force-recreate", "host-cp"], composeFile, buildComposeEnv(authSecret));
+    const composeDur = `${((Date.now() - composeStart) / 1e3).toFixed(1)}s`;
+    process.stdout.write(`${composeResult.ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${composeDur}
+`);
+    if (!composeResult.ok) {
+      printError(
+        `Rollback compose recreate failed:
+${composeResult.stderr}
+Canonical tags are at :olam-rollback (good); container restart pending. Manually: \`docker compose -f packages/host-cp/compose.yaml up -d --force-recreate host-cp\`.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(`  ${pc15.dim("recreate auth-service".padEnd(34))}`);
+    const authResult = await recreateAuthService();
+    const authDur = `${(authResult.durationMs / 1e3).toFixed(1)}s`;
+    process.stdout.write(`${authResult.ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${authDur}
+`);
+    if (!authResult.ok) {
+      printError(`Auth-service recreate failed: ${authResult.error ?? "unknown"}`);
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write("\n");
+    printSuccess("Rollback complete \u2014 canonical tags restored from :olam-rollback");
+  } finally {
+    releaseLock();
+    process.removeListener("SIGINT", releaseOnSignal);
+    process.removeListener("SIGTERM", releaseOnSignal);
+  }
+}
+async function runUpgradeStepsWithLockHeld(opts, cwd, logRow) {
   if (opts.branch !== null) {
     if (isGitDirty(cwd)) {
       printError(
@@ -17026,6 +17747,17 @@ If there are conflicts, resolve them manually then re-run \`olam upgrade\`.`
     process.exitCode = 1;
     return;
   }
+  const _targetSha = captureHeadSha(cwd);
+  logRow.sha_target = _targetSha ?? "";
+  if (_targetSha === null) {
+    logRow.failed_step = "capture HEAD SHA";
+    printError(
+      "Failed to capture HEAD SHA via `git rev-parse HEAD`. Aborting upgrade.\nRe-run from a clean git checkout; ensure `git rev-parse HEAD` returns a 40-char SHA."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  printInfo("Target SHA", abbreviateSha(_targetSha));
   const installDecision = shouldSkipInstall(opts, cwd);
   if (installDecision.skip) {
     printInfo("npm install", `skipped \u2014 ${installDecision.reason}`);
@@ -17063,7 +17795,7 @@ ${buildResult.stderr}`);
     return;
   }
   const authSecret = readAuthSecret2();
-  const spaDir = path26.join(cwd, "packages/control-plane/app");
+  const spaDir = path28.join(cwd, "packages/control-plane/app");
   const spaResult = runStep2(
     "vite build (SPA)",
     "npx",
@@ -17085,21 +17817,107 @@ ${spaResult.stderr}`);
     printTimings2(timings);
     return;
   }
-  const buildScript = path26.join(cwd, "packages/adapters/src/docker/build-host-cp.sh");
-  const imageResult = runStep2(
-    "bash build-host-cp.sh",
-    "bash",
-    [buildScript],
-    { cwd }
-  );
-  timings.push({ label: "docker image build", durationMs: imageResult.durationMs });
-  if (!imageResult.ok) {
-    printError(`Docker image build failed:
-${imageResult.stderr}`);
+  const olamTagEnv = { OLAM_TAG: "olam-next" };
+  if (opts.noCache) {
+    olamTagEnv.DOCKER_BUILD_NO_CACHE = "1";
+  }
+  const buildScripts = [
+    { label: "bash build-auth.sh", relPath: "packages/adapters/src/docker/build-auth.sh", tee: false },
+    { label: "bash build-devbox.sh", relPath: "packages/adapters/src/docker/build-devbox.sh", tee: true },
+    { label: "bash build-host-cp.sh", relPath: "packages/adapters/src/docker/build-host-cp.sh", tee: false }
+  ];
+  for (const step of buildScripts) {
+    const scriptPath = path28.join(cwd, step.relPath);
+    if (step.tee) {
+      process.stdout.write(`  ${pc15.dim(step.label.padEnd(34))}
+`);
+      const start = Date.now();
+      const result = spawnSync7("bash", [scriptPath], {
+        stdio: "inherit",
+        cwd,
+        env: { ...process.env, ...olamTagEnv }
+      });
+      const durationMs = Date.now() - start;
+      const ok = result.status === 0 && result.error === void 0;
+      const dur = `${(durationMs / 1e3).toFixed(1)}s`;
+      process.stdout.write(`  ${pc15.dim(step.label.padEnd(34))}${ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${dur}
+`);
+      timings.push({ label: step.label, durationMs });
+      if (!ok) {
+        printError(`${step.label} failed (see output above for details).`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      const result = runStep2(step.label, "bash", [scriptPath], {
+        cwd,
+        env: olamTagEnv
+      });
+      timings.push({ label: step.label, durationMs: result.durationMs });
+      logRow.durations_ms[step.label] = result.durationMs;
+      if (!result.ok) {
+        logRow.failed_step = step.label;
+        printError(`${step.label} failed:
+${result.stderr.split("\n").slice(-3).join("\n")}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+  for (const t of timings) logRow.durations_ms[t.label] = t.durationMs;
+  const smokeStart = Date.now();
+  process.stdout.write(`  ${pc15.dim("smoke (docker create + inspect)".padEnd(34))}`);
+  const smokeImages = [
+    "olam-auth:olam-next",
+    "olam-devbox:olam-next",
+    "olam-host-cp:olam-next"
+  ];
+  const smokeResults = smokeImages.map((img) => smokeImage(img, _targetSha));
+  const smokeFailures = smokeResults.filter((r) => !r.ok);
+  const smokeDurationMs = Date.now() - smokeStart;
+  const smokeDur = `${(smokeDurationMs / 1e3).toFixed(1)}s`;
+  process.stdout.write(`${smokeFailures.length === 0 ? pc15.green("\u2713") : pc15.red("\u2717")} ${smokeDur}
+`);
+  timings.push({ label: "smoke", durationMs: smokeDurationMs });
+  if (smokeFailures.length > 0) {
+    printError(
+      `Smoke failed for ${smokeFailures.length} of ${smokeResults.length} images:
+` + smokeFailures.map((r) => `  - ${r.image}: ${r.error}`).join("\n") + "\nCanonical tags (`:latest`/`:local`) untouched. Investigate the failed image(s), then re-run `olam upgrade` (--no-cache if cache-poisoning suspected)."
+    );
     process.exitCode = 1;
     return;
   }
-  const composeFile = path26.join(cwd, "packages/host-cp/compose.yaml");
+  const swapBoundarySha = captureHeadSha(cwd);
+  if (swapBoundarySha !== null && swapBoundarySha !== _targetSha && !opts.force) {
+    printError(
+      `HEAD drifted during build window:
+  captured (after pull): ${abbreviateSha(_targetSha)}
+  current at swap:       ${abbreviateSha(swapBoundarySha)}
+
+Operator-driven \`git checkout\` or \`git reset\` triggered drift.
+Recovery options:
+  \u2022 Re-run \`olam upgrade\` (will rebuild against current HEAD).
+  \u2022 Pass \`--force\` to swap anyway (canonical advances to the
+    captured-at-pull SHA, NOT current HEAD).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`  ${pc15.dim("atomic 6-tag swap".padEnd(34))}`);
+  const swapStart = Date.now();
+  const swapResult = performAtomicSwap(PRODUCTION_SWAP_PLAN);
+  const swapDurationMs = Date.now() - swapStart;
+  const swapDur = `${(swapDurationMs / 1e3).toFixed(1)}s`;
+  process.stdout.write(`${swapResult.ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${swapDur}
+`);
+  timings.push({ label: "atomic swap", durationMs: swapDurationMs });
+  if (!swapResult.ok) {
+    printError(`Atomic swap failed: ${swapResult.summary}`);
+    process.exitCode = 1;
+    return;
+  }
+  printInfo("Swap", swapResult.summary);
+  const composeFile = path28.join(cwd, "packages/host-cp/compose.yaml");
   process.stdout.write(`  ${pc15.dim("docker compose recreate".padEnd(34))}`);
   const composeStart = Date.now();
   const composeResult = runCompose(
@@ -17114,8 +17932,33 @@ ${imageResult.stderr}`);
 `);
   timings.push({ label: "container recreate", durationMs: composeDurationMs });
   if (!composeOk) {
-    printError(`docker compose up --force-recreate failed:
-${composeResult.stderr}`);
+    printError(
+      `docker compose up --force-recreate failed:
+${composeResult.stderr}
+
+Canonical tags advanced to new SHA but the stack failed to start.
+Recovery options:
+  \u2022 Run \`olam upgrade --rollback\` to restore the prior :olam-rollback set, then investigate.
+  \u2022 Manually \`docker logs olam-host-cp\` to diagnose; if recoverable, retry recreate without rollback.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`  ${pc15.dim("recreate auth-service".padEnd(34))}`);
+  const authResult = await recreateAuthService();
+  const authDur = `${(authResult.durationMs / 1e3).toFixed(1)}s`;
+  process.stdout.write(`${authResult.ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${authDur}
+`);
+  timings.push({ label: "auth recreate", durationMs: authResult.durationMs });
+  if (!authResult.ok) {
+    printError(
+      `Auth-service recreate failed: ${authResult.error ?? "unknown"}
+
+Canonical tags advanced to new SHA; host-cp recreated but auth-service is broken.
+Recovery options:
+  \u2022 Run \`olam upgrade --rollback\` to restore the prior :olam-rollback set + working stack.
+  \u2022 Manually: \`docker logs olam-auth\` to diagnose; \`olam auth up\` to restart.`
+    );
     process.exitCode = 1;
     return;
   }
@@ -17128,7 +17971,23 @@ ${composeResult.stderr}`);
 `);
   timings.push({ label: "/health", durationMs: healthDurationMs });
   if (!healthy) {
-    printWarning("Host CP started but /health did not respond within 10s. Check: docker logs olam-host-cp");
+    printWarning(
+      "Host CP started but /health did not respond within 10s.\n  \u2022 Check: docker logs olam-host-cp\n  \u2022 If the new SHA is broken: `olam upgrade --rollback` restores the prior set in <30s."
+    );
+  }
+  process.stdout.write(`  ${pc15.dim("verify /version/status round-trip".padEnd(34))}`);
+  const versionStart = Date.now();
+  const versionMatch = await waitForVersionMatch(_targetSha, 6e4);
+  const versionDurationMs = Date.now() - versionStart;
+  const versionDur = `${(versionDurationMs / 1e3).toFixed(1)}s`;
+  process.stdout.write(`${versionMatch.matched ? pc15.green("\u2713") : pc15.yellow("?")} ${versionDur}
+`);
+  timings.push({ label: "/version/status round-trip", durationMs: versionDurationMs });
+  if (!versionMatch.matched) {
+    printWarning(
+      `Version round-trip incomplete after ${(versionDurationMs / 1e3).toFixed(0)}s:
+` + formatVersionMismatch(_targetSha, versionMatch.snapshot) + "\n  \u2022 Banner may still show UPDATE AVAILABLE until host-cp's next poll cycle (~60s).\n  \u2022 If the mismatch persists, `olam upgrade --rollback` restores the prior :olam-rollback set."
+    );
   }
   process.stdout.write("\n");
   printSuccess("Upgrade complete");
@@ -17145,10 +18004,22 @@ function printTimings2(timings) {
   printInfo("total", `${(total / 1e3).toFixed(1)}s`);
 }
 function registerUpgrade(program2) {
-  program2.command("upgrade").description("Self-upgrade the local Olam dev stack (pull + rebuild + restart host-cp)").option("-y, --yes", "Skip the confirmation prompt").option("--skip-image", "Skip docker image rebuild + container recreate (source rebuild only)").option(
+  program2.command("upgrade").description("Self-upgrade the local Olam dev stack (pull + rebuild + restart all three components)").option("-y, --yes", "Skip the confirmation prompt").option("--skip-image", "Skip docker image rebuild + container recreate (source rebuild only)").option(
     "--skip-install",
     "Skip npm install entirely (use existing node_modules as-is). Useful when a native-module build failure blocks the normal upgrade path."
-  ).option("--branch <name>", "Switch to this branch before pulling (refuses if working tree is dirty)").action(async (opts) => {
+  ).option("--branch <name>", "Switch to this branch before pulling (refuses if working tree is dirty)").option(
+    "--rollback",
+    "Restore canonical tags from the :olam-rollback set (created by the prior successful upgrade).\n                              No git pull, no build, no smoke \u2014 just retag + recreate."
+  ).option(
+    "--force",
+    "Bypass HEAD-drift refusal at the swap boundary. Swap advances canonical to the\n                              captured-at-pull SHA even if current HEAD differs."
+  ).option(
+    "--no-cache",
+    "Pass --no-cache to all three build scripts (DOCKER_BUILD_NO_CACHE=1).\n                              Useful when retrying after a cache-poisoning failure."
+  ).option(
+    "--history",
+    "Print the upgrade history (~/.olam/upgrade.log) and exit.\n                              No upgrade is performed."
+  ).option("-n <count>", "Number of history rows to print (default 10)", "10").option("--json", "Emit history as JSONL instead of a table").action(async (opts) => {
     await handleUpgrade(parseUpgradeOpts(opts));
   });
 }
@@ -17282,7 +18153,7 @@ function registerLogs(program2) {
 // src/commands/ps.ts
 init_context();
 import pc17 from "picocolors";
-import { spawnSync as spawnSync7 } from "node:child_process";
+import { spawnSync as spawnSync8 } from "node:child_process";
 var SAFE_IDENT4 = /^[a-z0-9][a-z0-9-]{0,63}$/;
 function parseDockerTop(stdout) {
   const trimmed = stdout.trim();
@@ -17382,7 +18253,7 @@ function registerPs(program2) {
     const containerName = `olam-${worldId}-devbox`;
     let watchInterval;
     function fetchAndPrint() {
-      const result = spawnSync7(
+      const result = spawnSync8(
         "docker",
         ["top", containerName, "pid", "user", "pcpu", "pmem", "stime", "stat", "cmd"],
         { encoding: "utf-8", timeout: 3e3 }
@@ -17418,20 +18289,20 @@ ${pc17.dim(`world: ${worldId}  sort: ${sortKey}  refresh: 5s  Ctrl-C to exit`)}
 }
 
 // src/commands/keys.ts
-import * as fs23 from "node:fs";
-import * as os13 from "node:os";
-import * as path27 from "node:path";
+import * as fs25 from "node:fs";
+import * as os15 from "node:os";
+import * as path29 from "node:path";
 import YAML4 from "yaml";
 function olamHome2() {
-  return process.env.OLAM_HOME ?? path27.join(os13.homedir(), ".olam");
+  return process.env.OLAM_HOME ?? path29.join(os15.homedir(), ".olam");
 }
 function keysFilePath() {
-  return path27.join(olamHome2(), "keys.yaml");
+  return path29.join(olamHome2(), "keys.yaml");
 }
 function readKeysFile() {
   const filePath = keysFilePath();
-  if (!fs23.existsSync(filePath)) return null;
-  const raw = fs23.readFileSync(filePath, "utf-8").trim();
+  if (!fs25.existsSync(filePath)) return null;
+  const raw = fs25.readFileSync(filePath, "utf-8").trim();
   if (raw.length === 0) return null;
   try {
     const parsed = YAML4.parse(raw);
@@ -17447,13 +18318,13 @@ function readKeysFile() {
 }
 function writeKeysFile(keys) {
   const dir = olamHome2();
-  if (!fs23.existsSync(dir)) {
-    fs23.mkdirSync(dir, { recursive: true });
+  if (!fs25.existsSync(dir)) {
+    fs25.mkdirSync(dir, { recursive: true });
   }
   const filePath = keysFilePath();
   const content = YAML4.stringify(keys);
-  fs23.writeFileSync(filePath, content, { encoding: "utf-8", mode: 384 });
-  fs23.chmodSync(filePath, 384);
+  fs25.writeFileSync(filePath, content, { encoding: "utf-8", mode: 384 });
+  fs25.chmodSync(filePath, 384);
 }
 function redact(value) {
   if (value.length <= 8) return value + "...";
@@ -17496,7 +18367,7 @@ function registerKeys(program2) {
       }
       const { [key]: _removed, ...rest } = existing;
       if (Object.keys(rest).length === 0) {
-        fs23.unlinkSync(keysFilePath());
+        fs25.unlinkSync(keysFilePath());
       } else {
         writeKeysFile(rest);
       }
@@ -17519,26 +18390,26 @@ function registerKeys(program2) {
 }
 
 // src/commands/world-snapshot.ts
-import * as fs25 from "node:fs";
-import * as path29 from "node:path";
+import * as fs27 from "node:fs";
+import * as path31 from "node:path";
 import { execSync as execSync9 } from "node:child_process";
 import pc18 from "picocolors";
 
 // ../core/src/world/snapshot.ts
 import * as crypto6 from "node:crypto";
-import * as fs24 from "node:fs";
-import * as os14 from "node:os";
-import * as path28 from "node:path";
+import * as fs26 from "node:fs";
+import * as os16 from "node:os";
+import * as path30 from "node:path";
 import { execFileSync as execFileSync4 } from "node:child_process";
 function snapshotsDir() {
-  return process.env["OLAM_SNAPSHOTS_DIR"] ?? path28.join(os14.homedir(), ".olam", "snapshots");
+  return process.env["OLAM_SNAPSHOTS_DIR"] ?? path30.join(os16.homedir(), ".olam", "snapshots");
 }
 function snapshotKindDir(worldId, kind) {
-  return path28.join(snapshotsDir(), worldId, kind);
+  return path30.join(snapshotsDir(), worldId, kind);
 }
 function snapshotTarPath(worldId, kind, repoName, hash) {
   const base = repoName ? `${repoName}-${hash}` : hash;
-  return path28.join(snapshotKindDir(worldId, kind), `${base}.tar.gz`);
+  return path30.join(snapshotKindDir(worldId, kind), `${base}.tar.gz`);
 }
 function manifestPath(tarPath) {
   return tarPath.replace(/\.tar\.gz$/, ".manifest.json");
@@ -17555,16 +18426,16 @@ function hashBuffers(entries) {
   return hash.digest("hex").slice(0, 12);
 }
 function computeGemsFingerprint(repoDir) {
-  const lockfile = path28.join(repoDir, "Gemfile.lock");
-  if (!fs24.existsSync(lockfile)) return null;
-  return hashBuffers([{ path: "Gemfile.lock", content: fs24.readFileSync(lockfile) }]);
+  const lockfile = path30.join(repoDir, "Gemfile.lock");
+  if (!fs26.existsSync(lockfile)) return null;
+  return hashBuffers([{ path: "Gemfile.lock", content: fs26.readFileSync(lockfile) }]);
 }
 function computeNodeFingerprint(repoDir) {
   const candidates = ["yarn.lock", "pnpm-lock.yaml", "package-lock.json"];
   for (const name of candidates) {
-    const lockfile = path28.join(repoDir, name);
-    if (fs24.existsSync(lockfile)) {
-      return hashBuffers([{ path: name, content: fs24.readFileSync(lockfile) }]);
+    const lockfile = path30.join(repoDir, name);
+    if (fs26.existsSync(lockfile)) {
+      return hashBuffers([{ path: name, content: fs26.readFileSync(lockfile) }]);
     }
   }
   return null;
@@ -17574,59 +18445,59 @@ function computePgFingerprint(repoDirs) {
   const entries = [];
   for (const repoDir of repoDirs) {
     for (const pattern of patterns) {
-      const filePath = path28.join(repoDir, pattern);
-      if (fs24.existsSync(filePath)) {
-        entries.push({ path: filePath, content: fs24.readFileSync(filePath) });
+      const filePath = path30.join(repoDir, pattern);
+      if (fs26.existsSync(filePath)) {
+        entries.push({ path: filePath, content: fs26.readFileSync(filePath) });
       }
     }
   }
   return entries.length > 0 ? hashBuffers(entries) : null;
 }
 function packTarball(srcDir, destPath, opts = {}) {
-  fs24.mkdirSync(path28.dirname(destPath), { recursive: true });
+  fs26.mkdirSync(path30.dirname(destPath), { recursive: true });
   const tmp = `${destPath}.tmp`;
   const args = [];
   if (opts.followSymlinks) args.push("-h");
   args.push("-czf", tmp, "-C", srcDir, ".");
   try {
     execFileSync4("tar", args, { stdio: "pipe" });
-    fs24.renameSync(tmp, destPath);
+    fs26.renameSync(tmp, destPath);
   } catch (err) {
     try {
-      fs24.rmSync(tmp, { force: true });
+      fs26.rmSync(tmp, { force: true });
     } catch {
     }
     throw err;
   }
 }
 function writeManifest(manifest, tarPath) {
-  fs24.writeFileSync(manifestPath(tarPath), JSON.stringify(manifest, null, 2), "utf-8");
+  fs26.writeFileSync(manifestPath(tarPath), JSON.stringify(manifest, null, 2), "utf-8");
 }
 function readManifest(tarPath) {
   const mPath = manifestPath(tarPath);
-  if (!fs24.existsSync(mPath)) return null;
+  if (!fs26.existsSync(mPath)) return null;
   try {
-    return JSON.parse(fs24.readFileSync(mPath, "utf-8"));
+    return JSON.parse(fs26.readFileSync(mPath, "utf-8"));
   } catch {
     return null;
   }
 }
 function listSnapshots(worldIdFilter) {
   const root = snapshotsDir();
-  if (!fs24.existsSync(root)) return [];
+  if (!fs26.existsSync(root)) return [];
   const now = Date.now();
   const results = [];
-  const worlds = worldIdFilter ? [worldIdFilter] : fs24.readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  const worlds = worldIdFilter ? [worldIdFilter] : fs26.readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   for (const worldId of worlds) {
-    const worldDir = path28.join(root, worldId);
-    if (!fs24.existsSync(worldDir) || !fs24.statSync(worldDir).isDirectory()) continue;
+    const worldDir = path30.join(root, worldId);
+    if (!fs26.existsSync(worldDir) || !fs26.statSync(worldDir).isDirectory()) continue;
     for (const kind of ["gems", "node", "pg"]) {
-      const kindDir = path28.join(worldDir, kind);
-      if (!fs24.existsSync(kindDir)) continue;
-      const tarballs = fs24.readdirSync(kindDir).filter((f) => f.endsWith(".tar.gz"));
+      const kindDir = path30.join(worldDir, kind);
+      if (!fs26.existsSync(kindDir)) continue;
+      const tarballs = fs26.readdirSync(kindDir).filter((f) => f.endsWith(".tar.gz"));
       for (const tarFile of tarballs) {
-        const tarPath = path28.join(kindDir, tarFile);
-        const stat = fs24.statSync(tarPath);
+        const tarPath = path30.join(kindDir, tarFile);
+        const stat = fs26.statSync(tarPath);
         const manifest = readManifest(tarPath);
         if (!manifest) continue;
         results.push({ manifest, tarPath, ageMs: now - stat.mtimeMs });
@@ -17705,17 +18576,17 @@ function resolveKinds(arg) {
   return [];
 }
 async function captureGems(worldId, workspacePath, repo) {
-  const repoDir = path29.join(workspacePath, repo);
+  const repoDir = path31.join(workspacePath, repo);
   const fingerprint = computeGemsFingerprint(repoDir);
   if (!fingerprint) {
     return { ok: false, tarPath: "", msg: "no Gemfile.lock \u2014 layer does not apply" };
   }
   const tarPath = snapshotTarPath(worldId, "gems", repo, fingerprint);
-  const vendorBundle = path29.join(repoDir, "vendor", "bundle");
-  if (fs25.existsSync(vendorBundle)) {
+  const vendorBundle = path31.join(repoDir, "vendor", "bundle");
+  if (fs27.existsSync(vendorBundle)) {
     try {
       packTarball(vendorBundle, tarPath);
-      const stat = fs25.statSync(tarPath);
+      const stat = fs27.statSync(tarPath);
       const manifest = {
         kind: "gems",
         worldId,
@@ -17748,10 +18619,10 @@ async function captureGems(worldId, workspacePath, repo) {
       `docker exec ${containerName} sh -c 'mkdir -p "$(dirname ${tmpTar})" && tar -czf ${tmpTar}.tmp -C ${bundlePath} . && mv ${tmpTar}.tmp ${tmpTar}'`,
       { stdio: "pipe", timeout: 12e4 }
     );
-    fs25.mkdirSync(path29.dirname(tarPath), { recursive: true });
+    fs27.mkdirSync(path31.dirname(tarPath), { recursive: true });
     execSync9(`docker cp ${containerName}:${tmpTar} "${tarPath}"`, { stdio: "pipe", timeout: 12e4 });
     execSync9(`docker exec ${containerName} rm -f ${tmpTar}`, { stdio: "pipe" });
-    const stat = fs25.statSync(tarPath);
+    const stat = fs27.statSync(tarPath);
     const manifest = {
       kind: "gems",
       worldId,
@@ -17768,19 +18639,19 @@ async function captureGems(worldId, workspacePath, repo) {
   }
 }
 async function captureNode(worldId, workspacePath, repo) {
-  const repoDir = path29.join(workspacePath, repo);
+  const repoDir = path31.join(workspacePath, repo);
   const fingerprint = computeNodeFingerprint(repoDir);
   if (!fingerprint) {
     return { ok: false, tarPath: "", msg: "no lockfile \u2014 layer does not apply" };
   }
-  const nodeModules = path29.join(repoDir, "node_modules");
-  if (!fs25.existsSync(nodeModules)) {
+  const nodeModules = path31.join(repoDir, "node_modules");
+  if (!fs27.existsSync(nodeModules)) {
     return { ok: false, tarPath: "", msg: "node_modules not installed yet" };
   }
   const tarPath = snapshotTarPath(worldId, "node", repo, fingerprint);
   try {
     packTarball(nodeModules, tarPath);
-    const stat = fs25.statSync(tarPath);
+    const stat = fs27.statSync(tarPath);
     const manifest = {
       kind: "node",
       worldId,
@@ -17797,7 +18668,7 @@ async function captureNode(worldId, workspacePath, repo) {
   }
 }
 async function capturePg(worldId, workspacePath, repoNames) {
-  const repoDirs = repoNames.map((r) => path29.join(workspacePath, r));
+  const repoDirs = repoNames.map((r) => path31.join(workspacePath, r));
   const fingerprint = computePgFingerprint(repoDirs);
   if (!fingerprint) {
     return { ok: false, tarPath: "", msg: "no Gemfile.lock / schema.rb \u2014 layer does not apply" };
@@ -17812,13 +18683,13 @@ async function capturePg(worldId, workspacePath, repoNames) {
   }
   try {
     execSync9(`docker stop ${containerName}`, { stdio: "pipe", timeout: 3e4 });
-    fs25.mkdirSync(path29.dirname(tarPath), { recursive: true });
+    fs27.mkdirSync(path31.dirname(tarPath), { recursive: true });
     execSync9(
-      `docker run --rm         -v "${volumeName2}:/pgdata:ro"         -v "${path29.dirname(tarPath)}:/dest"         alpine         sh -c 'tar -czf /dest/${path29.basename(tarPath)}.tmp -C /pgdata . && mv /dest/${path29.basename(tarPath)}.tmp /dest/${path29.basename(tarPath)}'`,
+      `docker run --rm         -v "${volumeName2}:/pgdata:ro"         -v "${path31.dirname(tarPath)}:/dest"         alpine         sh -c 'tar -czf /dest/${path31.basename(tarPath)}.tmp -C /pgdata . && mv /dest/${path31.basename(tarPath)}.tmp /dest/${path31.basename(tarPath)}'`,
       { stdio: "pipe", timeout: 18e4 }
     );
     execSync9(`docker start ${containerName}`, { stdio: "pipe", timeout: 3e4 });
-    const stat = fs25.statSync(tarPath);
+    const stat = fs27.statSync(tarPath);
     const manifest = {
       kind: "pg",
       worldId,
@@ -17892,35 +18763,35 @@ function formatAge2(ms) {
 
 // src/commands/refresh.ts
 init_context();
-import * as fs27 from "node:fs";
-import * as os15 from "node:os";
-import * as path31 from "node:path";
-import { spawnSync as spawnSync8 } from "node:child_process";
+import * as fs29 from "node:fs";
+import * as os17 from "node:os";
+import * as path33 from "node:path";
+import { spawnSync as spawnSync9 } from "node:child_process";
 import ora5 from "ora";
 
 // src/commands/refresh-helpers.ts
-import * as fs26 from "node:fs";
-import * as path30 from "node:path";
+import * as fs28 from "node:fs";
+import * as path32 from "node:path";
 function collectCpSourceFiles(standaloneDir) {
-  if (!fs26.existsSync(standaloneDir)) {
+  if (!fs28.existsSync(standaloneDir)) {
     throw new Error(`CP standalone dir not found: ${standaloneDir}`);
   }
   const entries = [];
-  const topLevel = fs26.readdirSync(standaloneDir).filter((f) => {
-    const stat = fs26.statSync(path30.join(standaloneDir, f));
+  const topLevel = fs28.readdirSync(standaloneDir).filter((f) => {
+    const stat = fs28.statSync(path32.join(standaloneDir, f));
     return stat.isFile() && f.endsWith(".mjs") && !f.endsWith(".test.mjs");
   }).sort();
   for (const f of topLevel) {
-    entries.push({ srcPath: path30.join(standaloneDir, f), destRelPath: f });
+    entries.push({ srcPath: path32.join(standaloneDir, f), destRelPath: f });
   }
-  const libDir = path30.join(standaloneDir, "lib");
-  if (fs26.existsSync(libDir) && fs26.statSync(libDir).isDirectory()) {
-    const libFiles = fs26.readdirSync(libDir).filter((f) => {
-      const stat = fs26.statSync(path30.join(libDir, f));
+  const libDir = path32.join(standaloneDir, "lib");
+  if (fs28.existsSync(libDir) && fs28.statSync(libDir).isDirectory()) {
+    const libFiles = fs28.readdirSync(libDir).filter((f) => {
+      const stat = fs28.statSync(path32.join(libDir, f));
       return stat.isFile() && f.endsWith(".mjs") && !f.endsWith(".test.mjs");
     }).sort();
     for (const f of libFiles) {
-      entries.push({ srcPath: path30.join(libDir, f), destRelPath: `lib/${f}` });
+      entries.push({ srcPath: path32.join(libDir, f), destRelPath: `lib/${f}` });
     }
   }
   return entries;
@@ -17939,7 +18810,7 @@ var RESTART_TIMEOUT_S = 30;
 var HEALTH_POLL_MS = 500;
 var HEALTH_TIMEOUT_MS = 3e4;
 function docker(args) {
-  const result = spawnSync8("docker", args, {
+  const result = spawnSync9("docker", args, {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -17978,16 +18849,16 @@ async function refreshWorld(worldId, portOffset, standaloneDir, opts) {
       error: err instanceof Error ? err.message : String(err)
     };
   }
-  const stagingDir = fs27.mkdtempSync(
-    path31.join(os15.tmpdir(), `olam-refresh-${worldId}-`)
+  const stagingDir = fs29.mkdtempSync(
+    path33.join(os17.tmpdir(), `olam-refresh-${worldId}-`)
   );
   try {
     const hasLib = entries.some((e) => e.destRelPath.startsWith("lib/"));
     if (hasLib) {
-      fs27.mkdirSync(path31.join(stagingDir, "lib"), { recursive: true });
+      fs29.mkdirSync(path33.join(stagingDir, "lib"), { recursive: true });
     }
     for (const { srcPath, destRelPath } of entries) {
-      fs27.copyFileSync(srcPath, path31.join(stagingDir, destRelPath));
+      fs29.copyFileSync(srcPath, path33.join(stagingDir, destRelPath));
     }
     const cpResult = docker([
       "cp",
@@ -18002,7 +18873,7 @@ async function refreshWorld(worldId, portOffset, standaloneDir, opts) {
       };
     }
   } finally {
-    fs27.rmSync(stagingDir, { recursive: true, force: true });
+    fs29.rmSync(stagingDir, { recursive: true, force: true });
   }
   if (opts.restart) {
     const restartResult = docker([
@@ -18039,11 +18910,11 @@ function registerRefresh(program2) {
       process.exitCode = 1;
       return;
     }
-    const standaloneDir = path31.join(
+    const standaloneDir = path33.join(
       process.cwd(),
       "packages/control-plane/standalone"
     );
-    if (!fs27.existsSync(standaloneDir)) {
+    if (!fs29.existsSync(standaloneDir)) {
       printError(
         `CP standalone source not found at ${standaloneDir}.
 Run \`olam refresh\` from the olam repo root.`
@@ -18121,6 +18992,25 @@ Run \`olam refresh\` from the olam repo root.`
   });
 }
 
+// src/pleri-config.ts
+import * as fs30 from "node:fs";
+import * as path34 from "node:path";
+function isPleriConfigured(configDir = process.env.OLAM_CONFIG_DIR ?? ".olam") {
+  if (process.env.PLERI_BASE_URL) {
+    return true;
+  }
+  const configPath = path34.join(configDir, "config.yaml");
+  if (!fs30.existsSync(configPath)) {
+    return false;
+  }
+  try {
+    const contents = fs30.readFileSync(configPath, "utf8");
+    return /^[^#\n]*\bpleri:/m.test(contents);
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var program = new Command();
 program.name("olam").description("Olam \u2014 isolated development worlds with thought graph capture").version("0.1.0");
@@ -18134,7 +19024,7 @@ registerList(program);
 registerStatus(program);
 registerDestroy(program);
 registerEnter(program);
-registerCrystallize(program);
+registerCrystallize(program, { hidden: !isPleriConfigured() });
 registerPr(program);
 registerWorkspace(program);
 registerHostCp(program);