@pushpalsdev/cli 1.0.5 → 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,15 +743,327 @@ 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;
+var MONITOR_POLL_MS = 2000;
 var HTTP_TIMEOUT_MS = 2500;
 var LOCALBUDDY_TIMEOUT_MS = 4000;
 var SSE_RECONNECT_MS = 1500;
 var DEFAULT_RUNTIME_BOOT_TIMEOUT_MS = 90000;
 var DEFAULT_RUNTIME_BOOT_POLL_MS = 1000;
 var DEFAULT_SERVER_BOOT_TIMEOUT_MS = 20000;
+var DEFAULT_SERVICE_STABILITY_GRACE_MS = 4000;
 var GITHUB_OWNER = "PushPalsDev";
 var GITHUB_REPO = "pushpals";
 var GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}`;
@@ -853,11 +1169,14 @@ 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;
 }
+function jsonHtmlBootstrap(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
 async function runGit(args, cwd) {
   const proc = Bun.spawn(["git", ...args], {
     cwd,
@@ -878,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();
@@ -932,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) {
@@ -958,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`);
   }
@@ -973,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);
     }
@@ -990,25 +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,
+    ...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 "";
@@ -1042,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);
@@ -1112,10 +1549,25 @@ function spawnRuntimeService(name, command, cwd, env, logPath) {
 function stopRuntimeServices(services) {
   for (const service of services) {
     try {
-      service.proc.kill();
+      if (process.platform === "win32" && typeof service.proc.pid === "number" && service.proc.pid > 0) {
+        Bun.spawnSync(["taskkill", "/PID", String(service.proc.pid), "/T", "/F"], {
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "ignore"
+        });
+      } else {
+        service.proc.kill();
+      }
     } catch {}
   }
 }
+async function repoHasRemote(repoRoot, remote) {
+  const normalizedRemote = remote.trim();
+  if (!normalizedRemote)
+    return false;
+  const result = await runGit(["remote", "get-url", normalizedRemote], repoRoot);
+  return result.ok && Boolean(result.stdout);
+}
 async function probeServer(serverUrl) {
   try {
     const response = await fetchWithTimeout(`${serverUrl}/healthz`, {}, HTTP_TIMEOUT_MS);
@@ -1162,21 +1614,22 @@ 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}`);
-  const runtimeEnv = {
-    ...process.env,
-    PUSHPALS_REPO_ROOT_OVERRIDE: opts.repoRoot,
-    PUSHPALS_PROJECT_ROOT_OVERRIDE: opts.repoRoot,
-    PUSHPALS_CONFIG_DIR_OVERRIDE: join2(runtimeRoot, "configs"),
-    PUSHPALS_PROMPTS_ROOT_OVERRIDE: runtimeRoot,
-    PUSHPALS_PROTOCOL_SCHEMAS_DIR: join2(runtimeRoot, "protocol", "schemas")
-  };
+  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,
+    useRuntimeConfig: opts.preparedRuntime.preflightUsesEmbeddedRuntime
+  });
   const services = [];
   const runToken = timestampFileToken();
   const logDir = join2(runtimeRoot, "logs", "bootstrap");
@@ -1224,11 +1677,14 @@ ${tail}` : ""}`);
   services.push(remotebuddyService);
   console.log(`[pushpals] remotebuddy log: ${remotebuddyService.logPath}`);
   const scmHealthy = await probeSourceControlManager(opts.sourceControlManagerPort);
-  if (!scmHealthy) {
+  const scmRemoteAvailable = await repoHasRemote(opts.repoRoot, opts.sourceControlManagerRemote);
+  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}`);
+  } else if (!scmRemoteAvailable) {
+    console.log(`[pushpals] Repo has no git remote "${opts.sourceControlManagerRemote}"; skipping embedded SourceControlManager.`);
   } else {
     console.log("[pushpals] SourceControlManager already healthy; skipping embedded start.");
   }
