@pleri/olam-cli 0.1.13 → 0.1.19

package/dist/index.js

@@ -421,8 +421,8 @@ var init_parseUtil = __esm({
     init_errors();
     init_en();
     makeIssue = (params) => {
-      const { data, path: path35, errorMaps, issueData } = params;
-      const fullPath = [...path35, ...issueData.path || []];
+      const { data, path: path36, errorMaps, issueData } = params;
+      const fullPath = [...path36, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -730,11 +730,11 @@ var init_types = __esm({
     init_parseUtil();
     init_util();
     ParseInputLazyPath = class {
-      constructor(parent, value, path35, key) {
+      constructor(parent, value, path36, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path35;
+        this._path = path36;
         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, path35, ctx, rejectSource) {
+function refineForbiddenKeys(value, path36, ctx, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
@@ -4229,12 +4229,12 @@ function refineForbiddenKeys(value, path35, ctx, rejectSource) {
     if (FORBIDDEN_KEYS.has(key)) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
-        path: [...path35, key],
+        path: [...path36, key],
         message: `forbidden key "${key}" (prototype-pollution surface)`
       });
       continue;
     }
-    if (rejectSource && path35.length === 0 && key === "source") {
+    if (rejectSource && path36.length === 0 && key === "source") {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: ["source"],
@@ -4244,30 +4244,30 @@ function refineForbiddenKeys(value, path35, ctx, rejectSource) {
     }
     refineForbiddenKeys(
       value[key],
-      [...path35, key],
+      [...path36, key],
       ctx,
       false
     );
   }
 }
-function rejectForbiddenKeys(value, path35, rejectSource) {
+function rejectForbiddenKeys(value, path36, 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] ${path35}: forbidden key "${key}" (prototype-pollution surface)`
+        `[manifest] ${path36}: forbidden key "${key}" (prototype-pollution surface)`
       );
     }
     if (rejectSource && key === "source") {
       throw new Error(
-        `[manifest] ${path35}: top-level "source" is loader-stamped \u2014 manifests must not author it`
+        `[manifest] ${path36}: top-level "source" is loader-stamped \u2014 manifests must not author it`
       );
     }
     rejectForbiddenKeys(
       value[key],
-      `${path35}.${key}`,
+      `${path36}.${key}`,
       false
     );
   }
@@ -5088,7 +5088,7 @@ async function safeText(res) {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 var DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, RETRY_COUNT, RETRY_BACKOFF_MS, AuthClient;
 var init_client = __esm({
@@ -5208,8 +5208,8 @@ var init_client = __esm({
           throw new Error(`failed to report rate-limit for ${accountId} (HTTP ${res.status})`);
         }
       }
-      async request(method, path35, body, attempt = 0) {
-        const url = `${this.baseUrl}${path35}`;
+      async request(method, path36, body, attempt = 0) {
+        const url = `${this.baseUrl}${path36}`;
         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, path35, body, attempt + 1);
+            return this.request(method, path36, body, attempt + 1);
           }
           throw err;
         } finally {
@@ -5246,7 +5246,7 @@ function resolveAuthServicePath() {
   return path8.join(pkgsDir, "auth-service");
 }
 function sleep2(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 var DEFAULT_PORT, DEFAULT_VOLUME, DEFAULT_CONTAINER, DEFAULT_IMAGE, AuthContainerController;
 var init_container = __esm({
@@ -5800,7 +5800,7 @@ var demuxStream, execInContainer;
 var init_exec = __esm({
   "../adapters/dist/docker/exec.js"() {
     "use strict";
-    demuxStream = (stream) => new Promise((resolve7, reject) => {
+    demuxStream = (stream) => new Promise((resolve8, reject) => {
       const stdoutChunks = [];
       const stderrChunks = [];
       const stdout = new PassThrough();
@@ -5814,7 +5814,7 @@ var init_exec = __esm({
         stream.pipe(stdout);
       }
       stream.on("end", () => {
-        resolve7({
+        resolve8({
           stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
           stderr: Buffer.concat(stderrChunks).toString("utf-8")
         });
@@ -6188,7 +6188,7 @@ var init_connection = __esm({
       // -----------------------------------------------------------------------
       async exec(host, command) {
         const client = await this.getConnection(host);
-        return new Promise((resolve7, reject) => {
+        return new Promise((resolve8, reject) => {
           client.exec(command, (err, stream) => {
             if (err) {
               reject(new Error(`SSH exec failed on ${host}: ${err.message}`));
@@ -6203,7 +6203,7 @@ var init_connection = __esm({
               stderr += data.toString();
             });
             stream.on("close", (code) => {
-              resolve7({
+              resolve8({
                 exitCode: code ?? 0,
                 stdout: stdout.trimEnd(),
                 stderr: stderr.trimEnd()
@@ -6234,10 +6234,10 @@ var init_connection = __esm({
           throw new Error(`No SSH configuration found for host: ${host}`);
         }
         const client = new SSHClient();
-        return new Promise((resolve7, reject) => {
+        return new Promise((resolve8, reject) => {
           client.on("ready", () => {
             this.connections.set(host, client);
-            resolve7(client);
+            resolve8(client);
           }).on("error", (err) => {
             this.connections.delete(host);
             reject(new Error(`SSH connection to ${host} failed: ${err.message}`));
@@ -6676,8 +6676,8 @@ var init_provider3 = __esm({
       // -----------------------------------------------------------------------
       // Internal fetch helper
       // -----------------------------------------------------------------------
-      async request(path35, method, body) {
-        const url = `${this.config.workerUrl}${path35}`;
+      async request(path36, method, body) {
+        const url = `${this.config.workerUrl}${path36}`;
         const bearer = await this.config.mintToken();
         const headers = {
           Authorization: `Bearer ${bearer}`
@@ -11420,7 +11420,7 @@ function isCloudflaredAvailable() {
   }
 }
 function startTunnel(port) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const child = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
       stdio: ["ignore", "pipe", "pipe"],
       detached: false
@@ -11441,7 +11441,7 @@ function startTunnel(port) {
       if (match2) {
         resolved = true;
         clearTimeout(timeout);
-        resolve7(match2[0]);
+        resolve8(match2[0]);
       }
     }
     child.stdout?.on("data", scan);
@@ -11528,8 +11528,8 @@ var init_dashboard = __esm({
           }
           throw err;
         }
-        await new Promise((resolve7, reject) => {
-          this.server.on("listening", resolve7);
+        await new Promise((resolve8, reject) => {
+          this.server.on("listening", resolve8);
           this.server.on("error", reject);
         });
         this.info = { localUrl: `http://localhost:${port}` };
@@ -11574,8 +11574,8 @@ var init_dashboard = __esm({
       async stop() {
         stopTunnel();
         if (this.server) {
-          await new Promise((resolve7) => {
-            this.server.close(() => resolve7());
+          await new Promise((resolve8) => {
+            this.server.close(() => resolve8());
           });
           this.server = null;
         }
@@ -11780,6 +11780,54 @@ var init_context = __esm({
   }
 });
 
+// src/install-root.ts
+var install_root_exports = {};
+__export(install_root_exports, {
+  MissingBuildScriptError: () => MissingBuildScriptError,
+  installRoot: () => installRoot,
+  isDevMode: () => isDevMode,
+  resolveBuildScript: () => resolveBuildScript
+});
+import { existsSync as existsSync17 } from "node:fs";
+import { dirname as dirname13, join as join24, resolve as resolve6 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+function installRoot(metaUrl = import.meta.url) {
+  const here = fileURLToPath3(metaUrl);
+  return resolve6(dirname13(here), "..");
+}
+function isDevMode(env = process.env, installRootDir = installRoot()) {
+  if (env.OLAM_DEV !== "1") return false;
+  const repoRoot = resolve6(installRootDir, "..", "..");
+  return existsSync17(join24(repoRoot, "packages")) && existsSync17(join24(repoRoot, "package.json"));
+}
+function resolveBuildScript(input) {
+  const { scriptRelPath, env = process.env, installRootDir = installRoot() } = input;
+  if (!isDevMode(env, installRootDir)) {
+    throw new MissingBuildScriptError(scriptRelPath);
+  }
+  const repoRoot = resolve6(installRootDir, "..", "..");
+  return join24(repoRoot, scriptRelPath);
+}
+var MissingBuildScriptError;
+var init_install_root = __esm({
+  "src/install-root.ts"() {
+    "use strict";
+    MissingBuildScriptError = class extends Error {
+      constructor(scriptRelPath) {
+        super(
+          `Build script ${scriptRelPath} is not available in this CLI install.
+  Source-build paths require a monorepo clone:
+    git clone https://github.com/pleri/olam && cd olam
+    OLAM_DEV=1 olam <command> --from-source
+  For published-image upgrades (Phase B+), drop the --from-source flag
+  and the CLI will pull pre-built images from ghcr.io/pleri/* by digest.`
+        );
+        this.name = "MissingBuildScriptError";
+      }
+    };
+  }
+});
+
 // src/registry-allowlist.ts
 var registry_allowlist_exports = {};
 __export(registry_allowlist_exports, {
@@ -11898,6 +11946,9 @@ var init_checksum = __esm({
 
 // src/index.ts
 import { Command } from "commander";
+import * as fs31 from "node:fs";
+import * as path35 from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // src/commands/init.ts
 import * as fs5 from "node:fs";
@@ -12304,11 +12355,11 @@ var UnknownArchetypeError = class extends Error {
   known;
 };
 var ArchetypeCycleError = class extends Error {
-  constructor(path35) {
+  constructor(path36) {
     super(
-      `Archetype inheritance cycle detected: ${path35.join(" \u2192 ")} \u2192 ${path35[0] ?? "?"}`
+      `Archetype inheritance cycle detected: ${path36.join(" \u2192 ")} \u2192 ${path36[0] ?? "?"}`
     );
-    this.path = path35;
+    this.path = path36;
     this.name = "ArchetypeCycleError";
   }
   path;
@@ -12501,9 +12552,9 @@ function registerInstall(program2) {
 
 // src/commands/auth.ts
 init_auth();
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 import * as readline from "node:readline/promises";
-import { spawn as spawn2 } from "node:child_process";
+import { spawn as spawn3 } from "node:child_process";
 
 // src/commands/auth-status.ts
 import * as fs8 from "node:fs";
@@ -12555,6 +12606,8 @@ init_auth();
 // src/exit-codes.ts
 var EXIT_GENERIC_ERROR = 1;
 var EXIT_PLERI_NOT_CONFIGURED = 2;
+var EXIT_BOOTSTRAP_PULL_FAILED = 3;
+var EXIT_PROTOCOL_MISMATCH = 4;
 var EXIT_AUTH_NEEDS_ATTENTION = 5;
 
 // src/commands/auth-status.ts
@@ -12680,8 +12733,9 @@ async function runAuthStatus(getStatus) {
 // src/commands/auth-upgrade.ts
 import * as fs20 from "node:fs";
 import * as path23 from "node:path";
-import { spawnSync as spawnSync4 } from "node:child_process";
-import pc6 from "picocolors";
+import { spawnSync as spawnSync6 } from "node:child_process";
+import ora2 from "ora";
+import pc7 from "picocolors";
 
 // src/commands/host-cp.ts
 init_dist();
@@ -13127,10 +13181,10 @@ async function readHostCpToken2() {
   if (!fs19.existsSync(tp)) return null;
   return fs19.readFileSync(tp, "utf-8").trim();
 }
-async function callHostCpProxy(method, worldId, path35, body) {
+async function callHostCpProxy(method, worldId, path36, 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)}${path35}`;
+  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path36}`;
   try {
     const headers = {
       Authorization: `Bearer ${token}`
@@ -13237,13 +13291,348 @@ async function handleDeregister(opts) {
 
 // src/commands/auth-upgrade.ts
 init_auth();
+
+// src/commands/bootstrap.ts
+init_install_root();
+import { spawn as spawn2, spawnSync as spawnSync5 } from "node:child_process";
+import { existsSync as existsSync18, readFileSync as readFileSync15 } from "node:fs";
+import { join as join25 } from "node:path";
+import ora from "ora";
+import pc6 from "picocolors";
+
+// src/protocol-version.ts
+import { spawnSync as spawnSync4 } from "node:child_process";
+var OLAM_PROTOCOL_VERSIONS_SUPPORTED = [1];
+function parseProtocolVersionsLabel(labelValue) {
+  if (!labelValue) return [];
+  const parts = labelValue.split(",").map((s) => s.trim()).filter(Boolean);
+  const versions = /* @__PURE__ */ new Set();
+  for (const part of parts) {
+    const n = Number.parseInt(part, 10);
+    if (Number.isFinite(n) && n > 0 && String(n) === part) {
+      versions.add(n);
+    }
+  }
+  return Array.from(versions).sort((a, b) => a - b);
+}
+function checkProtocolOverlap(imageVersions, cliVersions = OLAM_PROTOCOL_VERSIONS_SUPPORTED) {
+  const cliSet = new Set(cliVersions);
+  const overlap = imageVersions.filter((v) => cliSet.has(v));
+  if (imageVersions.length === 0) {
+    return {
+      overlap: [],
+      imageVersions: [],
+      cliVersions,
+      compatible: false,
+      remedy: `Devbox image is missing the \`olam.protocol.versions\` LABEL. This CLI requires versions [${cliVersions.join(", ")}]. See docs/architecture/devbox-contract.md \xA71 for the contract; rebuild the image with \`LABEL olam.protocol.versions="1"\`.`
+    };
+  }
+  if (overlap.length === 0) {
+    const imgLow = Math.min(...imageVersions);
+    const imgHigh = Math.max(...imageVersions);
+    const cliLow = Math.min(...cliVersions);
+    const cliHigh = Math.max(...cliVersions);
+    return {
+      overlap: [],
+      imageVersions: [...imageVersions],
+      cliVersions,
+      compatible: false,
+      remedy: `Devbox image protocol versions [${imageVersions.join(", ")}] don't overlap CLI's [${cliVersions.join(", ")}]. ` + (imgHigh < cliLow ? `The image is older than this CLI supports \u2014 rebuild against the contract version ${cliLow}+ at docs/architecture/devbox-contract.md.` : imgLow > cliHigh ? `The image is newer than this CLI supports \u2014 pin a compatible CLI: \`npm install -g @pleri/olam-cli@<version-with-protocol-${imgLow}>\`.` : `Pin a compatible CLI version that overlaps with the image's range.`)
+    };
+  }
+  return {
+    overlap,
+    imageVersions: [...imageVersions],
+    cliVersions,
+    compatible: true,
+    remedy: ""
+  };
+}
+
+// src/commands/bootstrap.ts
+function loadImageDigests(installRootDir = installRoot()) {
+  const digestsPath = join25(installRootDir, "dist", "image-digests.json");
+  if (!existsSync18(digestsPath)) {
+    throw new Error(
+      `image-digests.json missing at ${digestsPath}. Re-run \`npm install -g @pleri/olam-cli@<version>\` to refresh the tarball.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync15(digestsPath, "utf8"));
+  } catch (err) {
+    throw new Error(`image-digests.json is not valid JSON: ${err.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("image-digests.json is not an object");
+  }
+  const obj = parsed;
+  const required = ["host-cp", "auth", "devbox"];
+  const missing = required.filter((k) => typeof obj[k] !== "string" || !obj[k]);
+  if (missing.length > 0) {
+    throw new Error(
+      `image-digests.json missing required key(s): ${missing.join(", ")}. Tarball may be corrupted; reinstall the CLI.`
+    );
+  }
+  return parsed;
+}
+var realDocker = {
+  async info() {
+    return spawnAsync("docker", ["info"]);
+  },
+  async pull(imageRef, opts) {
+    return spawnAsync("docker", ["pull", imageRef], { signal: opts?.signal });
+  },
+  async inspectLabel(imageRef, label) {
+    return spawnAsync("docker", [
+      "inspect",
+      imageRef,
+      "--format",
+      `{{ index .Config.Labels "${label}" }}`
+    ]);
+  }
+};
+function spawnAsync(cmd, args, opts = {}) {
+  return new Promise((resolve8) => {
+    const child = spawn2(cmd, [...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      signal: opts.signal
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve8({ exitCode: -1, stdout, stderr: stderr + err.message });
+    });
+    child.on("close", (code) => {
+      resolve8({ exitCode: code ?? -1, stdout, stderr });
+    });
+  });
+}
+var inflightPulls = /* @__PURE__ */ new Map();
+var DEFAULT_PULL_POLICY = {
+  perAttemptTimeoutMs: 18e4,
+  retryOnce: true
+};
+function isTransientPullFailure(result) {
+  const s = result.stderr.toLowerCase();
+  return result.exitCode !== 0 && (/timeout|connection|temporarily|429|503|tls handshake|network/.test(s) || result.exitCode === 124 || result.exitCode === -1);
+}
+async function pullImageWithRetry(imageRef, docker2 = realDocker, policy = DEFAULT_PULL_POLICY) {
+  const existing = inflightPulls.get(imageRef);
+  if (existing) return existing;
+  const promise = (async () => {
+    let result = await pullOnce(imageRef, docker2, policy.perAttemptTimeoutMs);
+    if (result.exitCode !== 0 && policy.retryOnce && isTransientPullFailure(result)) {
+      result = await pullOnce(imageRef, docker2, policy.perAttemptTimeoutMs);
+    }
+    return result;
+  })();
+  inflightPulls.set(imageRef, promise);
+  try {
+    return await promise;
+  } finally {
+    inflightPulls.delete(imageRef);
+  }
+}
+async function pullOnce(imageRef, docker2, timeoutMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs).unref?.();
+  try {
+    return await docker2.pull(imageRef, { signal: ac.signal });
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var REAL_OLAM_SUBCOMMAND = (args) => {
+  const result = spawnSync5(process.execPath, [
+    process.argv[1] ?? "olam",
+    ...args
+  ], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return {
+    exitCode: result.status ?? -1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
+};
+async function runBootstrap2(opts, deps = {}) {
+  const docker2 = deps.docker ?? realDocker;
+  const digests = deps.digests ?? loadImageDigests();
+  const registry = opts.registry ?? deps.registry ?? digests.$registry ?? "ghcr.io/pleri";
+  printHeader("olam bootstrap");
+  const infoSpinner = ora("Checking docker daemon").start();
+  const info = await docker2.info();
+  if (info.exitCode !== 0) {
+    infoSpinner.fail("docker daemon not reachable");
+    process.stderr.write(
+      `${pc6.red("error")} docker info exited with ${info.exitCode}.
+  Ensure Docker Desktop / Colima / Rancher is running, then retry.
+  stderr: ${info.stderr.split("\n")[0] ?? ""}
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "docker daemon not reachable" };
+  }
+  infoSpinner.succeed("docker daemon reachable");
+  const imageRefs = [
+    { name: "host-cp", ref: `${registry}/olam-host-cp@${digests["host-cp"]}` },
+    { name: "auth", ref: `${registry}/olam-auth@${digests.auth}` },
+    { name: "devbox", ref: `${registry}/olam-devbox@${digests.devbox}` }
+  ];
+  const pullSpinner = ora("Pulling images (3 parallel)").start();
+  const pullStart = Date.now();
+  const pullResults = await Promise.all(
+    imageRefs.map(async ({ name, ref }) => ({
+      name,
+      ref,
+      result: await pullImageWithRetry(ref, docker2)
+    }))
+  );
+  const pullElapsed = ((Date.now() - pullStart) / 1e3).toFixed(1);
+  const failed = pullResults.filter((r) => r.result.exitCode !== 0);
+  if (failed.length > 0) {
+    pullSpinner.fail(`Pull failed for ${failed.map((r) => r.name).join(", ")}`);
+    for (const f of failed) {
+      process.stderr.write(
+        `  ${pc6.red(f.name)} (${f.ref}):
+    exit=${f.result.exitCode}
+    stderr: ${f.result.stderr.split("\n")[0] ?? "(empty)"}
+`
+      );
+    }
+    process.stderr.write(
+      "\n  Remedy: `olam bootstrap` is the only on-ramp. Re-run after\n  resolving network / GHCR availability. If a specific image is\n  permanently unavailable, file a bug at github.com/pleri/olam/issues.\n"
+    );
+    return {
+      exitCode: EXIT_BOOTSTRAP_PULL_FAILED,
+      summary: `pull failed: ${failed.map((r) => r.name).join(", ")}`
+    };
+  }
+  pullSpinner.succeed(`Pulled 3 images in ${pullElapsed}s`);
+  const handshakeSpinner = ora("Verifying olam.protocol.versions handshake").start();
+  for (const { name, ref } of imageRefs) {
+    const inspect = await docker2.inspectLabel(ref, "olam.protocol.versions");
+    if (inspect.exitCode !== 0) {
+      handshakeSpinner.fail(`Could not inspect ${name}`);
+      process.stderr.write(
+        `${pc6.red("error")} docker inspect ${ref} failed: ${inspect.stderr}
+`
+      );
+      return { exitCode: EXIT_GENERIC_ERROR, summary: `inspect failed: ${name}` };
+    }
+    const labelValue = (inspect.stdout || "").trim();
+    const versions = parseProtocolVersionsLabel(
+      labelValue === "<no value>" ? "" : labelValue
+    );
+    const decision = checkProtocolOverlap(versions);
+    if (!decision.compatible) {
+      handshakeSpinner.fail(`Protocol mismatch on ${name}`);
+      process.stderr.write(`${pc6.red("error")} ${decision.remedy}
+`);
+      return {
+        exitCode: EXIT_PROTOCOL_MISMATCH,
+        summary: `protocol mismatch: ${name}`
+      };
+    }
+  }
+  handshakeSpinner.succeed("Protocol handshake passed (all 3 images)");
+  const runOlam = deps.runOlamSubcommand ?? REAL_OLAM_SUBCOMMAND;
+  const hostCpSpinner = ora("Starting host-cp").start();
+  const hostCp = runOlam(["host-cp", "start"]);
+  if (hostCp.exitCode !== 0) {
+    hostCpSpinner.fail("host-cp start failed");
+    process.stderr.write(`  stderr: ${hostCp.stderr.split("\n").slice(0, 3).join("\n  ")}
+`);
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "host-cp start failed" };
+  }
+  hostCpSpinner.succeed("host-cp running");
+  const authUpSpinner = ora("Starting auth-service").start();
+  const authUp = runOlam(["auth", "up"]);
+  if (authUp.exitCode !== 0) {
+    authUpSpinner.fail("auth up failed");
+    process.stderr.write(`  stderr: ${authUp.stderr.split("\n").slice(0, 3).join("\n  ")}
+`);
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "auth up failed" };
+  }
+  authUpSpinner.succeed("auth-service running");
+  if (opts.skipAuthLogin || process.env.OLAM_BOOTSTRAP_SKIP_AUTH_LOGIN === "1") {
+    printInfo("auth login", "skipped");
+  } else {
+    printHeader("Authenticate with Anthropic");
+    process.stdout.write(
+      "  This opens an OAuth PKCE flow against Anthropic. The auth-service\n  will hold your refresh token; per-world access tokens are issued\n  on demand and rotated every 6h.\n\n  Press Ctrl+C to cancel \u2014 re-run `olam bootstrap` to retry.\n\n"
+    );
+    const login = runOlam(["auth", "login"]);
+    if (login.exitCode !== 0) {
+      printError("auth login failed (or was cancelled)");
+      process.stderr.write(`  Re-run \`olam bootstrap\` after resolving.
+`);
+      return { exitCode: EXIT_GENERIC_ERROR, summary: "auth login failed" };
+    }
+    printSuccess("auth login complete");
+  }
+  if (opts.withSmoke) {
+    printHeader("Smoke test");
+    const smoke = runOlam([
+      "create",
+      "--workspace",
+      "smoke",
+      "--task",
+      "smoke test from olam bootstrap"
+    ]);
+    if (smoke.exitCode !== 0) {
+      printError("smoke world create failed");
+      process.stderr.write(`  stderr: ${smoke.stderr.split("\n").slice(0, 3).join("\n  ")}
+`);
+      return { exitCode: EXIT_GENERIC_ERROR, summary: "smoke create failed" };
+    }
+    printSuccess("Smoke world created");
+  }
+  printHeader("Stack ready");
+  printInfo("host-cp", `running (${digests["host-cp"].slice(0, 19)}\u2026)`);
+  printInfo("auth", `running (${digests.auth.slice(0, 19)}\u2026)`);
+  printInfo("devbox", `pulled (${digests.devbox.slice(0, 19)}\u2026)`);
+  printInfo("next", '`olam create --task "your task"` to spawn a world');
+  return { exitCode: 0, summary: "stack ready" };
+}
+function registerBootstrap(program2) {
+  program2.command("bootstrap").description(
+    "Bootstrap the olam stack: pull 3 images by digest, verify protocol handshake, start host-cp + auth, run auth login."
+  ).option("--with-smoke", "After bootstrap, create a smoke-test world to verify end-to-end").option("--skip-auth-login", "Skip the interactive PKCE step (CI / scripted use only)").option(
+    "--registry <ref>",
+    "Override the registry prefix (default: read from image-digests.json or fall back to ghcr.io/pleri)"
+  ).action(async (opts) => {
+    try {
+      const result = await runBootstrap2({
+        withSmoke: opts.withSmoke === true,
+        skipAuthLogin: opts.skipAuthLogin === true,
+        registry: opts.registry
+      });
+      process.exitCode = result.exitCode;
+    } catch (err) {
+      printError(err instanceof Error ? err.message : String(err));
+      process.exitCode = EXIT_GENERIC_ERROR;
+    }
+  });
+}
+
+// src/commands/auth-upgrade.ts
+init_install_root();
 var AUTH_PORT = 9999;
 var AUTH_HEALTH_URL = `http://127.0.0.1:${AUTH_PORT}/health`;
 var AUTH_ADD_URL = `http://127.0.0.1:${AUTH_PORT}/credentials/add`;
 function parseAuthUpgradeOpts(raw) {
   return {
     yes: raw.yes === true,
-    skipRecreate: raw.skipRecreate === true
+    skipRecreate: raw.skipRecreate === true,
+    fromSource: raw.fromSource === true
   };
 }
 function validateAuthRepoRoot(cwd) {
@@ -13304,8 +13693,8 @@ async function smokeTestCodexProvider(authSecret) {
 }
 function runStep(label, cmd, args, opts = {}) {
   const start = Date.now();
-  process.stdout.write(`  ${pc6.dim(label.padEnd(34))}`);
-  const result = spawnSync4(cmd, [...args], {
+  process.stdout.write(`  ${pc7.dim(label.padEnd(34))}`);
+  const result = spawnSync6(cmd, [...args], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd: opts.cwd ?? process.cwd(),
@@ -13314,7 +13703,7 @@ function runStep(label, cmd, args, opts = {}) {
   const durationMs = Date.now() - start;
   const ok = result.status === 0 && result.error === void 0;
   const dur = `${(durationMs / 1e3).toFixed(1)}s`;
-  process.stdout.write(`${ok ? pc6.green("\u2713") : pc6.red("\u2717")} ${dur}
+  process.stdout.write(`${ok ? pc7.green("\u2713") : pc7.red("\u2717")} ${dur}
 `);
   return {
     ok,
@@ -13327,10 +13716,10 @@ async function confirm(message) {
   if (!process.stdin.isTTY) return true;
   const { createInterface: createInterface2 } = await import("node:readline");
   const rl = createInterface2({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     rl.question(`${message} [y/N] `, (answer) => {
       rl.close();
-      resolve7(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+      resolve8(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
     });
   });
 }
@@ -13342,6 +13731,126 @@ function printTimings(timings) {
   }
   printInfo("total", `${(total / 1e3).toFixed(1)}s`);
 }
+async function runAuthUpgradePullByDigest(deps = {}) {
+  const docker2 = deps.docker ?? realDocker;
+  const digests = deps.digests ?? loadImageDigests();
+  const registry = deps.registry ?? digests.$registry ?? "ghcr.io/pleri";
+  printHeader("olam auth upgrade (pull-by-digest)");
+  const infoSpinner = ora2("Checking docker daemon").start();
+  const info = await docker2.info();
+  if (info.exitCode !== 0) {
+    infoSpinner.fail("docker daemon not reachable");
+    process.stderr.write(
+      `${pc7.red("error")} docker info exited with ${info.exitCode}.
+  Ensure Docker is running, then retry.
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "docker daemon not reachable" };
+  }
+  infoSpinner.succeed("docker daemon reachable");
+  const ref = `${registry}/olam-auth@${digests.auth}`;
+  const pullSpinner = ora2(`Pulling ${ref.slice(0, 60)}\u2026`).start();
+  const pullResult = await pullImageWithRetry(ref, docker2);
+  if (pullResult.exitCode !== 0) {
+    pullSpinner.fail("Pull failed");
+    process.stderr.write(
+      `${pc7.red("error")} pull failed (exit ${pullResult.exitCode}):
+  ${pullResult.stderr.split("\n")[0] ?? "(empty)"}
+
+  Remedy: re-run after resolving network / GHCR availability.
+  For monorepo dev, \`OLAM_DEV=1 olam auth upgrade --from-source\` builds locally.
+`
+    );
+    return { exitCode: EXIT_BOOTSTRAP_PULL_FAILED, summary: "pull failed: auth" };
+  }
+  pullSpinner.succeed("Image pulled");
+  const handshakeSpinner = ora2("Verifying olam.protocol.versions handshake").start();
+  const inspect = await docker2.inspectLabel(ref, "olam.protocol.versions");
+  if (inspect.exitCode !== 0) {
+    handshakeSpinner.fail("Could not inspect auth image");
+    process.stderr.write(
+      `${pc7.red("error")} docker inspect ${ref} failed: ${inspect.stderr}
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "inspect failed: auth" };
+  }
+  const labelValue = (inspect.stdout || "").trim();
+  const versions = parseProtocolVersionsLabel(
+    labelValue === "<no value>" ? "" : labelValue
+  );
+  const decision = checkProtocolOverlap(versions);
+  if (!decision.compatible) {
+    handshakeSpinner.fail("Protocol mismatch on auth image");
+    process.stderr.write(`${pc7.red("error")} ${decision.remedy}
+`);
+    return { exitCode: EXIT_PROTOCOL_MISMATCH, summary: "protocol mismatch: auth" };
+  }
+  handshakeSpinner.succeed("Protocol handshake passed");
+  const tagSpinner = ora2("Tagging digest \u2192 olam-auth:local").start();
+  const tagger = deps.tagImpl ?? defaultTagAuth;
+  const tagResult = tagger(ref, "olam-auth:local");
+  if (!tagResult.ok) {
+    tagSpinner.fail("docker tag failed");
+    process.stderr.write(`${pc7.red("error")} ${tagResult.error ?? "docker tag failed"}
+`);
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "tag failed: auth" };
+  }
+  tagSpinner.succeed("Re-tagged \u2192 olam-auth:local");
+  const authSpinner = ora2("Recreating auth-service container").start();
+  const recreate = deps.recreateAuth ?? defaultRecreateAuth;
+  const recreateResult = await recreate();
+  if (!recreateResult.ok) {
+    authSpinner.fail("auth-service recreate failed");
+    process.stderr.write(
+      `${pc7.red("error")} ${recreateResult.error ?? "unknown failure"}
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "auth recreate failed" };
+  }
+  authSpinner.succeed("auth-service running on new image");
+  printSuccess("Auth upgrade complete (pull-by-digest)");
+  printInfo("digest", digests.auth.slice(0, 32) + "\u2026");
+  return { exitCode: 0, summary: "auth upgraded" };
+}
+function defaultTagAuth(from, to) {
+  try {
+    const r = spawnSync6("docker", ["tag", from, to], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    if (r.status === 0 && r.error === void 0) return { ok: true };
+    return {
+      ok: false,
+      error: (r.stderr ?? "").trim() || r.error?.message || "docker tag failed"
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? `spawnSync threw: ${err.message}` : "spawnSync threw"
+    };
+  }
+}
+async function defaultRecreateAuth() {
+  try {
+    spawnSync6("docker", ["stop", "olam-auth"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    spawnSync6("docker", ["rm", "olam-auth"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    const controller = new AuthContainerController();
+    controller.start();
+    const healthy = await waitForAuthHealth(15e3);
+    if (!healthy) {
+      return { ok: false, error: "auth-service /health did not respond within 15s" };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
 async function handleAuthUpgrade(opts) {
   const cwd = process.cwd();
   const rootCheck = validateAuthRepoRoot(cwd);
@@ -13369,7 +13878,17 @@ async function handleAuthUpgrade(opts) {
     }
   }
   const timings = [];
-  const buildScript = path23.join(cwd, "packages/adapters/src/docker/build-auth.sh");
+  let buildScript;
+  try {
+    const { resolveBuildScript: resolveBuildScript2 } = await Promise.resolve().then(() => (init_install_root(), install_root_exports));
+    buildScript = resolveBuildScript2({
+      scriptRelPath: "packages/adapters/src/docker/build-auth.sh"
+    });
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
   const imageResult = runStep("bash build-auth.sh", "bash", [buildScript], { cwd });
   timings.push({ label: "docker image build", durationMs: imageResult.durationMs });
   if (!imageResult.ok) {
@@ -13385,49 +13904,49 @@ ${imageResult.stderr}`);
     return;
   }
   const stopStart = Date.now();
-  process.stdout.write(`  ${pc6.dim("docker stop olam-auth".padEnd(34))}`);
-  spawnSync4("docker", ["stop", "olam-auth"], {
+  process.stdout.write(`  ${pc7.dim("docker stop olam-auth".padEnd(34))}`);
+  spawnSync6("docker", ["stop", "olam-auth"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
   const stopDurationMs = Date.now() - stopStart;
-  process.stdout.write(`${pc6.green("\u2713")} ${(stopDurationMs / 1e3).toFixed(1)}s
+  process.stdout.write(`${pc7.green("\u2713")} ${(stopDurationMs / 1e3).toFixed(1)}s
 `);
   timings.push({ label: "container stop", durationMs: stopDurationMs });
   const rmStart = Date.now();
-  process.stdout.write(`  ${pc6.dim("docker rm olam-auth".padEnd(34))}`);
-  spawnSync4("docker", ["rm", "olam-auth"], {
+  process.stdout.write(`  ${pc7.dim("docker rm olam-auth".padEnd(34))}`);
+  spawnSync6("docker", ["rm", "olam-auth"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
   const rmDurationMs = Date.now() - rmStart;
-  process.stdout.write(`${pc6.green("\u2713")} ${(rmDurationMs / 1e3).toFixed(1)}s
+  process.stdout.write(`${pc7.green("\u2713")} ${(rmDurationMs / 1e3).toFixed(1)}s
 `);
   timings.push({ label: "container remove", durationMs: rmDurationMs });
   const startStart = Date.now();
-  process.stdout.write(`  ${pc6.dim("docker run olam-auth:local".padEnd(34))}`);
+  process.stdout.write(`  ${pc7.dim("docker run olam-auth:local".padEnd(34))}`);
   try {
     const controller = new AuthContainerController();
     controller.start();
     const startDurationMs = Date.now() - startStart;
-    process.stdout.write(`${pc6.green("\u2713")} ${(startDurationMs / 1e3).toFixed(1)}s
+    process.stdout.write(`${pc7.green("\u2713")} ${(startDurationMs / 1e3).toFixed(1)}s
 `);
     timings.push({ label: "container start", durationMs: startDurationMs });
   } catch (err) {
     const startDurationMs = Date.now() - startStart;
-    process.stdout.write(`${pc6.red("\u2717")} ${(startDurationMs / 1e3).toFixed(1)}s
+    process.stdout.write(`${pc7.red("\u2717")} ${(startDurationMs / 1e3).toFixed(1)}s
 `);
     timings.push({ label: "container start", durationMs: startDurationMs });
     printError(`Failed to start auth container: ${err instanceof Error ? err.message : String(err)}`);
     process.exitCode = 1;
     return;
   }
-  process.stdout.write(`  ${pc6.dim("waiting for /health".padEnd(34))}`);
+  process.stdout.write(`  ${pc7.dim("waiting for /health".padEnd(34))}`);
   const healthStart = Date.now();
   const healthy = await waitForAuthHealth(1e4);
   const healthDurationMs = Date.now() - healthStart;
   const healthDur = `${(healthDurationMs / 1e3).toFixed(1)}s`;
-  process.stdout.write(`${healthy ? pc6.green("\u2713") : pc6.yellow("?")} ${healthDur}
+  process.stdout.write(`${healthy ? pc7.green("\u2713") : pc7.yellow("?")} ${healthDur}
 `);
   timings.push({ label: "/health", durationMs: healthDurationMs });
   if (!healthy) {
@@ -13436,13 +13955,13 @@ ${imageResult.stderr}`);
     printTimings(timings);
     return;
   }
-  process.stdout.write(`  ${pc6.dim("smoke test: codex provider".padEnd(34))}`);
+  process.stdout.write(`  ${pc7.dim("smoke test: codex provider".padEnd(34))}`);
   const smokeStart = Date.now();
   const authSecret = readAuthSecret2();
   const smoke = await smokeTestCodexProvider(authSecret);
   const smokeDurationMs = Date.now() - smokeStart;
   const smokeDur = `${(smokeDurationMs / 1e3).toFixed(1)}s`;
-  process.stdout.write(`${smoke.ok ? pc6.green("\u2713") : pc6.red("\u2717")} ${smokeDur}
+  process.stdout.write(`${smoke.ok ? pc7.green("\u2713") : pc7.red("\u2717")} ${smokeDur}
 `);
   timings.push({ label: "smoke test", durationMs: smokeDurationMs });
   if (!smoke.ok) {
@@ -13457,8 +13976,31 @@ ${imageResult.stderr}`);
   printTimings(timings);
 }
 function registerAuthUpgrade(auth) {
-  auth.command("upgrade").description("Rebuild the olam-auth image and force-recreate the container").option("-y, --yes", "Skip the confirmation prompt").option("--skip-recreate", "Build the image only; skip container stop/rm/start").action(async (opts) => {
-    await handleAuthUpgrade(parseAuthUpgradeOpts(opts));
+  auth.command("upgrade").description(
+    "Upgrade the olam-auth container. Default: pull olam-auth@<digest> from ghcr.io and recreate. Use --from-source to rebuild from monorepo source (requires OLAM_DEV=1)."
+  ).option("-y, --yes", "Skip the confirmation prompt").option("--skip-recreate", "Build the image only; skip container stop/rm/start (only with --from-source)").option(
+    "--from-source",
+    "Build olam-auth from monorepo source (legacy path).\n                              Requires OLAM_DEV=1 + a `packages/` sibling at the install root."
+  ).action(async (opts) => {
+    const parsed = parseAuthUpgradeOpts(opts);
+    if (parsed.fromSource) {
+      if (!isDevMode()) {
+        printError(
+          new MissingBuildScriptError("packages/adapters/src/docker/build-auth.sh").message
+        );
+        process.exitCode = 1;
+        return;
+      }
+      await handleAuthUpgrade(parsed);
+      return;
+    }
+    try {
+      const result = await runAuthUpgradePullByDigest();
+      process.exitCode = result.exitCode;
+    } catch (err) {
+      printError(err instanceof Error ? err.message : String(err));
+      process.exitCode = EXIT_GENERIC_ERROR;
+    }
   });
 }
 
@@ -13466,7 +14008,7 @@ function registerAuthUpgrade(auth) {
 function openBrowser(url) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   try {
-    const child = spawn2(cmd, [url], { detached: true, stdio: "ignore" });
+    const child = spawn3(cmd, [url], { detached: true, stdio: "ignore" });
     child.unref();
   } catch {
   }
@@ -13506,7 +14048,7 @@ function registerAuth(program2) {
     printInfo("Port", String(initial.port));
     printInfo("Volume", "olam-auth-data");
     console.log(`
-${pc7.dim("Next: olam auth login")}`);
+${pc8.dim("Next: olam auth login")}`);
   });
   auth.command("down").description("Stop the auth container (tokens persist in the volume)").action(() => {
     const controller = new AuthContainerController();
@@ -13531,15 +14073,15 @@ ${pc7.dim("Next: olam auth login")}`);
     }
     printHeader(`Credentials (${status.accounts.length})`);
     if (status.accounts.length === 0) {
-      console.log(`  ${pc7.dim("No credentials \u2014 run: olam auth login --label primary")}`);
+      console.log(`  ${pc8.dim("No credentials \u2014 run: olam auth login --label primary")}`);
       return;
     }
     const stateColor = (s) => {
-      if (s === "active") return pc7.green("active");
-      if (s === "cooldown") return pc7.yellow("cooldown");
-      if (s === "expired") return pc7.red("expired");
-      if (s === "disabled") return pc7.dim("disabled");
-      return pc7.dim(s ?? "unknown");
+      if (s === "active") return pc8.green("active");
+      if (s === "cooldown") return pc8.yellow("cooldown");
+      if (s === "expired") return pc8.red("expired");
+      if (s === "disabled") return pc8.dim("disabled");
+      return pc8.dim(s ?? "unknown");
     };
     for (const a of status.accounts) {
       const label = a.accountLabel ?? a.id;
@@ -13547,7 +14089,7 @@ ${pc7.dim("Next: olam auth login")}`);
       const last429 = a.usage?.last429At ? `last429=${a.usage.last429At}` : "last429=never";
       const reset = a.rateLimitResetsAt ? `resets=${a.rateLimitResetsAt}` : "";
       console.log(
-        `  ${pc7.bold(label.padEnd(18))} ${stateColor(a.state).padEnd(18)} ${pc7.dim(`req5h=${reqs}`)}  ${pc7.dim(`exp=${a.expiresIn}`)} ${pc7.dim(last429)} ${pc7.yellow(reset)}`
+        `  ${pc8.bold(label.padEnd(18))} ${stateColor(a.state).padEnd(18)} ${pc8.dim(`req5h=${reqs}`)}  ${pc8.dim(`exp=${a.expiresIn}`)} ${pc8.dim(last429)} ${pc8.yellow(reset)}`
       );
     }
   });
@@ -13585,7 +14127,7 @@ ${pc7.dim("Next: olam auth login")}`);
     const preflight = await runAuthPreflight({ autoStart: true });
     if (preflight.verdict !== "ok" && preflight.verdict !== "no-accounts") {
       printError(preflight.message);
-      console.log(`  ${pc7.dim(preflight.remedy)}`);
+      console.log(`  ${pc8.dim(preflight.remedy)}`);
       process.exitCode = 1;
       return;
     }
@@ -13618,14 +14160,14 @@ ${pc7.dim("Next: olam auth login")}`);
     }
     printHeader("Claude OAuth \u2014 PKCE flow");
     console.log(`
-  ${pc7.bold("1.")} Opening Claude in your default browser\u2026`);
-    console.log(`     ${pc7.dim(pending.loginUrl)}`);
+  ${pc8.bold("1.")} Opening Claude in your default browser\u2026`);
+    console.log(`     ${pc8.dim(pending.loginUrl)}`);
     openBrowser(pending.loginUrl);
     console.log(`
-  ${pc7.bold("2.")} After approving, paste the authorization code from the redirect page.`);
-    console.log(`     ${pc7.dim("(Format: <code>#<state> or just <code>.)")}
+  ${pc8.bold("2.")} After approving, paste the authorization code from the redirect page.`);
+    console.log(`     ${pc8.dim("(Format: <code>#<state> or just <code>.)")}
 `);
-    const raw = await promptLine(`${pc7.dim("code:")} `);
+    const raw = await promptLine(`${pc8.dim("code:")} `);
     if (!raw) {
       printError("No code provided.");
       process.exitCode = 1;
@@ -13636,7 +14178,7 @@ ${pc7.dim("Next: olam auth login")}`);
       const result = await client.completeLogin(statePart, codePart);
       printSuccess(`Account stored: ${result.account} (${result.expiresIn})`);
       console.log(`
-${pc7.dim("Next: olam create --name my-world")}`);
+${pc8.dim("Next: olam create --name my-world")}`);
     } catch (err) {
       printError(err instanceof Error ? err.message : "token exchange failed");
       process.exitCode = 1;
@@ -13667,16 +14209,16 @@ ${pc7.dim("Next: olam create --name my-world")}`);
 
 // src/commands/create.ts
 init_manager();
-import { spawnSync as spawnSync5 } from "node:child_process";
-import { existsSync as existsSync19 } from "node:fs";
-import { dirname as dirname13, resolve as resolve6 } from "node:path";
-import ora from "ora";
-import pc8 from "picocolors";
+import { spawnSync as spawnSync7 } from "node:child_process";
+import { existsSync as existsSync21 } from "node:fs";
+import { dirname as dirname14, resolve as resolve7 } from "node:path";
+import ora3 from "ora";
+import pc9 from "picocolors";
 
 // ../core/src/world/devbox-freshness.ts
 import { execSync as execSync6 } from "node:child_process";
-import { existsSync as existsSync18, statSync as statSync5 } from "node:fs";
-import { join as join25 } from "node:path";
+import { existsSync as existsSync20, statSync as statSync5 } from "node:fs";
+import { join as join27 } from "node:path";
 var DEFAULT_DEVBOX_IMAGE = "olam-devbox:latest";
 var DEVBOX_BAKED_SOURCES = [
   "packages/adapters/src/docker/devbox.Dockerfile",
@@ -13711,7 +14253,7 @@ function getDevboxFreshness(deps) {
   }
   const newerSources = [];
   for (const relPath of DEVBOX_BAKED_SOURCES) {
-    const absPath = join25(deps.repoRoot, relPath);
+    const absPath = join27(deps.repoRoot, relPath);
     const mtimeMs = statMtime(absPath);
     if (mtimeMs === null) continue;
     if (mtimeMs > imageCreatedAtMs) {
@@ -13741,9 +14283,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: path35, mtimeMs } of result.newerSources) {
+  for (const { path: path36, mtimeMs } of result.newerSources) {
     const when = new Date(mtimeMs).toISOString();
-    lines.push(`  \u2022 ${path35}  (modified ${when})`);
+    lines.push(`  \u2022 ${path36}  (modified ${when})`);
   }
   lines.push("");
   lines.push("Rebuild with:");
@@ -13765,7 +14307,7 @@ function defaultDockerInspect(image) {
 }
 function defaultStatMtime(absPath) {
   try {
-    if (!existsSync18(absPath)) return null;
+    if (!existsSync20(absPath)) return null;
     return statSync5(absPath).mtimeMs;
   } catch {
     return null;
@@ -13903,15 +14445,15 @@ init_context();
 var HOST_CP_URL = "http://127.0.0.1:19000";
 async function readHostCpTokenForCreate() {
   try {
-    const { default: fs31 } = await import("node:fs");
+    const { default: fs32 } = 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"),
+    const { default: path36 } = await import("node:path");
+    const tp = path36.join(
+      process.env.OLAM_HOME ?? path36.join(os18.homedir(), ".olam"),
       "host-cp.token"
     );
-    if (!fs31.existsSync(tp)) return null;
-    return fs31.readFileSync(tp, "utf-8").trim();
+    if (!fs32.existsSync(tp)) return null;
+    return fs32.readFileSync(tp, "utf-8").trim();
   } catch {
     return null;
   }
@@ -13952,7 +14494,7 @@ function registerCreate(program2) {
         resolvedName = defaultNameFromPrompt(opts.fromPrompt);
       }
       if (!resolvedWorkspace && !resolvedRepos) {
-        const inferenceSpinner = ora("Inferring workspace from prompt\u2026").start();
+        const inferenceSpinner = ora3("Inferring workspace from prompt\u2026").start();
         try {
           const catalog = await fetchHostCpWorkspaces();
           const catalogRepos = Array.from(
@@ -13967,9 +14509,9 @@ function registerCreate(program2) {
             const reason = inferred.repos.length === 0 ? "no repo names extracted from prompt" : `inference confidence ${inferred.confidence.toFixed(2)} below ${PICKER_CONFIDENCE_THRESHOLD}`;
             printError(`Picker needed: ${reason}`);
             if (catalogRepos.length > 0) {
-              console.log(pc8.dim(`  available repos: ${catalogRepos.join(", ")}`));
+              console.log(pc9.dim(`  available repos: ${catalogRepos.join(", ")}`));
             }
-            console.log(pc8.dim("  rerun with explicit --workspace <name> or --repos <a> <b> <c>"));
+            console.log(pc9.dim("  rerun with explicit --workspace <name> or --repos <a> <b> <c>"));
             process.exitCode = 1;
             return;
           }
@@ -13987,7 +14529,7 @@ function registerCreate(program2) {
             inferenceSpinner.fail(`Multiple workspaces match (${decision.result})`);
             const cands = decision.result === "exact-N" ? decision.candidates.map((w) => w.name) : decision.candidates.map((c) => c.workspace.name);
             printError(`Picker needed: ${cands.join(", ")}`);
-            console.log(pc8.dim("  rerun with explicit --workspace <name>"));
+            console.log(pc9.dim("  rerun with explicit --workspace <name>"));
             process.exitCode = 1;
             return;
           } else {
@@ -14020,10 +14562,24 @@ function registerCreate(program2) {
       const freshness = getDevboxFreshness({ repoRoot });
       if (freshness.isStale) {
         if (opts.rebuildBase) {
-          const spinner2 = ora("Rebuilding olam-devbox:latest\u2026").start();
-          const rebuild = spawnSync5(
+          const { resolveBuildScript: resolveBuildScript2, MissingBuildScriptError: MissingBuildScriptError2 } = await Promise.resolve().then(() => (init_install_root(), install_root_exports));
+          let buildScript;
+          try {
+            buildScript = resolveBuildScript2({
+              scriptRelPath: "packages/adapters/src/docker/build-devbox.sh"
+            });
+          } catch (err) {
+            if (err instanceof MissingBuildScriptError2) {
+              printError(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            throw err;
+          }
+          const spinner2 = ora3("Rebuilding olam-devbox:latest\u2026").start();
+          const rebuild = spawnSync7(
             "bash",
-            [resolve6(repoRoot, "packages/adapters/src/docker/build-devbox.sh")],
+            [buildScript],
             { cwd: repoRoot, stdio: "inherit" }
           );
           if (rebuild.status !== 0) {
@@ -14038,7 +14594,7 @@ function registerCreate(program2) {
         }
       }
     }
-    const spinner = ora("Creating world...").start();
+    const spinner = ora3("Creating world...").start();
     try {
       const world = await ctx.worldManager.createWorld({
         name: resolvedName,
@@ -14087,10 +14643,10 @@ function registerCreate(program2) {
       }
       if (world.credentialsInjected?.claude) {
         console.log(`
-${pc8.green("Credentials injected. World is ready for dispatch.")}`);
+${pc9.green("Credentials injected. World is ready for dispatch.")}`);
       } else if (world.dashboardUrl) {
         console.log(`
-${pc8.yellow("Authenticate at")} ${world.dashboardUrl}`);
+${pc9.yellow("Authenticate at")} ${world.dashboardUrl}`);
       }
       if (opts.hostCp !== false) {
         const probeResult = await probeHostCp().catch(() => null);
@@ -14102,14 +14658,14 @@ ${pc8.yellow("Authenticate at")} ${world.dashboardUrl}`);
           process.stderr.write(
             [
               "",
-              pc8.red("Host CP probe failed."),
+              pc9.red("Host CP probe failed."),
               `  tried: http://127.0.0.1:19000/api/bootstrap \u2192 ${diag.bootstrapStatus}`,
               `  tried: docker container "olam-host-cp" \u2192 ${diag.containerStatus}`,
               "",
-              pc8.yellow("World was created but the SPA inbox will not show it until you:"),
-              `  ${pc8.cyan("olam host-cp start")}            (start the host CP)`,
-              `  ${pc8.cyan(`olam host-cp register --world ${world.id}`)}   (register manually)`,
-              `  OR pass ${pc8.dim("--no-host-cp")} on next create to suppress this check.`,
+              pc9.yellow("World was created but the SPA inbox will not show it until you:"),
+              `  ${pc9.cyan("olam host-cp start")}            (start the host CP)`,
+              `  ${pc9.cyan(`olam host-cp register --world ${world.id}`)}   (register manually)`,
+              `  OR pass ${pc9.dim("--no-host-cp")} on next create to suppress this check.`,
               ""
             ].join("\n")
           );
@@ -14141,13 +14697,13 @@ ${pc8.yellow("Authenticate at")} ${world.dashboardUrl}`);
           process.stderr.write(
             [
               "",
-              pc8.red("Host CP registry POST failed."),
+              pc9.red("Host CP registry POST failed."),
               `  url: ${hostCpUrl}/api/admin/registry`,
               `  status: ${reg.status}`,
               `  error: ${reg.error}`,
               "",
-              pc8.yellow("World was created but not registered. Run manually:"),
-              `  ${pc8.cyan(`olam host-cp register --world ${world.id}`)}`,
+              pc9.yellow("World was created but not registered. Run manually:"),
+              `  ${pc9.cyan(`olam host-cp register --world ${world.id}`)}`,
               ""
             ].join("\n")
           );
@@ -14202,7 +14758,7 @@ ${pc8.yellow("Authenticate at")} ${world.dashboardUrl}`);
         }
         const worldUrl = `${hostCpUrl}/world/${encodeURIComponent(world.id)}`;
         console.log(`
-${pc8.cyan("Host CP UI:")} ${worldUrl}`);
+${pc9.cyan("Host CP UI:")} ${worldUrl}`);
         if (opts.open !== false && reg.ok) {
           const openResult = openUrl(worldUrl);
           if (openResult.opened) {
@@ -14216,7 +14772,7 @@ ${pc8.cyan("Host CP UI:")} ${worldUrl}`);
       spinner.fail("Failed to create world");
       if (err instanceof AuthPreflightError) {
         printError(err.message);
-        if (err.remedy) console.log(`  ${pc8.dim(err.remedy)}`);
+        if (err.remedy) console.log(`  ${pc9.dim(err.remedy)}`);
       } else {
         printError(err instanceof Error ? err.message : String(err));
       }
@@ -14227,10 +14783,10 @@ ${pc8.cyan("Host CP UI:")} ${worldUrl}`);
 function resolveRepoRoot(start) {
   let cur = start;
   while (true) {
-    if (existsSync19(resolve6(cur, "packages")) && existsSync19(resolve6(cur, "package.json"))) {
+    if (existsSync21(resolve7(cur, "packages")) && existsSync21(resolve7(cur, "package.json"))) {
       return cur;
     }
-    const parent = dirname13(cur);
+    const parent = dirname14(cur);
     if (parent === cur) return start;
     cur = parent;
   }
@@ -14241,12 +14797,12 @@ function defaultNameFromPrompt(prompt) {
 }
 async function readHostCpToken3() {
   try {
-    const { default: fs31 } = await import("node:fs");
+    const { default: fs32 } = 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();
+    const { default: path36 } = await import("node:path");
+    const tp = path36.join(os18.homedir(), ".olam", "host-cp.token");
+    if (!fs32.existsSync(tp)) return null;
+    const raw = fs32.readFileSync(tp, "utf-8").trim();
     return raw.length > 0 ? raw : null;
   } catch {
     return null;
@@ -14289,8 +14845,8 @@ async function fetchHostCpExactMatches(projects) {
 
 // src/commands/dispatch.ts
 init_context();
-import ora2 from "ora";
-import pc9 from "picocolors";
+import ora4 from "ora";
+import pc10 from "picocolors";
 
 // ../core/src/orchestrator/dispatch.ts
 var DEEP_MODE_SUFFIX = "\n\nUltrathink and use sub-agents (the Agent tool) to parallelize independent work. Break complex tasks into focused sub-tasks.";
@@ -14316,7 +14872,7 @@ function registerDispatch(program2) {
       process.exitCode = 1;
       return;
     }
-    const spinner = ora2("Dispatching...").start();
+    const spinner = ora4("Dispatching...").start();
     try {
       const computeWorld = await ctx.computeProvider.getWorld(worldId);
       if (!computeWorld) {
@@ -14373,7 +14929,7 @@ OLAM_EOF`
       const containerName = `olam-${worldId}-devbox`;
       console.log(
         `
-${pc9.dim(`Watch live: docker exec -it ${containerName} tmux attach -t claude-main -r`)}`
+${pc10.dim(`Watch live: docker exec -it ${containerName} tmux attach -t claude-main -r`)}`
       );
     } catch (err) {
       spinner.fail("Dispatch failed");
@@ -14385,7 +14941,7 @@ ${pc9.dim(`Watch live: docker exec -it ${containerName} tmux attach -t claude-ma
 
 // src/commands/observe.ts
 init_context();
-import pc10 from "picocolors";
+import pc11 from "picocolors";
 function registerObserve(program2) {
   program2.command("observe").description("Stream thoughts from a world (coming soon)").argument("<world>", "World ID").action(async (worldId) => {
     const { ctx, error } = await loadContext();
@@ -14401,22 +14957,22 @@ function registerObserve(program2) {
       return;
     }
     console.log(
-      pc10.yellow("Observation is coming in a future release.")
+      pc11.yellow("Observation is coming in a future release.")
     );
     console.log(
-      pc10.dim("This will stream the world's reasoning in real-time.")
+      pc11.dim("This will stream the world's reasoning in real-time.")
     );
     const containerName = `olam-${worldId}-devbox`;
     console.log(
       `
-${pc10.dim(`For now: docker exec -it ${containerName} tmux attach -t claude-main -r`)}`
+${pc11.dim(`For now: docker exec -it ${containerName} tmux attach -t claude-main -r`)}`
     );
   });
 }
 
 // src/commands/list.ts
 init_context();
-import pc11 from "picocolors";
+import pc12 from "picocolors";
 function registerList(program2) {
   program2.command("list").alias("ls").description("List active worlds").action(async () => {
     const { ctx, error } = await loadContext();
@@ -14427,18 +14983,18 @@ function registerList(program2) {
     }
     const worlds = ctx.worldManager.listWorlds();
     if (worlds.length === 0) {
-      console.log(pc11.dim("No worlds. Create one with `olam create --name my-world`."));
+      console.log(pc12.dim("No worlds. Create one with `olam create --name my-world`."));
       return;
     }
-    console.log(`${pc11.bold(String(worlds.length))} world(s)
+    console.log(`${pc12.bold(String(worlds.length))} world(s)
 `);
     for (const w of worlds) {
-      const statusColor = w.status === "running" ? pc11.green(w.status) : w.status === "error" ? pc11.red(w.status) : pc11.yellow(w.status);
+      const statusColor = w.status === "running" ? pc12.green(w.status) : w.status === "error" ? pc12.red(w.status) : pc12.yellow(w.status);
       const age = formatAge(w.createdAt);
       const cost = `$${w.totalCostUsd.toFixed(2)}`;
-      console.log(`  ${pc11.bold(w.name)} ${pc11.dim(`(${w.id})`)}`);
+      console.log(`  ${pc12.bold(w.name)} ${pc12.dim(`(${w.id})`)}`);
       console.log(
-        `    ${statusColor}  ${pc11.dim("|")}  ${w.repos.join(", ")}  ${pc11.dim("|")}  ${cost}  ${pc11.dim("|")}  ${age}`
+        `    ${statusColor}  ${pc12.dim("|")}  ${w.repos.join(", ")}  ${pc12.dim("|")}  ${cost}  ${pc12.dim("|")}  ${age}`
       );
       console.log();
     }
@@ -14490,7 +15046,7 @@ function registerStatus(program2) {
 
 // src/commands/destroy.ts
 init_context();
-import ora3 from "ora";
+import ora5 from "ora";
 function registerDestroy(program2) {
   program2.command("destroy").description("Destroy a world and clean up resources").argument("<world>", "World ID").option("--skip-crystallize", "Skip thought crystallization").action(async (worldId, opts) => {
     const { ctx, error } = await loadContext();
@@ -14505,7 +15061,7 @@ function registerDestroy(program2) {
       process.exitCode = 1;
       return;
     }
-    const spinner = ora3(`Destroying ${world.name}...`).start();
+    const spinner = ora5(`Destroying ${world.name}...`).start();
     try {
       await ctx.worldManager.destroyWorld(worldId, {
         skipCrystallize: opts.skipCrystallize
@@ -14529,7 +15085,7 @@ function registerDestroy(program2) {
 // src/commands/enter.ts
 init_context();
 import { execSync as execSync7 } from "node:child_process";
-import pc12 from "picocolors";
+import pc13 from "picocolors";
 var SAFE_IDENT3 = /^[a-z0-9][a-z0-9-]{0,63}$/;
 function buildStartClaudeCommands(containerName, sessionName, task) {
   if (!SAFE_IDENT3.test(containerName)) {
@@ -14631,7 +15187,7 @@ function registerEnter(program2) {
       }
       console.log("Run these commands in order to enter the world:\n");
       for (const step of steps) {
-        console.log(`  ${pc12.dim(`# ${step.description}`)}`);
+        console.log(`  ${pc13.dim(`# ${step.description}`)}`);
         if (step.stdin !== void 0) {
           const escaped = step.stdin.replace(/'/g, "'\\''");
           console.log(`  printf '%s' '${escaped}' | ${step.command}`);
@@ -14665,11 +15221,11 @@ function registerEnter(program2) {
       return;
     }
     console.log("Run this command to enter the world:\n");
-    console.log(`  ${pc12.bold(result.command)}`);
+    console.log(`  ${pc13.bold(result.command)}`);
     const containerName = `olam-${worldId}-devbox`;
     console.log(
       `
-${pc12.dim(`Observe dispatch: docker exec -it ${containerName} tmux attach -t olam-dispatch -r`)}`
+${pc13.dim(`Observe dispatch: docker exec -it ${containerName} tmux attach -t olam-dispatch -r`)}`
     );
   });
 }
@@ -14678,7 +15234,7 @@ ${pc12.dim(`Observe dispatch: docker exec -it ${containerName} tmux attach -t ol
 init_context();
 import * as fs21 from "node:fs";
 import "node:path";
-import ora4 from "ora";
+import ora6 from "ora";
 init_world_paths();
 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) => {
@@ -14714,7 +15270,7 @@ function registerCrystallize(program2, options = {}) {
       process.exitCode = EXIT_GENERIC_ERROR;
       return;
     }
-    const spinner = ora4("Crystallizing thoughts...").start();
+    const spinner = ora6("Crystallizing thoughts...").start();
     try {
       const { ThoughtLocalStore: ThoughtLocalStore2 } = await Promise.resolve().then(() => (init_local_store(), local_store_exports));
       const { computeGraphChecksum: computeGraphChecksum2 } = await Promise.resolve().then(() => (init_checksum(), checksum_exports));
@@ -14779,7 +15335,7 @@ function registerCrystallize(program2, options = {}) {
 
 // src/commands/pr.ts
 init_registry();
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 
 // ../core/src/pr-gate/client.ts
 var HOST_CONTROL_PLANE_BASE2 = 19080;
@@ -14859,26 +15415,26 @@ async function findGate(id) {
   return null;
 }
 function formatStateBadge(state) {
-  if (state === "approve") return pc13.green("approve");
-  if (state === "block") return pc13.red("block");
-  if (state === "denied") return pc13.gray("denied");
-  return pc13.yellow("pending");
+  if (state === "approve") return pc14.green("approve");
+  if (state === "block") return pc14.red("block");
+  if (state === "denied") return pc14.gray("denied");
+  return pc14.yellow("pending");
 }
 function registerPr(program2) {
   const pr = program2.command("pr").description("Review and decide PR-gate requests from running worlds");
   pr.command("list").description("List all PR-gate requests across every running world").action(async () => {
     const all = await fanoutList();
     if (all.length === 0) {
-      console.log(pc13.dim("No gates open."));
+      console.log(pc14.dim("No gates open."));
       return;
     }
     printHeader(`${all.length} gate(s)`);
     for (const { world, gate } of all) {
       const badge = formatStateBadge(gate.state);
       console.log(
-        `  ${pc13.bold(gate.id.slice(0, 8))} ${badge.padEnd(20)} ${pc13.dim(world.name)} ${pc13.dim(gate.branch)}`
+        `  ${pc14.bold(gate.id.slice(0, 8))} ${badge.padEnd(20)} ${pc14.dim(world.name)} ${pc14.dim(gate.branch)}`
       );
-      console.log(`    ${pc13.dim(gate.command.slice(0, 100))}`);
+      console.log(`    ${pc14.dim(gate.command.slice(0, 100))}`);
     }
   });
   pr.command("show").description("Show full gate detail (diff, command, commits)").argument("<id>", "Gate id (prefix match ok)").action(async (id) => {
@@ -14901,9 +15457,9 @@ function registerPr(program2) {
       if (gate.reason) printInfo("Reason", gate.reason);
     }
     printHeader("Commits");
-    console.log(gate.commitLog || pc13.dim("  (empty)"));
+    console.log(gate.commitLog || pc14.dim("  (empty)"));
     printHeader("Diff stat");
-    console.log(gate.diffStat || pc13.dim("  (empty)"));
+    console.log(gate.diffStat || pc14.dim("  (empty)"));
   });
   function decideCommand(verb, decision) {
     pr.command(verb).description(`${verb[0].toUpperCase()}${verb.slice(1)} a pending gate`).argument("<id>", "Gate id").option("--reason <reason>", "Short free-text reason").option("--by <name>", "Deciding identity (defaults to $USER)", process.env["USER"] ?? "human").action(async (id, opts) => {
@@ -15023,7 +15579,7 @@ function registerLanes(program2) {
 // src/commands/policy-check.ts
 init_loader2();
 import { execSync as execSync8 } from "node:child_process";
-import pc14 from "picocolors";
+import pc15 from "picocolors";
 
 // ../../node_modules/balanced-match/dist/esm/index.js
 var balanced = (a, b, str) => {
@@ -16887,7 +17443,7 @@ function registerPolicyCheck(program2) {
     const workspaceRoot = opts.workspace ?? process.cwd();
     const policies = loadPolicies(workspaceRoot);
     if (policies.length === 0) {
-      console.log(pc14.dim("policy-check: no policies found in .olam/policies/ \u2014 nothing to enforce"));
+      console.log(pc15.dim("policy-check: no policies found in .olam/policies/ \u2014 nothing to enforce"));
       return;
     }
     const diff = getDiff(opts.base, workspaceRoot);
@@ -16896,11 +17452,11 @@ function registerPolicyCheck(program2) {
     for (const result of results) {
       if (result.passed) continue;
       if (result.severity === "error") {
-        console.error(`${pc14.red("policy error")} [${result.policyId}]`);
+        console.error(`${pc15.red("policy error")} [${result.policyId}]`);
         console.error(result.message);
         hasErrorFailure = true;
       } else {
-        console.warn(`${pc14.yellow("policy warn")} [${result.policyId}]`);
+        console.warn(`${pc15.yellow("policy warn")} [${result.policyId}]`);
         console.warn(result.message);
       }
     }
@@ -16913,14 +17469,15 @@ 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";
+import { spawnSync as spawnSync9 } from "node:child_process";
+import ora7 from "ora";
+import pc16 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 { spawnSync as spawnSync8 } from "node:child_process";
 var LOCK_FILE_PATH = path26.join(os13.homedir(), ".olam", ".upgrade.lock");
 var STALE_LOCK_TIMEOUT_MS = 5 * 60 * 1e3;
 function readLockFile(lockPath) {
@@ -16945,7 +17502,7 @@ function isPidAlive(pid) {
 }
 var PS_UNAVAILABLE = "__ps_unavailable__";
 function getPidCommand(pid) {
-  const result = spawnSync6("ps", ["-p", String(pid), "-o", "comm="], {
+  const result = spawnSync8("ps", ["-p", String(pid), "-o", "comm="], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "ignore"]
   });
@@ -17143,6 +17700,7 @@ function handleHistory(opts) {
 
 // src/commands/upgrade.ts
 init_auth();
+init_install_root();
 var AUTH_HEALTH_URL2 = "http://127.0.0.1:9999/health";
 function isNodeModulesInSync(cwd) {
   const lockPath = path28.join(cwd, "package-lock.json");
@@ -17189,7 +17747,8 @@ function parseUpgradeOpts(raw) {
     noCache: raw.noCache === true,
     history: raw.history === true,
     historyN: Number.isFinite(historyN) && historyN > 0 ? historyN : 10,
-    historyJson: raw.json === true
+    historyJson: raw.json === true,
+    fromSource: raw.fromSource === true
   };
 }
 function extractBundleHash(indexHtml) {
@@ -17198,8 +17757,8 @@ function extractBundleHash(indexHtml) {
 }
 function runStep2(label, cmd, args, opts = {}) {
   const start = Date.now();
-  process.stdout.write(`  ${pc15.dim(label.padEnd(34))}`);
-  const result = spawnSync7(cmd, [...args], {
+  process.stdout.write(`  ${pc16.dim(label.padEnd(34))}`);
+  const result = spawnSync9(cmd, [...args], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd: opts.cwd ?? process.cwd(),
@@ -17208,7 +17767,7 @@ function runStep2(label, cmd, args, opts = {}) {
   const durationMs = Date.now() - start;
   const ok = result.status === 0 && result.error === void 0;
   const dur = `${(durationMs / 1e3).toFixed(1)}s`;
-  process.stdout.write(`${ok ? pc15.green("\u2713") : pc15.red("\u2717")} ${dur}
+  process.stdout.write(`${ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${dur}
 `);
   return {
     ok,
@@ -17218,7 +17777,7 @@ function runStep2(label, cmd, args, opts = {}) {
   };
 }
 function isGitDirty(cwd) {
-  const result = spawnSync7("git", ["status", "--porcelain"], {
+  const result = spawnSync9("git", ["status", "--porcelain"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd
@@ -17226,7 +17785,7 @@ function isGitDirty(cwd) {
   return (result.stdout ?? "").trim().length > 0;
 }
 function hasGitUpstream(cwd) {
-  const result = spawnSync7("git", ["rev-parse", "--abbrev-ref", "@{u}"], {
+  const result = spawnSync9("git", ["rev-parse", "--abbrev-ref", "@{u}"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd
@@ -17234,7 +17793,7 @@ function hasGitUpstream(cwd) {
   return result.status === 0;
 }
 function captureHeadSha(cwd) {
-  const result = spawnSync7("git", ["rev-parse", "HEAD"], {
+  const result = spawnSync9("git", ["rev-parse", "HEAD"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
     cwd
@@ -17249,7 +17808,7 @@ function abbreviateSha(sha) {
 }
 function imageExists(tag) {
   try {
-    const result = spawnSync7("docker", ["image", "inspect", "--format", "{{.Id}}", tag], {
+    const result = spawnSync9("docker", ["image", "inspect", "--format", "{{.Id}}", tag], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -17264,7 +17823,7 @@ function checkRollbackSetExists(plan) {
   return missing.join(", ");
 }
 function smokeImage(image, targetSha) {
-  const createResult = spawnSync7("docker", ["create", "--name", `olam-smoke-${Date.now()}`, image], {
+  const createResult = spawnSync9("docker", ["create", "--name", `olam-smoke-${Date.now()}`, image], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -17277,16 +17836,16 @@ function smokeImage(image, targetSha) {
     };
   }
   const containerId = (createResult.stdout ?? "").trim();
-  const inspectResult = spawnSync7(
+  const inspectResult = spawnSync9(
     "docker",
-    ["inspect", "--format", '{{index .Config.Labels "olam_build_sha"}}', image],
+    ["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], {
+    spawnSync9("docker", ["rm", "-f", containerId], {
       encoding: "utf-8",
       stdio: ["ignore", "ignore", "ignore"]
     });
@@ -17305,7 +17864,7 @@ function smokeImage(image, targetSha) {
       image,
       ok: false,
       bakedSha: null,
-      error: "olam_build_sha label is missing or empty"
+      error: "olam.build.sha label is missing or empty"
     };
   }
   if (bakedSha !== targetSha) {
@@ -17325,7 +17884,7 @@ var PRODUCTION_SWAP_PLAN = [
 ];
 function dockerTag(source, dest) {
   try {
-    const result = spawnSync7("docker", ["tag", source, dest], {
+    const result = spawnSync9("docker", ["tag", source, dest], {
       encoding: "utf-8",
       stdio: ["ignore", "ignore", "pipe"]
     });
@@ -17418,10 +17977,10 @@ async function confirm2(message) {
   if (!process.stdin.isTTY) return true;
   const { createInterface: createInterface2 } = await import("node:readline");
   const rl = createInterface2({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     rl.question(`${message} [y/N] `, (answer) => {
       rl.close();
-      resolve7(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+      resolve8(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
     });
   });
 }
@@ -17488,11 +18047,11 @@ async function waitForAuthHealthLocal(timeoutMs = 15e3) {
 async function recreateAuthService() {
   const start = Date.now();
   try {
-    spawnSync7("docker", ["stop", "olam-auth"], {
+    spawnSync9("docker", ["stop", "olam-auth"], {
       encoding: "utf-8",
       stdio: ["ignore", "ignore", "ignore"]
     });
-    spawnSync7("docker", ["rm", "olam-auth"], {
+    spawnSync9("docker", ["rm", "olam-auth"], {
       encoding: "utf-8",
       stdio: ["ignore", "ignore", "ignore"]
     });
@@ -17521,6 +18080,163 @@ function readBundleHash(cwd) {
   if (!fs24.existsSync(indexPath)) return null;
   return extractBundleHash(fs24.readFileSync(indexPath, "utf-8"));
 }
+async function runUpgradePullByDigest(deps = {}) {
+  const docker2 = deps.docker ?? realDocker;
+  const digests = deps.digests ?? loadImageDigests();
+  const registry = deps.registry ?? digests.$registry ?? "ghcr.io/pleri";
+  printHeader("olam upgrade (pull-by-digest)");
+  const infoSpinner = ora7("Checking docker daemon").start();
+  const info = await docker2.info();
+  if (info.exitCode !== 0) {
+    infoSpinner.fail("docker daemon not reachable");
+    process.stderr.write(
+      `${pc16.red("error")} docker info exited with ${info.exitCode}.
+  Ensure Docker Desktop / Colima / Rancher is running, then retry.
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "docker daemon not reachable" };
+  }
+  infoSpinner.succeed("docker daemon reachable");
+  const imageRefs = [
+    { name: "host-cp", ref: `${registry}/olam-host-cp@${digests["host-cp"]}` },
+    { name: "auth", ref: `${registry}/olam-auth@${digests.auth}` },
+    { name: "devbox", ref: `${registry}/olam-devbox@${digests.devbox}` }
+  ];
+  const pullSpinner = ora7("Pulling images (3 parallel)").start();
+  const pullStart = Date.now();
+  const pullResults = await Promise.all(
+    imageRefs.map(async ({ name, ref }) => ({
+      name,
+      ref,
+      result: await pullImageWithRetry(ref, docker2)
+    }))
+  );
+  const pullElapsed = ((Date.now() - pullStart) / 1e3).toFixed(1);
+  const failed = pullResults.filter((r) => r.result.exitCode !== 0);
+  if (failed.length > 0) {
+    pullSpinner.fail(`Pull failed for ${failed.map((r) => r.name).join(", ")}`);
+    for (const f of failed) {
+      process.stderr.write(
+        `  ${pc16.red(f.name)} (${f.ref}):
+    exit=${f.result.exitCode}
+    stderr: ${f.result.stderr.split("\n")[0] ?? "(empty)"}
+`
+      );
+    }
+    process.stderr.write(
+      "\n  Remedy: re-run after resolving network / GHCR availability.\n  For monorepo dev, `OLAM_DEV=1 olam upgrade --from-source` builds locally.\n"
+    );
+    return {
+      exitCode: EXIT_BOOTSTRAP_PULL_FAILED,
+      summary: `pull failed: ${failed.map((r) => r.name).join(", ")}`
+    };
+  }
+  pullSpinner.succeed(`Pulled 3 images in ${pullElapsed}s`);
+  const handshakeSpinner = ora7("Verifying olam.protocol.versions handshake").start();
+  for (const { name, ref } of imageRefs) {
+    const inspect = await docker2.inspectLabel(ref, "olam.protocol.versions");
+    if (inspect.exitCode !== 0) {
+      handshakeSpinner.fail(`Could not inspect ${name}`);
+      process.stderr.write(
+        `${pc16.red("error")} docker inspect ${ref} failed: ${inspect.stderr}
+`
+      );
+      return { exitCode: EXIT_GENERIC_ERROR, summary: `inspect failed: ${name}` };
+    }
+    const labelValue = (inspect.stdout || "").trim();
+    const versions = parseProtocolVersionsLabel(
+      labelValue === "<no value>" ? "" : labelValue
+    );
+    const decision = checkProtocolOverlap(versions);
+    if (!decision.compatible) {
+      handshakeSpinner.fail(`Protocol mismatch on ${name}`);
+      process.stderr.write(`${pc16.red("error")} ${decision.remedy}
+`);
+      return {
+        exitCode: EXIT_PROTOCOL_MISMATCH,
+        summary: `protocol mismatch: ${name}`
+      };
+    }
+  }
+  handshakeSpinner.succeed("Protocol handshake passed (all 3 images)");
+  const tagPlan = [
+    { from: imageRefs[0].ref, to: "olam-host-cp:latest", name: "host-cp" },
+    { from: imageRefs[1].ref, to: "olam-auth:local", name: "auth" },
+    { from: imageRefs[2].ref, to: "olam-devbox:latest", name: "devbox" }
+  ];
+  const tagSpinner = ora7("Tagging digests \u2192 canonical local refs").start();
+  const tagger = deps.tagImpl ?? dockerTag;
+  for (const t of tagPlan) {
+    const r = tagger(t.from, t.to);
+    if (!r.ok) {
+      tagSpinner.fail(`docker tag failed for ${t.name}`);
+      process.stderr.write(`${pc16.red("error")} ${r.error ?? "docker tag failed"}
+`);
+      return { exitCode: EXIT_GENERIC_ERROR, summary: `tag failed: ${t.name}` };
+    }
+  }
+  tagSpinner.succeed("Re-tagged 3 images to canonical refs");
+  const composeFile = deps.composeFile ?? path28.join(process.cwd(), "packages/host-cp/compose.yaml");
+  const authSecret = deps.authSecret ?? readAuthSecret2();
+  const composeRunner = deps.runComposeImpl ?? runCompose;
+  const composeSpinner = ora7("docker compose recreate host-cp").start();
+  const composeResult = composeRunner(
+    ["up", "-d", "--force-recreate", "host-cp"],
+    composeFile,
+    buildComposeEnv(authSecret)
+  );
+  if (!composeResult.ok) {
+    composeSpinner.fail("compose recreate failed");
+    process.stderr.write(
+      `${pc16.red("error")} docker compose up --force-recreate host-cp failed:
+  ${composeResult.stderr.split("\n").slice(0, 3).join("\n  ")}
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "compose recreate failed" };
+  }
+  composeSpinner.succeed("host-cp recreated");
+  const authSpinner = ora7("recreate auth-service").start();
+  const authRecreate = deps.recreateAuth ?? defaultRecreateAuthForUpgrade;
+  const authResult = await authRecreate();
+  if (!authResult.ok) {
+    authSpinner.fail("auth-service recreate failed");
+    process.stderr.write(
+      `${pc16.red("error")} ${authResult.error ?? "unknown failure"}
+`
+    );
+    return { exitCode: EXIT_GENERIC_ERROR, summary: "auth recreate failed" };
+  }
+  authSpinner.succeed("auth-service running on new image");
+  printSuccess("Upgrade complete (pull-by-digest)");
+  printInfo("host-cp", `running (${digests["host-cp"].slice(0, 19)}\u2026)`);
+  printInfo("auth", `running (${digests.auth.slice(0, 19)}\u2026)`);
+  printInfo("devbox", `pulled (${digests.devbox.slice(0, 19)}\u2026)`);
+  return { exitCode: 0, summary: "stack upgraded" };
+}
+async function defaultRecreateAuthForUpgrade() {
+  try {
+    spawnSync9("docker", ["stop", "olam-auth"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    spawnSync9("docker", ["rm", "olam-auth"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    const controller = new AuthContainerController();
+    controller.start();
+    const healthy = await waitForAuthHealthLocal(15e3);
+    if (!healthy) {
+      return { ok: false, error: "auth-service /health did not respond within 15s" };
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
 async function handleUpgrade(opts) {
   const cwd = process.cwd();
   const rootCheck = validateRepoRoot(cwd);
@@ -17529,6 +18245,10 @@ async function handleUpgrade(opts) {
     process.exitCode = 1;
     return;
   }
+  if (opts.history) {
+    handleHistory(parseHistoryOpts({ n: opts.historyN, json: opts.historyJson }));
+    return;
+  }
   printHeader("olam upgrade");
   const steps = [
     "git fetch origin --prune",
@@ -17537,9 +18257,13 @@ async function handleUpgrade(opts) {
     "npm run build (TS workspaces)",
     "vite build (SPA)",
     ...opts.skipImage ? [] : [
-      "bash build-host-cp.sh (docker image)",
-      "docker compose up -d --force-recreate",
-      "wait for /health"
+      "bash build-auth.sh (auth-service image)",
+      "bash build-devbox.sh (devbox image)",
+      "bash build-host-cp.sh (host-cp image)",
+      "smoke (docker create + inspect)",
+      "atomic 6-tag swap (canonical -> :olam-rollback; :olam-next -> canonical)",
+      "docker compose --force-recreate host-cp + AuthContainerController.start auth",
+      "poll /api/version/status until SHAs match"
     ]
   ];
   printInfo("Steps", steps.join(", "));
@@ -17554,10 +18278,6 @@ async function handleUpgrade(opts) {
       return;
     }
   }
-  if (opts.history) {
-    handleHistory(parseHistoryOpts({ n: opts.historyN, json: opts.historyJson }));
-    return;
-  }
   if (opts.rollback) {
     return await handleRollback();
   }
@@ -17641,11 +18361,11 @@ manually inspect images with \`docker images olam-*:olam-rollback\`.`
   process.once("SIGINT", releaseOnSignal);
   process.once("SIGTERM", releaseOnSignal);
   try {
-    process.stdout.write(`  ${pc15.dim("rollback retag (3 ops)".padEnd(34))}`);
+    process.stdout.write(`  ${pc16.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}
+    process.stdout.write(`${swapResult.ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${swapDur}
 `);
     if (!swapResult.ok) {
       printError(`Rollback retag failed: ${swapResult.summary}`);
@@ -17656,11 +18376,11 @@ manually inspect images with \`docker images olam-*:olam-rollback\`.`
     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))}`);
+    process.stdout.write(`  ${pc16.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}
+    process.stdout.write(`${composeResult.ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${composeDur}
 `);
     if (!composeResult.ok) {
       printError(
@@ -17671,10 +18391,10 @@ Canonical tags are at :olam-rollback (good); container restart pending. Manually
       process.exitCode = 1;
       return;
     }
-    process.stdout.write(`  ${pc15.dim("recreate auth-service".padEnd(34))}`);
+    process.stdout.write(`  ${pc16.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}
+    process.stdout.write(`${authResult.ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${authDur}
 `);
     if (!authResult.ok) {
       printError(`Auth-service recreate failed: ${authResult.error ?? "unknown"}`);
@@ -17826,13 +18546,24 @@ ${spaResult.stderr}`);
     { 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 }
   ];
+  const { resolveBuildScript: resolveBuildScript2, MissingBuildScriptError: MissingBuildScriptError2 } = await Promise.resolve().then(() => (init_install_root(), install_root_exports));
   for (const step of buildScripts) {
-    const scriptPath = path28.join(cwd, step.relPath);
+    let scriptPath;
+    try {
+      scriptPath = resolveBuildScript2({ scriptRelPath: step.relPath });
+    } catch (err) {
+      if (err instanceof MissingBuildScriptError2) {
+        printError(err.message);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
     if (step.tee) {
-      process.stdout.write(`  ${pc15.dim(step.label.padEnd(34))}
+      process.stdout.write(`  ${pc16.dim(step.label.padEnd(34))}
 `);
       const start = Date.now();
-      const result = spawnSync7("bash", [scriptPath], {
+      const result = spawnSync9("bash", [scriptPath], {
         stdio: "inherit",
         cwd,
         env: { ...process.env, ...olamTagEnv }
@@ -17840,7 +18571,7 @@ ${spaResult.stderr}`);
       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}
+      process.stdout.write(`  ${pc16.dim(step.label.padEnd(34))}${ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${dur}
 `);
       timings.push({ label: step.label, durationMs });
       if (!ok) {
@@ -17866,7 +18597,7 @@ ${result.stderr.split("\n").slice(-3).join("\n")}`);
   }
   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))}`);
+  process.stdout.write(`  ${pc16.dim("smoke (docker create + inspect)".padEnd(34))}`);
   const smokeImages = [
     "olam-auth:olam-next",
     "olam-devbox:olam-next",
@@ -17876,7 +18607,7 @@ ${result.stderr.split("\n").slice(-3).join("\n")}`);
   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}
+  process.stdout.write(`${smokeFailures.length === 0 ? pc16.green("\u2713") : pc16.red("\u2717")} ${smokeDur}
 `);
   timings.push({ label: "smoke", durationMs: smokeDurationMs });
   if (smokeFailures.length > 0) {
@@ -17903,12 +18634,12 @@ Recovery options:
     process.exitCode = 1;
     return;
   }
-  process.stdout.write(`  ${pc15.dim("atomic 6-tag swap".padEnd(34))}`);
+  process.stdout.write(`  ${pc16.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}
+  process.stdout.write(`${swapResult.ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${swapDur}
 `);
   timings.push({ label: "atomic swap", durationMs: swapDurationMs });
   if (!swapResult.ok) {
@@ -17918,7 +18649,7 @@ Recovery options:
   }
   printInfo("Swap", swapResult.summary);
   const composeFile = path28.join(cwd, "packages/host-cp/compose.yaml");
-  process.stdout.write(`  ${pc15.dim("docker compose recreate".padEnd(34))}`);
+  process.stdout.write(`  ${pc16.dim("docker compose recreate".padEnd(34))}`);
   const composeStart = Date.now();
   const composeResult = runCompose(
     ["up", "-d", "--force-recreate"],
@@ -17928,7 +18659,7 @@ Recovery options:
   const composeDurationMs = Date.now() - composeStart;
   const composeOk = composeResult.ok;
   const composeDur = `${(composeDurationMs / 1e3).toFixed(1)}s`;
-  process.stdout.write(`${composeOk ? pc15.green("\u2713") : pc15.red("\u2717")} ${composeDur}
+  process.stdout.write(`${composeOk ? pc16.green("\u2713") : pc16.red("\u2717")} ${composeDur}
 `);
   timings.push({ label: "container recreate", durationMs: composeDurationMs });
   if (!composeOk) {
@@ -17944,10 +18675,10 @@ Recovery options:
     process.exitCode = 1;
     return;
   }
-  process.stdout.write(`  ${pc15.dim("recreate auth-service".padEnd(34))}`);
+  process.stdout.write(`  ${pc16.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}
+  process.stdout.write(`${authResult.ok ? pc16.green("\u2713") : pc16.red("\u2717")} ${authDur}
 `);
   timings.push({ label: "auth recreate", durationMs: authResult.durationMs });
   if (!authResult.ok) {
@@ -17962,12 +18693,12 @@ Recovery options:
     process.exitCode = 1;
     return;
   }
-  process.stdout.write(`  ${pc15.dim("waiting for /health".padEnd(34))}`);
+  process.stdout.write(`  ${pc16.dim("waiting for /health".padEnd(34))}`);
   const healthStart = Date.now();
   const healthy = await waitForHealth(1e4);
   const healthDurationMs = Date.now() - healthStart;
   const healthDur = `${(healthDurationMs / 1e3).toFixed(1)}s`;
-  process.stdout.write(`${healthy ? pc15.green("\u2713") : pc15.yellow("?")} ${healthDur}
+  process.stdout.write(`${healthy ? pc16.green("\u2713") : pc16.yellow("?")} ${healthDur}
 `);
   timings.push({ label: "/health", durationMs: healthDurationMs });
   if (!healthy) {
@@ -17975,12 +18706,12 @@ Recovery options:
       "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))}`);
+  process.stdout.write(`  ${pc16.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}
+  process.stdout.write(`${versionMatch.matched ? pc16.green("\u2713") : pc16.yellow("?")} ${versionDur}
 `);
   timings.push({ label: "/version/status round-trip", durationMs: versionDurationMs });
   if (!versionMatch.matched) {
@@ -18004,7 +18735,9 @@ 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 all three components)").option("-y, --yes", "Skip the confirmation prompt").option("--skip-image", "Skip docker image rebuild + container recreate (source rebuild only)").option(
+  program2.command("upgrade").description(
+    "Upgrade the local Olam stack to the CLI's pinned image digests. Default: pull pre-built images from ghcr.io and recreate containers. Use --from-source for the legacy monorepo build path (requires OLAM_DEV=1)."
+  ).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)").option(
@@ -18019,24 +18752,47 @@ function registerUpgrade(program2) {
   ).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));
+  ).option("-n <count>", "Number of history rows to print (default 10)", "10").option("--json", "Emit history as JSONL instead of a table").option(
+    "--from-source",
+    "Build host-cp + auth + devbox from monorepo source (legacy path).\n                              Requires OLAM_DEV=1 + a `packages/` sibling at the install root.\n                              Default (no flag): pull pre-built images from ghcr.io by digest."
+  ).action(async (opts) => {
+    const parsed = parseUpgradeOpts(opts);
+    if (parsed.fromSource) {
+      if (!isDevMode()) {
+        printError(new MissingBuildScriptError("packages/adapters/src/docker/build-*.sh").message);
+        process.exitCode = 1;
+        return;
+      }
+      await handleUpgrade(parsed);
+      return;
+    }
+    if (parsed.history) {
+      handleHistory(parseHistoryOpts({ n: parsed.historyN, json: parsed.historyJson }));
+      return;
+    }
+    try {
+      const result = await runUpgradePullByDigest();
+      process.exitCode = result.exitCode;
+    } catch (err) {
+      printError(err instanceof Error ? err.message : String(err));
+      process.exitCode = EXIT_GENERIC_ERROR;
+    }
   });
 }
 
 // src/commands/logs.ts
 import * as http3 from "node:http";
-import pc16 from "picocolors";
+import pc17 from "picocolors";
 init_context();
 var HOST_CP_PORT2 = 19e3;
 function colorLine(line) {
-  if (/\bERROR\b/.test(line)) return pc16.red(line);
-  if (/\bWARN\b/.test(line)) return pc16.yellow(line);
-  if (/\bINFO\b/.test(line)) return pc16.dim(line);
+  if (/\bERROR\b/.test(line)) return pc17.red(line);
+  if (/\bWARN\b/.test(line)) return pc17.yellow(line);
+  if (/\bINFO\b/.test(line)) return pc17.dim(line);
   return line;
 }
 function formatLine(line, service, showService) {
-  const prefix = showService && service ? `${pc16.cyan(`[${service}]`)} ` : "";
+  const prefix = showService && service ? `${pc17.cyan(`[${service}]`)} ` : "";
   return prefix + colorLine(line);
 }
 function parseSseEvent(raw) {
@@ -18152,8 +18908,8 @@ function registerLogs(program2) {
 
 // src/commands/ps.ts
 init_context();
-import pc17 from "picocolors";
-import { spawnSync as spawnSync8 } from "node:child_process";
+import pc18 from "picocolors";
+import { spawnSync as spawnSync10 } from "node:child_process";
 var SAFE_IDENT4 = /^[a-z0-9][a-z0-9-]{0,63}$/;
 function parseDockerTop(stdout) {
   const trimmed = stdout.trim();
@@ -18213,18 +18969,18 @@ function printTable(rows) {
   const fixedWidth = 5 + 1 + 8 + 1 + 6 + 1 + 6 + 1 + 10 + 1 + 6 + 1;
   const cmdWidth = Math.max(20, cols - fixedWidth);
   const header = [
-    pc17.bold(pc17.dim("PID".padEnd(5))),
-    pc17.bold(pc17.dim("USER".padEnd(8))),
-    pc17.bold(pc17.dim("%CPU".padEnd(6))),
-    pc17.bold(pc17.dim("%MEM".padEnd(6))),
-    pc17.bold(pc17.dim("STARTED".padEnd(10))),
-    pc17.bold(pc17.dim("STATE".padEnd(6))),
-    pc17.bold(pc17.dim("COMMAND"))
+    pc18.bold(pc18.dim("PID".padEnd(5))),
+    pc18.bold(pc18.dim("USER".padEnd(8))),
+    pc18.bold(pc18.dim("%CPU".padEnd(6))),
+    pc18.bold(pc18.dim("%MEM".padEnd(6))),
+    pc18.bold(pc18.dim("STARTED".padEnd(10))),
+    pc18.bold(pc18.dim("STATE".padEnd(6))),
+    pc18.bold(pc18.dim("COMMAND"))
   ].join(" ");
   console.log(header);
   for (const row of rows) {
     const cmd = row.command.length > cmdWidth ? row.command.slice(0, cmdWidth - 1) + "\u2026" : row.command;
-    const stateFn = row.state.startsWith("R") ? pc17.green : row.state.startsWith("Z") ? pc17.red : pc17.dim;
+    const stateFn = row.state.startsWith("R") ? pc18.green : row.state.startsWith("Z") ? pc18.red : pc18.dim;
     console.log([
       row.pid.padEnd(5),
       row.user.slice(0, 8).padEnd(8),
@@ -18253,7 +19009,7 @@ function registerPs(program2) {
     const containerName = `olam-${worldId}-devbox`;
     let watchInterval;
     function fetchAndPrint() {
-      const result = spawnSync8(
+      const result = spawnSync10(
         "docker",
         ["top", containerName, "pid", "user", "pcpu", "pmem", "stime", "stat", "cmd"],
         { encoding: "utf-8", timeout: 3e3 }
@@ -18273,7 +19029,7 @@ function registerPs(program2) {
       printTable(rows);
       if (opts.watch) {
         process.stdout.write(`
-${pc17.dim(`world: ${worldId}  sort: ${sortKey}  refresh: 5s  Ctrl-C to exit`)}
+${pc18.dim(`world: ${worldId}  sort: ${sortKey}  refresh: 5s  Ctrl-C to exit`)}
 `);
       }
     }
@@ -18393,7 +19149,7 @@ function registerKeys(program2) {
 import * as fs27 from "node:fs";
 import * as path31 from "node:path";
 import { execSync as execSync9 } from "node:child_process";
-import pc18 from "picocolors";
+import pc19 from "picocolors";
 
 // ../core/src/world/snapshot.ts
 import * as crypto6 from "node:crypto";
@@ -18562,7 +19318,7 @@ async function handleCreate2(worldId, kindArg) {
     const label = r.repo ? `${r.kind}/${r.repo}` : r.kind;
     if (r.ok) {
       printSuccess(`${label}`);
-      console.log(`         ${pc18.dim(r.tarPath)}`);
+      console.log(`         ${pc19.dim(r.tarPath)}`);
     } else {
       printWarning(`${label}: ${r.msg ?? "skipped"}`);
     }
@@ -18712,7 +19468,7 @@ function handleList2(worldIdFilter) {
   const entries = listSnapshots(worldIdFilter);
   if (entries.length === 0) {
     const where = worldIdFilter ? ` for world "${worldIdFilter}"` : "";
-    console.log(pc18.dim(`No snapshots found${where}. Run \`olam world snapshot create <worldId>\` first.`));
+    console.log(pc19.dim(`No snapshots found${where}. Run \`olam world snapshot create <worldId>\` first.`));
     return;
   }
   printHeader(`${entries.length} snapshot(s)`);
@@ -18721,15 +19477,15 @@ function handleList2(worldIdFilter) {
   for (const entry of entries) {
     const { manifest } = entry;
     if (manifest.worldId !== lastWorldId) {
-      console.log(pc18.bold(manifest.worldId));
+      console.log(pc19.bold(manifest.worldId));
       lastWorldId = manifest.worldId;
     }
     const repo = manifest.repo ?? "(all repos)";
     const size = formatBytes(manifest.sizeBytes);
     const age = formatAge2(entry.ageMs);
-    const kindColor = manifest.kind === "gems" ? pc18.magenta(manifest.kind) : manifest.kind === "node" ? pc18.cyan(manifest.kind) : pc18.yellow(manifest.kind);
+    const kindColor = manifest.kind === "gems" ? pc19.magenta(manifest.kind) : manifest.kind === "node" ? pc19.cyan(manifest.kind) : pc19.yellow(manifest.kind);
     console.log(
-      `  ${kindColor.padEnd(6)}  ${pc18.dim(repo.padEnd(24))}  ${manifest.fingerprint}  ${size.padStart(8)}  ${age}`
+      `  ${kindColor.padEnd(6)}  ${pc19.dim(repo.padEnd(24))}  ${manifest.fingerprint}  ${size.padStart(8)}  ${age}`
     );
   }
   console.log();
@@ -18766,8 +19522,8 @@ init_context();
 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";
+import { spawnSync as spawnSync11 } from "node:child_process";
+import ora8 from "ora";
 
 // src/commands/refresh-helpers.ts
 import * as fs28 from "node:fs";
@@ -18810,7 +19566,7 @@ var RESTART_TIMEOUT_S = 30;
 var HEALTH_POLL_MS = 500;
 var HEALTH_TIMEOUT_MS = 3e4;
 function docker(args) {
-  const result = spawnSync9("docker", args, {
+  const result = spawnSync11("docker", args, {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -18950,7 +19706,7 @@ Run \`olam refresh\` from the olam repo root.`
     process.stdout.write("\n");
     const results = [];
     for (const world of worldsToRefresh) {
-      const spinner = ora5(`${world.name}: copying CP source...`).start();
+      const spinner = ora8(`${world.name}: copying CP source...`).start();
       try {
         const result = await refreshWorld(
           world.id,
@@ -19013,7 +19769,24 @@ function isPleriConfigured(configDir = process.env.OLAM_CONFIG_DIR ?? ".olam") {
 
 // src/index.ts
 var program = new Command();
-program.name("olam").description("Olam \u2014 isolated development worlds with thought graph capture").version("0.1.0");
+function readCliVersion() {
+  try {
+    const here = path35.dirname(fileURLToPath4(import.meta.url));
+    for (const candidate of [
+      path35.join(here, "package.json"),
+      path35.join(here, "..", "package.json"),
+      path35.join(here, "..", "..", "package.json")
+    ]) {
+      if (fs31.existsSync(candidate)) {
+        const pkg = JSON.parse(fs31.readFileSync(candidate, "utf-8"));
+        if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+      }
+    }
+  } catch {
+  }
+  return "0.0.0-unknown";
+}
+program.name("olam").description("Olam \u2014 isolated development worlds with thought graph capture").version(readCliVersion());
 registerInit(program);
 registerInstall(program);
 registerAuth(program);
@@ -19036,4 +19809,5 @@ registerPs(program);
 registerKeys(program);
 registerWorldSnapshot(program);
 registerRefresh(program);
+registerBootstrap(program);
 program.parse();