@pushpalsdev/cli 1.0.6 → 1.0.8

package/dist/pushpals-cli.js

@@ -2,10 +2,14 @@
 // @bun
 
 // ../../scripts/pushpals-cli.ts
-import { appendFileSync, chmodSync, cpSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { dirname, join as join2, resolve as resolve2 } from "path";
+import { appendFileSync, chmodSync, cpSync, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { dirname, join as join2, resolve as resolve3 } from "path";
 import { createInterface } from "readline";
 
+// ../shared/src/client_preflight.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { relative, resolve as resolve2 } from "path";
+
 // ../shared/src/config.ts
 import { existsSync, readFileSync } from "fs";
 import { join, resolve, isAbsolute } from "path";
@@ -739,6 +743,316 @@ function loadPushPalsConfig(options = {}) {
   return config;
 }
 
+// ../shared/src/vision.ts
+var SECTION_HEADING_RE = /^##\s+(\d+)\)\s+(.+?)\s*$/;
+var ONE_SENTENCE_PROMPT_RE = /^\>\s*\*\*One sentence:\*\*\s*(.+)\s*$/i;
+var BLOCKQUOTE_RE = /^\>\s*(.+?)\s*$/;
+function toLines(markdown) {
+  return String(markdown ?? "").replace(/\r\n/g, `
+`).split(`
+`);
+}
+function extractOneSentence(lines) {
+  let expectNextBlockquoteSentence = false;
+  for (const line of lines) {
+    const marker = line.match(ONE_SENTENCE_PROMPT_RE);
+    if (marker) {
+      const inline = marker[1].trim();
+      if (inline)
+        return inline;
+      expectNextBlockquoteSentence = true;
+      continue;
+    }
+    const block = line.match(BLOCKQUOTE_RE);
+    if (expectNextBlockquoteSentence) {
+      if (!block)
+        continue;
+      const text = block[1].trim();
+      if (!text)
+        continue;
+      if (/^Example:/i.test(text))
+        continue;
+      return text;
+    }
+  }
+  for (const line of lines) {
+    const block = line.match(BLOCKQUOTE_RE);
+    if (!block)
+      continue;
+    const text = block[1].trim();
+    if (!text)
+      continue;
+    if (/^\*\*One sentence:\*\*/i.test(text))
+      continue;
+    if (/^Example:/i.test(text))
+      continue;
+    return text;
+  }
+  return "";
+}
+function parseVisionDoc(markdown) {
+  const lines = toLines(markdown);
+  const sections = [];
+  let currentNumber = "";
+  let currentTitle = "";
+  let currentBody = [];
+  const flushCurrent = () => {
+    if (!currentNumber)
+      return;
+    sections.push({
+      number: currentNumber,
+      title: currentTitle,
+      markdown: currentBody.join(`
+`).trim()
+    });
+    currentNumber = "";
+    currentTitle = "";
+    currentBody = [];
+  };
+  for (const line of lines) {
+    const heading = line.match(SECTION_HEADING_RE);
+    if (heading) {
+      flushCurrent();
+      currentNumber = heading[1];
+      currentTitle = heading[2].trim();
+      continue;
+    }
+    if (currentNumber) {
+      currentBody.push(line);
+    }
+  }
+  flushCurrent();
+  const sectionByNumber = {};
+  for (const section of sections) {
+    if (!sectionByNumber[section.number]) {
+      sectionByNumber[section.number] = section;
+    }
+  }
+  return {
+    oneSentence: extractOneSentence(lines),
+    sections,
+    sectionByNumber
+  };
+}
+function validateVisionDocStructure(markdown) {
+  const parsed = parseVisionDoc(markdown);
+  const missingSectionNumbers = [];
+  const errors = [];
+  if (!parsed.oneSentence) {
+    errors.push('Missing one-sentence vision line (expected near the top as a blockquote after "**One sentence:**").');
+  }
+  return {
+    ok: errors.length === 0,
+    sectionCount: parsed.sections.length,
+    hasOneSentence: Boolean(parsed.oneSentence),
+    missingSectionNumbers,
+    errors
+  };
+}
+
+// ../shared/src/client_preflight.ts
+function runtimeHasConfigDir(runtimeRoot, dirName) {
+  const dirPath = resolve2(runtimeRoot, dirName);
+  return existsSync2(resolve2(dirPath, "default.toml")) || existsSync2(resolve2(dirPath, "local.example.toml")) || existsSync2(resolve2(dirPath, "local.toml"));
+}
+function resolveClientConfigDir(projectRoot, runtimeRoot, explicitConfigDir) {
+  if (explicitConfigDir && explicitConfigDir.trim()) {
+    return resolve2(explicitConfigDir);
+  }
+  const runtimeCanonical = resolve2(runtimeRoot, "configs");
+  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) {
+  const rel = relative(currentRoot, pathValue);
+  if (!rel || rel === "")
+    return ".";
+  if (rel.startsWith(".."))
+    return pathValue;
+  return rel.replace(/\\/g, "/");
+}
+function quotePowerShell(pathValue) {
+  if (/^[A-Za-z0-9_./\\:-]+$/.test(pathValue))
+    return pathValue;
+  return `'${pathValue.replace(/'/g, "''")}'`;
+}
+function quoteBash(pathValue) {
+  if (/^[A-Za-z0-9_./\\:-]+$/.test(pathValue))
+    return pathValue;
+  return "'" + pathValue.replace(/'/g, `'"'"'`) + "'";
+}
+function buildCopyCommands(workspaceRoot, sourcePath, destPath) {
+  const displaySource = toDisplayPath(workspaceRoot, sourcePath);
+  const displayDest = toDisplayPath(workspaceRoot, destPath);
+  return {
+    windowsPowerShell: `Copy-Item ${quotePowerShell(displaySource)} ${quotePowerShell(displayDest)}`,
+    bash: `cp ${quoteBash(displaySource)} ${quoteBash(displayDest)}`
+  };
+}
+function evaluateClientRuntimePreflight(options) {
+  const projectRoot = resolve2(options.projectRoot);
+  const runtimeRoot = resolve2(options.runtimeRoot ?? projectRoot);
+  const configDir = resolveClientConfigDir(projectRoot, runtimeRoot, options.configDir);
+  const visionTemplateRoot = resolve2(options.visionTemplateRoot ?? runtimeRoot);
+  const config = options.config ?? loadPushPalsConfig({
+    projectRoot,
+    configDir,
+    reload: true
+  });
+  const issues = [];
+  const envPath = resolve2(runtimeRoot, ".env");
+  if (!existsSync2(envPath)) {
+    const envExamplePath = resolve2(runtimeRoot, ".env.example");
+    issues.push({
+      code: "missing_env_file",
+      message: `Missing required local env file: ${toDisplayPath(projectRoot, envPath)}.`,
+      copyCommands: existsSync2(envExamplePath) ? buildCopyCommands(projectRoot, envExamplePath, envPath) : undefined
+    });
+  }
+  const localTomlPath = resolve2(runtimeRoot, "configs", "local.toml");
+  const legacyLocalTomlPath = resolve2(runtimeRoot, "config", "local.toml");
+  if (!existsSync2(localTomlPath) && !existsSync2(legacyLocalTomlPath)) {
+    const localExamplePath = resolve2(runtimeRoot, "configs", "local.example.toml");
+    issues.push({
+      code: "missing_local_toml",
+      message: `Missing required local config file: ${toDisplayPath(projectRoot, localTomlPath)}.`,
+      copyCommands: existsSync2(localExamplePath) ? buildCopyCommands(projectRoot, localExamplePath, localTomlPath) : undefined
+    });
+  }
+  const autonomyEnabled = Boolean(config.remotebuddy.autonomy.enabled);
+  if (!autonomyEnabled) {
+    return {
+      ok: issues.length === 0,
+      projectRoot,
+      runtimeRoot,
+      config,
+      issues,
+      autonomyEnabled,
+      visionSummary: null
+    };
+  }
+  const visionPath = resolve2(projectRoot, "vision.md");
+  const visionTemplatePath = resolve2(visionTemplateRoot, "vision.example.md");
+  if (!existsSync2(visionPath)) {
+    issues.push({
+      code: "missing_vision_doc",
+      message: "Missing required autonomy vision file: vision.md " + "(required when remotebuddy.autonomy.enabled=true).",
+      copyCommands: existsSync2(visionTemplatePath) ? buildCopyCommands(projectRoot, visionTemplatePath, visionPath) : undefined
+    });
+    return {
+      ok: false,
+      projectRoot,
+      runtimeRoot,
+      config,
+      issues,
+      autonomyEnabled,
+      visionSummary: null
+    };
+  }
+  let rawVision = "";
+  try {
+    rawVision = readFileSync2(visionPath, "utf8");
+  } catch (err) {
+    issues.push({
+      code: "unreadable_vision_doc",
+      message: `Autonomy vision preflight failed: could not read vision.md.`,
+      detail: String(err)
+    });
+    return {
+      ok: false,
+      projectRoot,
+      runtimeRoot,
+      config,
+      issues,
+      autonomyEnabled,
+      visionSummary: null
+    };
+  }
+  const visionText = rawVision.trim();
+  if (!visionText) {
+    issues.push({
+      code: "empty_vision_doc",
+      message: "Autonomy vision preflight failed: vision.md is empty.",
+      detail: "Add repository vision/goals before startup."
+    });
+    return {
+      ok: false,
+      projectRoot,
+      runtimeRoot,
+      config,
+      issues,
+      autonomyEnabled,
+      visionSummary: null
+    };
+  }
+  const validation = validateVisionDocStructure(visionText);
+  if (!validation.ok) {
+    issues.push({
+      code: "invalid_vision_doc",
+      message: "Autonomy vision preflight failed: vision.md is invalid.",
+      detail: validation.errors.join(" ")
+    });
+    return {
+      ok: false,
+      projectRoot,
+      runtimeRoot,
+      config,
+      issues,
+      autonomyEnabled,
+      visionSummary: null
+    };
+  }
+  return {
+    ok: issues.length === 0,
+    projectRoot,
+    runtimeRoot,
+    config,
+    issues,
+    autonomyEnabled,
+    visionSummary: {
+      path: toDisplayPath(projectRoot, visionPath),
+      chars: visionText.length,
+      sectionCount: validation.sectionCount,
+      validation
+    }
+  };
+}
+function formatClientRuntimePreflightLines(result, prefix) {
+  const normalizedPrefix = prefix.trim();
+  const lines = [];
+  if (result.ok) {
+    if (result.visionSummary) {
+      lines.push(`${normalizedPrefix} Autonomy preflight: loaded ${result.visionSummary.path} ` + `(${result.visionSummary.chars} chars, ${result.visionSummary.sectionCount} section(s)).`);
+    }
+    return lines;
+  }
+  for (const issue of result.issues) {
+    lines.push(`${normalizedPrefix} ${issue.message}`);
+    if (issue.detail) {
+      lines.push(`${normalizedPrefix}   ${issue.detail}`);
+    }
+    if (issue.copyCommands) {
+      lines.push(`${normalizedPrefix}   Windows (PowerShell): ${issue.copyCommands.windowsPowerShell}`);
+      lines.push(`${normalizedPrefix}   Linux/macOS (bash): ${issue.copyCommands.bash}`);
+    }
+  }
+  return lines;
+}
+
 // ../../scripts/pushpals-cli.ts
 var DEFAULT_MONITOR_PORT = 8081;
 var MONITOR_SCAN_PORTS = 32;
@@ -855,7 +1169,7 @@ function parsePositiveInt(value, fallback) {
   return parsed;
 }
 function normalizePath(value) {
-  const normalized = resolve2(value).replace(/\\/g, "/").replace(/\/+$/, "");
+  const normalized = resolve3(value).replace(/\\/g, "/").replace(/\/+$/, "");
   if (process.platform === "win32")
     return normalized.toLowerCase();
   return normalized;
@@ -883,11 +1197,39 @@ async function resolveCurrentGitRepoRoot(cwd) {
   const root = await runGit(["rev-parse", "--show-toplevel"], cwd);
   if (!root.ok || !root.stdout)
     return null;
-  return resolve2(root.stdout);
+  return resolve3(root.stdout);
 }
 function resolveDefaultRuntimeRoot() {
   const home = process.env.USERPROFILE || process.env.HOME || process.cwd();
-  return resolve2(home, ".pushpals", "runtime");
+  return resolve3(home, ".pushpals", "runtime");
+}
+function buildRuntimeAssetSource(root, protocolSchemasDir) {
+  return {
+    root,
+    envExamplePath: join2(root, ".env.example"),
+    visionExamplePath: join2(root, "vision.example.md"),
+    configsDir: join2(root, "configs"),
+    promptsDir: join2(root, "prompts"),
+    protocolSchemasDir
+  };
+}
+function isCompleteRuntimeAssetSource(source) {
+  return existsSync3(source.envExamplePath) && existsSync3(source.visionExamplePath) && existsSync3(join2(source.configsDir, "default.toml")) && existsSync3(source.promptsDir) && existsSync3(join2(source.protocolSchemasDir, "envelope.schema.json")) && existsSync3(join2(source.protocolSchemasDir, "events.schema.json"));
+}
+function resolveBundledRuntimeAssetSource() {
+  const candidates = [
+    buildRuntimeAssetSource(resolve3(import.meta.dir, "..", "runtime"), resolve3(import.meta.dir, "..", "runtime", "protocol", "schemas")),
+    buildRuntimeAssetSource(resolve3(import.meta.dir, ".."), resolve3(import.meta.dir, "..", "packages", "protocol", "src", "schemas")),
+    buildRuntimeAssetSource(resolve3(import.meta.dir, "..", "packages", "cli", "runtime"), resolve3(import.meta.dir, "..", "packages", "cli", "runtime", "protocol", "schemas"))
+  ];
+  for (const candidate of candidates) {
+    if (isCompleteRuntimeAssetSource(candidate))
+      return candidate;
+  }
+  return null;
+}
+function repoLooksLikePushPalsSourceCheckout(repoRoot) {
+  return existsSync3(join2(repoRoot, "configs", "default.toml")) || existsSync3(join2(repoRoot, "config", "default.toml"));
 }
 function parseSemverFromPackageVersion(value) {
   const raw = String(value ?? "").trim();
@@ -937,18 +1279,56 @@ async function resolveRuntimeReleaseTag(explicitTag) {
   }
 }
 function writeTextFileIfMissing(pathValue, text) {
-  if (existsSync2(pathValue))
+  if (existsSync3(pathValue))
     return;
   mkdirSync(dirname(pathValue), { recursive: true });
   writeFileSync(pathValue, text, "utf8");
 }
-function copyBundledRuntimeAssets(runtimeRoot) {
-  const bundledRoot = resolve2(import.meta.dir, "..", "runtime");
-  if (!existsSync2(bundledRoot))
+function copyRuntimeAssetBundle(source, runtimeRoot, force) {
+  mkdirSync(runtimeRoot, { recursive: true });
+  cpSync(source.envExamplePath, join2(runtimeRoot, ".env.example"), {
+    force,
+    errorOnExist: false
+  });
+  cpSync(source.visionExamplePath, join2(runtimeRoot, "vision.example.md"), {
+    force,
+    errorOnExist: false
+  });
+  cpSync(source.configsDir, join2(runtimeRoot, "configs"), {
+    recursive: true,
+    force,
+    errorOnExist: false
+  });
+  cpSync(source.promptsDir, join2(runtimeRoot, "prompts"), {
+    recursive: true,
+    force,
+    errorOnExist: false
+  });
+  cpSync(source.protocolSchemasDir, join2(runtimeRoot, "protocol", "schemas"), {
+    recursive: true,
+    force,
+    errorOnExist: false
+  });
+}
+function copyBundledRuntimeAssets(runtimeRoot, force = true) {
+  const bundledSource = resolveBundledRuntimeAssetSource();
+  if (!bundledSource)
     return false;
-  cpSync(bundledRoot, runtimeRoot, { recursive: true, force: true });
+  copyRuntimeAssetBundle(bundledSource, runtimeRoot, force);
   return true;
 }
+function seedRuntimePreflightAssets(runtimeRoot) {
+  copyBundledRuntimeAssets(runtimeRoot, false);
+  writeTextFileIfMissing(join2(runtimeRoot, ".env"), `# Local PushPals runtime environment
+`);
+  const localExamplePath = join2(runtimeRoot, "configs", "local.example.toml");
+  if (existsSync3(localExamplePath)) {
+    writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), readFileSync3(localExamplePath, "utf8"));
+  } else {
+    writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), `# Local PushPals runtime overrides
+`);
+  }
+}
 async function fetchTextFromUrl(url, timeoutMs = 20000) {
   const response = await fetchWithTimeout(url, { headers: GITHUB_HEADERS }, timeoutMs);
   if (!response.ok) {
@@ -963,7 +1343,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.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.startsWith("configs/") || pathValue.startsWith("prompts/") || pathValue.startsWith("packages/protocol/src/schemas/"));
   if (paths.length === 0) {
     throw new Error(`Runtime source tree for ${tag} did not include prompts/config assets`);
   }
@@ -978,14 +1358,14 @@ async function downloadRuntimeAssetsFromSourceTag(runtimeRoot, tag) {
 }
 async function ensureRuntimeAssets(runtimeRoot, runtimeTag) {
   const markerPath = join2(runtimeRoot, ".runtime-assets-tag");
-  const currentTag = existsSync2(markerPath) ? readFileSync2(markerPath, "utf8").trim() : "";
+  const currentTag = existsSync3(markerPath) ? readFileSync3(markerPath, "utf8").trim() : "";
   const protocolSchemasDir = join2(runtimeRoot, "protocol", "schemas");
-  const hasProtocolSchemas = existsSync2(join2(protocolSchemasDir, "envelope.schema.json")) && existsSync2(join2(protocolSchemasDir, "events.schema.json"));
-  const hasAssets = existsSync2(join2(runtimeRoot, ".env.example")) && existsSync2(join2(runtimeRoot, "configs", "default.toml")) && existsSync2(join2(runtimeRoot, "prompts")) && hasProtocolSchemas;
+  const hasProtocolSchemas = existsSync3(join2(protocolSchemasDir, "envelope.schema.json")) && existsSync3(join2(protocolSchemasDir, "events.schema.json"));
+  const hasAssets = existsSync3(join2(runtimeRoot, ".env.example")) && existsSync3(join2(runtimeRoot, "vision.example.md")) && existsSync3(join2(runtimeRoot, "configs", "default.toml")) && existsSync3(join2(runtimeRoot, "prompts")) && hasProtocolSchemas;
   if (!hasAssets || currentTag !== runtimeTag) {
     copyBundledRuntimeAssets(runtimeRoot);
-    const hasProtocolSchemasAfterCopy = existsSync2(join2(protocolSchemasDir, "envelope.schema.json")) && existsSync2(join2(protocolSchemasDir, "events.schema.json"));
-    const hasAssetsAfterCopy = existsSync2(join2(runtimeRoot, ".env.example")) && existsSync2(join2(runtimeRoot, "configs", "default.toml")) && existsSync2(join2(runtimeRoot, "prompts")) && hasProtocolSchemasAfterCopy;
+    const hasProtocolSchemasAfterCopy = existsSync3(join2(protocolSchemasDir, "envelope.schema.json")) && existsSync3(join2(protocolSchemasDir, "events.schema.json"));
+    const hasAssetsAfterCopy = existsSync3(join2(runtimeRoot, ".env.example")) && existsSync3(join2(runtimeRoot, "vision.example.md")) && existsSync3(join2(runtimeRoot, "configs", "default.toml")) && existsSync3(join2(runtimeRoot, "prompts")) && hasProtocolSchemasAfterCopy;
     if (!hasAssetsAfterCopy) {
       await downloadRuntimeAssetsFromSourceTag(runtimeRoot, runtimeTag);
     }
@@ -995,36 +1375,130 @@ async function ensureRuntimeAssets(runtimeRoot, runtimeTag) {
   writeTextFileIfMissing(join2(runtimeRoot, ".env"), `# Local PushPals runtime environment
 `);
   const localExamplePath = join2(runtimeRoot, "configs", "local.example.toml");
-  if (existsSync2(localExamplePath)) {
-    writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), readFileSync2(localExamplePath, "utf8"));
+  if (existsSync3(localExamplePath)) {
+    writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), readFileSync3(localExamplePath, "utf8"));
   } else {
     writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), `# Local PushPals runtime overrides
 `);
   }
 }
