@pushpalsdev/cli 1.0.17 → 1.0.19

package/dist/pushpals-cli.js

@@ -25,6 +25,41 @@ import { relative, resolve as resolve2 } from "path";
 import { existsSync, readFileSync } from "fs";
 import { join, resolve, isAbsolute } from "path";
 
+// ../shared/src/autonomy_policy.ts
+var DRIVE_RE = /^[A-Za-z]:\//;
+var SLASH_RE = /\/+/g;
+function normalizeAutonomyComponentArea(value) {
+  const normalized = normalizeRepoRelativePath(value);
+  if (!normalized)
+    return null;
+  return normalized;
+}
+function normalizeRepoRelativePath(value) {
+  if (typeof value !== "string")
+    return null;
+  let path = value.trim();
+  if (!path)
+    return null;
+  path = path.normalize("NFC").replace(/\\/g, "/");
+  if (path.startsWith("/"))
+    return null;
+  if (DRIVE_RE.test(path))
+    return null;
+  path = path.replace(SLASH_RE, "/");
+  const out = [];
+  for (const rawSegment of path.split("/")) {
+    const segment = rawSegment.trim();
+    if (!segment || segment === ".")
+      continue;
+    if (segment === "..")
+      return null;
+    out.push(segment);
+  }
+  if (out.length === 0)
+    return null;
+  return out.join("/");
+}
+
 // ../shared/src/local_network.ts
 var DEFAULT_LOCAL_LOOPBACK_HOST = "127.0.0.1";
 function isLoopbackHost(hostname) {
@@ -398,14 +433,26 @@ function loadPushPalsConfig(options = {}) {
     "tests/unit": 2
   };
   const remoteAutonomyDispatchByComponentRaw = asStringNumberRecord(remoteAutonomyNode.max_dispatch_per_hour_by_component);
-  const remoteAutonomyDispatchByComponent = {
-    ...remoteAutonomyDispatchByComponentCfg
+  const legacyAutonomyComponentAliasMap = new Map(Object.keys(remoteAutonomyDispatchByComponentCfg).flatMap((key) => {
+    const direct = normalizeAutonomyComponentArea(key);
+    const legacyUnderscore = normalizeAutonomyComponentArea(key.replace(/\//g, "_"));
+    const legacyHyphen = normalizeAutonomyComponentArea(key.replace(/\//g, "-"));
+    return [direct, legacyUnderscore, legacyHyphen].filter((value) => Boolean(value)).map((value) => [value, key]);
+  }));
+  const coerceAutonomyComponentConfigKey = (value) => {
+    const direct = normalizeAutonomyComponentArea(value);
+    const legacyAliasCandidate = normalizeAutonomyComponentArea(value.trim().toLowerCase().replace(/\\/g, "/").replace(/_+/g, "/").replace(/-+/g, "/").replace(/\/+/g, "/"));
+    if (legacyAliasCandidate && legacyAutonomyComponentAliasMap.has(legacyAliasCandidate)) {
+      return legacyAutonomyComponentAliasMap.get(legacyAliasCandidate) ?? legacyAliasCandidate;
+    }
+    return direct;
   };
-  const normalizeAutonomyComponentKey = (value) => value.trim().toLowerCase().replace(/\\/g, "/").replace(/_+/g, "/").replace(/-+/g, "/").replace(/\/+/g, "/");
-  const canonicalComponentByNormalized = new Map(Object.keys(remoteAutonomyDispatchByComponentCfg).map((key) => [normalizeAutonomyComponentKey(key), key]));
+  const remoteAutonomyDispatchByComponent = Object.fromEntries(Object.entries(remoteAutonomyDispatchByComponentCfg).map(([key, value]) => [
+    coerceAutonomyComponentConfigKey(key) ?? key,
+    value
+  ]));
   for (const [rawKey, rawValue] of Object.entries(remoteAutonomyDispatchByComponentRaw)) {
-    const normalized = normalizeAutonomyComponentKey(rawKey);
-    const canonical = canonicalComponentByNormalized.get(normalized);
+    const canonical = coerceAutonomyComponentConfigKey(rawKey);
     if (!canonical)
       continue;
     const parsed = typeof rawValue === "number" ? rawValue : typeof rawValue === "string" ? Number.parseInt(rawValue.trim(), 10) : Number.NaN;
@@ -1369,9 +1416,9 @@ function parsePositiveInt(value, fallback) {
 function jsonHtmlBootstrap(value) {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
-async function runGitWithEnv(args, cwd, env) {
+async function runCommandWithEnv(command, cwd, env) {
   try {
-    const proc = Bun.spawn(["git", ...args], {
+    const proc = Bun.spawn(command, {
       cwd,
       env,
       stdout: "pipe",
@@ -1392,6 +1439,9 @@ async function runGitWithEnv(args, cwd, env) {
     };
   }
 }
+async function runGitWithEnv(args, cwd, env) {
+  return await runCommandWithEnv(["git", ...args], cwd, env);
+}
 async function runGit(args, cwd) {
   return await runGitWithEnv(args, cwd, {
     ...process.env,
@@ -1422,6 +1472,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"));
 }
@@ -1608,6 +1782,7 @@ function copyRuntimeAssetBundle(source, runtimeRoot, force) {
     force,
     errorOnExist: false
   });
+  copyWorkerpalSandboxBuildContext(source, runtimeRoot, force);
 }
 function copyBundledRuntimeAssets(runtimeRoot, force = true) {
   const bundledSource = resolveBundledRuntimeAssetSource();
@@ -1643,7 +1818,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`);
   }
@@ -1651,10 +1826,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}...`);
@@ -1662,12 +1843,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);
@@ -1737,14 +1918,18 @@ 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
     },
     PUSHPALS_PROTOCOL_SCHEMAS_DIR: join2(opts.runtimeRoot, "protocol", "schemas"),
     ...typeof opts.sessionId === "string" && opts.sessionId.trim() ? { PUSHPALS_SESSION_ID: opts.sessionId.trim() } : {},
     ...typeof env.PUSHPALS_GIT_BIN === "string" && env.PUSHPALS_GIT_BIN.trim() ? { PUSHPALS_GIT_BIN: env.PUSHPALS_GIT_BIN.trim() } : {},
-    ...typeof env.PUSHPALS_GIT_BIN_ABSOLUTE === "string" && env.PUSHPALS_GIT_BIN_ABSOLUTE.trim() ? { PUSHPALS_GIT_BIN_ABSOLUTE: env.PUSHPALS_GIT_BIN_ABSOLUTE.trim() } : {}
+    ...typeof env.PUSHPALS_GIT_BIN_ABSOLUTE === "string" && env.PUSHPALS_GIT_BIN_ABSOLUTE.trim() ? { PUSHPALS_GIT_BIN_ABSOLUTE: env.PUSHPALS_GIT_BIN_ABSOLUTE.trim() } : {},
+    ...typeof env.PUSHPALS_DOCKER_BIN === "string" && env.PUSHPALS_DOCKER_BIN.trim() ? { PUSHPALS_DOCKER_BIN: env.PUSHPALS_DOCKER_BIN.trim() } : {},
+    ...typeof env.PUSHPALS_DOCKER_BIN_ABSOLUTE === "string" && env.PUSHPALS_DOCKER_BIN_ABSOLUTE.trim() ? { PUSHPALS_DOCKER_BIN_ABSOLUTE: env.PUSHPALS_DOCKER_BIN_ABSOLUTE.trim() } : {}
   };
 }
 function normalizeChildProcessEnv(baseEnv, platform = process.platform) {
@@ -2020,6 +2205,19 @@ function applyResolvedGitBinaryToRuntimeEnv(env, resolvedGitBinary, platform = p
   }
   return env;
 }
+function applyResolvedDockerBinaryToRuntimeEnv(env, resolvedDockerBinary, platform = process.platform) {
+  const resolvedPath = String(resolvedDockerBinary ?? "").trim();
+  if (!resolvedPath)
+    return env;
+  prependExecutableDirToPath(env, resolvedPath, platform);
+  env.PUSHPALS_DOCKER_BIN = basename(resolvedPath);
+  if (resolvedPath.includes("/") || resolvedPath.includes("\\")) {
+    env.PUSHPALS_DOCKER_BIN_ABSOLUTE = resolvedPath;
+  } else {
+    delete env.PUSHPALS_DOCKER_BIN_ABSOLUTE;
+  }
+  return env;
+}
 function resolveRuntimeGitExecutableCandidates(env, platform = process.platform) {
   const candidates = [];
   const seen = new Set;
@@ -2039,6 +2237,25 @@ function resolveRuntimeGitExecutableCandidates(env, platform = process.platform)
   pushCandidate("git");
   return candidates;
 }
+function resolveRuntimeDockerExecutableCandidates(env, platform = process.platform) {
+  const candidates = [];
+  const seen = new Set;
+  const pushCandidate = (value) => {
+    const trimmed = String(value ?? "").trim();
+    if (!trimmed)
+      return;
+    const key = platform === "win32" ? trimmed.toLowerCase() : trimmed;
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    candidates.push(trimmed);
+  };
+  pushCandidate(env.PUSHPALS_DOCKER_BIN ?? "");
+  pushCandidate(env.PUSHPALS_DOCKER_BIN_ABSOLUTE ?? "");
+  pushCandidate(platform === "win32" ? "docker.exe" : "docker");
+  pushCandidate("docker");
+  return candidates;
+}
 function resolveWindowsShellExecutableCandidatesForEnv(env, platform = process.platform) {
   if (platform !== "win32")
     return [];
@@ -2153,6 +2370,142 @@ async function resolveSourceControlManagerGitProbe(cwd, env, platform = process.
     detail: candidates.join(", ") || "git"
   };
 }
+async function resolveWorkerpalDockerProbe(cwd, env, platform = process.platform) {
+  const resolvedDockerBinary = await resolveCommandPath(platform === "win32" ? "docker.exe" : "docker", cwd, env);
+  if (resolvedDockerBinary) {
+    prependExecutableDirToPath(env, resolvedDockerBinary, platform);
+    env.PUSHPALS_DOCKER_BIN = basename(resolvedDockerBinary);
+    env.PUSHPALS_DOCKER_BIN_ABSOLUTE = resolvedDockerBinary;
+  }
+  const candidates = resolveRuntimeDockerExecutableCandidates(env, platform);
+  const failures = [];
+  for (const candidate of candidates) {
+    const result = await runCommandWithEnv([candidate, "version", "--format", "{{.Server.Version}}"], cwd, env);
+    if (result.ok) {
+      const version = result.stdout.trim();
+      return {
+        ok: true,
+        detail: version ? `${candidate} (${version})` : candidate
+      };
+    }
+    const detail = result.stderr || result.stdout || `exit ${result.exitCode}`;
+    failures.push(`${candidate}: ${detail}`);
+  }
+  return {
+    ok: false,
+    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, {
@@ -2161,8 +2514,9 @@ async function precheckSourceControlManagerGitAvailability(opts) {
     useRuntimeConfig: opts.preflightUsesEmbeddedRuntime,
     sessionId: opts.sessionId
   });
-  if (env.PUSHPALS_GIT_BIN) {
-    applyResolvedGitBinaryToRuntimeEnv(env, env.PUSHPALS_GIT_BIN, platform);
+  const preconfiguredGitBinary = env.PUSHPALS_GIT_BIN_ABSOLUTE ?? env.PUSHPALS_GIT_BIN;
+  if (preconfiguredGitBinary) {
+    applyResolvedGitBinaryToRuntimeEnv(env, preconfiguredGitBinary, platform);
   }
   const remoteStatus = opts.gitRemoteCheckFn ? await opts.gitRemoteCheckFn(opts.repoRoot, opts.remote, env) : opts.repoHasRemoteFn ? await opts.repoHasRemoteFn(opts.repoRoot, opts.remote) ? { status: "ok", remote: opts.remote } : { status: "missing_remote", remote: opts.remote } : await checkGitRemoteConfigured(opts.repoRoot, opts.remote, env);
   if (remoteStatus.status === "missing_remote") {
@@ -2198,6 +2552,55 @@ async function precheckSourceControlManagerGitAvailability(opts) {
     env
   };
 }
+async function precheckWorkerpalDockerAvailability(opts) {
+  const env = buildEmbeddedRuntimeEnv(opts.baseEnv ?? process.env, {
+    repoRoot: opts.repoRoot,
+    runtimeRoot: opts.runtimeRoot,
+    useRuntimeConfig: opts.preflightUsesEmbeddedRuntime,
+    sessionId: opts.sessionId
+  });
+  const preconfiguredDockerBinary = env.PUSHPALS_DOCKER_BIN_ABSOLUTE ?? env.PUSHPALS_DOCKER_BIN;
+  if (preconfiguredDockerBinary) {
+    applyResolvedDockerBinaryToRuntimeEnv(env, preconfiguredDockerBinary, opts.platform ?? process.platform);
+  }
+  if (!opts.autoSpawnWorkerpals) {
+    return {
+      status: "skipped",
+      detail: "WorkerPal auto-spawn is disabled",
+      env
+    };
+  }
+  if (!opts.dockerEnabled) {
+    return {
+      status: "skipped",
+      detail: "WorkerPal docker mode is disabled",
+      env
+    };
+  }
+  if (!opts.requireDocker) {
+    return {
+      status: "skipped",
+      detail: "WorkerPal docker mode is optional",
+      env
+    };
+  }
+  const dockerProbe = await (opts.dockerProbeFn ?? resolveWorkerpalDockerProbe)(opts.repoRoot, env, opts.platform ?? process.platform);
+  if (!dockerProbe.ok) {
+    return {
+      status: "failed",
+      detail: dockerProbe.detail,
+      env
+    };
+  }
+  return {
+    status: "ok",
+    detail: dockerProbe.detail,
+    env
+  };
+}
+function resolveWorkerpalCapacityTimeoutMs(config) {
+  return Math.max(config.remotebuddy.waitForWorkerpalMs, config.remotebuddy.workerpalStartupTimeoutMs, config.remotebuddy.workerpalDocker ? config.workerpals.dockerAgentStartupTimeoutMs + 15000 : 0, 1e4);
+}
 async function checkGitRemoteConfigured(repoRoot, remote, env) {
   const normalizedRemote = String(remote ?? "").trim();
   if (!normalizedRemote) {
@@ -2539,6 +2942,42 @@ async function probeSourceControlManager(port) {
     return false;
   }
 }
+async function fetchWorkerStatusRows(serverUrl, ttlMs) {
+  const payload = await fetchJsonWithTimeout(`${serverUrl}/workers?ttlMs=${Math.max(1000, Math.floor(ttlMs))}`, {}, 1e4);
+  if (!payload?.ok || !Array.isArray(payload.workers)) {
+    return [];
+  }
+  return payload.workers;
+}
+async function waitForWorkerpalCapacity(opts) {
+  const deadline = Date.now() + Math.max(1000, opts.timeoutMs);
+  let lastObservedOnline = 0;
+  while (Date.now() < deadline) {
+    const workers = await (opts.fetchWorkersFn ?? fetchWorkerStatusRows)(opts.serverUrl, opts.ttlMs);
+    const onlineWorkers = workers.filter((worker) => Boolean(worker?.isOnline) && String(worker?.status ?? "").trim().toLowerCase() !== "offline");
+    const idleWorkers = onlineWorkers.filter((worker) => Number(worker?.activeJobCount ?? 0) <= 0);
+    if (onlineWorkers.length > 0) {
+      lastObservedOnline = Math.max(lastObservedOnline, onlineWorkers.length);
+    }
+    if (idleWorkers.length > 0) {
+      return {
+        ok: true,
+        detail: `${idleWorkers.length} idle / ${onlineWorkers.length} online`
+      };
+    }
+    await (opts.sleepFn ?? Bun.sleep)(DEFAULT_RUNTIME_BOOT_POLL_MS);
+  }
+  if (lastObservedOnline > 0) {
+    return {
+      ok: false,
+      detail: `${lastObservedOnline} online WorkerPal(s) reported but none became idle within ${Math.max(1000, opts.timeoutMs)}ms`
+    };
+  }
+  return {
+    ok: false,
+    detail: `no online WorkerPal reported within ${Math.max(1000, opts.timeoutMs)}ms`
+  };
+}
 async function fetchWithTimeout(url, init = {}, timeoutMs = HTTP_TIMEOUT_MS) {
   const controller = new AbortController;
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -2624,15 +3063,21 @@ async function autoStartRuntimeServices(opts) {
   }
   await ensureRuntimeAssets(runtimeRoot, runtimeTag);
   const runtimeBinaries = await ensureRuntimeBinaries(runtimeRoot, runtimeTag);
-  const runtimeEnv = buildEmbeddedRuntimeEnv(process.env, {
+  const runtimeEnv = buildEmbeddedRuntimeEnv(opts.baseEnv ?? process.env, {
     repoRoot: opts.repoRoot,
     runtimeRoot,
     useRuntimeConfig: opts.preparedRuntime.preflightUsesEmbeddedRuntime,
-    sessionId: opts.sessionId
+    sessionId: opts.sessionId,
+    runtimeTag
   });
   runtimeEnv.PUSHPALS_WORKERPALS_BIN = runtimeBinaries.workerpals;
-  if (runtimeEnv.PUSHPALS_GIT_BIN) {
-    applyResolvedGitBinaryToRuntimeEnv(runtimeEnv, runtimeEnv.PUSHPALS_GIT_BIN);
+  const preconfiguredRuntimeGitBinary = runtimeEnv.PUSHPALS_GIT_BIN_ABSOLUTE ?? runtimeEnv.PUSHPALS_GIT_BIN;
+  if (preconfiguredRuntimeGitBinary) {
+    applyResolvedGitBinaryToRuntimeEnv(runtimeEnv, preconfiguredRuntimeGitBinary);
+  }
+  const preconfiguredRuntimeDockerBinary = runtimeEnv.PUSHPALS_DOCKER_BIN_ABSOLUTE ?? runtimeEnv.PUSHPALS_DOCKER_BIN;
+  if (preconfiguredRuntimeDockerBinary) {
+    applyResolvedDockerBinaryToRuntimeEnv(runtimeEnv, preconfiguredRuntimeDockerBinary);
   }
   const gitLookupCommand = typeof runtimeEnv.PUSHPALS_GIT_BIN === "string" && runtimeEnv.PUSHPALS_GIT_BIN.trim() ? runtimeEnv.PUSHPALS_GIT_BIN.trim() : "git";
   const resolvedGitBinary = await resolveCommandPath(gitLookupCommand, opts.repoRoot, runtimeEnv);
@@ -2720,6 +3165,24 @@ ${tail}` : ""}`);
     appendRuntimeServicesLogLine(runtimeServicesLogPath, "[pushpals] embedded remotebuddy autonomous engine is disabled (remotebuddy.autonomy.enabled=false).");
   };
   reportRemoteBuddyAutonomousEngineState();
+  if (runtimePreflight.config.remotebuddy.autoSpawnWorkerpals) {
+    const workerpalReadyTimeoutMs = resolveWorkerpalCapacityTimeoutMs(runtimePreflight.config);
+    const workerpalCapacity = await waitForWorkerpalCapacity({
+      serverUrl: opts.serverUrl,
+      timeoutMs: workerpalReadyTimeoutMs,
+      ttlMs: runtimePreflight.config.remotebuddy.workerpalOnlineTtlMs
+    });
+    if (!workerpalCapacity.ok) {
+      const tail = readLogTail(remotebuddyService.logPath);
+      appendRuntimeServicesLogLine(runtimeServicesLogPath, `[pushpals] embedded workerpal capacity did not become available within ${workerpalReadyTimeoutMs}ms.`);
+      stopRuntimeServices(services);
+      throw new Error(`Embedded WorkerPal capacity did not become available within ${workerpalReadyTimeoutMs}ms (${workerpalCapacity.detail}). ` + `See ${remotebuddyService.logPath}${tail ? `
+--- remotebuddy log tail ---
+${tail}` : ""}`);
+    }
+    console.log(`[pushpals] Embedded WorkerPal capacity is ready (${workerpalCapacity.detail}).`);
+    appendRuntimeServicesLogLine(runtimeServicesLogPath, `[pushpals] embedded workerpal capacity ready (${workerpalCapacity.detail}).`);
+  }
   const scmHealthy = await probeSourceControlManager(opts.sourceControlManagerPort);
   const scmGitProbe = await resolveSourceControlManagerGitProbe(opts.repoRoot, runtimeEnv, process.platform);
   const scmRemoteStatus = await checkGitRemoteConfigured(opts.repoRoot, opts.sourceControlManagerRemote, runtimeEnv);
@@ -3396,6 +3859,15 @@ async function main() {
     console.error(`[pushpals] Precheck failed: embedded SourceControlManager git command is unavailable (${scmGitPrecheck.detail}).`);
     process.exit(1);
   }
+  const workerpalDockerPrecheck = await precheckWorkerpalDockerAvailability({
+    repoRoot,
+    runtimeRoot: preparedRuntime.runtimeRoot,
+    preflightUsesEmbeddedRuntime: preparedRuntime.preflightUsesEmbeddedRuntime,
+    autoSpawnWorkerpals: Boolean(config.remotebuddy.autoSpawnWorkerpals),
+    dockerEnabled: Boolean(config.remotebuddy.workerpalDocker),
+    requireDocker: Boolean(config.remotebuddy.workerpalRequireDocker),
+    baseEnv: scmGitPrecheck.env
+  });
   const precheckPassed = await enforcePushpalsRemoteBranchPrecheck(repoRoot, config.sourceControlManager.remote, config.sourceControlManager.mainBranch);
   if (!precheckPassed) {
     process.exit(1);
@@ -3414,6 +3886,7 @@ async function main() {
   };
   let autoStartedServices = [];
   let pushpalsLogPath;
+  let resolvedRuntimeTagForAutoStart = preparedRuntime.runtimeTag || parsed.runtimeTag || "";
   const stopAutoStartedServices = () => {
     if (autoStartedServices.length === 0)
       return;
@@ -3422,6 +3895,26 @@ 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}`
@@ -3437,8 +3930,9 @@ async function main() {
           sourceControlManagerPort: config.sourceControlManager.port,
           sourceControlManagerRemote: config.sourceControlManager.remote,
           preparedRuntime,
-          requestedRuntimeTag: parsed.runtimeTag,
-          startLocalBuddy: resolveCliLocalBuddyAutostart(parsed.runtimeOnly, Boolean(config.localbuddy.enabled))
+          requestedRuntimeTag: resolvedRuntimeTagForAutoStart || parsed.runtimeTag,
+          startLocalBuddy: resolveCliLocalBuddyAutostart(parsed.runtimeOnly, Boolean(config.localbuddy.enabled)),
+          baseEnv: workerpalDockerPrecheck.env
         });
         autoStartedServices = startedRuntime.services;
         pushpalsLogPath = startedRuntime.pushpalsLogPath;
@@ -3493,6 +3987,22 @@ async function main() {
     }
     process.exit(1);
   }
+  const workerpalCapacity = await waitForWorkerpalCapacity({
+    serverUrl,
+    timeoutMs: resolveWorkerpalCapacityTimeoutMs(config),
+    ttlMs: config.remotebuddy.workerpalOnlineTtlMs
+  });
+  if (!workerpalCapacity.ok) {
+    stopAutoStartedServices();
+    console.error(`[pushpals] WorkerPal capacity is not ready for repo ${repoRoot}: ${workerpalCapacity.detail}.`);
+    if (workerpalDockerPrecheck.status === "failed") {
+      console.error(`[pushpals] Docker precheck detail: ${workerpalDockerPrecheck.detail}`);
+    } else if (serverWasAlreadyHealthy) {
+      console.error("[pushpals] A PushPals runtime is already serving this repo, but it does not currently have an idle WorkerPal available.");
+      console.error("[pushpals] Wait for a worker to become idle or restart the runtime after fixing WorkerPal startup.");
+    }
+    process.exit(1);
+  }
   const saved = statePath ? readCliState(statePath) : {};
   pushpalsLogPath = pushpalsLogPath || (typeof saved.pushpalsLogPath === "string" ? saved.pushpalsLogPath : undefined);
   const preferredHubUrl = normalizeUrl(parsed.monitoringHubUrl ?? process.env.PUSHPALS_MONITOR_URL ?? saved.monitoringHubUrl ?? "");
@@ -3667,17 +4177,21 @@ if (import.meta.main) {
   });
 }
 export {
+  waitForWorkerpalCapacity,
   startEmbeddedMonitoringHub,
   resolveWindowsWhereExecutableCandidatesForEnv,
   resolveWindowsShellExecutableCandidatesForEnv,
   resolveRuntimeGitExecutableCandidates,
+  resolveRuntimeDockerExecutableCandidates,
   resolvePreferredRuntimeReleaseTag,
   resolveCommandPath,
   resolveCliStatePath,
   resolveCliLocalBuddyAutostart,
   resolveBundledRuntimeAssetSource,
   resolveBundledMonitoringHubRoot,
+  prepareEmbeddedWorkerpalDockerImageIfNeeded,
   prepareCliRuntime,
+  precheckWorkerpalDockerAvailability,
   precheckSourceControlManagerGitAvailability,
   normalizeRepoPathForComparison,
   normalizeCliInteractiveMessage,
@@ -3688,12 +4202,17 @@ export {
   formatSessionEventLine,
   extractRemoteBuddySessionConsumerHealth,
   extractRemoteBuddyAutonomousEngineState,
+  ensureWorkerpalDockerImageReady,
+  downloadRuntimeAssetsFromSourceTag,
+  copyTrackedRepoPath,
   bundledMonitoringHubNeedsRefresh,
+  buildWorkerpalSandboxPaths,
   buildServiceStopCommand,
   buildRuntimeServiceLogPaths,
   buildOpenMonitoringHubCommand,
   buildEmbeddedRuntimeEnv,
   buildEmbeddedMonitoringHubHtml,
   buildCliClearTargets,
-  applyResolvedGitBinaryToRuntimeEnv
+  applyResolvedGitBinaryToRuntimeEnv,
+  applyResolvedDockerBinaryToRuntimeEnv
 };