@pleri/olam-cli 0.1.70 → 0.1.73

package/dist/mcp-server.js

@@ -412,11 +412,11 @@ var require_codegen = __commonJS({
         const rhs = this.rhs === void 0 ? "" : ` = ${this.rhs}`;
         return `${varKind} ${this.name}${rhs};` + _n;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         if (!names[this.name.str])
           return;
         if (this.rhs)
-          this.rhs = optimizeExpr(this.rhs, names, constants);
+          this.rhs = optimizeExpr(this.rhs, names, constants2);
         return this;
       }
       get names() {
@@ -433,10 +433,10 @@ var require_codegen = __commonJS({
       render({ _n }) {
         return `${this.lhs} = ${this.rhs};` + _n;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
           return;
-        this.rhs = optimizeExpr(this.rhs, names, constants);
+        this.rhs = optimizeExpr(this.rhs, names, constants2);
         return this;
       }
       get names() {
@@ -497,8 +497,8 @@ var require_codegen = __commonJS({
       optimizeNodes() {
         return `${this.code}` ? this : void 0;
       }
-      optimizeNames(names, constants) {
-        this.code = optimizeExpr(this.code, names, constants);
+      optimizeNames(names, constants2) {
+        this.code = optimizeExpr(this.code, names, constants2);
         return this;
       }
       get names() {
@@ -527,12 +527,12 @@ var require_codegen = __commonJS({
         }
         return nodes.length > 0 ? this : void 0;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         const { nodes } = this;
         let i = nodes.length;
         while (i--) {
           const n = nodes[i];
-          if (n.optimizeNames(names, constants))
+          if (n.optimizeNames(names, constants2))
             continue;
           subtractNames(names, n.names);
           nodes.splice(i, 1);
@@ -585,12 +585,12 @@ var require_codegen = __commonJS({
           return void 0;
         return this;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         var _a;
-        this.else = (_a = this.else) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants);
-        if (!(super.optimizeNames(names, constants) || this.else))
+        this.else = (_a = this.else) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants2);
+        if (!(super.optimizeNames(names, constants2) || this.else))
           return;
-        this.condition = optimizeExpr(this.condition, names, constants);
+        this.condition = optimizeExpr(this.condition, names, constants2);
         return this;
       }
       get names() {
@@ -613,10 +613,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.iteration})` + super.render(opts);
       }
-      optimizeNames(names, constants) {
-        if (!super.optimizeNames(names, constants))
+      optimizeNames(names, constants2) {
+        if (!super.optimizeNames(names, constants2))
           return;
-        this.iteration = optimizeExpr(this.iteration, names, constants);
+        this.iteration = optimizeExpr(this.iteration, names, constants2);
         return this;
       }
       get names() {
@@ -652,10 +652,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
       }
-      optimizeNames(names, constants) {
-        if (!super.optimizeNames(names, constants))
+      optimizeNames(names, constants2) {
+        if (!super.optimizeNames(names, constants2))
           return;
-        this.iterable = optimizeExpr(this.iterable, names, constants);
+        this.iterable = optimizeExpr(this.iterable, names, constants2);
         return this;
       }
       get names() {
@@ -697,11 +697,11 @@ var require_codegen = __commonJS({
         (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNodes();
         return this;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants2) {
         var _a, _b;
-        super.optimizeNames(names, constants);
-        (_a = this.catch) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants);
-        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants);
+        super.optimizeNames(names, constants2);
+        (_a = this.catch) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants2);
+        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants2);
         return this;
       }
       get names() {
@@ -1002,7 +1002,7 @@ var require_codegen = __commonJS({
     function addExprNames(names, from) {
       return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
     }
-    function optimizeExpr(expr, names, constants) {
+    function optimizeExpr(expr, names, constants2) {
       if (expr instanceof code_1.Name)
         return replaceName(expr);
       if (!canOptimize(expr))
@@ -1017,14 +1017,14 @@ var require_codegen = __commonJS({
         return items;
       }, []));
       function replaceName(n) {
-        const c = constants[n.str];
+        const c = constants2[n.str];
         if (c === void 0 || names[n.str] !== 1)
           return n;
         delete names[n.str];
         return c;
       }
       function canOptimize(e) {
-        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants[c.str] !== void 0);
+        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants2[c.str] !== void 0);
       }
     }
     function subtractNames(names, from) {
@@ -2986,7 +2986,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve6.call(this, root, ref);
+      let _sch = resolve8.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3013,7 +3013,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve6(root, ref) {
+    function resolve8(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3228,8 +3228,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path24) {
-      let input = path24;
+    function removeDotSegments(path27) {
+      let input = path27;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3428,8 +3428,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path24, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path24 && path24 !== "/" ? path24 : void 0;
+        const [path27, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path27 && path27 !== "/" ? path27 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -3588,55 +3588,55 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve6(baseURI, relativeURI, options) {
+    function resolve8(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative2, options, skipNormalization) {
+    function resolveComponent(base, relative3, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative2 = parse3(serialize(relative2, options), options);
+        relative3 = parse3(serialize(relative3, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative2.scheme) {
-        target.scheme = relative2.scheme;
-        target.userinfo = relative2.userinfo;
-        target.host = relative2.host;
-        target.port = relative2.port;
-        target.path = removeDotSegments(relative2.path || "");
-        target.query = relative2.query;
+      if (!options.tolerant && relative3.scheme) {
+        target.scheme = relative3.scheme;
+        target.userinfo = relative3.userinfo;
+        target.host = relative3.host;
+        target.port = relative3.port;
+        target.path = removeDotSegments(relative3.path || "");
+        target.query = relative3.query;
       } else {
-        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
-          target.userinfo = relative2.userinfo;
-          target.host = relative2.host;
-          target.port = relative2.port;
-          target.path = removeDotSegments(relative2.path || "");
-          target.query = relative2.query;
+        if (relative3.userinfo !== void 0 || relative3.host !== void 0 || relative3.port !== void 0) {
+          target.userinfo = relative3.userinfo;
+          target.host = relative3.host;
+          target.port = relative3.port;
+          target.path = removeDotSegments(relative3.path || "");
+          target.query = relative3.query;
         } else {
-          if (!relative2.path) {
+          if (!relative3.path) {
             target.path = base.path;
-            if (relative2.query !== void 0) {
-              target.query = relative2.query;
+            if (relative3.query !== void 0) {
+              target.query = relative3.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative2.path[0] === "/") {
-              target.path = removeDotSegments(relative2.path);
+            if (relative3.path[0] === "/") {
+              target.path = removeDotSegments(relative3.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative2.path;
+                target.path = "/" + relative3.path;
               } else if (!base.path) {
-                target.path = relative2.path;
+                target.path = relative3.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative3.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative2.query;
+            target.query = relative3.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3644,7 +3644,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative2.fragment;
+      target.fragment = relative3.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -3815,7 +3815,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve6,
+      resolve: resolve8,
       resolveComponent,
       equal,
       serialize,
@@ -6791,12 +6791,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs20, exportName) {
+    function addFormats(ajv, list, fs23, exportName) {
       var _a;
       var _b;
       (_a = (_b = ajv.opts.code).formats) !== null && _a !== void 0 ? _a : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs20[f]);
+        ajv.addFormat(f, fs23[f]);
     }
     module.exports = exports = formatsPlugin;
     Object.defineProperty(exports, "__esModule", { value: true });
@@ -7002,10 +7002,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path24) {
-  if (!path24)
+function getElementAtPath(obj, path27) {
+  if (!path27)
     return obj;
-  return path24.reduce((acc, key) => acc?.[key], obj);
+  return path27.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -7325,11 +7325,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path24, issues) {
+function prefixIssues(path27, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path24);
+    iss.path.unshift(path27);
     return iss;
   });
 }
@@ -12914,12 +12914,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve6) => {
+    return new Promise((resolve8) => {
       const json = serializeMessage(message);
       if (this._stdout.write(json)) {
-        resolve6();
+        resolve8();
       } else {
-        this._stdout.once("drain", resolve6);
+        this._stdout.once("drain", resolve8);
       }
     });
   }
@@ -13403,8 +13403,8 @@ function getErrorMap() {
 
 // ../../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path24, errorMaps, issueData } = params;
-  const fullPath = [...path24, ...issueData.path || []];
+  const { data, path: path27, errorMaps, issueData } = params;
+  const fullPath = [...path27, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -13520,11 +13520,11 @@ var errorUtil;
 
 // ../../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path24, key) {
+  constructor(parent, value, path27, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path24;
+    this._path = path27;
     this._key = key;
   }
   get path() {
@@ -18987,7 +18987,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve6) => setTimeout(resolve6, pollInterval));
+        await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -19004,7 +19004,7 @@ var Protocol = class {
    */
   request(request2, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve6, reject2) => {
+    return new Promise((resolve8, reject2) => {
       const earlyReject = (error2) => {
         reject2(error2);
       };
@@ -19082,7 +19082,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject2(parseResult.error);
           } else {
-            resolve6(parseResult.data);
+            resolve8(parseResult.data);
           }
         } catch (error2) {
           reject2(error2);
@@ -19343,12 +19343,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve6, reject2) => {
+    return new Promise((resolve8, reject2) => {
       if (signal.aborted) {
         reject2(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve6, interval);
+      const timeoutId = setTimeout(resolve8, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject2(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -20448,7 +20448,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve6) => setTimeout(resolve6, pollInterval));
+      await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -21365,8 +21365,8 @@ var AuthClient = class {
       throw new Error(`failed to report rate-limit for ${accountId} (HTTP ${res.status})`);
     }
   }
-  async request(method, path24, body, attempt = 0) {
-    const url = `${this.baseUrl}${path24}`;
+  async request(method, path27, body, attempt = 0) {
+    const url = `${this.baseUrl}${path27}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     const headers = {};
@@ -21384,7 +21384,7 @@ var AuthClient = class {
     } catch (err) {
       if (attempt < RETRY_COUNT && isTransient(err)) {
         await sleep(RETRY_BACKOFF_MS * (attempt + 1));
-        return this.request(method, path24, body, attempt + 1);
+        return this.request(method, path27, body, attempt + 1);
       }
       throw err;
     } finally {
@@ -21411,7 +21411,7 @@ async function safeText(res) {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve6) => setTimeout(resolve6, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
 // ../core/dist/auth/container.js
@@ -21543,7 +21543,7 @@ function resolveAuthServicePath() {
   return path3.join(pkgsDir, "auth-service");
 }
 function sleep2(ms) {
-  return new Promise((resolve6) => setTimeout(resolve6, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
 // ../core/dist/auth/preflight.js
@@ -22191,12 +22191,12 @@ function register3(server, _ctx, _initError) {
         registry2.close();
       }
       try {
-        const { default: fs20 } = await import("node:fs");
-        const { default: os13 } = await import("node:os");
-        const { default: path24 } = await import("node:path");
-        const tokenPath = path24.join(os13.homedir(), ".olam", "host-cp.token");
-        if (fs20.existsSync(tokenPath)) {
-          const token = fs20.readFileSync(tokenPath, "utf-8").trim();
+        const { default: fs23 } = await import("node:fs");
+        const { default: os15 } = await import("node:os");
+        const { default: path27 } = await import("node:path");
+        const tokenPath = path27.join(os15.homedir(), ".olam", "host-cp.token");
+        if (fs23.existsSync(tokenPath)) {
+          const token = fs23.readFileSync(tokenPath, "utf-8").trim();
           await fetch("http://127.0.0.1:19000/api/admin/world-pr", {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
@@ -22338,11 +22338,13 @@ var serviceSchema = external_exports.object({
 var deploySchema = external_exports.object({
   tags: external_exports.array(external_exports.string()).optional()
 }).passthrough();
+var BootstrapKindSchema = external_exports.enum(["gems", "node", "pg"]);
 var BootstrapStepSchema = external_exports.union([
   external_exports.string(),
   external_exports.object({
     cmd: external_exports.string().min(1),
-    idempotent_check: external_exports.string().min(1).optional()
+    idempotent_check: external_exports.string().min(1).optional(),
+    produces: BootstrapKindSchema.nullable().optional()
   }).passthrough()
 ]);
 function bootstrapStepCmd(entry) {
@@ -22389,7 +22391,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "deploy"
 ]);
 var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-function refineForbiddenKeys(value, path24, ctx, rejectSource) {
+function refineForbiddenKeys(value, path27, ctx, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
@@ -22397,12 +22399,12 @@ function refineForbiddenKeys(value, path24, ctx, rejectSource) {
     if (FORBIDDEN_KEYS.has(key)) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
-        path: [...path24, key],
+        path: [...path27, key],
         message: `forbidden key "${key}" (prototype-pollution surface)`
       });
       continue;
     }
-    if (rejectSource && path24.length === 0 && key === "source") {
+    if (rejectSource && path27.length === 0 && key === "source") {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: ["source"],
@@ -22410,21 +22412,21 @@ function refineForbiddenKeys(value, path24, ctx, rejectSource) {
       });
       continue;
     }
-    refineForbiddenKeys(value[key], [...path24, key], ctx, false);
+    refineForbiddenKeys(value[key], [...path27, key], ctx, false);
   }
 }
-function rejectForbiddenKeys(value, path24, rejectSource) {
+function rejectForbiddenKeys(value, path27, 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] ${path24}: forbidden key "${key}" (prototype-pollution surface)`);
+      throw new Error(`[manifest] ${path27}: forbidden key "${key}" (prototype-pollution surface)`);
     }
     if (rejectSource && key === "source") {
-      throw new Error(`[manifest] ${path24}: top-level "source" is loader-stamped \u2014 manifests must not author it`);
+      throw new Error(`[manifest] ${path27}: top-level "source" is loader-stamped \u2014 manifests must not author it`);
     }
-    rejectForbiddenKeys(value[key], `${path24}.${key}`, false);
+    rejectForbiddenKeys(value[key], `${path27}.${key}`, false);
   }
 }
 function unknownTopLevelKeys(parsed) {
@@ -22433,40 +22435,40 @@ function unknownTopLevelKeys(parsed) {
 function loadRepoManifest(repoDir) {
   const olamPath = join5(repoDir, ".olam.yaml");
   const adbPath = join5(repoDir, ".adb.yaml");
-  let manifestPath;
+  let manifestPath2;
   let source;
   if (existsSync4(olamPath)) {
-    manifestPath = olamPath;
+    manifestPath2 = olamPath;
     source = "olam";
   } else if (existsSync4(adbPath)) {
-    manifestPath = adbPath;
+    manifestPath2 = adbPath;
     source = "adb";
   } else {
     return null;
   }
-  const stat = lstatSync(manifestPath);
+  const stat = lstatSync(manifestPath2);
   if (stat.isSymbolicLink()) {
-    throw new Error(`[manifest] ${manifestPath}: symbolic links are not permitted`);
+    throw new Error(`[manifest] ${manifestPath2}: symbolic links are not permitted`);
   }
-  const raw = readFileSync3(manifestPath, "utf-8");
+  const raw = readFileSync3(manifestPath2, "utf-8");
   const parsed = YAML.parse(raw, { maxAliasCount: 100 });
   if (parsed === null || parsed === void 0) {
     if (source === "olam" && existsSync4(adbPath)) {
-      console.warn(`[manifest] ${manifestPath}: file is empty; .adb.yaml is NOT consulted (delete .olam.yaml to fall back)`);
+      console.warn(`[manifest] ${manifestPath2}: file is empty; .adb.yaml is NOT consulted (delete .olam.yaml to fall back)`);
     }
     return null;
   }
   if (typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`[manifest] ${manifestPath}: expected a YAML mapping at the top level`);
+    throw new Error(`[manifest] ${manifestPath2}: expected a YAML mapping at the top level`);
   }
-  rejectForbiddenKeys(parsed, manifestPath, true);
+  rejectForbiddenKeys(parsed, manifestPath2, true);
   const body = RepoManifestSchema.parse(parsed);
   if (parsed["version"] === void 0) {
-    console.warn(`[manifest] ${manifestPath}: missing "version: ${MANIFEST_VERSION}" field \u2014 add it to suppress this warning (backward-compat: file still parses)`);
+    console.warn(`[manifest] ${manifestPath2}: missing "version: ${MANIFEST_VERSION}" field \u2014 add it to suppress this warning (backward-compat: file still parses)`);
   }
   const unknown2 = unknownTopLevelKeys(parsed);
   if (unknown2.length > 0) {
-    console.warn(`[manifest] ${manifestPath}: unknown top-level fields preserved (passthrough): ${unknown2.join(", ")}`);
+    console.warn(`[manifest] ${manifestPath2}: unknown top-level fields preserved (passthrough): ${unknown2.join(", ")}`);
   }
   return { ...body, source };
 }
@@ -22862,10 +22864,10 @@ function extractMcpConfig(claudeJsonPath) {
   }
   return { mcpServers, secrets };
 }
-function readOptional(path24) {
-  if (!existsSync6(path24)) return null;
+function readOptional(path27) {
+  if (!existsSync6(path27)) return null;
   try {
-    return readFileSync5(path24, "utf8");
+    return readFileSync5(path27, "utf8");
   } catch {
     return null;
   }
@@ -23163,6 +23165,7 @@ var createWorldContainer = async (docker, worldId, worldName, image, env, resour
   }
   const hostControlPlanePort = HOST_CONTROL_PLANE_BASE2 + (portOffset ?? 0);
   const hostTtydPort = 17681 + (portOffset ?? 0);
+  const hostTtydShellPort = 17682 + (portOffset ?? 0);
   const appPortBindings = {};
   const appExposedPorts = {};
   const appHostPorts = [];
@@ -23177,6 +23180,7 @@ var createWorldContainer = async (docker, worldId, worldName, image, env, resour
   await auditPortsForZombies(docker, [
     hostControlPlanePort,
     hostTtydPort,
+    hostTtydShellPort,
     ...appHostPorts
   ]);
   const container = await docker.createContainer({
@@ -23190,6 +23194,7 @@ var createWorldContainer = async (docker, worldId, worldName, image, env, resour
     ExposedPorts: {
       [`${CONTROL_PLANE_PORT}/tcp`]: {},
       "7681/tcp": {},
+      "7682/tcp": {},
       ...appExposedPorts
     },
     HostConfig: {
@@ -23202,6 +23207,7 @@ var createWorldContainer = async (docker, worldId, worldName, image, env, resour
       PortBindings: {
         [`${CONTROL_PLANE_PORT}/tcp`]: [{ HostPort: String(hostControlPlanePort), HostIp: "127.0.0.1" }],
         "7681/tcp": [{ HostPort: String(hostTtydPort), HostIp: "127.0.0.1" }],
+        "7682/tcp": [{ HostPort: String(hostTtydShellPort), HostIp: "127.0.0.1" }],
         ...appPortBindings
       },
       NanoCpus: resources?.cpuCores ? resources.cpuCores * 1e9 : void 0,
@@ -23235,7 +23241,7 @@ var stopAndRemove = async (container) => {
 
 // ../adapters/dist/docker/exec.js
 import { PassThrough } from "node:stream";
-var demuxStream = (stream) => new Promise((resolve6, reject2) => {
+var demuxStream = (stream) => new Promise((resolve8, reject2) => {
   const stdoutChunks = [];
   const stderrChunks = [];
   const stdout = new PassThrough();
@@ -23249,7 +23255,7 @@ var demuxStream = (stream) => new Promise((resolve6, reject2) => {
     stream.pipe(stdout);
   }
   stream.on("end", () => {
-    resolve6({
+    resolve8({
       stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
       stderr: Buffer.concat(stderrChunks).toString("utf-8")
     });
@@ -23542,7 +23548,7 @@ var SSHConnectionPool = class {
   // -----------------------------------------------------------------------
   async exec(host, command) {
     const client = await this.getConnection(host);
-    return new Promise((resolve6, reject2) => {
+    return new Promise((resolve8, reject2) => {
       client.exec(command, (err, stream) => {
         if (err) {
           reject2(new Error(`SSH exec failed on ${host}: ${err.message}`));
@@ -23557,7 +23563,7 @@ var SSHConnectionPool = class {
           stderr += data.toString();
         });
         stream.on("close", (code) => {
-          resolve6({
+          resolve8({
             exitCode: code ?? 0,
             stdout: stdout.trimEnd(),
             stderr: stderr.trimEnd()
@@ -23588,10 +23594,10 @@ var SSHConnectionPool = class {
       throw new Error(`No SSH configuration found for host: ${host}`);
     }
     const client = new SSHClient();
-    return new Promise((resolve6, reject2) => {
+    return new Promise((resolve8, reject2) => {
       client.on("ready", () => {
         this.connections.set(host, client);
-        resolve6(client);
+        resolve8(client);
       }).on("error", (err) => {
         this.connections.delete(host);
         reject2(new Error(`SSH connection to ${host} failed: ${err.message}`));
@@ -24008,8 +24014,8 @@ var CloudflareProvider = class extends ComputeProvider {
   // -----------------------------------------------------------------------
   // Internal fetch helper
   // -----------------------------------------------------------------------
-  async request(path24, method, body) {
-    const url = `${this.config.workerUrl}${path24}`;
+  async request(path27, method, body) {
+    const url = `${this.config.workerUrl}${path27}`;
     const bearer = await this.config.mintToken();
     const headers = {
       Authorization: `Bearer ${bearer}`
@@ -24446,7 +24452,8 @@ function register6(server, ctx, initError) {
       // strip step so any operator-side uncommitted edits survive into
       // the world's worktree. The baseline-diff snapshot still runs
       // unconditionally (Phase C reaper still needs it).
-      carryUncommitted: external_exports.boolean().optional().describe("Preserve operator's uncommitted edits in the world's worktree (B3); default false")
+      carryUncommitted: external_exports.boolean().optional().describe("Preserve operator's uncommitted edits in the world's worktree (B3); default false"),
+      runbookName: external_exports.string().optional().describe("Named runbook profile from ~/.olam/config.json \u2014 seeds ports, env overrides, and fixture-copy steps")
     },
     async (params) => {
       if (!ctx) {
@@ -24510,7 +24517,8 @@ function register6(server, ctx, initError) {
           branchName: params.branchName,
           planFile: params.planFile,
           taskContext: params.taskContext,
-          carryUncommitted: params.carryUncommitted ?? false
+          carryUncommitted: params.carryUncommitted ?? false,
+          ...params.runbookName ? { runbookName: params.runbookName } : {}
         });
         const lines = [
           `World created successfully.`,
@@ -24569,7 +24577,7 @@ function register6(server, ctx, initError) {
                 }
               } catch {
               }
-              await new Promise((resolve6) => setTimeout(resolve6, POLL_INTERVAL_MS));
+              await new Promise((resolve8) => setTimeout(resolve8, POLL_INTERVAL_MS));
             }
           }
           if (authenticated) {
@@ -25301,8 +25309,8 @@ function copyDirRecursive(src, dest, depth = 0, skipFiles = /* @__PURE__ */ new
   }
 }
 async function copyClaudeConfigIntoContainer(containerName) {
-  const { execSync: execSync6 } = await import("node:child_process");
-  const dockerExec = (cmd) => execSync6(`docker exec ${containerName} sh -c '${cmd}'`, { stdio: "pipe" });
+  const { execSync: execSync7 } = await import("node:child_process");
+  const dockerExec = (cmd) => execSync7(`docker exec ${containerName} sh -c '${cmd}'`, { stdio: "pipe" });
   dockerExec("mkdir -p /home/olam/.claude");
   dockerExec("test -f /home/olam/workspace/.claude-host-config/settings.json && cp /home/olam/workspace/.claude-host-config/settings.json /home/olam/.claude/settings.json || true");
   dockerExec("test -f /home/olam/workspace/.claude-host-config/CLAUDE.md && cp /home/olam/workspace/.claude-host-config/CLAUDE.md /home/olam/.claude/CLAUDE.md || true");
@@ -25318,7 +25326,7 @@ async function copyClaudeConfigIntoContainer(containerName) {
   await sanitizeContainerClaudeHooks(containerName);
 }
 async function sanitizeContainerClaudeHooks(containerName) {
-  const { execSync: execSync6 } = await import("node:child_process");
+  const { execSync: execSync7 } = await import("node:child_process");
   const script = `
 const fs = require('fs');
 const p = '/home/olam/.claude/settings.json';
@@ -25362,7 +25370,7 @@ if (changed) {
 }
 `;
   try {
-    execSync6(`docker exec ${containerName} /usr/local/bin/node -e ${shQuote(script)}`, { stdio: "pipe" });
+    execSync7(`docker exec ${containerName} /usr/local/bin/node -e ${shQuote(script)}`, { stdio: "pipe" });
   } catch {
   }
 }
@@ -25499,8 +25507,8 @@ function copyMatchingFiles(sourcePath, destPath, pattern) {
   try {
     const matches2 = globSync(fullPattern);
     for (const match of matches2) {
-      const relative2 = path9.relative(sourcePath, match);
-      const dest = path9.join(destPath, relative2);
+      const relative3 = path9.relative(sourcePath, match);
+      const dest = path9.join(destPath, relative3);
       fs6.mkdirSync(path9.dirname(dest), { recursive: true });
       fs6.copyFileSync(match, dest);
     }
@@ -26442,10 +26450,10 @@ async function writeManifest(args) {
     capturedAt: args.capturedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
     shots: entries
   };
-  const path24 = join12(args.outDir, "manifest.json");
-  await writeFile(path24, `${JSON.stringify(manifest, null, 2)}
+  const path27 = join12(args.outDir, "manifest.json");
+  await writeFile(path27, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  return { path: path24, manifest };
+  return { path: path27, manifest };
 }
 
 // ../mcp-server/src/tools/_capture/proxy.ts
@@ -26699,9 +26707,9 @@ async function startProxy(opts) {
       const liveCompiled = verified.allowedPaths.map(compileGlob);
       const target = parseRequestTarget(req);
       if (!target) return httpReject(400, "invalid_target");
-      const path24 = target.pathname;
-      if (!liveCompiled.some((re) => re.test(path24))) {
-        return httpReject(403, "outside_allow_list", { path: path24 });
+      const path27 = target.pathname;
+      if (!liveCompiled.some((re) => re.test(path27))) {
+        return httpReject(403, "outside_allow_list", { path: path27 });
       }
       const headerWorld = req.headers[WORLD_ASSERT_HEADER];
       const headerWorldStr = typeof headerWorld === "string" ? headerWorld : Array.isArray(headerWorld) && headerWorld.length > 0 ? headerWorld[0] : void 0;
@@ -26805,15 +26813,15 @@ ${JSON.stringify({ error: reason })}`
       unlinkSync2(udsPath);
     } catch {
     }
-    await new Promise((resolve6, reject2) => {
-      server.listen(udsPath, () => resolve6());
+    await new Promise((resolve8, reject2) => {
+      server.listen(udsPath, () => resolve8());
       server.once("error", reject2);
     });
     chmodSync3(udsPath, 384);
     port = 0;
   } else {
-    await new Promise((resolve6, reject2) => {
-      server.listen(opts.port ?? 0, "127.0.0.1", () => resolve6());
+    await new Promise((resolve8, reject2) => {
+      server.listen(opts.port ?? 0, "127.0.0.1", () => resolve8());
       server.once("error", reject2);
     });
     const addr = server.address();
@@ -26829,10 +26837,10 @@ ${JSON.stringify({ error: reason })}`
     } catch {
     }
     await Promise.race([
-      new Promise((resolve6, reject2) => {
-        server.close((err) => err ? reject2(err) : resolve6());
+      new Promise((resolve8, reject2) => {
+        server.close((err) => err ? reject2(err) : resolve8());
       }),
-      new Promise((resolve6) => setTimeout(resolve6, 5e3))
+      new Promise((resolve8) => setTimeout(resolve8, 5e3))
     ]);
     if (udsPath) {
       try {
@@ -27164,10 +27172,10 @@ async function acquireLaunchSlot() {
     _inFlightLaunches++;
     return releaseLaunchSlot;
   }
-  return new Promise((resolve6) => {
+  return new Promise((resolve8) => {
     _launchQueue.push(() => {
       _inFlightLaunches++;
-      resolve6(releaseLaunchSlot);
+      resolve8(releaseLaunchSlot);
     });
   });
 }
@@ -27480,14 +27488,14 @@ async function runShot(browser, shot, outDir, format, jpegQuality, allowEval, as
       await page.waitForTimeout(shot.afterLoadMs);
     }
     const ext = format === "jpeg" ? "jpg" : "png";
-    const path24 = join13(outDir, `${shot.name}.${ext}`);
+    const path27 = join13(outDir, `${shot.name}.${ext}`);
     await page.screenshot({
-      path: path24,
+      path: path27,
       type: format,
       ...format === "jpeg" ? { quality: jpegQuality } : {},
       fullPage: false
     });
-    return { name: shot.name, path: path24, urlRedacted: redactUrl(shot.url), viewport };
+    return { name: shot.name, path: path27, urlRedacted: redactUrl(shot.url), viewport };
   } finally {
     await context.close();
   }
@@ -27708,7 +27716,7 @@ function register20(server, ctx, initError) {
             shot.url === navigableShot.url ? result : { ...result, urlRedacted: redactUrl(shot.url) }
           );
         }
-        const { path: manifestPath } = await writeManifest({
+        const { path: manifestPath2 } = await writeManifest({
           outDir: absOutDir,
           correlationId,
           shots: results
@@ -27720,7 +27728,7 @@ function register20(server, ctx, initError) {
               type: "text",
               text: `Captured ${results.length} shot(s) to ${absOutDir} (correlationId=${correlationId}):
 ${lines.join("\n")}
-  manifest \u2192 ${manifestPath}`
+  manifest \u2192 ${manifestPath2}`
             }
           ]
         };
@@ -27930,12 +27938,12 @@ function openUrl(url) {
 var HOST_CP_URL = "http://127.0.0.1:19000";
 async function readHostCpToken2() {
   try {
-    const { default: fs20 } = await import("node:fs");
-    const { default: os13 } = await import("node:os");
-    const { default: path24 } = await import("node:path");
-    const tp = path24.join(os13.homedir(), ".olam", "host-cp.token");
-    if (!fs20.existsSync(tp)) return { token: null };
-    return { token: fs20.readFileSync(tp, "utf-8").trim() };
+    const { default: fs23 } = await import("node:fs");
+    const { default: os15 } = await import("node:os");
+    const { default: path27 } = await import("node:path");
+    const tp = path27.join(os15.homedir(), ".olam", "host-cp.token");
+    if (!fs23.existsSync(tp)) return { token: null };
+    return { token: fs23.readFileSync(tp, "utf-8").trim() };
   } catch {
     return { token: null };
   }
@@ -28354,6 +28362,168 @@ function updateRepo(name, updates) {
   return updated;
 }
 
+// ../core/dist/global-config/runbooks.js
+function validateRunbookIntegrity(rb, registeredRepoNames) {
+  const runbookRepoSet = new Set(rb.repos);
+  for (const repoName of rb.repos) {
+    if (!registeredRepoNames.has(repoName)) {
+      throw new Error(`repo "${repoName}" is not registered. Add it with "olam repos add".`);
+    }
+  }
+  if (rb.seeds) {
+    for (const seed of rb.seeds) {
+      if (seed.repo && !runbookRepoSet.has(seed.repo)) {
+        throw new Error(`seed references repo "${seed.repo}" which is not in runbook repos [${rb.repos.join(", ")}].`);
+      }
+    }
+  }
+  if (rb.portMap) {
+    for (const repoKey of Object.keys(rb.portMap)) {
+      if (!runbookRepoSet.has(repoKey)) {
+        throw new Error(`portMap references repo "${repoKey}" which is not in runbook repos [${rb.repos.join(", ")}].`);
+      }
+    }
+  }
+  if (rb.env) {
+    for (const repoKey of Object.keys(rb.env)) {
+      if (!runbookRepoSet.has(repoKey)) {
+        throw new Error(`env references repo "${repoKey}" which is not in runbook repos [${rb.repos.join(", ")}].`);
+      }
+    }
+  }
+  if (rb.portMap) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const [repoName, svcMap] of Object.entries(rb.portMap)) {
+      for (const [svcName, port] of Object.entries(svcMap)) {
+        if (port < 1024 || port > 65535) {
+          throw new Error(`port ${port} for ${repoName}.${svcName} is out of range. Ports must be 1024\u201365535.`);
+        }
+        const label = `${repoName}.${svcName}`;
+        const previous = seen.get(port);
+        if (previous !== void 0) {
+          throw new Error(`port ${port} declared twice in runbook "${rb.name}" (${previous} and ${label}). Each port must be unique within a runbook.`);
+        }
+        seen.set(port, label);
+      }
+    }
+  }
+}
+function listRunbooks() {
+  return readGlobalConfig().runbooks;
+}
+function addRunbook(entry) {
+  const config2 = readGlobalConfig();
+  if (config2.runbooks.some((r) => r.name === entry.name)) {
+    throw new Error(`runbook "${entry.name}" already exists. Use "olam runbooks update" to modify it.`);
+  }
+  const registeredRepoNames = new Set(config2.repos.map((r) => r.name));
+  validateRunbookIntegrity({ ...entry, seeds: entry.seeds }, registeredRepoNames);
+  const now = Date.now();
+  const newRunbook = {
+    name: entry.name,
+    repos: entry.repos,
+    updatedAt: now,
+    ...entry.description !== void 0 ? { description: entry.description } : {},
+    ...entry.portMap !== void 0 ? { portMap: entry.portMap } : {},
+    ...entry.seeds !== void 0 ? { seeds: entry.seeds } : {},
+    ...entry.env !== void 0 ? { env: entry.env } : {}
+  };
+  writeGlobalConfig({ ...config2, runbooks: [...config2.runbooks, newRunbook] });
+  return newRunbook;
+}
+function removeRunbook(name) {
+  const config2 = readGlobalConfig();
+  if (!config2.runbooks.some((r) => r.name === name)) {
+    throw new Error(`runbook "${name}" not found. Run "olam runbooks list" to see available runbooks.`);
+  }
+  writeGlobalConfig({ ...config2, runbooks: config2.runbooks.filter((r) => r.name !== name) });
+}
+function getRunbook(name) {
+  const config2 = readGlobalConfig();
+  const found = config2.runbooks.find((r) => r.name === name);
+  if (!found) {
+    throw new Error(`runbook "${name}" not found. Run "olam runbooks list" to see available runbooks.`);
+  }
+  return found;
+}
+
+// ../core/dist/global-config/port-validator.js
+import * as net2 from "node:net";
+import * as childProcess from "node:child_process";
+import { createRequire as createRequire3 } from "node:module";
+var _require3;
+function getRequire() {
+  if (!_require3) {
+    _require3 = createRequire3(import.meta.url);
+  }
+  return _require3;
+}
+function checkPortInUse(port) {
+  try {
+    const server = net2.createServer();
+    server.unref();
+    let inUse = false;
+    try {
+      server.listen({ port, host: "0.0.0.0" });
+      server.close();
+    } catch {
+      inUse = true;
+    }
+    return inUse;
+  } catch {
+    return false;
+  }
+}
+function getPidForPort(port) {
+  try {
+    const out = childProcess.execSync(`lsof -ti :${port}`, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 2e3
+    });
+    const pid = parseInt(out.trim().split("\n")[0] ?? "", 10);
+    return Number.isNaN(pid) ? void 0 : pid;
+  } catch {
+    return void 0;
+  }
+}
+function getOlamWorldForPortDefault(port) {
+  try {
+    const { WorldRegistry: WorldRegistry2 } = getRequire()("../world/registry.js");
+    const registry2 = new WorldRegistry2();
+    try {
+      const worlds = registry2.list();
+      for (const world of worlds) {
+        if (world.appPortUrls?.some((apu) => apu.hostPort === port)) {
+          return world.id;
+        }
+      }
+    } finally {
+      registry2.close();
+    }
+  } catch {
+  }
+  return void 0;
+}
+function validateRunbookPorts(runbook, deps) {
+  if (!runbook.portMap || Object.keys(runbook.portMap).length === 0) {
+    return { conflicts: [] };
+  }
+  const isInUse = deps?.isPortInUse ?? checkPortInUse;
+  const getWorldId = deps?.getOlamWorldForPort ?? getOlamWorldForPortDefault;
+  const conflicts = [];
+  for (const [repoName, svcMap] of Object.entries(runbook.portMap)) {
+    for (const [serviceName, port] of Object.entries(svcMap)) {
+      if (!isInUse(port))
+        continue;
+      const worldId = getWorldId(port);
+      const occupant = worldId ? { type: "olam-world", worldId } : { type: "non-olam", pid: getPidForPort(port) };
+      conflicts.push({ port, repoName, serviceName, occupant });
+    }
+  }
+  return { conflicts };
+}
+
 // ../mcp-server/src/tools/repo.ts
 function asMessage4(err) {
   return err instanceof Error ? err.message : String(err);
@@ -28382,9 +28552,9 @@ function register22(server, _ctx, _initError) {
       description: external_exports.string().optional().describe("Optional human-readable description."),
       defaultBranch: external_exports.string().optional().describe("Default branch name (e.g. main).")
     },
-    async ({ name, path: path24, description, defaultBranch }) => {
+    async ({ name, path: path27, description, defaultBranch }) => {
       try {
-        const entry = addRepo({ name, path: path24, description, defaultBranch });
+        const entry = addRepo({ name, path: path27, description, defaultBranch });
         return {
           content: [{
             type: "text",
@@ -28425,9 +28595,9 @@ function register22(server, _ctx, _initError) {
       description: external_exports.string().optional().describe("New description."),
       defaultBranch: external_exports.string().optional().describe("New default branch.")
     },
-    async ({ name, path: path24, description, defaultBranch }) => {
+    async ({ name, path: path27, description, defaultBranch }) => {
       try {
-        const entry = updateRepo(name, { path: path24, description, defaultBranch });
+        const entry = updateRepo(name, { path: path27, description, defaultBranch });
         return {
           content: [{
             type: "text",
@@ -28577,6 +28747,163 @@ function register23(server, _ctx, _initError) {
   );
 }
 
+// ../mcp-server/src/tools/runbook.ts
+var runbook_exports = {};
+__export(runbook_exports, {
+  register: () => register24
+});
+function asMessage6(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function formatConflicts(conflicts) {
+  const lines = conflicts.map((c) => {
+    const occupant = c.occupant.type === "olam-world" ? `in use by world "${c.occupant.worldId}" (olam)` : `in use by PID ${c.occupant.pid ?? "unknown"} (non-olam)`;
+    return `  \u2717 ${c.repoName}.${c.serviceName}:${c.port} \u2014 ${occupant}`;
+  });
+  return lines.join("\n");
+}
+function register24(server, ctx, _initError) {
+  server.tool(
+    "olam_runbook_list",
+    "List all runbooks in ~/.olam/config.json. Returns { runbooks: Runbook[] }.",
+    {},
+    async () => {
+      const runbooks = listRunbooks();
+      return {
+        content: [{ type: "text", text: JSON.stringify({ runbooks }, null, 2) }]
+      };
+    }
+  );
+  server.tool(
+    "olam_runbook_show",
+    "Show a single runbook by name. Returns { runbook: Runbook }.",
+    {
+      name: external_exports.string().min(1).describe("Runbook name.")
+    },
+    async ({ name }) => {
+      try {
+        const runbook = getRunbook(name);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ runbook }, null, 2) }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: asMessage6(err) }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "olam_runbook_add",
+    "Create a new runbook. Validates that all referenced repos exist in the global registry and that portMap has no duplicates.",
+    {
+      name: external_exports.string().min(1).describe("Runbook name (lowercase, digits, dash; 1\u201364 chars)."),
+      repos: external_exports.array(external_exports.string().min(1)).min(1).describe("Repo names (must exist in registry)."),
+      description: external_exports.string().optional().describe("Optional human-readable description."),
+      portMap: external_exports.record(external_exports.string().min(1), external_exports.record(external_exports.string().min(1), external_exports.number().int())).optional().describe("Port mappings: { repoName: { serviceName: hostPort } }."),
+      seeds: external_exports.array(
+        external_exports.union([
+          external_exports.object({ type: external_exports.literal("sql-file"), repo: external_exports.string(), service: external_exports.string(), path: external_exports.string() }),
+          external_exports.object({ type: external_exports.literal("command"), repo: external_exports.string(), run: external_exports.string() }),
+          external_exports.object({ type: external_exports.literal("fixture-copy"), repo: external_exports.string(), src: external_exports.string(), dest: external_exports.string() })
+        ])
+      ).optional().describe("Optional seed operations to run when applying the runbook."),
+      env: external_exports.record(external_exports.string().min(1), external_exports.record(external_exports.string().min(1), external_exports.string())).optional().describe("Per-repo environment variable overrides.")
+    },
+    async ({ name, repos, description, portMap, seeds, env }) => {
+      try {
+        const runbook = addRunbook({ name, repos, description, portMap, seeds, env });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ name: runbook.name, message: `Created runbook "${runbook.name}".` }, null, 2)
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: asMessage6(err) }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "olam_runbook_remove",
+    "Remove a runbook from the global config. Does not affect any running worlds.",
+    {
+      name: external_exports.string().min(1).describe("Runbook name to remove.")
+    },
+    async ({ name }) => {
+      try {
+        removeRunbook(name);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ name, message: `Removed runbook "${name}".` }, null, 2)
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: asMessage6(err) }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "olam_runbook_apply",
+    "Validate ports then create a world from a runbook. Errors (isError: true) on port conflicts. Returns world metadata on success.",
+    {
+      name: external_exports.string().min(1).describe("Runbook name."),
+      worldName: external_exports.string().optional().describe("Override the world name."),
+      task: external_exports.string().optional().describe("Initial task to dispatch into the world."),
+      branchName: external_exports.string().optional().describe("Override the default branch name.")
+    },
+    async ({ name, worldName, task, branchName }) => {
+      if (!ctx) {
+        return {
+          content: [{ type: "text", text: "Olam is not configured. Run /olam:init to set up." }],
+          isError: true
+        };
+      }
+      let runbook;
+      try {
+        runbook = getRunbook(name);
+      } catch (err) {
+        return { content: [{ type: "text", text: asMessage6(err) }], isError: true };
+      }
+      const { conflicts } = validateRunbookPorts(runbook);
+      if (conflicts.length > 0) {
+        const detail = formatConflicts(conflicts);
+        const msg = `Port conflicts detected for runbook "${name}":
+${detail}
+
+${conflicts.length} port conflict(s). Stop the conflicting processes or update portMap in runbook "${name}".`;
+        return {
+          content: [{ type: "text", text: msg }],
+          isError: true
+        };
+      }
+      try {
+        const worldOpts = {
+          name: worldName ?? name,
+          repos: runbook.repos,
+          task: task ?? `Apply runbook "${name}"`,
+          ...branchName ? { branchName } : {}
+        };
+        const world = await ctx.worldManager.createWorld(worldOpts);
+        const result = {
+          worldId: world.id,
+          name: world.name,
+          branch: world.branch,
+          status: world.status,
+          repos: world.repos,
+          portOffset: world.portOffset,
+          ...world.appPortUrls ? { appPortUrls: world.appPortUrls } : {},
+          message: `World "${world.name}" created from runbook "${name}".`
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: asMessage6(err) }], isError: true };
+      }
+    }
+  );
+}
+
 // ../mcp-server/src/tools/index.ts
 var toolModules = [
   init_exports,
@@ -28601,7 +28928,8 @@ var toolModules = [
   capture_view_exports,
   create_from_prompt_exports,
   repo_exports,
-  process_port_exports
+  process_port_exports,
+  runbook_exports
 ];
 function registerAllTools(server, ctx, initError) {
   for (const mod of toolModules) {
@@ -28618,7 +28946,7 @@ var SERVER_INSTRUCTIONS = [
   "Use olam_observe to watch a world's reasoning. Use olam_crystallize to save thoughts.",
   "Always olam_destroy_world when done to clean up resources."
 ].join("\n");
-function createServer3(ctx, initError) {
+function createServer4(ctx, initError) {
   const server = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION },
     { instructions: SERVER_INSTRUCTIONS }
@@ -29098,11 +29426,11 @@ function loadConfig(startDir) {
 }
 
 // ../core/dist/world/manager.js
-import * as crypto4 from "node:crypto";
-import { execSync as execSync4 } from "node:child_process";
-import * as fs17 from "node:fs";
-import * as os11 from "node:os";
-import * as path21 from "node:path";
+import * as crypto5 from "node:crypto";
+import { execSync as execSync5 } from "node:child_process";
+import * as fs20 from "node:fs";
+import * as os13 from "node:os";
+import * as path24 from "node:path";
 
 // ../core/dist/world/state.js
 var VALID_TRANSITIONS = {
@@ -29136,6 +29464,7 @@ var WorldStateMachine = class {
 };
 
 // ../core/dist/world/devbox-image.js
+var WORLDSPEC_OVERRIDE_TAG = "worldspec-override";
 function selectDevboxImage(config2, repos) {
   const selectors = config2.devbox?.image_selectors;
   if (!selectors || selectors.length === 0)
@@ -29147,7 +29476,8 @@ function selectDevboxImage(config2, repos) {
       return {
         image: resolveDevboxImage(config2, sel.tag),
         cacheArch: sel.cache_arch,
-        tag: sel.tag
+        tag: sel.tag,
+        source: "image_selector"
       };
     }
   }
@@ -29168,6 +29498,18 @@ function matches(sel, repoNames, repoTypes) {
   }
   return true;
 }
+function selectDevboxImageForWorld(args) {
+  if (args.worldspec) {
+    return {
+      image: args.worldspec.images.devbox,
+      cacheArch: void 0,
+      // v1 worldspec schema doesn't carry cache_arch
+      tag: WORLDSPEC_OVERRIDE_TAG,
+      source: "worldspec"
+    };
+  }
+  return selectDevboxImage(args.config, args.repos);
+}
 function resolveDevboxImage(config2, tag) {
   const registry2 = config2.devbox?.registry;
   if (!registry2)
@@ -29311,8 +29653,8 @@ import * as fs14 from "node:fs";
 import * as os10 from "node:os";
 import * as path17 from "node:path";
 var DEFAULT_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
-function expandHome(p, homedir13) {
-  return p.replace(/^~(?=$|\/|\\)/, homedir13());
+function expandHome(p, homedir15) {
+  return p.replace(/^~(?=$|\/|\\)/, homedir15());
 }
 function sanitizeRepoFilename(name) {
   const sanitized = name.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -29335,7 +29677,7 @@ ${stderr}`;
 }
 function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
   const exec = deps.exec ?? ((cmd, args, opts) => execFileSync3(cmd, args, opts));
-  const homedir13 = deps.homedir ?? (() => os10.homedir());
+  const homedir15 = deps.homedir ?? (() => os10.homedir());
   const baselineDir = path17.join(workspacePath, ".olam", "baseline");
   try {
     fs14.mkdirSync(baselineDir, { recursive: true });
@@ -29351,7 +29693,7 @@ function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
       continue;
     const filename = `${sanitizeRepoFilename(repo.name)}.diff`;
     const outPath = path17.join(baselineDir, filename);
-    const repoPath = expandHome(repo.path, homedir13);
+    const repoPath = expandHome(repo.path, homedir15);
     if (!fs14.existsSync(repoPath)) {
       writeBaselineFile(outPath, `# repo: ${repo.name}
 # (skipped: path ${repoPath} does not exist)
@@ -29866,7 +30208,7 @@ async function installStack(exec, repos, stacks) {
 }
 
 // ../core/dist/world/stack-image.js
-import { execSync as execSync2 } from "node:child_process";
+import { execSync as execSync3 } from "node:child_process";
 import * as crypto3 from "node:crypto";
 var BASE_IMAGE = "olam-devbox";
 var LABEL_PREFIX = "olam.stack-image";
@@ -29898,7 +30240,7 @@ function lookupCachedImage(runtimes) {
   const tag = computeImageTag(runtimes);
   const imageName = `${BASE_IMAGE}:${tag}`;
   try {
-    execSync2(`docker image inspect ${imageName} > /dev/null 2>&1`, {
+    execSync3(`docker image inspect ${imageName} > /dev/null 2>&1`, {
       stdio: "pipe",
       timeout: 5e3
     });
@@ -29910,14 +30252,14 @@ function lookupCachedImage(runtimes) {
 function commitAsImage(containerName, imageName) {
   const baseDigest = getBaseImageDigest();
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  execSync2(`docker commit --change 'LABEL ${LABEL_PREFIX}=true' --change 'LABEL ${LABEL_PREFIX}.created-at=${now}' --change 'LABEL ${LABEL_PREFIX}.base-digest=${baseDigest}' ${containerName} ${imageName}`, { stdio: "pipe", timeout: 12e4 });
+  execSync3(`docker commit --change 'LABEL ${LABEL_PREFIX}=true' --change 'LABEL ${LABEL_PREFIX}.created-at=${now}' --change 'LABEL ${LABEL_PREFIX}.base-digest=${baseDigest}' ${containerName} ${imageName}`, { stdio: "pipe", timeout: 12e4 });
 }
 var cachedBaseDigest;
 function getBaseImageDigest() {
   if (cachedBaseDigest)
     return cachedBaseDigest;
   try {
-    const digest = execSync2(`docker inspect ${BASE_IMAGE}:latest --format '{{.Id}}'`, { encoding: "utf-8", timeout: 5e3 }).trim();
+    const digest = execSync3(`docker inspect ${BASE_IMAGE}:latest --format '{{.Id}}'`, { encoding: "utf-8", timeout: 5e3 }).trim();
     cachedBaseDigest = digest.replace("sha256:", "").slice(0, 16);
     return cachedBaseDigest;
   } catch {
@@ -30142,6 +30484,9 @@ var SENTINEL_SUFFIX = "-done";
 function sentinelPath(workdir, index) {
   return `${workdir}/${SENTINEL_PREFIX}${index}${SENTINEL_SUFFIX}`;
 }
+function bootstrapStepSentinelPath(workdir, index) {
+  return sentinelPath(workdir, index);
+}
 async function runBootstrap(containerName, workdir, steps, exec, options = {}) {
   if (!SAFE_IDENT.test(containerName)) {
     throw new Error(`containerName "${containerName}" must match ${SAFE_IDENT} (defensive guard)`);
@@ -30197,8 +30542,430 @@ function shellQuote(s) {
   return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 
+// ../core/dist/world/snapshot.js
+import * as crypto4 from "node:crypto";
+import * as fs16 from "node:fs";
+import * as os11 from "node:os";
+import * as path19 from "node:path";
+import { execFileSync as execFileSync4, spawn } from "node:child_process";
+import { gunzipSync } from "node:zlib";
+function snapshotsDir() {
+  return process.env["OLAM_SNAPSHOTS_DIR"] ?? path19.join(os11.homedir(), ".olam", "snapshots");
+}
+function snapshotKindDirByWorkspace(workspace, arch, kind) {
+  return path19.join(snapshotsDir(), "by-workspace", workspace, arch, kind);
+}
+function cleanupLegacyByWorldDir(worldId) {
+  const legacyDir = path19.join(snapshotsDir(), worldId);
+  if (worldId === "by-workspace")
+    return;
+  if (!fs16.existsSync(legacyDir))
+    return;
+  try {
+    fs16.rmSync(legacyDir, { recursive: true, force: true });
+  } catch {
+  }
+}
+function manifestPath(tarPath) {
+  return tarPath.replace(/\.tar\.gz$/, ".manifest.json");
+}
+function hashBuffers(entries) {
+  const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+  const hash = crypto4.createHash("sha256");
+  for (const entry of sorted) {
+    hash.update(entry.path);
+    hash.update("\0");
+    hash.update(entry.content);
+    hash.update("\0");
+  }
+  return hash.digest("hex").slice(0, 12);
+}
+function computeGemsFingerprint(repoDir, imageDigest) {
+  const lockfile = path19.join(repoDir, "Gemfile.lock");
+  if (!fs16.existsSync(lockfile))
+    return null;
+  const entries = [
+    { path: "Gemfile.lock", content: fs16.readFileSync(lockfile) }
+  ];
+  if (imageDigest) {
+    entries.push({ path: "__image_digest__", content: Buffer.from(imageDigest, "utf-8") });
+  }
+  return hashBuffers(entries);
+}
+function computeNodeFingerprint(repoDir, imageDigest) {
+  const candidates = ["yarn.lock", "pnpm-lock.yaml", "package-lock.json"];
+  for (const name of candidates) {
+    const lockfile = path19.join(repoDir, name);
+    if (fs16.existsSync(lockfile)) {
+      const entries = [
+        { path: name, content: fs16.readFileSync(lockfile) }
+      ];
+      if (imageDigest) {
+        entries.push({ path: "__image_digest__", content: Buffer.from(imageDigest, "utf-8") });
+      }
+      return hashBuffers(entries);
+    }
+  }
+  return null;
+}
+function unpackTarballAtomic(srcPath, destDir) {
+  const validation = enumerateAndValidateTarballEntries(srcPath, destDir);
+  if (!validation.valid) {
+    return {
+      ok: false,
+      reason: validation.reason,
+      detail: validation.detail ?? `unsafe entry: ${validation.unsafePath}`
+    };
+  }
+  const parent = path19.dirname(destDir);
+  fs16.mkdirSync(parent, { recursive: true });
+  const tmpSuffix = `.tmp-${process.pid}-${crypto4.randomBytes(4).toString("hex")}`;
+  const tmpDir = `${destDir}${tmpSuffix}`;
+  try {
+    fs16.mkdirSync(tmpDir, { recursive: true });
+    execFileSync4("tar", ["-xzf", srcPath, "-C", tmpDir], { stdio: "pipe" });
+    fs16.renameSync(tmpDir, destDir);
+    return { ok: true, entryCount: validation.entries.length };
+  } catch (err) {
+    try {
+      fs16.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+    }
+    return {
+      ok: false,
+      reason: "extract-error",
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function resolvesWithin(base, target) {
+  const resolved = path19.resolve(base, target);
+  const baseResolved = path19.resolve(base);
+  const rel = path19.relative(baseResolved, resolved);
+  if (rel === "")
+    return true;
+  return !rel.startsWith("..") && !path19.isAbsolute(rel);
+}
+var TYPE_CHAR_TO_TYPE = {
+  "-": "file",
+  "d": "dir",
+  "l": "symlink",
+  "h": "hardlink"
+};
+var DATE_MARKER_RE = /(?:\d{1,2}:\d{2}|(?:19|20)\d{2})\s+(.+)$/;
+function parseTarListLine(line) {
+  const trimmed = line.trimEnd();
+  if (trimmed.length === 0)
+    return null;
+  const typeChar = trimmed[0];
+  if (typeChar === void 0)
+    return null;
+  const type = TYPE_CHAR_TO_TYPE[typeChar];
+  if (!type)
+    return null;
+  const match = trimmed.match(DATE_MARKER_RE);
+  if (!match)
+    return null;
+  const remainderRaw = match[1];
+  if (remainderRaw === void 0)
+    return null;
+  let remainder = remainderRaw;
+  if (remainder.startsWith("./"))
+    remainder = remainder.slice(2);
+  const symlinkSplit = remainder.indexOf(" -> ");
+  if (type === "symlink" && symlinkSplit !== -1) {
+    return {
+      type: "symlink",
+      name: remainder.slice(0, symlinkSplit),
+      linkname: remainder.slice(symlinkSplit + 4)
+    };
+  }
+  const hardlinkMarker = " link to ";
+  const hardlinkSplit = remainder.indexOf(hardlinkMarker);
+  if (type === "hardlink" && hardlinkSplit !== -1) {
+    return {
+      type: "hardlink",
+      name: remainder.slice(0, hardlinkSplit),
+      linkname: remainder.slice(hardlinkSplit + hardlinkMarker.length)
+    };
+  }
+  return { type, name: remainder };
+}
+function validateHardlinksBinary(tarPath, targetDir) {
+  let raw;
+  try {
+    raw = gunzipSync(fs16.readFileSync(tarPath));
+  } catch {
+    return null;
+  }
+  let offset = 0;
+  while (offset + 512 <= raw.length) {
+    const block = raw.subarray(offset, offset + 512);
+    if (!block.some((b) => b !== 0))
+      break;
+    const typeflag = block[156] !== void 0 ? String.fromCharCode(block[156]) : "";
+    if (typeflag === "1") {
+      const nameNull = block.indexOf(0, 0);
+      const name = block.subarray(0, nameNull >= 0 && nameNull <= 99 ? nameNull : 100).toString("utf-8");
+      const linkNull = block.indexOf(0, 157);
+      const linkname = block.subarray(157, linkNull >= 157 && linkNull <= 256 ? linkNull : 257).toString("utf-8");
+      if (linkname && (path19.isAbsolute(linkname) || !resolvesWithin(targetDir, linkname))) {
+        return {
+          valid: false,
+          reason: "hardlink-escape",
+          unsafePath: name || tarPath,
+          detail: `linkname=${linkname} resolves outside targetDir`
+        };
+      }
+    }
+    const sizeRaw = block.subarray(124, 136).toString("utf-8").replace(/[\0 ]/g, "");
+    const size = sizeRaw ? parseInt(sizeRaw, 8) : 0;
+    offset += (1 + Math.ceil((isNaN(size) ? 0 : size) / 512)) * 512;
+  }
+  return null;
+}
+function enumerateAndValidateTarballEntries(tarPath, targetDir) {
+  let raw;
+  try {
+    raw = execFileSync4("tar", ["-tvf", tarPath], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+      encoding: "utf-8",
+      maxBuffer: 64 * 1024 * 1024
+      // 64 MiB ceiling for very large tarballs
+    });
+  } catch (err) {
+    return {
+      valid: false,
+      reason: "parse-error",
+      unsafePath: tarPath,
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const entries = [];
+  for (const line of raw.split("\n")) {
+    const entry = parseTarListLine(line);
+    if (!entry)
+      continue;
+    if (path19.isAbsolute(entry.name) || !resolvesWithin(targetDir, entry.name)) {
+      return {
+        valid: false,
+        reason: "path-traversal",
+        unsafePath: entry.name
+      };
+    }
+    if (entry.type === "symlink" && entry.linkname !== void 0) {
+      const symlinkParent = path19.join(targetDir, path19.dirname(entry.name));
+      if (path19.isAbsolute(entry.linkname) || !resolvesWithin(targetDir, path19.join(path19.dirname(entry.name), entry.linkname))) {
+        return {
+          valid: false,
+          reason: "symlink-escape",
+          unsafePath: entry.name,
+          detail: `linkname=${entry.linkname} resolves outside ${symlinkParent}`
+        };
+      }
+    }
+    if (entry.type === "hardlink" && entry.linkname !== void 0) {
+      if (path19.isAbsolute(entry.linkname) || !resolvesWithin(targetDir, entry.linkname)) {
+        return {
+          valid: false,
+          reason: "hardlink-escape",
+          unsafePath: entry.name,
+          detail: `linkname=${entry.linkname} resolves outside targetDir`
+        };
+      }
+    }
+    entries.push(entry);
+  }
+  const hardlinkResult = validateHardlinksBinary(tarPath, targetDir);
+  if (hardlinkResult !== null)
+    return hardlinkResult;
+  return { valid: true, entries };
+}
+var KINDS_BY_REPO = [
+  { kind: "gems", targetSubpath: "vendor/bundle", computeFp: computeGemsFingerprint },
+  { kind: "node", targetSubpath: "node_modules", computeFp: computeNodeFingerprint }
+];
+function restoreSnapshotsForRepos(input) {
+  const restored = /* @__PURE__ */ new Map();
+  const outcomes = [];
+  for (const repo of input.repos) {
+    const repoRestored = [];
+    for (const { kind, targetSubpath, computeFp } of KINDS_BY_REPO) {
+      const fingerprint = computeFp(repo.worktreeDir, input.imageDigest);
+      if (!fingerprint) {
+        outcomes.push({ repo: repo.name, kind, outcome: "miss", reason: "no-lockfile" });
+        continue;
+      }
+      const archDir = snapshotKindDirByWorkspace(input.workspace, input.arch, kind);
+      const tarFilename = `${repo.name}-${input.arch}-${fingerprint}.tar.gz`;
+      const tarPath = path19.join(archDir, tarFilename);
+      if (!fs16.existsSync(tarPath)) {
+        outcomes.push({ repo: repo.name, kind, outcome: "miss", reason: "no-tarball", fingerprint });
+        continue;
+      }
+      const manifest = readManifest(tarPath);
+      if (!manifest || manifest.arch !== input.arch) {
+        outcomes.push({
+          repo: repo.name,
+          kind,
+          outcome: "refused",
+          reason: "arch-mismatch",
+          fingerprint
+        });
+        continue;
+      }
+      const targetDir = path19.join(repo.worktreeDir, targetSubpath);
+      try {
+        fs16.rmSync(targetDir, { recursive: true, force: true });
+      } catch {
+      }
+      const result = unpackTarballAtomic(tarPath, targetDir);
+      if (!result.ok) {
+        outcomes.push({
+          repo: repo.name,
+          kind,
+          outcome: "refused",
+          reason: result.reason,
+          fingerprint
+        });
+        try {
+          fs16.rmSync(tarPath, { force: true });
+          fs16.rmSync(manifestPath(tarPath), { force: true });
+        } catch {
+        }
+        continue;
+      }
+      outcomes.push({ repo: repo.name, kind, outcome: "hit", fingerprint });
+      repoRestored.push(kind);
+    }
+    if (repoRestored.length > 0) {
+      restored.set(repo.name, repoRestored);
+    }
+  }
+  return { restored, outcomes };
+}
+function readManifest(tarPath) {
+  const mPath = manifestPath(tarPath);
+  if (!fs16.existsSync(mPath))
+    return null;
+  try {
+    return JSON.parse(fs16.readFileSync(mPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+var EVICT_LOCK_FILENAME = ".evict.lock";
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function evictOldSnapshotsWithFlock(maxBytes, dir = snapshotsDir()) {
+  fs16.mkdirSync(dir, { recursive: true });
+  const lockPath = path19.join(dir, EVICT_LOCK_FILENAME);
+  let fd;
+  try {
+    fd = fs16.openSync(lockPath, fs16.constants.O_WRONLY | fs16.constants.O_CREAT | fs16.constants.O_EXCL, 384);
+  } catch (err) {
+    if (err.code !== "EEXIST")
+      return 0;
+    let holderPid = null;
+    try {
+      holderPid = parseInt(fs16.readFileSync(lockPath, "utf-8").trim(), 10);
+    } catch {
+      holderPid = null;
+    }
+    if (holderPid && Number.isInteger(holderPid) && isPidAlive(holderPid)) {
+      return 0;
+    }
+    try {
+      fs16.unlinkSync(lockPath);
+      fd = fs16.openSync(lockPath, fs16.constants.O_WRONLY | fs16.constants.O_CREAT | fs16.constants.O_EXCL, 384);
+    } catch {
+      return 0;
+    }
+  }
+  try {
+    fs16.writeSync(fd, `${process.pid}
+`);
+  } finally {
+    fs16.closeSync(fd);
+  }
+  try {
+    return evictOldSnapshots(maxBytes, dir);
+  } finally {
+    try {
+      fs16.unlinkSync(lockPath);
+    } catch {
+    }
+  }
+}
+function spawnAutoCapture(worldId, olamBin = "olam") {
+  if (process.env["OLAM_SNAPSHOT_AUTO_CAPTURE"] === "0")
+    return null;
+  if (!/^[a-zA-Z0-9_\-.]+$/.test(worldId))
+    return null;
+  try {
+    const child = spawn(olamBin, ["world", "snapshot", "create", worldId, "--kind", "all"], {
+      detached: true,
+      stdio: "ignore",
+      // OLAM_INTERNAL_SNAPSHOT=1 sentinel — Phase D D1's deprecation
+      // counter (in packages/cli/src/commands/world-snapshot.ts) skips
+      // the bump when this env var is set. Preserves D22 signal
+      // integrity: the counter measures operator-driven invocations
+      // only, not auto-capture-triggered ones. See CP3 review HIGH
+      // finding for context.
+      env: {
+        ...process.env,
+        OLAM_INTERNAL_SNAPSHOT: "1",
+        NODE_OPTIONS: process.env["NODE_OPTIONS"] ?? ""
+      }
+    });
+    child.unref();
+    return child.pid ?? null;
+  } catch {
+    return null;
+  }
+}
+function evictOldSnapshots(maxBytes, dir = snapshotsDir()) {
+  if (!fs16.existsSync(dir))
+    return 0;
+  const allTars = [];
+  const walk = (d) => {
+    for (const entry of fs16.readdirSync(d, { withFileTypes: true })) {
+      const full = path19.join(d, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.name.endsWith(".tar.gz")) {
+        const stat = fs16.statSync(full);
+        allTars.push({ path: full, size: stat.size, mtime: stat.mtimeMs });
+      }
+    }
+  };
+  walk(dir);
+  const total = allTars.reduce((acc, t) => acc + t.size, 0);
+  if (total <= maxBytes)
+    return 0;
+  allTars.sort((a, b) => a.mtime - b.mtime);
+  let freed = 0;
+  let remaining = total;
+  for (const tar of allTars) {
+    if (remaining <= maxBytes)
+      break;
+    fs16.rmSync(tar.path, { force: true });
+    fs16.rmSync(manifestPath(tar.path), { force: true });
+    freed += tar.size;
+    remaining -= tar.size;
+  }
+  return freed;
+}
+
 // ../core/dist/world/secrets-fetcher.js
-import { execSync as execSync3 } from "node:child_process";
+import { execSync as execSync4 } from "node:child_process";
 function parseGcpSecretUrl(url) {
   if (!url.startsWith("gcp://"))
     return null;
@@ -30213,7 +30980,7 @@ function parseGcpSecretUrl(url) {
   return { project, secretName };
 }
 function defaultExecFn(cmd, opts) {
-  return execSync3(cmd, { encoding: "utf-8", timeout: opts?.timeout ?? 15e3 });
+  return execSync4(cmd, { encoding: "utf-8", timeout: opts?.timeout ?? 15e3 });
 }
 function fetchGcpSecret(ref, execFn = defaultExecFn) {
   const { project, secretName } = ref;
@@ -30306,14 +31073,14 @@ function gcloudAvailable(execFn = defaultExecFn) {
 }
 
 // ../core/dist/world/olam-yaml.js
-import * as path19 from "node:path";
+import * as path20 from "node:path";
 import YAML2 from "yaml";
 function enrichReposWithManifests(repos, workspacePath) {
   return repos.map((repo) => {
     if (repo.manifest !== void 0 && repo.manifest !== null) {
       return repo;
     }
-    const repoDir = path19.join(workspacePath, repo.name);
+    const repoDir = path20.join(workspacePath, repo.name);
     let manifest = null;
     try {
       manifest = loadRepoManifest(repoDir);
@@ -30328,8 +31095,8 @@ function enrichReposWithManifests(repos, workspacePath) {
 }
 
 // ../core/dist/policies/loader.js
-import * as fs16 from "node:fs";
-import * as path20 from "node:path";
+import * as fs17 from "node:fs";
+import * as path21 from "node:path";
 import { parse as parseYaml3 } from "yaml";
 function parseFrontmatter(content) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/m.exec(content);
@@ -30349,20 +31116,20 @@ function toStringArray(v) {
   return v.filter((x) => typeof x === "string");
 }
 function loadPolicies(workspaceRoot) {
-  const policiesDir = path20.join(workspaceRoot, ".olam", "policies");
-  if (!fs16.existsSync(policiesDir))
+  const policiesDir = path21.join(workspaceRoot, ".olam", "policies");
+  if (!fs17.existsSync(policiesDir))
     return [];
   let files;
   try {
-    files = fs16.readdirSync(policiesDir).filter((f) => f.endsWith(".md")).sort();
+    files = fs17.readdirSync(policiesDir).filter((f) => f.endsWith(".md")).sort();
   } catch {
     return [];
   }
   const policies = [];
   for (const file of files) {
-    const filePath = path20.join(policiesDir, file);
+    const filePath = path21.join(policiesDir, file);
     try {
-      const content = fs16.readFileSync(filePath, "utf8");
+      const content = fs17.readFileSync(filePath, "utf8");
       const parsed = parseFrontmatter(content);
       if (!parsed) {
         console.warn(`[policies] skipping ${file}: no valid frontmatter block`);
@@ -30412,17 +31179,93 @@ function formatPoliciesBrief(policies) {
   return lines.join("\n");
 }
 
+// ../core/dist/global-config/runbook-resolver.js
+import * as fs18 from "node:fs";
+import * as os12 from "node:os";
+import * as path22 from "node:path";
+function expandTilde(p) {
+  if (p === "~" || p.startsWith("~/")) {
+    return path22.join(os12.homedir(), p.slice(1));
+  }
+  return p;
+}
+function resolveRunbookToWorldParams(runbook, repoRegistry) {
+  const registryMap = new Map(repoRegistry.map((r) => [r.name, r]));
+  for (const repoName of runbook.repos) {
+    const entry = registryMap.get(repoName);
+    if (!entry) {
+      throw new Error(`repo "${repoName}" is referenced by runbook "${runbook.name}" but is not in the registry. Run "olam repos add ${repoName} --path <path>" to register it.`);
+    }
+    const resolvedPath = expandTilde(entry.path);
+    if (!fs18.existsSync(resolvedPath)) {
+      throw new Error(`repo "${repoName}" path "${resolvedPath}" no longer exists. Run "olam repos update ${repoName} --path <new-path>" to fix.`);
+    }
+  }
+  return {
+    repoNames: [...runbook.repos],
+    portOverrides: runbook.portMap ?? {},
+    envOverrides: runbook.env ?? {},
+    seeds: runbook.seeds
+  };
+}
+
+// ../core/dist/world/bootstrap-hooks.js
+import * as fs19 from "node:fs";
+import * as path23 from "node:path";
+function runFixtureCopySeeds(seeds, workspacePath) {
+  if (!seeds)
+    return;
+  for (const seed of seeds) {
+    if (seed.type !== "fixture-copy")
+      continue;
+    const srcAbs = path23.resolve(workspacePath, seed.repo, seed.src);
+    const destAbs = path23.resolve(workspacePath, seed.repo, seed.dest);
+    const destDir = path23.dirname(destAbs);
+    fs19.mkdirSync(destDir, { recursive: true });
+    fs19.cpSync(srcAbs, destAbs, { recursive: true, force: true });
+  }
+}
+async function runSeedHooks(seeds, containerName, servicePortMap, exec) {
+  if (!seeds)
+    return;
+  for (const seed of seeds) {
+    if (seed.type === "fixture-copy")
+      continue;
+    if (seed.type === "sql-file") {
+      const servicePorts = servicePortMap[seed.repo] ?? {};
+      const port = servicePorts[seed.service] ?? 5432;
+      const waitCmd = `until pg_isready -h localhost -p ${port} -t 1 2>/dev/null; do sleep 2; done`;
+      const psqlCmd = `psql -h localhost -p ${port} -f /home/olam/workspace/${seed.repo}/${seed.path}`;
+      const combined = `${waitCmd} && ${psqlCmd}`;
+      try {
+        exec(containerName, combined);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`seed failed for repo "${seed.repo}" (type: sql-file, service: "${seed.service}", path: "${seed.path}"): ${msg}`);
+      }
+    } else if (seed.type === "command") {
+      const workdir = `/home/olam/workspace/${seed.repo}`;
+      try {
+        exec(containerName, `cd ${workdir} && ${seed.run}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`seed failed for repo "${seed.repo}" (type: command, run: "${seed.run}"): ${msg}`);
+      }
+    }
+  }
+}
+
 // ../core/dist/world/tmux-supervisor.js
 var PortInUseError = class extends Error {
   port;
   repo;
   manifestPath;
-  constructor(port, repo, manifestPath) {
-    super(`Port ${port} already in use on host (claimed by repo "${repo}"). Free the port or change \`app_port\` in ${manifestPath}.`);
+  constructor(port, repo, manifestPath2) {
+    super(`Port ${port} already in use on host (claimed by repo "${repo}"). Free the port or change \`app_port\` in ${manifestPath2}.`);
     this.name = "PortInUseError";
     this.port = port;
     this.repo = repo;
-    this.manifestPath = manifestPath;
+    this.manifestPath = manifestPath2;
   }
 };
 var SAFE_IDENT2 = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -30517,7 +31360,7 @@ var BotIdentityError = class extends Error {
     this.name = "BotIdentityError";
   }
 };
-function getTokenScopes(ghToken, _exec = execSync4) {
+function getTokenScopes(ghToken, _exec = execSync5) {
   try {
     const out = _exec("gh auth status 2>&1", {
       encoding: "utf-8",
@@ -30534,13 +31377,13 @@ function getTokenScopes(ghToken, _exec = execSync4) {
   }
 }
 async function setupContainerGit(containerName, repos, branch) {
-  const dockerExec = (cmd) => execSync4(`docker exec ${containerName} sh -c '${cmd.replace(/'/g, "'\\''")}'`, {
+  const dockerExec = (cmd) => execSync5(`docker exec ${containerName} sh -c '${cmd.replace(/'/g, "'\\''")}'`, {
     stdio: "pipe",
     timeout: 6e4
   }).toString();
   let ghToken = "";
   try {
-    ghToken = execSync4("gh auth token 2>/dev/null", { encoding: "utf-8", timeout: 5e3 }).trim();
+    ghToken = execSync5("gh auth token 2>/dev/null", { encoding: "utf-8", timeout: 5e3 }).trim();
   } catch {
   }
   const actorName = process.env.OLAM_BOT_NAME ?? "Claude Code (olam)";
@@ -30560,7 +31403,7 @@ async function setupContainerGit(containerName, repos, branch) {
         continue;
       const ownerRepo = ghMatch[1];
       try {
-        execSync4(`gh api repos/${ownerRepo} --silent`, {
+        execSync5(`gh api repos/${ownerRepo} --silent`, {
           stdio: "pipe",
           timeout: 5e3,
           env: { ...process.env, GH_TOKEN: ghToken }
@@ -30608,8 +31451,8 @@ ${stderr.split("\n").slice(0, 3).join(" ")}`);
     if (!olamUserPresent) {
       const imageName = (() => {
         try {
-          const { execSync: execSync6 } = __require("node:child_process");
-          return execSync6(`docker inspect ${containerName} --format '{{.Config.Image}}'`, {
+          const { execSync: execSync7 } = __require("node:child_process");
+          return execSync7(`docker inspect ${containerName} --format '{{.Config.Image}}'`, {
             encoding: "utf8",
             timeout: 5e3
           }).trim() || "(unknown)";
@@ -30652,7 +31495,7 @@ ${stderr.split("\n").slice(0, 3).join(" ")}`);
 function makeHostExecFn() {
   return async (cmd) => {
     try {
-      const stdout = execSync4(cmd, { encoding: "utf-8", timeout: 5e3 });
+      const stdout = execSync5(cmd, { encoding: "utf-8", timeout: 5e3 });
       return { stdout, stderr: "", exitCode: 0 };
     } catch {
       return { stdout: "", stderr: "", exitCode: 1 };
@@ -30662,7 +31505,7 @@ function makeHostExecFn() {
 function makeContainerExecFn(containerName) {
   return async (cmd) => {
     try {
-      const result = execSync4(`docker exec ${containerName} sh -c '${cmd.replace(/'/g, "'\\''")}'`, { stdio: "pipe", timeout: 6e5 });
+      const result = execSync5(`docker exec ${containerName} sh -c '${cmd.replace(/'/g, "'\\''")}'`, { stdio: "pipe", timeout: 6e5 });
       return { stdout: result.toString(), stderr: "", exitCode: 0 };
     } catch (err) {
       const execErr = err;
@@ -30676,7 +31519,7 @@ function makeContainerExecFn(containerName) {
 }
 function defaultDockerExec() {
   return (containerName, cmd) => {
-    const result = execSync4(
+    const result = execSync5(
       `docker exec ${containerName} sh -c '${cmd.replace(/'/g, "'\\''")}'`,
       // Phase E E5 raise: 10min was too tight on cold-boot for atlas-core's
       // `rails db:create` chain (Rails 7 boot + initializer load + first
@@ -30900,8 +31743,28 @@ var WorldManager = class {
         throw new AuthPreflightError(preflight.verdict, preflight.message, preflight.remedy);
       }
     }
+    let runbookPortOverrides = {};
+    let runbookEnvOverrides = {};
+    let runbookSeeds;
+    if (opts.runbookName) {
+      const runbook = getRunbook(opts.runbookName);
+      const globalConfig2 = readGlobalConfig();
+      const resolved = resolveRunbookToWorldParams(runbook, globalConfig2.repos);
+      const { conflicts } = validateRunbookPorts(runbook);
+      if (conflicts.length > 0) {
+        const detail = conflicts.map((c) => {
+          const occ = c.occupant.type === "olam-world" ? `in use by world "${c.occupant.worldId}" (olam)` : `in use by PID ${c.occupant.pid ?? "unknown"} (non-olam)`;
+          return `  ${c.repoName}.${c.serviceName}:${c.port} \u2014 ${occ}`;
+        }).join("\n");
+        throw new Error(`Port conflicts detected for runbook "${opts.runbookName}":
+${detail}`);
+      }
+      runbookPortOverrides = resolved.portOverrides;
+      runbookEnvOverrides = resolved.envOverrides;
+      runbookSeeds = resolved.seeds;
+    }
     const worldId = generateWorldId();
-    const workspacePath = path21.join(os11.homedir(), ".olam", "worlds", worldId);
+    const workspacePath = path24.join(os13.homedir(), ".olam", "worlds", worldId);
     const portOffset = this.registry.getNextPortOffset();
     const branch = opts.branchName ?? `olam/${worldId}`;
     const repos = this.resolveReposWithWorkspace(opts);
@@ -30933,6 +31796,19 @@ var WorldManager = class {
       this.registry.update(worldId, { status: "error" });
       throw err;
     }
+    if (opts.runbookName && runbookSeeds) {
+      try {
+        runFixtureCopySeeds(runbookSeeds, workspacePath);
+      } catch (err) {
+        sm.transition("error");
+        this.registry.update(worldId, { status: "error" });
+        try {
+          await removeWorktrees(repos, workspacePath);
+        } catch {
+        }
+        throw err;
+      }
+    }
     try {
       const baseline = snapshotBaselineDiff(repos, workspacePath);
       console.log(formatBaselineSummary(baseline));
@@ -30957,38 +31833,38 @@ var WorldManager = class {
     for (const repo of repos) {
       if (!repo.path)
         continue;
-      const sourceRoot = repo.path.replace(/^~/, os11.homedir());
-      const worktreeRoot = path21.join(workspacePath, repo.name);
-      if (!fs17.existsSync(sourceRoot) || !fs17.existsSync(worktreeRoot))
+      const sourceRoot = repo.path.replace(/^~/, os13.homedir());
+      const worktreeRoot = path24.join(workspacePath, repo.name);
+      if (!fs20.existsSync(sourceRoot) || !fs20.existsSync(worktreeRoot))
         continue;
       let copied = 0;
       for (const pattern of RUNTIME_FILE_PATTERNS) {
         const matches2 = [];
         if (pattern.includes("*")) {
-          const [dir, glob] = [path21.dirname(pattern), path21.basename(pattern)];
-          const sourceDir = path21.join(sourceRoot, dir);
-          if (fs17.existsSync(sourceDir)) {
+          const [dir, glob] = [path24.dirname(pattern), path24.basename(pattern)];
+          const sourceDir = path24.join(sourceRoot, dir);
+          if (fs20.existsSync(sourceDir)) {
             const ext = glob.replace(/^\*+/, "");
             try {
-              for (const entry of fs17.readdirSync(sourceDir)) {
+              for (const entry of fs20.readdirSync(sourceDir)) {
                 if (ext === "" || entry.endsWith(ext))
-                  matches2.push(path21.join(dir, entry));
+                  matches2.push(path24.join(dir, entry));
               }
             } catch {
             }
           }
-        } else if (fs17.existsSync(path21.join(sourceRoot, pattern))) {
+        } else if (fs20.existsSync(path24.join(sourceRoot, pattern))) {
           matches2.push(pattern);
         }
         for (const rel of matches2) {
-          const src = path21.join(sourceRoot, rel);
-          const dst = path21.join(worktreeRoot, rel);
+          const src = path24.join(sourceRoot, rel);
+          const dst = path24.join(worktreeRoot, rel);
           try {
-            const st = fs17.statSync(src);
+            const st = fs20.statSync(src);
             if (!st.isFile())
               continue;
-            fs17.mkdirSync(path21.dirname(dst), { recursive: true });
-            fs17.copyFileSync(src, dst);
+            fs20.mkdirSync(path24.dirname(dst), { recursive: true });
+            fs20.copyFileSync(src, dst);
             copied++;
           } catch {
           }
@@ -31088,7 +31964,7 @@ var WorldManager = class {
       try {
         const hostExec = makeHostExecFn();
         for (const repo of repos) {
-          const repoDir = path21.join(workspacePath, repo.name);
+          const repoDir = path24.join(workspacePath, repo.name);
           if (repo.stack && Object.keys(repo.stack).length > 0) {
             preDetectedStacks.set(repo.name, { repoName: repo.name, versions: repo.stack });
           } else {
@@ -31114,11 +31990,19 @@ var WorldManager = class {
     }
     let cacheArchOverride;
     if (!stackCacheHit) {
-      const selected = selectDevboxImage(this.config, repos);
+      const selected = selectDevboxImageForWorld({
+        config: this.config,
+        repos,
+        worldspec: opts.worldspec
+      });
       if (selected) {
         selectedImage = selected.image;
         cacheArchOverride = selected.cacheArch;
-        console.log(`[WorldManager] image_selector matched \u2014 using ${selected.image} (tag=${selected.tag}${selected.cacheArch ? `, cache_arch=${selected.cacheArch}` : ""})`);
+        if (selected.source === "worldspec") {
+          console.log(`[WorldManager] worldspec override \u2014 using ${selected.image} (tag=${selected.tag})`);
+        } else {
+          console.log(`[WorldManager] image_selector matched \u2014 using ${selected.image} (tag=${selected.tag}${selected.cacheArch ? `, cache_arch=${selected.cacheArch}` : ""})`);
+        }
       } else {
         const hasRailsRepo = repos.some((r) => r.type === "rails");
         if (hasRailsRepo) {
@@ -31138,17 +32022,18 @@ var WorldManager = class {
       }
     }
     const appPortUrls = appPorts.map((ap) => {
-      const hostPort = ap.port + 1e4 + portOffset;
+      const override = runbookPortOverrides[ap.name]?.["app"];
+      const hostPort = override !== void 0 ? override : ap.port + 1e4 + portOffset;
       return { repoName: ap.name, internalPort: ap.port, hostPort, url: `http://localhost:${hostPort}` };
     });
     try {
       const worldEnv = {};
       if (opts.task)
         worldEnv.OLAM_TASK = opts.task;
-      const r2CredsPath = path21.join(os11.homedir(), ".olam", "r2-credentials.json");
-      if (fs17.existsSync(r2CredsPath)) {
+      const r2CredsPath = path24.join(os13.homedir(), ".olam", "r2-credentials.json");
+      if (fs20.existsSync(r2CredsPath)) {
         try {
-          const r2Raw = fs17.readFileSync(r2CredsPath, "utf-8").trim();
+          const r2Raw = fs20.readFileSync(r2CredsPath, "utf-8").trim();
           if (r2Raw.length > 0) {
             const r2 = JSON.parse(r2Raw);
             if (typeof r2.account_id === "string")
@@ -31165,10 +32050,10 @@ var WorldManager = class {
         } catch {
         }
       }
-      const keysYamlPath = path21.join(os11.homedir(), ".olam", "keys.yaml");
-      if (fs17.existsSync(keysYamlPath)) {
+      const keysYamlPath = path24.join(os13.homedir(), ".olam", "keys.yaml");
+      if (fs20.existsSync(keysYamlPath)) {
         try {
-          const keysRaw = fs17.readFileSync(keysYamlPath, "utf-8").trim();
+          const keysRaw = fs20.readFileSync(keysYamlPath, "utf-8").trim();
           if (keysRaw.length > 0) {
             const parsed = YAML3.parse(keysRaw);
             if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
@@ -31204,6 +32089,18 @@ var WorldManager = class {
           seenFromRepo.set(k, repo.name);
         }
       }
+      if (opts.runbookName) {
+        for (const [repoName, repoEnv] of Object.entries(runbookEnvOverrides)) {
+          for (const [k, v] of Object.entries(repoEnv)) {
+            if (PROTECTED_ENV_KEY_SET.has(k))
+              continue;
+            if (k.startsWith("OLAM_"))
+              continue;
+            worldEnv[k] = v;
+          }
+          void repoName;
+        }
+      }
       if (repoSecretUrls.length > 0) {
         const { env: gcpSecrets, fileWrites } = fetchSecretsForRepos(repoSecretUrls);
         for (const [k, v] of Object.entries(gcpSecrets)) {
@@ -31215,10 +32112,10 @@ var WorldManager = class {
             worldEnv[k] = v;
         }
         for (const { repoName, relativePath, content } of fileWrites) {
-          const absPath = path21.join(workspacePath, repoName, relativePath);
+          const absPath = path24.join(workspacePath, repoName, relativePath);
           try {
-            fs17.mkdirSync(path21.dirname(absPath), { recursive: true });
-            fs17.writeFileSync(absPath, content.endsWith("\n") ? content : content + "\n", {
+            fs20.mkdirSync(path24.dirname(absPath), { recursive: true });
+            fs20.writeFileSync(absPath, content.endsWith("\n") ? content : content + "\n", {
               mode: 384
             });
             console.log(`[secrets] ${repoName}: materialised ${relativePath} (${content.length} chars, mode 0600)`);
@@ -31324,6 +32221,44 @@ var WorldManager = class {
       const msg = err instanceof Error ? err.message : String(err);
       console.warn(`[WorldManager] stack installation failed: ${msg}`);
     }
+    try {
+      cleanupLegacyByWorldDir(worldId);
+      const restoreResult = restoreSnapshotsForRepos({
+        workspace: opts.workspace ?? "default",
+        arch: process.arch,
+        imageDigest: void 0,
+        repos: enrichedRepos.map((r) => ({
+          name: r.name,
+          worktreeDir: path24.join(workspacePath, r.name)
+        }))
+      });
+      for (const out of restoreResult.outcomes) {
+        if (out.outcome === "hit") {
+          console.log(`[snapshot] Restored ${out.kind} for ${out.repo} (${out.fingerprint?.slice(0, 12)})`);
+        } else if (out.outcome === "refused") {
+          console.warn(`[snapshot] Skipped ${out.repo} ${out.kind}: ${out.reason ?? "unknown"}`);
+        }
+      }
+      for (const [repoName, restoredKinds] of restoreResult.restored) {
+        const repo = enrichedRepos.find((r) => r.name === repoName);
+        if (!repo?.manifest?.bootstrap)
+          continue;
+        const containerWorkdir = `/home/olam/workspace/${repoName}`;
+        repo.manifest.bootstrap.forEach((step, idx) => {
+          const produces = typeof step === "object" && step !== null ? step.produces : void 0;
+          if (produces && restoredKinds.includes(produces)) {
+            const sentinel = bootstrapStepSentinelPath(containerWorkdir, idx);
+            try {
+              this.dockerExec(containerName, `touch ${sentinel}`);
+            } catch {
+            }
+          }
+        });
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[snapshot] restore failed (cold path): ${msg}`);
+    }
     try {
       await runManifestRuntime(containerName, worldId, enrichedRepos, this.dockerExec);
     } catch (err) {
@@ -31348,12 +32283,30 @@ var WorldManager = class {
         console.warn(`[manifest] step 4e/4f/4g non-fatal failure: ${msg}`);
       }
     }
+    if (opts.runbookName && runbookSeeds) {
+      const servicePortMap = {};
+      for (const repo of enrichedRepos) {
+        if (!repo.manifest?.services)
+          continue;
+        const svcPorts = {};
+        for (const [svcName, svc] of Object.entries(repo.manifest.services)) {
+          svcPorts[svcName] = svc.port ?? 5432;
+        }
+        servicePortMap[repo.name] = svcPorts;
+      }
+      try {
+        await runSeedHooks(runbookSeeds, containerName, servicePortMap, this.dockerExec);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[runbook] seed hook failed: ${msg}`);
+      }
+    }
     for (const repo of repos) {
       if (repo.setup_commands.length > 0) {
         const escapedDir = `/home/olam/workspace/${repo.name.replace(/["$`\\]/g, "\\$&")}`;
         for (const cmd of repo.setup_commands) {
           try {
-            execSync4(`docker exec ${containerName} sh -c 'cd "${escapedDir}" && ${cmd.replace(/'/g, "'\\''")}'`, { stdio: "pipe", timeout: 6e5 });
+            execSync5(`docker exec ${containerName} sh -c 'cd "${escapedDir}" && ${cmd.replace(/'/g, "'\\''")}'`, { stdio: "pipe", timeout: 6e5 });
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             console.warn(`[WorldManager] setup command failed for ${repo.name}: ${msg}`);
@@ -31363,14 +32316,14 @@ var WorldManager = class {
     }
     if (credentialsInjected.claude) {
       try {
-        execSync4(`docker exec ${containerName} curl -sf -X POST http://localhost:8080/session/start-agent 2>/dev/null || true`, { stdio: "pipe", timeout: 45e3 });
+        execSync5(`docker exec ${containerName} curl -sf -X POST http://localhost:8080/session/start-agent 2>/dev/null || true`, { stdio: "pipe", timeout: 45e3 });
       } catch {
       }
       if (opts.task) {
         let taskWithPolicies = opts.task;
         try {
           const allPolicies = repos.flatMap((repo) => {
-            const repoWorktree = path21.join(workspacePath, repo.name);
+            const repoWorktree = path24.join(workspacePath, repo.name);
             return loadPolicies(repoWorktree);
           });
           const seen = /* @__PURE__ */ new Set();
@@ -31384,11 +32337,11 @@ var WorldManager = class {
             const brief = formatPoliciesBrief(uniquePolicies);
             taskWithPolicies = `${brief}## Your task
 ${opts.task}`;
-            execSync4(`docker exec ${containerName} mkdir -p /home/olam/.olam/policies`, { stdio: "pipe", timeout: 1e4 });
+            execSync5(`docker exec ${containerName} mkdir -p /home/olam/.olam/policies`, { stdio: "pipe", timeout: 1e4 });
             for (const repo of repos) {
-              const policiesDir = path21.join(workspacePath, repo.name, ".olam", "policies");
-              if (fs17.existsSync(policiesDir)) {
-                execSync4(`docker cp "${policiesDir}/." "${containerName}:/home/olam/.olam/policies/"`, { stdio: "pipe", timeout: 15e3 });
+              const policiesDir = path24.join(workspacePath, repo.name, ".olam", "policies");
+              if (fs20.existsSync(policiesDir)) {
+                execSync5(`docker cp "${policiesDir}/." "${containerName}:/home/olam/.olam/policies/"`, { stdio: "pipe", timeout: 15e3 });
               }
             }
           }
@@ -31398,7 +32351,7 @@ ${opts.task}`;
         }
         try {
           const payload = JSON.stringify({ prompt: taskWithPolicies }).replace(/'/g, "'\\''");
-          execSync4(`docker exec ${containerName} curl -sf -X POST -H 'Content-Type: application/json' -d '${payload}' http://localhost:8080/dispatch 2>/dev/null || true`, { stdio: "pipe", timeout: 3e4 });
+          execSync5(`docker exec ${containerName} curl -sf -X POST -H 'Content-Type: application/json' -d '${payload}' http://localhost:8080/dispatch 2>/dev/null || true`, { stdio: "pipe", timeout: 3e4 });
           console.log("[world] Task auto-dispatched");
         } catch {
         }
@@ -31409,6 +32362,19 @@ ${opts.task}`;
     const terminalPort = 17681 + portOffset;
     const dashboardUrl = `http://localhost:${dashboardPort}`;
     const terminalUrl = `http://localhost:${terminalPort}`;
+    try {
+      spawnAutoCapture(worldId);
+    } catch {
+    }
+    try {
+      const cap = parseInt(process.env["OLAM_SNAPSHOT_MAX_BYTES"] ?? "", 10);
+      const maxBytes = Number.isInteger(cap) && cap > 0 ? cap : 5 * 1024 * 1024 * 1024;
+      const freed = evictOldSnapshotsWithFlock(maxBytes);
+      if (freed > 0) {
+        console.log(`[snapshot] evicted ${(freed / 1024 / 1024).toFixed(0)}MB to stay under ${(maxBytes / 1024 / 1024 / 1024).toFixed(1)}GB cap`);
+      }
+    } catch {
+    }
     return {
       ...metadata,
       status: "running",
@@ -31466,8 +32432,8 @@ ${opts.task}`;
     } catch {
     }
     try {
-      fs17.rmSync(world.workspacePath, { recursive: true, force: true });
-      if (fs17.existsSync(world.workspacePath)) {
+      fs20.rmSync(world.workspacePath, { recursive: true, force: true });
+      if (fs20.existsSync(world.workspacePath)) {
         console.warn(`[WorldManager] destroyWorld(${worldId}): workspace dir ${world.workspacePath} still exists after rmSync. Run \`olam clean --apply\` to reap.`);
       }
     } catch (err) {
@@ -31552,14 +32518,14 @@ ${opts.task}`;
     return names.map((name) => this.config.repos.find((r) => r.name === name)).filter((r) => r !== void 0);
   }
   transportPlanFile(planFilePath, workspacePath, repoNames) {
-    const planContent = fs17.readFileSync(planFilePath, "utf-8");
-    const planFileName = path21.basename(planFilePath);
+    const planContent = fs20.readFileSync(planFilePath, "utf-8");
+    const planFileName = path24.basename(planFilePath);
     const targetRepo = repoNames[0];
     if (!targetRepo)
       return;
-    const plansDir = path21.join(workspacePath, targetRepo, "docs", "plans");
-    fs17.mkdirSync(plansDir, { recursive: true });
-    fs17.writeFileSync(path21.join(plansDir, planFileName), planContent);
+    const plansDir = path24.join(workspacePath, targetRepo, "docs", "plans");
+    fs20.mkdirSync(plansDir, { recursive: true });
+    fs20.writeFileSync(path24.join(plansDir, planFileName), planContent);
   }
   resolveServices(repos) {
     const services = [];
@@ -31644,8 +32610,8 @@ import * as http2 from "node:http";
 
 // ../core/dist/dashboard/server.js
 import * as http from "node:http";
-import * as fs18 from "node:fs";
-import * as path22 from "node:path";
+import * as fs21 from "node:fs";
+import * as path25 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../core/dist/dashboard/serialize.js
@@ -31980,7 +32946,7 @@ function notFound(res) {
 }
 function openThoughtStore(workspacePath) {
   const dbPath = getWorldDbPath(workspacePath);
-  if (!fs18.existsSync(dbPath))
+  if (!fs21.existsSync(dbPath))
     return null;
   return new ThoughtLocalStore(dbPath);
 }
@@ -32151,13 +33117,13 @@ function findSessionInWorld(registry2, sessionId) {
 }
 function createDashboardServer(opts) {
   const { port, registry: registry2 } = opts;
-  const thisDir = path22.dirname(fileURLToPath2(import.meta.url));
-  const defaultPublicDir = path22.resolve(thisDir, "../../../control-plane/public");
+  const thisDir = path25.dirname(fileURLToPath2(import.meta.url));
+  const defaultPublicDir = path25.resolve(thisDir, "../../../control-plane/public");
   const publicDir = opts.publicDir ?? defaultPublicDir;
-  let hasPublicDir = fs18.existsSync(publicDir);
+  let hasPublicDir = fs21.existsSync(publicDir);
   const server = http.createServer((req, res) => {
     if (!hasPublicDir) {
-      hasPublicDir = fs18.existsSync(publicDir);
+      hasPublicDir = fs21.existsSync(publicDir);
     }
     const host = req.headers.host ?? `localhost:${port}`;
     const url = new URL(req.url ?? "/", `http://${host}`);
@@ -32431,22 +33397,22 @@ function createDashboardServer(opts) {
       res.end(`<html><body style="font-family:system-ui;padding:2rem"><h1>Olam Dashboard</h1><p>The React app has not been built yet.</p><p>Run <code>npm run build:app</code> in <code>packages/control-plane</code> to build it.</p><p>API routes are available at <code>/api/*</code>.</p></body></html>`);
       return;
     }
-    let filePath = path22.join(publicDir, pathname === "/" ? "index.html" : pathname);
+    let filePath = path25.join(publicDir, pathname === "/" ? "index.html" : pathname);
     if (!filePath.startsWith(publicDir)) {
       notFound(res);
       return;
     }
-    if (fs18.existsSync(filePath) && fs18.statSync(filePath).isFile()) {
-      const ext = path22.extname(filePath);
+    if (fs21.existsSync(filePath) && fs21.statSync(filePath).isFile()) {
+      const ext = path25.extname(filePath);
       const contentType = MIME[ext] ?? "application/octet-stream";
       res.writeHead(200, { "Content-Type": contentType });
-      fs18.createReadStream(filePath).pipe(res);
+      fs21.createReadStream(filePath).pipe(res);
       return;
     }
-    filePath = path22.join(publicDir, "index.html");
-    if (fs18.existsSync(filePath)) {
+    filePath = path25.join(publicDir, "index.html");
+    if (fs21.existsSync(filePath)) {
       res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-      fs18.createReadStream(filePath).pipe(res);
+      fs21.createReadStream(filePath).pipe(res);
       return;
     }
     notFound(res);
@@ -32456,17 +33422,17 @@ function createDashboardServer(opts) {
 }
 
 // ../core/dist/dashboard/state.js
-import * as fs19 from "node:fs";
-import * as os12 from "node:os";
-import * as path23 from "node:path";
-var STATE_PATH = path23.join(os12.homedir(), ".olam", "dashboard.json");
+import * as fs22 from "node:fs";
+import * as os14 from "node:os";
+import * as path26 from "node:path";
+var STATE_PATH = path26.join(os14.homedir(), ".olam", "dashboard.json");
 function saveDashboardState(state) {
-  fs19.mkdirSync(path23.dirname(STATE_PATH), { recursive: true });
-  fs19.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+  fs22.mkdirSync(path26.dirname(STATE_PATH), { recursive: true });
+  fs22.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
 }
 function loadDashboardState() {
   try {
-    const raw = fs19.readFileSync(STATE_PATH, "utf-8");
+    const raw = fs22.readFileSync(STATE_PATH, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -32474,7 +33440,7 @@ function loadDashboardState() {
 }
 function clearDashboardState() {
   try {
-    fs19.unlinkSync(STATE_PATH);
+    fs22.unlinkSync(STATE_PATH);
   } catch {
   }
 }
@@ -32492,19 +33458,19 @@ function isDashboardRunning() {
 }
 
 // ../core/dist/dashboard/tunnel.js
-import { spawn, execSync as execSync5 } from "node:child_process";
+import { spawn as spawn2, execSync as execSync6 } from "node:child_process";
 var tunnelProcess = null;
 function isCloudflaredAvailable() {
   try {
-    execSync5("which cloudflared", { stdio: "ignore" });
+    execSync6("which cloudflared", { stdio: "ignore" });
     return true;
   } catch {
     return false;
   }
 }
 function startTunnel(port) {
-  return new Promise((resolve6, reject2) => {
-    const child = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
+  return new Promise((resolve8, reject2) => {
+    const child = spawn2("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
       stdio: ["ignore", "pipe", "pipe"],
       detached: false
     });
@@ -32525,7 +33491,7 @@ function startTunnel(port) {
       if (match) {
         resolved = true;
         clearTimeout(timeout);
-        resolve6(match[0]);
+        resolve8(match[0]);
       }
     }
     child.stdout?.on("data", scan);
@@ -32593,8 +33559,8 @@ var DashboardManager = class {
       }
       throw err;
     }
-    await new Promise((resolve6, reject2) => {
-      this.server.on("listening", resolve6);
+    await new Promise((resolve8, reject2) => {
+      this.server.on("listening", resolve8);
       this.server.on("error", reject2);
     });
     this.info = { localUrl: `http://localhost:${port}` };
@@ -32640,8 +33606,8 @@ var DashboardManager = class {
   async stop() {
     stopTunnel();
     if (this.server) {
-      await new Promise((resolve6) => {
-        this.server.close(() => resolve6());
+      await new Promise((resolve8) => {
+        this.server.close(() => resolve8());
       });
       this.server = null;
     }
@@ -32754,8 +33720,8 @@ var PleriClient = class {
 };
 
 // ../mcp-server/src/env-loader.ts
-import { readFileSync as readFileSync15, existsSync as existsSync19, statSync as statSync6 } from "node:fs";
-import { join as join25, dirname as dirname13, resolve as resolve5 } from "node:path";
+import { readFileSync as readFileSync16, existsSync as existsSync21, statSync as statSync7 } from "node:fs";
+import { join as join27, dirname as dirname15, resolve as resolve7 } from "node:path";
 var PROJECT_MARKERS = [
   ".olam/config.yaml",
   ".olam/config.yml",
@@ -32763,30 +33729,30 @@ var PROJECT_MARKERS = [
   "olam.yml"
 ];
 function findProjectRoot2(startDir) {
-  let dir = resolve5(startDir);
-  const root = resolve5("/");
+  let dir = resolve7(startDir);
+  const root = resolve7("/");
   while (true) {
     for (const marker of PROJECT_MARKERS) {
-      if (existsSync19(join25(dir, marker))) return dir;
+      if (existsSync21(join27(dir, marker))) return dir;
     }
-    const pkg = join25(dir, "package.json");
-    if (existsSync19(pkg)) {
+    const pkg = join27(dir, "package.json");
+    if (existsSync21(pkg)) {
       try {
-        const json = JSON.parse(readFileSync15(pkg, "utf8"));
+        const json = JSON.parse(readFileSync16(pkg, "utf8"));
         const isOlamWorkspace = typeof json.name === "string" && json.name.startsWith("@olam/");
         const hasOlamDep = json.dependencies && Object.keys(json.dependencies).some((k) => k.startsWith("@olam/")) || json.devDependencies && Object.keys(json.devDependencies).some((k) => k.startsWith("@olam/"));
         if (isOlamWorkspace || hasOlamDep) return dir;
       } catch {
       }
     }
-    const parent = dirname13(dir);
+    const parent = dirname15(dir);
     if (parent === dir || parent === root) return null;
     dir = parent;
   }
 }
-function parseEnvFile(path24) {
+function parseEnvFile(path27) {
   const out = {};
-  const raw = readFileSync15(path24, "utf8");
+  const raw = readFileSync16(path27, "utf8");
   for (const line of raw.split(/\r?\n/)) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith("#")) continue;
@@ -32809,8 +33775,8 @@ function loadProjectEnv(startDir = process.cwd()) {
   const filesRead = [];
   const merged = {};
   for (const name of [".env", ".env.local"]) {
-    const p = join25(root, name);
-    if (existsSync19(p) && statSync6(p).isFile()) {
+    const p = join27(root, name);
+    if (existsSync21(p) && statSync7(p).isFile()) {
       Object.assign(merged, parseEnvFile(p));
       filesRead.push(p);
     }
@@ -32880,7 +33846,7 @@ async function main() {
     initError = err instanceof Error ? err : new Error(String(err));
     logger.error("Failed to initialize Olam", { error: initError.message });
   }
-  const server = createServer3(ctx, initError);
+  const server = createServer4(ctx, initError);
   const transport = new StdioServerTransport();
   await server.connect(transport);
   logger.info("Olam MCP server running on stdio transport");