+function resolveDeferredRuntimeTagHint(explicitTag) {
+  return String(explicitTag || process.env.PUSHPALS_RUNTIME_TAG || "").trim();
+}
+async function prepareCliRuntime(opts) {
+  const runtimeRoot = resolve3(opts.runtimeRoot || process.env.PUSHPALS_RUNTIME_ROOT || resolveDefaultRuntimeRoot());
+  if (repoLooksLikePushPalsSourceCheckout(opts.repoRoot)) {
+    return {
+      runtimeRoot,
+      runtimeTag: "",
+      runtimePreflight: evaluateClientRuntimePreflight({
+        projectRoot: opts.repoRoot
+      }),
+      preflightUsesEmbeddedRuntime: false
+    };
+  }
+  seedRuntimePreflightAssets(runtimeRoot);
+  return {
+    runtimeRoot,
+    runtimeTag: resolveDeferredRuntimeTagHint(opts.runtimeTag),
+    runtimePreflight: evaluateClientRuntimePreflight({
+      projectRoot: opts.repoRoot,
+      runtimeRoot,
+      visionTemplateRoot: runtimeRoot
+    }),
+    preflightUsesEmbeddedRuntime: true
+  };
+}
+function emitCliRuntimePreflight(result) {
+  const lines = formatClientRuntimePreflightLines(result, "[pushpals]");
+  if (result.ok) {
+    for (const line of lines)
+      console.log(line);
+    return;
+  }
+  for (const line of lines)
+    console.error(line);
+}
 function runtimeBinaryFilename(serviceName, platformKey) {
   const serviceToken = serviceName === "source_control_manager" ? "source-control-manager" : serviceName;
   const extension = platformKey.startsWith("windows-") ? ".exe" : "";
   return `pushpals-runtime-${serviceToken}-${platformKey}${extension}`;
 }
 function buildEmbeddedRuntimeEnv(baseEnv, opts) {
+  const env = normalizeChildProcessEnv(baseEnv);
+  const useRuntimeConfig = opts.useRuntimeConfig !== false;
   return {
-    ...baseEnv,
+    ...env,
     PUSHPALS_REPO_ROOT_OVERRIDE: opts.repoRoot,
     PUSHPALS_PROJECT_ROOT_OVERRIDE: opts.repoRoot,
-    PUSHPALS_CONFIG_DIR_OVERRIDE: join2(opts.runtimeRoot, "configs"),
-    PUSHPALS_PROMPTS_ROOT_OVERRIDE: opts.runtimeRoot,
+    ...useRuntimeConfig ? {
+      PUSHPALS_CONFIG_DIR_OVERRIDE: join2(opts.runtimeRoot, "configs"),
+      PUSHPALS_PROMPTS_ROOT_OVERRIDE: opts.runtimeRoot
+    } : {
+      PUSHPALS_PROMPTS_ROOT_OVERRIDE: opts.repoRoot
+    },
     PUSHPALS_PROTOCOL_SCHEMAS_DIR: join2(opts.runtimeRoot, "protocol", "schemas"),
-    REMOTEBUDDY_AUTONOMY_ENABLED: String(baseEnv.REMOTEBUDDY_AUTONOMY_ENABLED ?? "").trim() || "false"
+    ...typeof env.PUSHPALS_GIT_BIN === "string" && env.PUSHPALS_GIT_BIN.trim() ? { PUSHPALS_GIT_BIN: env.PUSHPALS_GIT_BIN.trim() } : {}
   };
 }
