@pushpalsdev/cli 1.0.18 → 1.0.20

package/dist/pushpals-cli.js

@@ -101,7 +101,6 @@ function normalizeLoopbackHttpUrl(value, fallbackPort) {
 // ../shared/src/config.ts
 var PROJECT_ROOT = resolve(import.meta.dir, "..", "..", "..");
 var DEFAULT_CONFIG_DIR = "configs";
-var LEGACY_CONFIG_DIR = "config";
 var TRUTHY = new Set(["1", "true", "yes", "on"]);
 var FALSY = new Set(["0", "false", "no", "off"]);
 var DEFAULT_WORKERPALS_QUALITY_CRITIC_MIN_SCORE = 8;
@@ -114,6 +113,7 @@ var DEFAULT_WORKERPALS_QUALITY_VALIDATION_STEP_TIMEOUT_MS = 180000;
 var DEFAULT_WORKERPALS_QUALITY_CRITIC_TIMEOUT_MS = 45000;
 var DEFAULT_WORKERPALS_QUALITY_CRITIC_MAX_DIFF_CHARS = 16000;
 var DEFAULT_WORKERPALS_QUALITY_CRITIC_MAX_VALIDATION_OUTPUT_CHARS = 8000;
+var DEFAULT_WORKERPALS_EXECUTOR = "openai_codex";
 var DEFAULT_WORKERPALS_EXECUTOR_RESULT_PREFIX = "__PUSHPALS_OH_RESULT__ ";
 var DEFAULT_REMOTEBUDDY_MEMORY_MAX_RECALL_ITEMS = 12;
 var DEFAULT_REMOTEBUDDY_MEMORY_MAX_RECALL_CHARS = 2400;
@@ -155,6 +155,12 @@ function parseTomlFile(path) {
     return {};
   return parsed;
 }
+function parseRequiredTomlFile(path) {
+  if (!existsSync(path)) {
+    throw new Error(`Missing required runtime config file: ${path}`);
+  }
+  return parseTomlFile(path);
+}
 function isObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -260,20 +266,7 @@ function resolveRuntimeConfigDir(projectRoot, configuredDir) {
   if (configuredDir && configuredDir.trim()) {
     return resolvePathFromRoot(projectRoot, configuredDir);
   }
-  const canonicalDir = resolvePathFromRoot(projectRoot, DEFAULT_CONFIG_DIR);
-  const legacyDir = resolvePathFromRoot(projectRoot, LEGACY_CONFIG_DIR);
-  if (existsSync(join(canonicalDir, "default.toml")))
-    return canonicalDir;
-  if (existsSync(join(legacyDir, "default.toml")))
-    return legacyDir;
-  return canonicalDir;
-}
-function parseTomlWithLegacyFallback(primaryPath, fallbackPath) {
-  if (existsSync(primaryPath))
-    return parseTomlFile(primaryPath);
-  if (fallbackPath && existsSync(fallbackPath))
-    return parseTomlFile(fallbackPath);
-  return {};
+  return resolvePathFromRoot(projectRoot, DEFAULT_CONFIG_DIR);
 }
 function normalizeBackend(value) {
   const text = value.trim().toLowerCase();
@@ -345,17 +338,15 @@ function loadPushPalsConfig(options = {}) {
   const projectRoot = resolve(projectRootOverride);
   const configDirOverride = firstNonEmpty(options.configDir, process.env.PUSHPALS_CONFIG_DIR_OVERRIDE, "");
   const configDir = resolveRuntimeConfigDir(projectRoot, configDirOverride);
-  const legacyConfigDir = resolvePathFromRoot(projectRoot, LEGACY_CONFIG_DIR);
-  const fallbackConfigDir = !configDirOverride && configDir !== legacyConfigDir ? legacyConfigDir : "";
   const cacheKey = `${projectRoot}::${configDir}::${process.env.PUSHPALS_PROFILE ?? ""}`;
   if (!options.reload && cachedConfig && cachedConfigKey === cacheKey) {
     return cachedConfig;
   }
-  const defaultToml = parseTomlWithLegacyFallback(join(configDir, "default.toml"), fallbackConfigDir ? join(fallbackConfigDir, "default.toml") : undefined);
+  const defaultToml = parseRequiredTomlFile(join(configDir, "default.toml"));
   const preferredProfile = firstNonEmpty(process.env.PUSHPALS_PROFILE, asString(defaultToml.profile, "dev"), "dev");
-  const profileToml = parseTomlWithLegacyFallback(join(configDir, `${preferredProfile}.toml`), fallbackConfigDir ? join(fallbackConfigDir, `${preferredProfile}.toml`) : undefined);
-  const localExampleToml = parseTomlWithLegacyFallback(join(configDir, "local.example.toml"), fallbackConfigDir ? join(fallbackConfigDir, "local.example.toml") : undefined);
-  const localToml = parseTomlWithLegacyFallback(join(configDir, "local.toml"), fallbackConfigDir ? join(fallbackConfigDir, "local.toml") : undefined);
+  const profileToml = parseTomlFile(join(configDir, `${preferredProfile}.toml`));
+  const localExampleToml = parseTomlFile(join(configDir, "local.example.toml"));
+  const localToml = parseTomlFile(join(configDir, "local.toml"));
   const merged = mergeDeep(mergeDeep(mergeDeep(defaultToml, profileToml), localExampleToml), localToml);
   const profile = firstNonEmpty(process.env.PUSHPALS_PROFILE, asString(merged.profile, preferredProfile), preferredProfile);
   const sessionId = firstNonEmpty(process.env.PUSHPALS_SESSION_ID, asString(merged.session_id, "dev"), "dev");
@@ -462,7 +453,7 @@ function loadPushPalsConfig(options = {}) {
   const workerOpenHandsNode = getObject(workerNode, "openhands");
   const workerPollMs = Math.max(200, asInt(parseIntEnv("WORKERPALS_POLL_MS") ?? workerNode.poll_ms, 2000));
   const workerHeartbeatMs = Math.max(200, asInt(parseIntEnv("WORKERPALS_HEARTBEAT_MS") ?? workerNode.heartbeat_ms, 5000));
-  const workerExecutor = firstNonEmpty(process.env.WORKERPALS_EXECUTOR, asString(workerNode.executor, "openhands"), "openhands").toLowerCase();
+  const workerExecutor = firstNonEmpty(process.env.WORKERPALS_EXECUTOR, asString(workerNode.executor, DEFAULT_WORKERPALS_EXECUTOR), DEFAULT_WORKERPALS_EXECUTOR).toLowerCase();
   const workerOpenHandsPython = firstNonEmpty(process.env.WORKERPALS_OPENHANDS_PYTHON, asString(workerNode.openhands_python, "python"), "python");
   const workerOpenHandsTimeoutMs = Math.max(1e4, asInt(parseIntEnv("WORKERPALS_OPENHANDS_TIMEOUT_MS") ?? workerNode.openhands_timeout_ms, 1800000));
   const workerMiniswePython = firstNonEmpty(process.env.WORKERPALS_MINISWE_PYTHON, asString(workerNode.miniswe_python, "python"), "python");
@@ -964,18 +955,10 @@ function resolveClientConfigDir(projectRoot, runtimeRoot, explicitConfigDir) {
   if (runtimeHasConfigDir(runtimeRoot, "configs")) {
     return runtimeCanonical;
   }
-  const runtimeLegacy = resolve2(runtimeRoot, "config");
-  if (runtimeHasConfigDir(runtimeRoot, "config")) {
-    return runtimeLegacy;
-  }
   const projectCanonical = resolve2(projectRoot, "configs");
   if (runtimeHasConfigDir(projectRoot, "configs")) {
     return projectCanonical;
   }
-  const projectLegacy = resolve2(projectRoot, "config");
-  if (runtimeHasConfigDir(projectRoot, "config")) {
-    return projectLegacy;
-  }
   return runtimeCanonical;
 }
 function toDisplayPath(currentRoot, pathValue) {
@@ -1025,8 +1008,7 @@ function evaluateClientRuntimePreflight(options) {
     });
   }
   const localTomlPath = resolve2(runtimeRoot, "configs", "local.toml");
-  const legacyLocalTomlPath = resolve2(runtimeRoot, "config", "local.toml");
-  if (!existsSync2(localTomlPath) && !existsSync2(legacyLocalTomlPath)) {
+  if (!existsSync2(localTomlPath)) {
     const localExamplePath = resolve2(runtimeRoot, "configs", "local.example.toml");
     issues.push({
       code: "missing_local_toml",
@@ -1472,6 +1454,130 @@ function buildRuntimeAssetSource(root, protocolSchemasDir) {
     protocolSchemasDir
   };
 }
+function buildWorkerpalSandboxPaths(runtimeRoot) {
+  const root = join2(runtimeRoot, "sandbox");
+  return {
+    root,
+    dockerfilePath: join2(root, "apps", "workerpals", "Dockerfile.sandbox"),
+    packageJsonPath: join2(root, "package.json"),
+    workerpalsDir: join2(root, "apps", "workerpals"),
+    sharedDir: join2(root, "packages", "shared"),
+    protocolDir: join2(root, "packages", "protocol"),
+    configsDir: join2(root, "configs"),
+    workerpalsPromptsDir: join2(root, "prompts", "workerpals"),
+    protocolSchemasDir: join2(root, "protocol", "schemas")
+  };
+}
+function normalizeGitTrackedPath(pathValue) {
+  return String(pathValue ?? "").trim().replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+function listTrackedRepoFilesForPath(repoRoot, sourcePath) {
+  const normalizedSource = normalizeGitTrackedPath(sourcePath);
+  if (!normalizedSource)
+    return [];
+  const proc = Bun.spawnSync(["git", "ls-files", "-z", "--", normalizedSource], {
+    cwd: repoRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: "0",
+      GCM_INTERACTIVE: "Never"
+    }
+  });
+  if (proc.exitCode !== 0) {
+    const stderr = Buffer.from(proc.stderr ?? []).toString("utf8").trim();
+    throw new Error(`git ls-files failed for ${normalizedSource}${stderr ? `: ${stderr}` : ""}`);
+  }
+  return Buffer.from(proc.stdout ?? []).toString("utf8").split("\x00").map(normalizeGitTrackedPath).filter(Boolean);
+}
+function copyTrackedRepoPath(repoRoot, sourcePath, destinationPath, force = true) {
+  const normalizedSource = normalizeGitTrackedPath(sourcePath);
+  if (!normalizedSource) {
+    throw new Error("sourcePath is required");
+  }
+  const absoluteSource = resolve4(repoRoot, normalizedSource);
+  if (!existsSync4(absoluteSource)) {
+    throw new Error(`tracked repo source is missing: ${absoluteSource}`);
+  }
+  const trackedFiles = listTrackedRepoFilesForPath(repoRoot, normalizedSource);
+  const sourceStat = lstatSync(absoluteSource);
+  if (!sourceStat.isDirectory()) {
+    if (!trackedFiles.includes(normalizedSource)) {
+      throw new Error(`tracked repo file is not tracked by git: ${normalizedSource}`);
+    }
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    cpSync(absoluteSource, destinationPath, {
+      recursive: false,
+      force,
+      errorOnExist: false
+    });
+    return;
+  }
+  if (trackedFiles.length === 0) {
+    throw new Error(`tracked repo directory has no tracked files: ${normalizedSource}`);
+  }
+  for (const trackedFile of trackedFiles) {
+    const relativePath = trackedFile === normalizedSource ? basename(trackedFile) : trackedFile.slice(normalizedSource.length + 1);
+    const sourceFile = resolve4(repoRoot, trackedFile);
+    const targetFile = join2(destinationPath, relativePath);
+    mkdirSync(dirname(targetFile), { recursive: true });
+    cpSync(sourceFile, targetFile, {
+      recursive: false,
+      force,
+      errorOnExist: false
+    });
+  }
+}
+function isCompleteWorkerpalSandboxRoot(root) {
+  return existsSync4(join2(root, "package.json")) && existsSync4(join2(root, "apps", "workerpals", "Dockerfile.sandbox")) && existsSync4(join2(root, "packages", "shared", "package.json")) && existsSync4(join2(root, "packages", "protocol", "package.json")) && existsSync4(join2(root, "configs", "default.toml")) && existsSync4(join2(root, "prompts", "workerpals")) && existsSync4(join2(root, "protocol", "schemas", "envelope.schema.json")) && existsSync4(join2(root, "protocol", "schemas", "events.schema.json"));
+}
+function populateWorkerpalSandboxRuntimeAssets(runtimeRoot, force) {
+  const sandbox = buildWorkerpalSandboxPaths(runtimeRoot);
+  cpSync(join2(runtimeRoot, "configs"), sandbox.configsDir, {
+    recursive: true,
+    force,
+    errorOnExist: false
+  });
+  cpSync(join2(runtimeRoot, "prompts", "workerpals"), sandbox.workerpalsPromptsDir, {
+    recursive: true,
+    force,
+    errorOnExist: false
+  });
+  cpSync(join2(runtimeRoot, "protocol", "schemas"), sandbox.protocolSchemasDir, {
+    recursive: true,
+    force,
+    errorOnExist: false
+  });
+}
+function copySourceCheckoutWorkerpalSandboxBuildContext(sourceRoot, runtimeRoot, force) {
+  const sandbox = buildWorkerpalSandboxPaths(runtimeRoot);
+  const copyPairs = [
+    ["package.json", sandbox.packageJsonPath],
+    ["apps/workerpals", sandbox.workerpalsDir],
+    ["packages/shared", sandbox.sharedDir],
+    ["packages/protocol", sandbox.protocolDir]
+  ];
+  for (const [fromPath, toPath] of copyPairs) {
+    copyTrackedRepoPath(sourceRoot, fromPath, toPath, force);
+  }
+  if (existsSync4(join2(sourceRoot, "bun.lock"))) {
+    copyTrackedRepoPath(sourceRoot, "bun.lock", join2(sandbox.root, "bun.lock"), force);
+  }
+  populateWorkerpalSandboxRuntimeAssets(runtimeRoot, force);
+}
+function copyWorkerpalSandboxBuildContext(source, runtimeRoot, force) {
+  const packagedSandboxRoot = join2(source.root, "sandbox");
+  if (isCompleteWorkerpalSandboxRoot(packagedSandboxRoot)) {
+    cpSync(packagedSandboxRoot, join2(runtimeRoot, "sandbox"), {
+      recursive: true,
+      force,
+      errorOnExist: false
+    });
+    return;
+  }
+  copySourceCheckoutWorkerpalSandboxBuildContext(source.root, runtimeRoot, force);
+}
 function isCompleteRuntimeAssetSource(source) {
   return existsSync4(source.envExamplePath) && existsSync4(source.visionExamplePath) && existsSync4(join2(source.configsDir, "default.toml")) && existsSync4(source.promptsDir) && existsSync4(join2(source.protocolSchemasDir, "envelope.schema.json")) && existsSync4(join2(source.protocolSchemasDir, "events.schema.json"));
 }
@@ -1658,6 +1764,7 @@ function copyRuntimeAssetBundle(source, runtimeRoot, force) {
     force,
     errorOnExist: false
   });
+  copyWorkerpalSandboxBuildContext(source, runtimeRoot, force);
 }
 function copyBundledRuntimeAssets(runtimeRoot, force = true) {
   const bundledSource = resolveBundledRuntimeAssetSource();
@@ -1693,7 +1800,7 @@ async function downloadRuntimeAssetsFromSourceTag(runtimeRoot, tag) {
     throw new Error(`Failed to fetch runtime source tree for ${tag} (HTTP ${treeResponse.status})`);
   }
   const treePayload = await treeResponse.json();
-  const paths = (treePayload.tree ?? []).filter((entry) => entry.type === "blob" && typeof entry.path === "string").map((entry) => String(entry.path)).filter((pathValue) => pathValue === ".env.example" || pathValue === "vision.example.md" || pathValue.startsWith("configs/") || pathValue.startsWith("prompts/") || pathValue.startsWith("packages/protocol/src/schemas/"));
+  const paths = (treePayload.tree ?? []).filter((entry) => entry.type === "blob" && typeof entry.path === "string").map((entry) => String(entry.path)).filter((pathValue) => pathValue === ".env.example" || pathValue === "vision.example.md" || pathValue === "package.json" || pathValue === "bun.lock" || pathValue.startsWith("configs/") || pathValue.startsWith("prompts/workerpals/") || pathValue.startsWith("prompts/") || pathValue.startsWith("apps/workerpals/") || pathValue.startsWith("packages/shared/") || pathValue.startsWith("packages/protocol/") || pathValue.startsWith("packages/protocol/src/schemas/"));
   if (paths.length === 0) {
     throw new Error(`Runtime source tree for ${tag} did not include prompts/config assets`);
   }
@@ -1701,10 +1808,16 @@ async function downloadRuntimeAssetsFromSourceTag(runtimeRoot, tag) {
   for (const pathValue of sorted) {
     const rawUrl = `https://raw.githubusercontent.com/${GITHUB_OWNER}/${GITHUB_REPO}/${encodeURIComponent(tag)}/${pathValue}`;
     const body = await fetchTextFromUrl(rawUrl, 20000);
-    const outPath = pathValue.startsWith("packages/protocol/src/schemas/") ? join2(runtimeRoot, "protocol", "schemas", pathValue.slice("packages/protocol/src/schemas/".length)) : join2(runtimeRoot, pathValue);
+    const outPath = pathValue === "package.json" || pathValue === "bun.lock" ? join2(runtimeRoot, "sandbox", pathValue) : pathValue.startsWith("apps/workerpals/") || pathValue.startsWith("packages/shared/") || pathValue.startsWith("packages/protocol/") ? join2(runtimeRoot, "sandbox", pathValue) : join2(runtimeRoot, pathValue);
     mkdirSync(dirname(outPath), { recursive: true });
     writeFileSync(outPath, body, "utf8");
+    if (pathValue.startsWith("packages/protocol/src/schemas/")) {
+      const runtimeSchemaPath = join2(runtimeRoot, "protocol", "schemas", pathValue.slice("packages/protocol/src/schemas/".length));
+      mkdirSync(dirname(runtimeSchemaPath), { recursive: true });
+      writeFileSync(runtimeSchemaPath, body, "utf8");
+    }
   }
+  populateWorkerpalSandboxRuntimeAssets(runtimeRoot, true);
 }
 async function ensureRuntimeAssets(runtimeRoot, runtimeTag) {
   console.log(`[pushpals] Preparing embedded runtime assets for ${runtimeTag}...`);
@@ -1712,12 +1825,12 @@ async function ensureRuntimeAssets(runtimeRoot, runtimeTag) {
   const currentTag = existsSync4(markerPath) ? readFileSync4(markerPath, "utf8").trim() : "";
   const protocolSchemasDir = join2(runtimeRoot, "protocol", "schemas");
   const hasProtocolSchemas = existsSync4(join2(protocolSchemasDir, "envelope.schema.json")) && existsSync4(join2(protocolSchemasDir, "events.schema.json"));
-  const hasAssets = existsSync4(join2(runtimeRoot, ".env.example")) && existsSync4(join2(runtimeRoot, "vision.example.md")) && existsSync4(join2(runtimeRoot, "configs", "default.toml")) && existsSync4(join2(runtimeRoot, "prompts")) && hasProtocolSchemas;
+  const hasAssets = existsSync4(join2(runtimeRoot, ".env.example")) && existsSync4(join2(runtimeRoot, "vision.example.md")) && existsSync4(join2(runtimeRoot, "configs", "default.toml")) && existsSync4(join2(runtimeRoot, "prompts")) && hasProtocolSchemas && isCompleteWorkerpalSandboxRoot(join2(runtimeRoot, "sandbox"));
   if (!hasAssets || currentTag !== runtimeTag) {
     console.log(`[pushpals] Embedded runtime assets ${hasAssets ? "are stale" : "are missing"}; refreshing bundle...`);
     copyBundledRuntimeAssets(runtimeRoot);
     const hasProtocolSchemasAfterCopy = existsSync4(join2(protocolSchemasDir, "envelope.schema.json")) && existsSync4(join2(protocolSchemasDir, "events.schema.json"));
-    const hasAssetsAfterCopy = existsSync4(join2(runtimeRoot, ".env.example")) && existsSync4(join2(runtimeRoot, "vision.example.md")) && existsSync4(join2(runtimeRoot, "configs", "default.toml")) && existsSync4(join2(runtimeRoot, "prompts")) && hasProtocolSchemasAfterCopy;
+    const hasAssetsAfterCopy = existsSync4(join2(runtimeRoot, ".env.example")) && existsSync4(join2(runtimeRoot, "vision.example.md")) && existsSync4(join2(runtimeRoot, "configs", "default.toml")) && existsSync4(join2(runtimeRoot, "prompts")) && hasProtocolSchemasAfterCopy && isCompleteWorkerpalSandboxRoot(join2(runtimeRoot, "sandbox"));
     if (!hasAssetsAfterCopy) {
       console.log("[pushpals] Bundled runtime assets are incomplete; falling back to release source downloads...");
       await downloadRuntimeAssetsFromSourceTag(runtimeRoot, runtimeTag);
@@ -1787,7 +1900,9 @@ function buildEmbeddedRuntimeEnv(baseEnv, opts) {
     PUSHPALS_PROJECT_ROOT_OVERRIDE: opts.repoRoot,
     ...useRuntimeConfig ? {
       PUSHPALS_CONFIG_DIR_OVERRIDE: join2(opts.runtimeRoot, "configs"),
-      PUSHPALS_PROMPTS_ROOT_OVERRIDE: opts.runtimeRoot
+      PUSHPALS_PROMPTS_ROOT_OVERRIDE: opts.runtimeRoot,
+      PUSHPALS_WORKERPALS_SANDBOX_ROOT: join2(opts.runtimeRoot, "sandbox"),
+      ...typeof opts.runtimeTag === "string" && opts.runtimeTag.trim() ? { PUSHPALS_RUNTIME_TAG: opts.runtimeTag.trim() } : {}
     } : {
       PUSHPALS_PROMPTS_ROOT_OVERRIDE: opts.repoRoot
     },
@@ -2263,6 +2378,116 @@ async function resolveWorkerpalDockerProbe(cwd, env, platform = process.platform
     detail: failures.join(" | ") || "docker"
   };
 }
+var WORKERPAL_SANDBOX_RUNTIME_TAG_LABEL = "pushpals.runtime_tag";
+var WORKERPAL_SANDBOX_COMPONENT_LABEL = "pushpals.component=workerpals-sandbox";
+function resolveConfiguredDockerExecutable(env, platform = process.platform) {
+  const configured = String(env.PUSHPALS_DOCKER_BIN_ABSOLUTE ?? env.PUSHPALS_DOCKER_BIN ?? (platform === "win32" ? "docker.exe" : "docker")).trim();
+  return configured || (platform === "win32" ? "docker.exe" : "docker");
+}
+async function inspectDockerImageRuntimeTag(dockerExecutable, imageName, cwd, env) {
+  const inspect = await runCommandWithEnv([
+    dockerExecutable,
+    "image",
+    "inspect",
+    "--format",
+    `{{ index .Config.Labels "${WORKERPAL_SANDBOX_RUNTIME_TAG_LABEL}" }}`,
+    imageName
+  ], cwd, env);
+  if (!inspect.ok)
+    return "";
+  const value = inspect.stdout.trim();
+  return value === "<no value>" ? "" : value;
+}
+async function ensureWorkerpalDockerImageReady(opts) {
+  const runtimeTag = String(opts.runtimeTag ?? "").trim();
+  if (!runtimeTag) {
+    return {
+      ok: false,
+      detail: "embedded runtime tag is required to prepare the WorkerPal sandbox image"
+    };
+  }
+  await (opts.ensureRuntimeAssetsFn ?? ensureRuntimeAssets)(opts.runtimeRoot, runtimeTag);
+  const sandbox = buildWorkerpalSandboxPaths(opts.runtimeRoot);
+  if (!isCompleteWorkerpalSandboxRoot(sandbox.root)) {
+    return {
+      ok: false,
+      detail: `embedded WorkerPal sandbox assets are incomplete at ${sandbox.root}`
+    };
+  }
+  const dockerExecutable = resolveConfiguredDockerExecutable(opts.env, opts.platform ?? process.platform);
+  const inspectImageRuntimeTagFn = opts.inspectImageRuntimeTagFn ?? inspectDockerImageRuntimeTag;
+  const runCommandWithEnvFn = opts.runCommandWithEnvFn ?? runCommandWithEnv;
+  const existingRuntimeTag = await inspectImageRuntimeTagFn(dockerExecutable, opts.dockerImage, sandbox.root, opts.env);
+  if (existingRuntimeTag === runtimeTag) {
+    return {
+      ok: true,
+      detail: `WorkerPal sandbox image is ready locally (${opts.dockerImage}, runtimeTag=${runtimeTag})`
+    };
+  }
+  console.log(existingRuntimeTag ? `[pushpals] WorkerPal sandbox image ${opts.dockerImage} is stale (runtimeTag=${existingRuntimeTag}); rebuilding locally...` : `[pushpals] WorkerPal sandbox image ${opts.dockerImage} is missing; building locally...`);
+  const build = await runCommandWithEnvFn([
+    dockerExecutable,
+    "build",
+    "-f",
+    "apps/workerpals/Dockerfile.sandbox",
+    "--label",
+    `${WORKERPAL_SANDBOX_RUNTIME_TAG_LABEL}=${runtimeTag}`,
+    "--label",
+    WORKERPAL_SANDBOX_COMPONENT_LABEL,
+    "-t",
+    opts.dockerImage,
+    "."
+  ], sandbox.root, opts.env);
+  if (!build.ok) {
+    const detail = build.stderr || build.stdout || `docker build exited ${build.exitCode}`;
+    return {
+      ok: false,
+      detail: `failed to build local WorkerPal sandbox image ${opts.dockerImage}: ${detail}`
+    };
+  }
+  return {
+    ok: true,
+    detail: `built local WorkerPal sandbox image ${opts.dockerImage} for runtimeTag=${runtimeTag}`
+  };
+}
+async function prepareEmbeddedWorkerpalDockerImageIfNeeded(opts) {
+  if (!opts.preparedRuntime.preflightUsesEmbeddedRuntime) {
+    return {
+      status: "skipped",
+      detail: "repo is using source-checkout runtime assets",
+      runtimeTag: ""
+    };
+  }
+  if (!opts.config.remotebuddy.autoSpawnWorkerpals || !opts.config.remotebuddy.workerpalDocker || !opts.config.remotebuddy.workerpalRequireDocker) {
+    return {
+      status: "skipped",
+      detail: "embedded docker-backed WorkerPal auto-spawn is not required",
+      runtimeTag: ""
+    };
+  }
+  if (opts.dockerPrecheck.status === "failed") {
+    return {
+      status: "failed",
+      detail: opts.dockerPrecheck.detail,
+      runtimeTag: ""
+    };
+  }
+  const runtimeTag = opts.preparedRuntime.runtimeTag || String(opts.runtimeTagHint ?? "").trim() || await (opts.resolveRuntimeReleaseTagFn ?? resolveRuntimeReleaseTag)(opts.runtimeTagHint);
+  if (!runtimeTag) {
+    return {
+      status: "failed",
+      detail: "embedded runtime tag is required to prepare the WorkerPal sandbox image",
+      runtimeTag: ""
+    };
+  }
+  const ensureResult = await (opts.ensureWorkerpalDockerImageReadyFn ?? ensureWorkerpalDockerImageReady)({
+    runtimeRoot: opts.preparedRuntime.runtimeRoot,
+    runtimeTag,
+    dockerImage: opts.config.remotebuddy.workerpalImage ?? opts.config.workerpals.dockerImage,
+    env: opts.dockerPrecheck.env
+  });
+  return ensureResult.ok ? { status: "ok", detail: ensureResult.detail, runtimeTag } : { status: "failed", detail: ensureResult.detail, runtimeTag };
+}
 async function precheckSourceControlManagerGitAvailability(opts) {
   const platform = opts.platform ?? process.platform;
   const env = buildEmbeddedRuntimeEnv(opts.baseEnv ?? process.env, {
@@ -2824,7 +3049,8 @@ async function autoStartRuntimeServices(opts) {
     repoRoot: opts.repoRoot,
     runtimeRoot,
     useRuntimeConfig: opts.preparedRuntime.preflightUsesEmbeddedRuntime,
-    sessionId: opts.sessionId
+    sessionId: opts.sessionId,
+    runtimeTag
   });
   runtimeEnv.PUSHPALS_WORKERPALS_BIN = runtimeBinaries.workerpals;
   const preconfiguredRuntimeGitBinary = runtimeEnv.PUSHPALS_GIT_BIN_ABSOLUTE ?? runtimeEnv.PUSHPALS_GIT_BIN;
@@ -3642,6 +3868,7 @@ async function main() {
   };
   let autoStartedServices = [];
   let pushpalsLogPath;
+  let resolvedRuntimeTagForAutoStart = preparedRuntime.runtimeTag || parsed.runtimeTag || "";
   const stopAutoStartedServices = () => {
     if (autoStartedServices.length === 0)
       return;
@@ -3650,17 +3877,32 @@ async function main() {
   };
   let serverHealthy = await probeServer(serverUrl);
   const serverWasAlreadyHealthy = serverHealthy;
+  if (!serverHealthy && workerpalDockerPrecheck.status === "failed") {
+    console.error(`[pushpals] Precheck failed: Docker-backed WorkerPal auto-spawn is required but Docker is unavailable (${workerpalDockerPrecheck.detail}).`);
+    console.error("[pushpals] Precheck failed: start Docker Desktop or the Docker daemon, then retry pushpals.");
+    process.exit(1);
+  }
+  if (workerpalDockerPrecheck.status !== "failed") {
+    const workerpalImagePrecheck = await prepareEmbeddedWorkerpalDockerImageIfNeeded({
+      preparedRuntime,
+      config,
+      dockerPrecheck: workerpalDockerPrecheck,
+      runtimeTagHint: resolvedRuntimeTagForAutoStart || parsed.runtimeTag
+    });
+    if (workerpalImagePrecheck.status === "failed") {
+      console.error(`[pushpals] Precheck failed: ${workerpalImagePrecheck.detail}.`);
+      process.exit(1);
+    }
+    if (workerpalImagePrecheck.runtimeTag) {
+      resolvedRuntimeTagForAutoStart = workerpalImagePrecheck.runtimeTag;
+    }
+  }
   let remoteBuddyConsumerHealth = {
     ok: false,
     detail: `No connected RemoteBuddy session consumer found for session ${sessionId}`
   };
   if (!serverHealthy) {
     if (!parsed.noAutoStart) {
-      if (workerpalDockerPrecheck.status === "failed") {
-        console.error(`[pushpals] Precheck failed: Docker-backed WorkerPal auto-spawn is required but Docker is unavailable (${workerpalDockerPrecheck.detail}).`);
-        console.error("[pushpals] Precheck failed: start Docker Desktop or the Docker daemon, then retry pushpals.");
-        process.exit(1);
-      }
       try {
         const startedRuntime = await autoStartRuntimeServices({
           repoRoot,
@@ -3670,7 +3912,7 @@ async function main() {
           sourceControlManagerPort: config.sourceControlManager.port,
           sourceControlManagerRemote: config.sourceControlManager.remote,
           preparedRuntime,
-          requestedRuntimeTag: parsed.runtimeTag,
+          requestedRuntimeTag: resolvedRuntimeTagForAutoStart || parsed.runtimeTag,
           startLocalBuddy: resolveCliLocalBuddyAutostart(parsed.runtimeOnly, Boolean(config.localbuddy.enabled)),
           baseEnv: workerpalDockerPrecheck.env
         });
@@ -3929,6 +4171,7 @@ export {
   resolveCliLocalBuddyAutostart,
   resolveBundledRuntimeAssetSource,
   resolveBundledMonitoringHubRoot,
+  prepareEmbeddedWorkerpalDockerImageIfNeeded,
   prepareCliRuntime,
   precheckWorkerpalDockerAvailability,
   precheckSourceControlManagerGitAvailability,
@@ -3941,7 +4184,11 @@ export {
   formatSessionEventLine,
   extractRemoteBuddySessionConsumerHealth,
   extractRemoteBuddyAutonomousEngineState,
+  ensureWorkerpalDockerImageReady,
+  downloadRuntimeAssetsFromSourceTag,
+  copyTrackedRepoPath,
   bundledMonitoringHubNeedsRefresh,
+  buildWorkerpalSandboxPaths,
   buildServiceStopCommand,
   buildRuntimeServiceLogPaths,
   buildOpenMonitoringHubCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushpalsdev/cli",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "PushPals terminal CLI for LocalBuddy -> RemoteBuddy orchestration",
   "license": "MIT",
   "repository": {

package/runtime/configs/backend.toml

@@ -1,4 +1,4 @@
-default_backend = "miniswe"
+default_backend = "openai_codex"
 
 [env]
 shared_passthrough = [

package/runtime/configs/default.toml

@@ -118,7 +118,7 @@ max_payload_bytes = 262144
 [workerpals]
 poll_ms = 2000
 heartbeat_ms = 5000
-executor = "miniswe"
+executor = "openai_codex"
 openhands_python = "python"
 openhands_timeout_ms = 1800000
 miniswe_python = "python"

package/runtime/sandbox/apps/workerpals/.python-version

@@ -0,0 +1 @@
+3.12

package/runtime/sandbox/apps/workerpals/Dockerfile.sandbox

@@ -0,0 +1,71 @@
+# PushPals Worker Sandbox Dockerfile
+# This image provides an isolated environment for job execution
+# The entire monorepo is available in the container for job execution
+
+FROM oven/bun:1-debian AS base
+
+# Install git and other essential tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    ca-certificates \
+    openssh-client \
+    grep \
+    jq \
+    ripgrep \
+    fd-find \
+    less \
+    unzip \
+    zip \
+    procps \
+    dnsutils \
+    iputils-ping \
+    python3 \
+    python3-venv \
+    python3-pip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Worker runtime in one shared venv (uv default layout).
+# Keep the venv at /workspace/.venv so all backends use the same Python runtime.
+RUN mkdir -p /workspace \
+    && python3 -m venv /workspace/.venv \
+    && /workspace/.venv/bin/pip install --no-cache-dir --upgrade pip \
+    && /workspace/.venv/bin/pip install --no-cache-dir \
+        openhands-sdk \
+        openhands-agent-server \
+        openhands-workspace \
+        openhands-tools \
+        mini-swe-agent \
+        playwright \
+    && bun add -g @openai/codex \
+    && /workspace/.venv/bin/playwright install --with-deps chromium
+
+ENV PATH="/workspace/.venv/bin:/root/.bun/bin:${PATH}"
+ENV WORKERPALS_OPENHANDS_PYTHON="/workspace/.venv/bin/python"
+ENV WORKERPALS_OPENHANDS_WORKSPACE_PYTHON="/workspace/.venv/bin/python"
+ENV WORKERPALS_MINISWE_PYTHON="/workspace/.venv/bin/python"
+ENV PUSHPALS_OPENAI_CODEX_PYTHON="/workspace/.venv/bin/python"
+
+# Configure git for the worker
+RUN git config --global user.name "PushPals Worker" \
+    && git config --global user.email "worker@pushpals.local" \
+    && git config --global safe.directory '*' \
+    && git config --global core.autocrlf input
+
+# Set up the full monorepo structure
+WORKDIR /workspace
+
+# Copy entire repository (build context should be repo root)
+COPY . .
+
+# Install workspace dependencies (including devDeps needed for protocol build)
+RUN bun install
+
+# Build protocol package (needed by worker)
+RUN cd packages/protocol && bun run build
+
+# Set working directory for job execution
+WORKDIR /workspace
+
+# Default entrypoint runs the job runner with base64-encoded job spec
+ENTRYPOINT ["bun", "run", "/workspace/apps/workerpals/src/job_runner.ts"]

package/runtime/sandbox/apps/workerpals/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "workerpals",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch --no-clear-screen src/workerpals_main.ts",
+    "start": "bun run src/workerpals_main.ts",
+    "build:sandbox": "docker build -f Dockerfile.sandbox -t pushpals-worker-sandbox:latest ../..",
+    "docker:build": "docker build -f Dockerfile.sandbox -t pushpals-worker-sandbox:latest ../..",
+    "docker:build:local": "docker build -f Dockerfile.sandbox -t pushpals-worker-sandbox:local ../..",
+    "docker:run": "docker run --rm -it pushpals-worker-sandbox:latest",
+    "dev:docker": "bun run src/workerpals_main.ts --docker",
+    "workerpals:docker": "bun run src/workerpals_main.ts --docker",
+    "workerpals:docker:local": "bun run src/workerpals_main.ts --docker --docker-image pushpals-worker-sandbox:local"
+  },
+  "dependencies": {
+    "protocol": "workspace:*",
+    "shared": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2",
+    "@types/bun": "latest"
+  },
+  "private": true
+}

package/runtime/sandbox/apps/workerpals/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "workerpals"
+version = "0.1.0"
+description = "Add your description here"
+requires-python = ">=3.12"
+dependencies = [
+    "mini-swe-agent>=2.1.0",
+]