@pleri/olam-cli 0.1.110 → 0.1.112

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,MAAM,CAAC;KACZ,WAAW,CAAC,+DAA+D,CAAC;KAC5E,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;AAE7B,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1B,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,mBAAmB,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AAC/D,UAAU,CAAC,OAAO,CAAC,CAAC;AACpB,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,UAAU,CAAC,OAAO,CAAC,CAAC;AACpB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1B,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,WAAW,CAAC,OAAO,CAAC,CAAC;AACrB,UAAU,CAAC,OAAO,CAAC,CAAC;AACpB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAE1B,0EAA0E;AAC1E,6EAA6E;AAC7E,yEAAyE;AACzE,wBAAwB;AAExB,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/lib/shell-rc.d.ts

@@ -0,0 +1,90 @@
+/**
+ * shell-rc.ts — Idempotent shell-rc file append + timestamped backup.
+ *
+ * Phase C1 of olam-operator-onboarding-parity (plan
+ * ~/.claude/plans/olam-operator-onboarding-parity.md).
+ *
+ * Phase C's `olam setup` wizard offers to add
+ *   eval "$(olam completion zsh)"
+ * to the operator's `~/.zshrc` / `~/.bashrc`. This module is the safety
+ * layer that:
+ *
+ *   1. Grep-checks a marker substring before writing — re-running the
+ *      wizard is a no-op (no duplicate eval lines, no n-times appended).
+ *   2. Backs the file up to `<rcPath>.olam-bak.<ISO-timestamp>` before
+ *      ANY mutation — recoverable if the operator decides they didn't
+ *      want the line.
+ *   3. Writes atomically via tmp-file + rename — `kill -9` mid-write
+ *      can't leave a half-written rc file.
+ *
+ * Decision 6 (plan): mirrors adb's `phase_mise_activation` pattern; the
+ * idempotency + backup pair is the operator-UX floor.
+ *
+ * Risk T4 mitigation (per plan + design doc): the grep-for-marker check
+ * uses `String.includes` not a per-line scan — a marker can match across
+ * whitespace if needed. The backup runs unconditionally before the
+ * append; corrupted rc states are recoverable via `mv <backup> <rcPath>`.
+ */
+export type AppendStatus = 'appended' | 'already-present' | 'no-rc-file';
+export interface AppendResult {
+    readonly status: AppendStatus;
+    /** Path to the timestamped backup file. `null` when `status !== 'appended'`. */
+    readonly backupPath: string | null;
+}
+export interface AppendOptions {
+    /** Absolute path to the operator's shell rc (e.g. `/Users/me/.zshrc`). */
+    readonly rcPath: string;
+    /**
+     * Substring searched for in the rc to detect "already present."
+     * Convention: a short stable token (e.g. `olam completion`) — distinct
+     * enough to avoid collisions with unrelated mentions, short enough that
+     * the operator can edit the exact line shape without breaking
+     * idempotency.
+     */
+    readonly marker: string;
+    /**
+     * The exact line to append. The function adds a trailing newline if
+     * not already present + ensures the previous line of the rc file ends
+     * with a newline (so the appended line isn't concatenated onto the
+     * previous line on rcs that don't end with `\n`).
+     */
+    readonly contentLine: string;
+    /**
+     * Optional clock override for deterministic test timestamps. Defaults
+     * to `() => new Date()`.
+     */
+    readonly clock?: () => Date;
+}
+/**
+ * Append `contentLine` to `rcPath` exactly once.
+ *
+ *   - rcPath doesn't exist           → returns `{status: 'no-rc-file', backupPath: null}`
+ *   - rcPath content already includes the marker substring
+ *                                    → returns `{status: 'already-present', backupPath: null}`
+ *   - otherwise: backup + append
+ *                                    → returns `{status: 'appended', backupPath: <ts-path>}`
+ *
+ * The write is atomic: content is staged to `<rcPath>.olam-tmp.<pid>`
+ * and then `renameSync`'d to `rcPath`. POSIX rename is atomic within a
+ * filesystem; a `kill -9` mid-call leaves either the backup-only state
+ * (no rc change) or the renamed-final state (atomic apply), never a
+ * half-written rc.
+ *
+ * The backup path uses a filesystem-safe ISO timestamp with `:` + `.`
+ * replaced by `-` (avoids colons in filenames on Windows for cross-
+ * platform consumers; not strictly required on macOS / Linux but
+ * cosmetically nicer).
+ */
+export declare function appendIdempotent(opts: AppendOptions): AppendResult;
+/**
+ * Resolve the operator's shell rc path based on `$SHELL`.
+ *
+ *   /bin/zsh, /usr/bin/zsh, /opt/homebrew/bin/zsh → ~/.zshrc
+ *   /bin/bash, /usr/bin/bash                     → ~/.bashrc
+ *   anything else                                → null (caller must surface)
+ *
+ * The caller decides what to do on null — typically Phase C surfaces a
+ * remedy message naming the supported shells.
+ */
+export declare function resolveShellRc(home: string, shellEnv: string | undefined): string | null;
+//# sourceMappingURL=shell-rc.d.ts.map