+function normalizeChildProcessEnv(baseEnv, platform = process.platform) {
+  const env = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  if (platform === "win32") {
+    const resolvedPath = String(env.Path ?? env.PATH ?? process.env.Path ?? process.env.PATH ?? "").trim();
+    if (resolvedPath) {
+      env.Path = resolvedPath;
+      env.PATH = resolvedPath;
+    }
+    const systemRoot = String(env.SystemRoot ?? env.SYSTEMROOT ?? process.env.SystemRoot ?? process.env.SYSTEMROOT ?? "").trim();
+    if (systemRoot) {
+      env.SystemRoot = systemRoot;
+      env.SYSTEMROOT = systemRoot;
+    }
+    const comSpec = String(env.ComSpec ?? env.COMSPEC ?? process.env.ComSpec ?? process.env.COMSPEC ?? "").trim();
+    if (comSpec) {
+      env.ComSpec = comSpec;
+      env.COMSPEC = comSpec;
+    }
+  }
+  return env;
+}
+async function resolveCommandPath(command, cwd, env) {
+  const lookupCommands = process.platform === "win32" ? [
+    ["where.exe", command],
+    ["where", command]
+  ] : [["which", command]];
+  for (const lookup of lookupCommands) {
+    try {
+      const proc = Bun.spawn(lookup, {
+        cwd,
+        env,
+        stdout: "pipe",
+        stderr: "ignore"
+      });
+      const [stdout, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        proc.exited
+      ]);
+      if (exitCode !== 0)
+        continue;
+      const resolved = stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0);
+      if (resolved)
+        return resolved;
+    } catch {}
+  }
+  return null;
+}
 function timestampFileToken() {
   return new Date().toISOString().replace(/[:.]/g, "-");
 }
 function readLogTail(logPath, maxLines = 40) {
-  if (!existsSync2(logPath))
+  if (!existsSync3(logPath))
     return "";
-  const raw = readFileSync2(logPath, "utf8");
+  const raw = readFileSync3(logPath, "utf8");
   const lines = raw.split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.length > 0);
   if (lines.length === 0)
     return "";
