@pushpalsdev/cli 1.0.6 → 1.0.7

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,77 @@ 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 useRuntimeConfig = opts.useRuntimeConfig !== false;
   return {
     ...baseEnv,
     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,
-    PUSHPALS_PROTOCOL_SCHEMAS_DIR: join2(opts.runtimeRoot, "protocol", "schemas"),
-    REMOTEBUDDY_AUTONOMY_ENABLED: String(baseEnv.REMOTEBUDDY_AUTONOMY_ENABLED ?? "").trim() || "false"
+    ...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")
   };
 }
 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 +1479,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);
@@ -1193,16 +1614,21 @@ 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 services = [];
   const runToken = timestampFileToken();
@@ -1308,10 +1734,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 {};
@@ -1760,7 +2186,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 +2194,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 +2234,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 +2252,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 +2270,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 +2395,8 @@ if (import.meta.main) {
 }
 export {
   startEmbeddedMonitoringHub,
+  resolveBundledRuntimeAssetSource,
+  prepareCliRuntime,
   buildEmbeddedRuntimeEnv,
   buildEmbeddedMonitoringHubHtml
 };