@@ -1256,6 +1712,19 @@ ${tail}` : ""}`);
     }
     const health = await probeLocalBuddy(opts.localAgentUrl, opts.authToken);
     if (health?.ok) {
+      const stabilityDeadline = Date.now() + DEFAULT_SERVICE_STABILITY_GRACE_MS;
+      while (Date.now() < stabilityDeadline) {
+        for (const service of services) {
+          if (!service.exited)
+            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 ? `
+--- ${service.name} log tail ---
+${tail}` : ""}`);
+        }
+        await Bun.sleep(250);
+      }
       console.log("[pushpals] Embedded runtime is ready.");
       return services;
     }
@@ -1265,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 {};
@@ -1309,17 +1778,221 @@ async function looksLikeMonitoringHub(url) {
     return false;
   }
 }
-async function resolveMonitoringHubUrl(preferredUrl, fallbackPort) {
-  const explicit = normalizeUrl(preferredUrl);
-  if (explicit)
-    return explicit;
-  const basePort = fallbackPort;
-  for (let port = basePort;port < basePort + MONITOR_SCAN_PORTS; port++) {
-    const candidate = `http://localhost:${port}`;
-    if (await looksLikeMonitoringHub(candidate))
-      return candidate;
+function buildEmbeddedMonitoringHubHtml(opts) {
+  const bootstrap = jsonHtmlBootstrap(opts);
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>PushPals CLI Monitor</title>
+  <style>
+    :root { color-scheme: dark; --bg:#08111b; --panel:#112235; --panel2:#16324a; --line:#2b5876; --fg:#edf6ff; --muted:#90b5d6; --accent:#58d8c3; --warn:#ffbf5f; --bad:#ff7f7f; }
+    * { box-sizing:border-box; }
+    body { margin:0; font-family:Consolas, "SFMono-Regular", monospace; background:radial-gradient(circle at top, #0d2233, var(--bg) 56%); color:var(--fg); }
+    main { max-width:1200px; margin:0 auto; padding:24px; }
+    h1,h2 { margin:0 0 12px; }
+    p { color:var(--muted); }
+    .row { display:grid; gap:16px; margin-top:16px; }
+    .cards { grid-template-columns:repeat(auto-fit,minmax(180px,1fr)); }
+    .panels { grid-template-columns:repeat(auto-fit,minmax(320px,1fr)); }
+    .card, .panel { border:1px solid var(--line); background:linear-gradient(180deg,var(--panel),var(--panel2)); border-radius:16px; padding:16px; box-shadow:0 12px 40px rgba(0,0,0,.22); }
+    .label { font-size:12px; letter-spacing:.12em; text-transform:uppercase; color:var(--muted); margin-bottom:10px; }
+    .value { font-size:32px; font-weight:700; color:var(--accent); }
+    .sub { margin-top:8px; color:var(--muted); white-space:pre-wrap; word-break:break-word; }
+    .list { display:grid; gap:10px; margin-top:12px; }
+    .item { border:1px solid rgba(88,216,195,.18); border-radius:12px; padding:12px; background:rgba(8,17,27,.42); }
+    .meta { display:flex; flex-wrap:wrap; gap:8px; margin:12px 0 0; }
+    .pill { border:1px solid var(--line); border-radius:999px; padding:6px 10px; color:var(--muted); }
+    a { color:var(--accent); }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>PushPals CLI Monitor</h1>
+    <p>Lightweight embedded monitor for CLI-managed runtimes.</p>
+    <div class="meta" id="meta"></div>
+    <section class="row cards" id="cards"></section>
+    <section class="row panels">
+      <div class="panel">
+        <h2>Requests</h2>
+        <div id="requests" class="list"></div>
+      </div>
+      <div class="panel">
+        <h2>Jobs</h2>
+        <div id="jobs" class="list"></div>
+      </div>
+      <div class="panel">
+        <h2>Completions</h2>
+        <div id="completions" class="list"></div>
+      </div>
+    </section>
+  </main>
+  <script>
+    const boot = ${bootstrap};
+    const pollMs = ${MONITOR_POLL_MS};
+    const metaEl = document.getElementById("meta");
+    const cardsEl = document.getElementById("cards");
+    const requestsEl = document.getElementById("requests");
+    const jobsEl = document.getElementById("jobs");
+    const completionsEl = document.getElementById("completions");
+
+    function esc(value) {
+      return String(value ?? "")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+    }
+
+    async function fetchJson(path) {
+      const res = await fetch(path, { cache: "no-store" });
+      if (!res.ok) throw new Error(path + " -> HTTP " + res.status);
+      return await res.json();
+    }
+
+    function setList(target, rows, emptyLabel, formatter) {
+      if (!Array.isArray(rows) || rows.length === 0) {
+        target.innerHTML = '<div class="item">' + esc(emptyLabel) + "</div>";
+        return;
+      }
+      target.innerHTML = rows.map((row) => '<div class="item">' + formatter(row) + "</div>").join("");
+    }
+
+    function renderStatus(status) {
+      const workers = status?.workers ?? {};
+      const queues = status?.queues ?? {};
+      const runtime = status?.runtime ?? {};
+      const repo = status?.repo ?? {};
+      const llmUsage = status?.llmUsage ?? {};
+      const cards = [
+        { label: "Server uptime", value: Math.round((Number(runtime.uptimeMs ?? 0) / 60000)) + "m", sub: runtime.startedAt ?? "unknown" },
+        { label: "Workers online", value: String(workers.online ?? 0), sub: "busy " + String(workers.busy ?? 0) + " | idle " + String(workers.idle ?? 0) },
+        { label: "Pending requests", value: String(queues.requests?.pending ?? 0), sub: "claimed " + String(queues.requests?.claimed ?? 0) },
+        { label: "Pending jobs", value: String(queues.jobs?.pending ?? 0), sub: "claimed " + String(queues.jobs?.claimed ?? 0) },
+        { label: "Completions", value: String(queues.completions?.pending ?? 0), sub: "processed " + String(queues.completions?.processed ?? 0) },
+        { label: "LLM usage (24h)", value: String(llmUsage.totalTokens ?? 0), sub: "calls " + String(llmUsage.totalCalls ?? 0) }
+      ];
+      cardsEl.innerHTML = cards.map((card) => '<div class="card"><div class="label">' + esc(card.label) + '</div><div class="value">' + esc(card.value) + '</div><div class="sub">' + esc(card.sub) + '</div></div>').join("");
+      metaEl.innerHTML = [
+        '<span class="pill">server ' + esc(boot.serverUrl) + '</span>',
+        '<span class="pill">localbuddy ' + esc(boot.localAgentUrl) + '</span>',
+        '<span class="pill">session ' + esc(boot.sessionId) + '</span>',
+        '<span class="pill">repo ' + esc(repo?.root ?? repo?.remoteUrl ?? "current repo") + '</span>'
+      ].join("");
+    }
+
+    function render() {
+      Promise.all([
+        fetchJson('/api/status'),
+        fetchJson('/api/requests'),
+        fetchJson('/api/jobs'),
+        fetchJson('/api/completions')
+      ]).then(([status, requests, jobs, completions]) => {
+        renderStatus(status);
+        setList(requestsEl, requests?.requests?.slice(0, 8), 'No requests', (row) =>
+          '<strong>' + esc(row?.priority ?? 'request') + '</strong><div class="sub">' +
+          esc((row?.status ?? 'unknown') + ' | ' + (row?.id ?? '')) + '</div><div class="sub">' +
+          esc(String(row?.prompt ?? '').slice(0, 220)) + '</div>');
+        setList(jobsEl, jobs?.jobs?.slice(0, 8), 'No jobs', (row) =>
+          '<strong>' + esc(row?.kind ?? 'job') + '</strong><div class="sub">' +
+          esc((row?.status ?? 'unknown') + ' | worker ' + (row?.workerId ?? '--')) + '</div><div class="sub">' +
+          esc((row?.summary ?? row?.error ?? row?.id ?? '').slice(0, 220)) + '</div>');
+        setList(completionsEl, completions?.completions?.slice(0, 8), 'No completions', (row) =>
+          '<strong>' + esc(row?.status ?? 'completion') + '</strong><div class="sub">' +
+          esc((row?.jobId ?? '') + ' | ' + (row?.commitSha ?? '')) + '</div><div class="sub">' +
+          esc((row?.message ?? '').slice(0, 220)) + '</div>');
+      }).catch((err) => {
+        cardsEl.innerHTML = '<div class="card"><div class="label">Monitor error</div><div class="sub">' + esc(err?.message ?? err) + '</div></div>';
+      });
+    }
+
+    render();
+    setInterval(render, pollMs);
+  </script>
+</body>
+</html>`;
+}
+async function proxyMonitoringHubRequest(serverUrl, authToken, pathValue) {
+  const target = `${serverUrl}${pathValue}`;
+  const upstream = await fetchWithTimeout(target, { headers: authHeaders(authToken) }, 1e4);
+  const body = await upstream.text();
+  return new Response(body, {
+    status: upstream.status,
+    headers: {
+      "content-type": String(upstream.headers.get("content-type") ?? "application/json"),
+      "cache-control": "no-store"
+    }
+  });
+}
+async function startEmbeddedMonitoringHub(opts) {
+  const html = buildEmbeddedMonitoringHubHtml({
+    serverUrl: opts.serverUrl,
+    localAgentUrl: opts.localAgentUrl,
+    sessionId: opts.sessionId
+  });
+  const candidatePorts = Array.from({ length: MONITOR_SCAN_PORTS }, (_, index) => opts.preferredPort + index).concat(0);
+  for (const port of candidatePorts) {
+    try {
+      const server = Bun.serve({
+        port,
+        idleTimeout: 30,
+        fetch: async (req) => {
+          const url = new URL(req.url);
+          if (url.pathname === "/") {
+            return new Response(html, {
+              headers: {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store"
+              }
+            });
+          }
+          if (url.pathname === "/healthz") {
+            return Response.json({ ok: true, port, serverUrl: opts.serverUrl, sessionId: opts.sessionId });
+          }
+          if (url.pathname === "/api/status") {
+            return await proxyMonitoringHubRequest(opts.serverUrl, opts.authToken, "/system/status");
+          }
+          if (url.pathname === "/api/requests") {
+            return await proxyMonitoringHubRequest(opts.serverUrl, opts.authToken, "/requests?status=all&limit=20");
+          }
+          if (url.pathname === "/api/jobs") {
+            return await proxyMonitoringHubRequest(opts.serverUrl, opts.authToken, "/jobs?status=all&limit=20");
+          }
+          if (url.pathname === "/api/completions") {
+            return await proxyMonitoringHubRequest(opts.serverUrl, opts.authToken, "/completions?status=all&limit=20");
+          }
+          return new Response("Not found", { status: 404 });
+        }
+      });
+      return {
+        url: `http://127.0.0.1:${server.port}`,
+        port: Number(server.port),
+        embedded: true,
+        stop: () => server.stop(true)
+      };
+    } catch {}
   }
-  return `http://localhost:${basePort}`;
+  return null;
+}
+async function resolveMonitoringHub(opts) {
+  const explicit = normalizeUrl(opts.preferredUrl);
+  if (explicit) {
+    if (await looksLikeMonitoringHub(explicit)) {
+      return { url: explicit, port: 0, stop: () => {}, embedded: false };
+    }
+    console.warn(`[pushpals] Preferred monitoring hub ${explicit} is unavailable; starting embedded monitor instead.`);
+  }
+  for (let port = opts.fallbackPort;port < opts.fallbackPort + MONITOR_SCAN_PORTS; port++) {
+    const candidate = `http://127.0.0.1:${port}`;
+    if (await looksLikeMonitoringHub(candidate)) {
+      return { url: candidate, port, stop: () => {}, embedded: false };
+    }
+  }
+  const embedded = await startEmbeddedMonitoringHub(opts);
+  if (!embedded) {
+    console.warn("[pushpals] Embedded monitoring hub could not start on any expected local port.");
+  }
+  return embedded;
 }
 async function sendMessageToLocalBuddy(localAgentUrl, text) {
   let response;
@@ -1493,8 +2166,7 @@ async function runSessionStream(serverUrl, sessionId, authToken, print, signal)
 async function openMonitoringHub(url) {
   let cmd = null;
   if (process.platform === "win32") {
-    const escaped = url.replace(/'/g, "''");
-    cmd = ["powershell", "-NoProfile", "-Command", `Start-Process '${escaped}'`];
+    cmd = ["cmd", "/c", "start", "", url];
   } else if (process.platform === "darwin") {
     cmd = ["open", url];
   } else {
@@ -1514,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) {
@@ -1523,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();
@@ -1542,9 +2232,10 @@ async function main() {
         serverUrl,
         localAgentUrl,
         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) {
@@ -1561,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.");
@@ -1579,20 +2270,35 @@ 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);
-  const monitoringHubUrl = await resolveMonitoringHubUrl(preferredHubUrl, monitorPort);
+  const monitoringHub = await resolveMonitoringHub({
+    preferredUrl: preferredHubUrl,
+    fallbackPort: monitorPort,
+    serverUrl,
+    localAgentUrl,
+    sessionId: localBuddySessionId,
+    authToken
+  });
+  const monitoringHubUrl = monitoringHub?.url ?? "";
   writeCliState(statePath, {
-    monitoringHubUrl,
+    monitoringHubUrl: monitoringHubUrl || undefined,
     serverUrl,
     localAgentUrl,
     sessionId: localBuddySessionId,
     repoRoot
   });
   console.log("[pushpals] Connected.");
-  console.log(`monitoringHubUrl=${monitoringHubUrl}`);
+  if (monitoringHubUrl) {
+    console.log(`monitoringHubUrl=${monitoringHubUrl}`);
+    if (monitoringHub?.embedded) {
+      console.log("[pushpals] Embedded monitoring hub is running.");
+    }
+  } else {
+    console.log("monitoringHubUrl=unavailable");
+  }
   console.log(`serverUrl=${serverUrl}`);
   console.log(`localAgentUrl=${localAgentUrl}`);
   console.log(`sessionId=${localBuddySessionId}`);
@@ -1622,10 +2328,14 @@ ${line}
     streamAbort.abort();
     if (rl)
       rl.close();
+    try {
+      monitoringHub?.stop();
+    } catch {}
     stopAutoStartedServices();
   };
   process.once("SIGINT", requestStop);
   process.once("SIGTERM", requestStop);
+  process.once("exit", requestStop);
   rl = createInterface({
     input: process.stdin,
     output: process.stdout,
@@ -1644,20 +2354,25 @@ ${line}
       break;
     }
     if (text === "/hub") {
-      console.log(`monitoringHubUrl=${monitoringHubUrl}`);
+      console.log(monitoringHubUrl ? `monitoringHubUrl=${monitoringHubUrl}` : "monitoringHubUrl=unavailable");
       rl.prompt();
       continue;
     }
     if (text === "/status") {
       console.log(`serverUrl=${serverUrl}`);
       console.log(`localAgentUrl=${localAgentUrl}`);
-      console.log(`sessionId=${sessionId}`);
+      console.log(`sessionId=${localBuddySessionId}`);
       console.log(`repoRoot=${repoRoot}`);
-      console.log(`monitoringHubUrl=${monitoringHubUrl}`);
+      console.log(monitoringHubUrl ? `monitoringHubUrl=${monitoringHubUrl}` : "monitoringHubUrl=unavailable");
       rl.prompt();
       continue;
     }
     if (text === "/open") {
+      if (!monitoringHubUrl) {
+        console.log("[pushpals] Monitoring hub is unavailable.");
+        rl.prompt();
+        continue;
+      }
       const opened = await openMonitoringHub(monitoringHubUrl);
       console.log(opened ? `[pushpals] Opened ${monitoringHubUrl}` : `[pushpals] Failed to open browser. Use this link: ${monitoringHubUrl}`);
       rl.prompt();
@@ -1672,7 +2387,16 @@ ${line}
   requestStop();
   await Promise.race([streamTask, Bun.sleep(2000)]);
 }
-main().catch((err) => {
-  console.error(`[pushpals] Fatal: ${String(err)}`);
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(`[pushpals] Fatal: ${String(err)}`);
+    process.exit(1);
+  });
+}
+export {
+  startEmbeddedMonitoringHub,
+  resolveBundledRuntimeAssetSource,
+  prepareCliRuntime,
+  buildEmbeddedRuntimeEnv,
+  buildEmbeddedMonitoringHubHtml
+};