@@ -1058,7 +1532,7 @@ async function ensureRuntimeBinaries(runtimeRoot, runtimeTag) {
     runtimeBinaries.sourceControlManager
   ];
   for (const binaryPath of requiredAssets) {
-    if (existsSync2(binaryPath))
+    if (existsSync3(binaryPath))
       continue;
     const assetName = binaryPath.split(/[\\/]/).pop() || "";
     await downloadBinaryAsset(runtimeTag, assetName, binaryPath);
@@ -1125,11 +1599,18 @@ function spawnRuntimeService(name, command, cwd, env, logPath) {
   });
   return service;
 }
+function buildServiceStopCommand(pid, platform = process.platform) {
+  if (platform === "win32" && typeof pid === "number" && pid > 0) {
+    return ["taskkill", "/PID", String(pid), "/T", "/F"];
+  }
+  return null;
+}
 function stopRuntimeServices(services) {
   for (const service of services) {
     try {
-      if (process.platform === "win32" && typeof service.proc.pid === "number" && service.proc.pid > 0) {
-        Bun.spawnSync(["taskkill", "/PID", String(service.proc.pid), "/T", "/F"], {
+      const stopCommand = buildServiceStopCommand(service.proc.pid, process.platform);
+      if (stopCommand) {
+        Bun.spawnSync(stopCommand, {
           stdin: "ignore",
           stdout: "ignore",
           stderr: "ignore"
@@ -1140,6 +1621,24 @@ function stopRuntimeServices(services) {
     } catch {}
   }
 }
+function isOptionalEmbeddedService(name) {
+  return name === "source_control_manager";
+}
+async function canSpawnCommand(command, cwd, env) {
+  try {
+    const proc = Bun.spawn(command, {
+      cwd,
+      env,
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore"
+    });
+    const exitCode = await proc.exited;
+    return exitCode === 0;
+  } catch {
+    return false;
+  }
+}
 async function repoHasRemote(repoRoot, remote) {
   const normalizedRemote = remote.trim();
   if (!normalizedRemote)
@@ -1193,17 +1692,26 @@ async function probeLocalBuddy(localAgentUrl, authToken) {
   return await fetchJsonWithTimeout(`${localAgentUrl}/healthz`, { headers: authHeaders(authToken) }, LOCALBUDDY_TIMEOUT_MS);
 }
 async function autoStartRuntimeServices(opts) {
-  const runtimeRoot = resolve2(opts.runtimeRoot || process.env.PUSHPALS_RUNTIME_ROOT || resolveDefaultRuntimeRoot());
-  const runtimeTag = await resolveRuntimeReleaseTag(opts.runtimeTag);
-  const runtimeBinaries = await ensureRuntimeBinaries(runtimeRoot, runtimeTag);
-  await ensureRuntimeAssets(runtimeRoot, runtimeTag);
+  const { runtimePreflight } = opts.preparedRuntime;
+  const runtimeRoot = opts.preparedRuntime.runtimeRoot;
+  const runtimeTag = opts.preparedRuntime.runtimeTag || await resolveRuntimeReleaseTag(opts.requestedRuntimeTag);
   console.log(`[pushpals] LocalBuddy unavailable. Auto-starting runtime for repo: ${opts.repoRoot}`);
   console.log(`[pushpals] runtimeRoot=${runtimeRoot}`);
   console.log(`[pushpals] runtimeTag=${runtimeTag}`);
+  if (!runtimePreflight.ok) {
+    throw new Error("Embedded runtime preflight failed.");
+  }
+  await ensureRuntimeAssets(runtimeRoot, runtimeTag);
+  const runtimeBinaries = await ensureRuntimeBinaries(runtimeRoot, runtimeTag);
   const runtimeEnv = buildEmbeddedRuntimeEnv(process.env, {
     repoRoot: opts.repoRoot,
-    runtimeRoot
+    runtimeRoot,
+    useRuntimeConfig: opts.preparedRuntime.preflightUsesEmbeddedRuntime
   });
+  const resolvedGitBinary = await resolveCommandPath("git", opts.repoRoot, normalizeChildProcessEnv(process.env));
+  if (resolvedGitBinary) {
+    runtimeEnv.PUSHPALS_GIT_BIN = resolvedGitBinary;
+  }
   const services = [];
   const runToken = timestampFileToken();
   const logDir = join2(runtimeRoot, "logs", "bootstrap");
@@ -1252,13 +1760,24 @@ ${tail}` : ""}`);
   console.log(`[pushpals] remotebuddy log: ${remotebuddyService.logPath}`);
   const scmHealthy = await probeSourceControlManager(opts.sourceControlManagerPort);
   const scmRemoteAvailable = await repoHasRemote(opts.repoRoot, opts.sourceControlManagerRemote);
+  const gitProbeCommand = typeof runtimeEnv.PUSHPALS_GIT_BIN === "string" && runtimeEnv.PUSHPALS_GIT_BIN.trim() ? [runtimeEnv.PUSHPALS_GIT_BIN.trim(), "--version"] : ["git", "--version"];
+  const gitAvailableForScm = await canSpawnCommand(gitProbeCommand, opts.repoRoot, runtimeEnv);
   if (!scmHealthy && scmRemoteAvailable) {
-    console.log("[pushpals] Starting embedded SourceControlManager...");
-    const sourceControlManagerService = spawnRuntimeService("source_control_manager", [runtimeBinaries.sourceControlManager, "--skip-clean-check"], opts.repoRoot, runtimeEnv, logPathFor("source_control_manager"));
-    services.push(sourceControlManagerService);
-    console.log(`[pushpals] source_control_manager log: ${sourceControlManagerService.logPath}`);
+    if (!gitAvailableForScm) {
+      console.warn("[pushpals] Git is not available to embedded SourceControlManager; skipping SCM startup.");
+    } else {
+      if (runtimeEnv.PUSHPALS_GIT_BIN) {
+        console.log(`[pushpals] Embedded SourceControlManager git=${runtimeEnv.PUSHPALS_GIT_BIN}`);
+      }
+      console.log("[pushpals] Starting embedded SourceControlManager...");
+      const sourceControlManagerService = spawnRuntimeService("source_control_manager", [runtimeBinaries.sourceControlManager, "--skip-clean-check"], opts.repoRoot, runtimeEnv, logPathFor("source_control_manager"));
+      services.push(sourceControlManagerService);
+      console.log(`[pushpals] source_control_manager log: ${sourceControlManagerService.logPath}`);
+    }
   } else if (!scmRemoteAvailable) {
     console.log(`[pushpals] Repo has no git remote "${opts.sourceControlManagerRemote}"; skipping embedded SourceControlManager.`);
+  } else if (!gitAvailableForScm) {
+    console.warn("[pushpals] Git is not available to embedded SourceControlManager; skipping SCM startup.");
   } else {
     console.log("[pushpals] SourceControlManager already healthy; skipping embedded start.");
   }
@@ -1267,7 +1786,7 @@ ${tail}` : ""}`);
     for (let i = services.length - 1;i >= 0; i--) {
       const service = services[i];
       if (service.exited) {
-        if (service.name === "source_control_manager") {
+        if (isOptionalEmbeddedService(service.name)) {
           console.warn(`[pushpals] Embedded ${service.name} exited during startup (code=${service.exitCode ?? "unknown"}); continuing without SCM.`);
           const tail2 = readLogTail(service.logPath);
           if (tail2) {
@@ -1288,9 +1807,20 @@ ${tail}` : ""}`);
     if (health?.ok) {
       const stabilityDeadline = Date.now() + DEFAULT_SERVICE_STABILITY_GRACE_MS;
       while (Date.now() < stabilityDeadline) {
-        for (const service of services) {
+        for (let i = services.length - 1;i >= 0; i--) {
+          const service = services[i];
           if (!service.exited)
             continue;
+          if (isOptionalEmbeddedService(service.name)) {
+            const tail2 = readLogTail(service.logPath);
+            console.warn(`[pushpals] Embedded ${service.name} exited immediately after bootstrap (code=${service.exitCode ?? "unknown"}); continuing without SCM.`);
+            if (tail2) {
+              console.warn(`[pushpals] ${service.name} log tail:
+${tail2}`);
+            }
+            services.splice(i, 1);
+            continue;
+          }
           const tail = readLogTail(service.logPath);
           stopRuntimeServices(services);
           throw new Error(`Embedded ${service.name} exited immediately after bootstrap (code=${service.exitCode ?? "unknown"}). ` + `See ${service.logPath}${tail ? `
@@ -1308,10 +1838,10 @@ ${tail}` : ""}`);
   throw new Error(`Timed out waiting for LocalBuddy at ${opts.localAgentUrl} after ${DEFAULT_RUNTIME_BOOT_TIMEOUT_MS}ms`);
 }
 function readCliState(pathValue) {
-  if (!existsSync2(pathValue))
+  if (!existsSync3(pathValue))
     return {};
   try {
-    const raw = readFileSync2(pathValue, "utf8");
+    const raw = readFileSync3(pathValue, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object")
       return {};
@@ -1737,15 +2267,17 @@ async function runSessionStream(serverUrl, sessionId, authToken, print, signal)
     }
   }
 }
-async function openMonitoringHub(url) {
-  let cmd = null;
-  if (process.platform === "win32") {
-    cmd = ["cmd", "/c", "start", "", url];
-  } else if (process.platform === "darwin") {
-    cmd = ["open", url];
-  } else {
-    cmd = ["xdg-open", url];
+function buildOpenMonitoringHubCommand(url, platform = process.platform) {
+  if (platform === "win32") {
+    return ["cmd", "/c", "start", "", url];
+  }
+  if (platform === "darwin") {
+    return ["open", url];
   }
+  return ["xdg-open", url];
+}
+async function openMonitoringHub(url) {
+  const cmd = buildOpenMonitoringHubCommand(url, process.platform);
   const proc = Bun.spawn(cmd, {
     stdin: "ignore",
     stdout: "ignore",
@@ -1760,7 +2292,6 @@ async function main() {
   const parsed = parseArgs(argv);
   if (!parsed)
     return;
-  const config = loadPushPalsConfig();
   const cwd = process.cwd();
   const repoRoot = await resolveCurrentGitRepoRoot(cwd);
   if (!repoRoot) {
@@ -1769,6 +2300,25 @@ async function main() {
     console.error("[pushpals] Run from a repo directory, or initialize one with `git init`.");
     process.exit(1);
   }
+  const preparedRuntime = await prepareCliRuntime({
+    repoRoot,
+    runtimeRoot: parsed.runtimeRoot,
+    runtimeTag: parsed.runtimeTag
+  });
+  console.log("[pushpals] Running runtime preflight...");
+  console.log(`[pushpals] runtimeRoot=${preparedRuntime.runtimeRoot}`);
+  if (preparedRuntime.runtimeTag) {
+    console.log(`[pushpals] runtimeTag=${preparedRuntime.runtimeTag}`);
+  } else if (!preparedRuntime.preflightUsesEmbeddedRuntime) {
+    console.log("[pushpals] runtimeTag=(deferred; using repo config for preflight)");
+  } else {
+    console.log("[pushpals] runtimeTag=(deferred until embedded auto-start is needed)");
+  }
+  emitCliRuntimePreflight(preparedRuntime.runtimePreflight);
+  if (!preparedRuntime.runtimePreflight.ok) {
+    process.exit(1);
+  }
+  const config = preparedRuntime.runtimePreflight.config;
   const serverUrl = normalizeUrl(parsed.serverUrl ?? process.env.PUSHPALS_SERVER_URL, config.server.url);
   const localAgentUrl = normalizeUrl(parsed.localAgentUrl ?? process.env.EXPO_PUBLIC_LOCAL_AGENT_URL, config.client.localAgentUrl);
   const sessionId = String(parsed.sessionId ?? process.env.PUSHPALS_SESSION_ID ?? config.sessionId).trim();
@@ -1790,8 +2340,8 @@ async function main() {
         sourceControlManagerPort: config.sourceControlManager.port,
         sourceControlManagerRemote: config.sourceControlManager.remote,
         authToken,
-        runtimeRoot: parsed.runtimeRoot,
-        runtimeTag: parsed.runtimeTag
+        preparedRuntime,
+        requestedRuntimeTag: parsed.runtimeTag
       });
       health = await probeLocalBuddy(localAgentUrl, authToken);
     } catch (err) {
@@ -1808,7 +2358,7 @@ async function main() {
     }
     process.exit(1);
   }
-  const localBuddyRepo = health.repo ? resolve2(health.repo) : "";
+  const localBuddyRepo = health.repo ? resolve3(health.repo) : "";
   if (!localBuddyRepo) {
     stopAutoStartedServices();
     console.error("[pushpals] LocalBuddy health response did not include repo path.");
@@ -1826,7 +2376,7 @@ async function main() {
   if (sessionId && sessionId !== localBuddySessionId) {
     console.warn(`[pushpals] Requested sessionId=${sessionId}, but LocalBuddy is currently attached to sessionId=${localBuddySessionId}.`);
   }
-  const statePath = resolve2(repoRoot, ".git", "pushpals-cli-state.json");
+  const statePath = resolve3(repoRoot, ".git", "pushpals-cli-state.json");
   const saved = readCliState(statePath);
   const preferredHubUrl = normalizeUrl(parsed.monitoringHubUrl ?? process.env.PUSHPALS_MONITOR_URL ?? saved.monitoringHubUrl ?? "");
   const monitorPort = parsePositiveInt(process.env.PUSHPALS_CLIENT_PORT, DEFAULT_MONITOR_PORT);
@@ -1951,6 +2501,12 @@ if (import.meta.main) {
 }
 export {
   startEmbeddedMonitoringHub,
+  resolveCommandPath,
+  resolveBundledRuntimeAssetSource,
+  prepareCliRuntime,
+  normalizeChildProcessEnv,
+  buildServiceStopCommand,
+  buildOpenMonitoringHubCommand,
   buildEmbeddedRuntimeEnv,
   buildEmbeddedMonitoringHubHtml
 };