package/dist/lib/shell-rc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-rc.d.ts","sourceRoot":"","sources":["../../src/lib/shell-rc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CA0BlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMxF"}

package/dist/lib/shell-rc.js

@@ -0,0 +1,91 @@
+/**
+ * shell-rc.ts — Idempotent shell-rc file append + timestamped backup.
+ *
+ * Phase C1 of olam-operator-onboarding-parity (plan
+ * ~/.claude/plans/olam-operator-onboarding-parity.md).
+ *
+ * Phase C's `olam setup` wizard offers to add
+ *   eval "$(olam completion zsh)"
+ * to the operator's `~/.zshrc` / `~/.bashrc`. This module is the safety
+ * layer that:
+ *
+ *   1. Grep-checks a marker substring before writing — re-running the
+ *      wizard is a no-op (no duplicate eval lines, no n-times appended).
+ *   2. Backs the file up to `<rcPath>.olam-bak.<ISO-timestamp>` before
+ *      ANY mutation — recoverable if the operator decides they didn't
+ *      want the line.
+ *   3. Writes atomically via tmp-file + rename — `kill -9` mid-write
+ *      can't leave a half-written rc file.
+ *
+ * Decision 6 (plan): mirrors adb's `phase_mise_activation` pattern; the
+ * idempotency + backup pair is the operator-UX floor.
+ *
+ * Risk T4 mitigation (per plan + design doc): the grep-for-marker check
+ * uses `String.includes` not a per-line scan — a marker can match across
+ * whitespace if needed. The backup runs unconditionally before the
+ * append; corrupted rc states are recoverable via `mv <backup> <rcPath>`.
+ */
+import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Append `contentLine` to `rcPath` exactly once.
+ *
+ *   - rcPath doesn't exist           → returns `{status: 'no-rc-file', backupPath: null}`
+ *   - rcPath content already includes the marker substring
+ *                                    → returns `{status: 'already-present', backupPath: null}`
+ *   - otherwise: backup + append
+ *                                    → returns `{status: 'appended', backupPath: <ts-path>}`
+ *
+ * The write is atomic: content is staged to `<rcPath>.olam-tmp.<pid>`
+ * and then `renameSync`'d to `rcPath`. POSIX rename is atomic within a
+ * filesystem; a `kill -9` mid-call leaves either the backup-only state
+ * (no rc change) or the renamed-final state (atomic apply), never a
+ * half-written rc.
+ *
+ * The backup path uses a filesystem-safe ISO timestamp with `:` + `.`
+ * replaced by `-` (avoids colons in filenames on Windows for cross-
+ * platform consumers; not strictly required on macOS / Linux but
+ * cosmetically nicer).
+ */
+export function appendIdempotent(opts) {
+    const { rcPath, marker, contentLine, clock = () => new Date() } = opts;
+    if (!existsSync(rcPath)) {
+        return { status: 'no-rc-file', backupPath: null };
+    }
+    const content = readFileSync(rcPath, 'utf-8');
+    if (content.includes(marker)) {
+        return { status: 'already-present', backupPath: null };
+    }
+    const timestamp = clock().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${rcPath}.olam-bak.${timestamp}`;
+    copyFileSync(rcPath, backupPath);
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    const trailing = contentLine.endsWith('\n') ? '' : '\n';
+    const nextContent = `${content}${separator}${contentLine}${trailing}`;
+    // Atomic write: tmp + rename. POSIX rename is atomic within filesystem.
+    const tmpPath = `${rcPath}.olam-tmp.${process.pid}`;
+    writeFileSync(tmpPath, nextContent, { encoding: 'utf-8' });
+    renameSync(tmpPath, rcPath);
+    return { status: 'appended', backupPath };
+}
+/**
+ * Resolve the operator's shell rc path based on `$SHELL`.
+ *
+ *   /bin/zsh, /usr/bin/zsh, /opt/homebrew/bin/zsh → ~/.zshrc
+ *   /bin/bash, /usr/bin/bash                     → ~/.bashrc
+ *   anything else                                → null (caller must surface)
+ *
+ * The caller decides what to do on null — typically Phase C surfaces a
+ * remedy message naming the supported shells.
+ */
+export function resolveShellRc(home, shellEnv) {
+    if (!shellEnv)
+        return null;
+    const basename = path.basename(shellEnv);
+    if (basename === 'zsh')
+        return path.join(home, '.zshrc');
+    if (basename === 'bash')
+        return path.join(home, '.bashrc');
+    return null;
+}
+//# sourceMappingURL=shell-rc.js.map

package/dist/lib/shell-rc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-rc.js","sourceRoot":"","sources":["../../src/lib/shell-rc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,IAAI,MAAM,WAAW,CAAC;AAmC7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAmB;IAClD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC;IAEvE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,GAAG,MAAM,aAAa,SAAS,EAAE,CAAC;IACrD,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEjC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,MAAM,WAAW,GAAG,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,EAAE,CAAC;IAEtE,wEAAwE;IACxE,MAAM,OAAO,GAAG,GAAG,MAAM,aAAa,OAAO,CAAC,GAAG,EAAE,CAAC;IACpD,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE5B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAA4B;IACvE,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzD,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/mcp-server.js

@@ -22986,6 +22986,92 @@ var removeNetwork = async (docker, worldId) => {
   }
 };
 
+// ../adapters/dist/docker/pull.js
+import { spawn } from "node:child_process";
+var realDocker = {
+  async info() {
+    return spawnAsync("docker", ["info"]);
+  },
+  async pull(imageRef, opts) {
+    const args = ["pull"];
+    if (opts?.platform)
+      args.push(`--platform=${opts.platform}`);
+    args.push(imageRef);
+    return spawnAsync("docker", args, { signal: opts?.signal });
+  },
+  async inspectLabel(imageRef, label) {
+    return spawnAsync("docker", [
+      "inspect",
+      imageRef,
+      "--format",
+      `{{ index .Config.Labels "${label}" }}`
+    ]);
+  },
+  async tag(source, target) {
+    return spawnAsync("docker", ["tag", source, target]);
+  }
+};
+function spawnAsync(cmd, args, opts = {}) {
+  return new Promise((resolve8) => {
+    const child = spawn(cmd, [...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      signal: opts.signal
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve8({ exitCode: -1, stdout, stderr: stderr + err.message });
+    });
+    child.on("close", (code) => {
+      resolve8({ exitCode: code ?? -1, stdout, stderr });
+    });
+  });
+}
+var inflightPulls = /* @__PURE__ */ new Map();
+var DEFAULT_PULL_POLICY = {
+  perAttemptTimeoutMs: 18e4,
+  retryOnce: true
+};
+function isTransientPullFailure(result) {
+  const s = result.stderr.toLowerCase();
+  return result.exitCode !== 0 && (/timeout|connection|temporarily|429|503|tls handshake|network/.test(s) || result.exitCode === 124 || result.exitCode === -1);
+}
+async function pullImageWithRetry(imageRef, docker = realDocker, policy = DEFAULT_PULL_POLICY) {
+  const key = policy.platform ? `${imageRef}@@${policy.platform}` : imageRef;
+  const existing = inflightPulls.get(key);
+  if (existing)
+    return existing;
+  const promise = (async () => {
+    let result = await pullOnce(imageRef, docker, policy.perAttemptTimeoutMs, policy.platform);
+    if (result.exitCode !== 0 && policy.retryOnce && isTransientPullFailure(result)) {
+      result = await pullOnce(imageRef, docker, policy.perAttemptTimeoutMs, policy.platform);
+    }
+    return result;
+  })();
+  inflightPulls.set(key, promise);
+  try {
+    return await promise;
+  } finally {
+    inflightPulls.delete(key);
+  }
+}
+async function pullOnce(imageRef, docker, timeoutMs, platform) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs).unref?.();
+  try {
+    return await docker.pull(imageRef, { signal: ac.signal, ...platform ? { platform } : {} });
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+}
+
 // ../adapters/dist/docker/volume.js
 var volumeName = (worldId, serviceName) => `olam-${worldId}-${serviceName}-data`;
 var createVolume = async (docker, worldId, worldName, serviceName) => {
@@ -22998,6 +23084,7 @@ var createVolume = async (docker, worldId, worldName, serviceName) => {
 };
 
 // ../adapters/dist/docker/container.js
+var realPullImage = (imageRef, platform) => pullImageWithRetry(imageRef, void 0, platform ? { perAttemptTimeoutMs: 18e4, retryOnce: true, platform } : { perAttemptTimeoutMs: 18e4, retryOnce: true });
 function readAuthSecret() {
   const fromEnv = process.env["OLAM_AUTH_SECRET"];
   if (fromEnv && fromEnv.length > 0)
@@ -23048,10 +23135,15 @@ function buildPackageManagerCacheBinds(homeDir) {
   }
   return result;
 }
-var createServiceContainer = async (docker, worldId, worldName, service, portOffset) => {
+var createServiceContainer = async (docker, worldId, worldName, service, portOffset, pullImage = realPullImage) => {
   const labels = olamLabels(worldId, worldName);
   const hostPort = service.port + portOffset;
   const envList = service.environment ? Object.entries(service.environment).map(([k, v]) => `${k}=${v}`) : [];
+  const pullResult = await pullImage(service.image, service.platform);
+  if (pullResult.exitCode !== 0) {
+    const reason = pullResult.stderr.trim() || `exit ${pullResult.exitCode}`;
+    throw new Error(`failed to pull ${service.image}${service.platform ? ` (platform=${service.platform})` : ""}: ${reason}`);
+  }
   const container = await docker.createContainer({
     name: serviceContainerName(worldId, service.name),
     Image: service.image,
@@ -23413,10 +23505,18 @@ var DockerProvider = class extends ComputeProvider {
   };
   docker;
   dockerOptions;
-  constructor(dockerOptions) {
+  /**
+   * Injectable image-pull helper. Defaults to the real
+   * `pullImageWithRetry` (docker CLI shell-out). Tests override with a
+   * no-op so they don't need a real Docker daemon to exercise the
+   * dockerode-mocked code paths.
+   */
+  pullImage;
+  constructor(dockerOptions, opts) {
     super();
     this.docker = new Dockerode(dockerOptions);
     this.dockerOptions = dockerOptions;
+    this.pullImage = opts?.pullImage;
   }
   // -----------------------------------------------------------------------
   // createWorld
@@ -23435,7 +23535,7 @@ var DockerProvider = class extends ComputeProvider {
       await createVolume(this.docker, id, name, svc.name);
     }
     for (const svc of services) {
-      await createServiceContainer(this.docker, id, name, svc, portOffset);
+      await createServiceContainer(this.docker, id, name, svc, portOffset, this.pullImage);
     }
     const SERVICE_ENV_ALIASES = {
       postgres: "POSTGRESQL",
@@ -30609,7 +30709,7 @@ import * as crypto4 from "node:crypto";
 import * as fs17 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 { execFileSync as execFileSync4, spawn as spawn2 } from "node:child_process";
 import { gunzipSync } from "node:zlib";
 function snapshotsDir() {
   return process.env["OLAM_SNAPSHOTS_DIR"] ?? path19.join(os11.homedir(), ".olam", "snapshots");
@@ -30972,7 +31072,7 @@ function spawnAutoCapture(worldId, olamBin = "olam") {
   if (!/^[a-zA-Z0-9_\-.]+$/.test(worldId))
     return null;
   try {
-    const child = spawn(olamBin, ["world", "snapshot", "create", worldId, "--kind", "all"], {
+    const child = spawn2(olamBin, ["world", "snapshot", "create", worldId, "--kind", "all"], {
       detached: true,
       stdio: "ignore",
       // OLAM_INTERNAL_SNAPSHOT=1 sentinel — Phase D D1's deprecation
@@ -33678,7 +33778,7 @@ function isDashboardRunning() {
 }
 
 // ../core/dist/dashboard/tunnel.js
-import { spawn as spawn2, execSync as execSync6 } from "node:child_process";
+import { spawn as spawn3, execSync as execSync6 } from "node:child_process";
 var tunnelProcess = null;
 function isCloudflaredAvailable() {
   try {
@@ -33690,7 +33790,7 @@ function isCloudflaredAvailable() {
 }
 function startTunnel(port) {
   return new Promise((resolve8, reject2) => {
-    const child = spawn2("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
+    const child = spawn3("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
       stdio: ["ignore", "pipe", "pipe"],
       detached: false
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.110",
+  "version": "0.1.112",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"