@pushpalsdev/cli 1.0.15 → 1.0.17

package/dist/pushpals-cli.js

@@ -11,9 +11,10 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync as readFileSync4,
+  rmSync,
   writeFileSync
 } from "fs";
-import { basename, delimiter, dirname, extname, join as join2, resolve as resolve4 } from "path";
+import { basename, delimiter, dirname, extname, join as join2, resolve as resolve4, win32 as pathWin32 } from "path";
 import { createInterface } from "readline";
 
 // ../shared/src/client_preflight.ts
@@ -1257,6 +1258,7 @@ function printUsage() {
   console.log("  --no-auto-start        Disable runtime auto-start when the server is down");
   console.log("  --no-stream            Disable live session event stream");
   console.log("  --runtime-only         Start the local runtime and wait for shutdown without opening the interactive chat");
+  console.log("  --clear                Remove repo-local PushPals state and exit");
   console.log("  -h, --help             Show this help");
   console.log("");
   console.log("Chat commands:");
@@ -1271,7 +1273,12 @@ function printUsage() {
   console.log("  - Interactive CLI talks directly to server sessions; LocalBuddy is optional.");
 }
 function parseArgs(argv) {
-  const options = { noAutoStart: false, noStream: false, runtimeOnly: false };
+  const options = {
+    noAutoStart: false,
+    noStream: false,
+    runtimeOnly: false,
+    clear: false
+  };
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "-h" || arg === "--help") {
@@ -1290,6 +1297,10 @@ function parseArgs(argv) {
       options.runtimeOnly = true;
       continue;
     }
+    if (arg === "--clear") {
+      options.clear = true;
+      continue;
+    }
     if (arg === "--server-url") {
       options.serverUrl = argv[++i];
       continue;
@@ -1358,23 +1369,35 @@ function parsePositiveInt(value, fallback) {
 function jsonHtmlBootstrap(value) {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
+async function runGitWithEnv(args, cwd, env) {
+  try {
+    const proc = Bun.spawn(["git", ...args], {
+      cwd,
+      env,
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    return { ok: exitCode === 0, stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+  } catch (err) {
+    return {
+      ok: false,
+      stdout: "",
+      stderr: err instanceof Error ? err.message : String(err),
+      exitCode: -1
+    };
+  }
+}
 async function runGit(args, cwd) {
-  const proc = Bun.spawn(["git", ...args], {
-    cwd,
-    env: {
-      ...process.env,
-      GIT_TERMINAL_PROMPT: "0",
-      GCM_INTERACTIVE: "Never"
-    },
-    stdout: "pipe",
-    stderr: "pipe"
+  return await runGitWithEnv(args, cwd, {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: "0",
+    GCM_INTERACTIVE: "Never"
   });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited
-  ]);
-  return { ok: exitCode === 0, stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
 }
 async function resolveCurrentGitRepoRoot(cwd) {
   const inside = await runGit(["rev-parse", "--is-inside-work-tree"], cwd);
@@ -1535,25 +1558,24 @@ async function fetchLatestReleaseTag() {
     throw new Error("Latest release payload did not include tag_name");
   return tagName;
 }
-async function resolveRuntimeReleaseTag(explicitTag) {
+function resolvePreferredRuntimeReleaseTag(explicitTag, env = process.env) {
   const fromArg = String(explicitTag ?? "").trim();
   if (fromArg)
     return fromArg;
-  const fromEnv = String(process.env.PUSHPALS_RUNTIME_TAG ?? "").trim();
+  const fromEnv = String(env.PUSHPALS_RUNTIME_TAG ?? "").trim();
   if (fromEnv)
     return fromEnv;
-  const packageVersion = parseSemverFromPackageVersion(process.env.PUSHPALS_CLI_PACKAGE_VERSION);
+  const packageVersion = parseSemverFromPackageVersion(env.PUSHPALS_CLI_PACKAGE_VERSION);
+  if (packageVersion)
+    return `v${packageVersion}`;
+  return "";
+}
+async function resolveRuntimeReleaseTag(explicitTag) {
+  const preferredTag = resolvePreferredRuntimeReleaseTag(explicitTag, process.env);
+  if (preferredTag)
+    return preferredTag;
   console.log("[pushpals] Resolving embedded runtime release tag from GitHub...");
-  try {
-    return await fetchLatestReleaseTag();
-  } catch (err) {
-    if (packageVersion) {
-      const fallbackTag = `v${packageVersion}`;
-      console.warn(`[pushpals] Could not resolve latest runtime tag; falling back to package version tag ${fallbackTag}: ${String(err)}`);
-      return fallbackTag;
-    }
-    throw err;
-  }
+  return await fetchLatestReleaseTag();
 }
 function writeTextFileIfMissing(pathValue, text) {
   if (existsSync4(pathValue))
@@ -1751,10 +1773,7 @@ function normalizeChildProcessEnv(baseEnv, platform = process.platform) {
   return env;
 }
 async function resolveCommandPath(command, cwd, env) {
-  const lookupCommands = process.platform === "win32" ? [
-    ["where.exe", command],
-    ["where", command]
-  ] : [["which", command]];
+  const lookupCommands = process.platform === "win32" ? resolveWindowsWhereExecutableCandidatesForEnv(env, process.platform).map((lookup) => [lookup, command]) : [["which", command]];
   for (const lookup of lookupCommands) {
     try {
       const proc = Bun.spawn(lookup, {
@@ -1848,12 +1867,14 @@ async function ensureRuntimeBinaries(runtimeRoot, runtimeTag) {
     server: join2(binDir, runtimeBinaryFilename("server", platformKey)),
     localbuddy: join2(binDir, runtimeBinaryFilename("localbuddy", platformKey)),
     remotebuddy: join2(binDir, runtimeBinaryFilename("remotebuddy", platformKey)),
+    workerpals: join2(binDir, runtimeBinaryFilename("workerpals", platformKey)),
     sourceControlManager: join2(binDir, runtimeBinaryFilename("source_control_manager", platformKey))
   };
   const requiredAssets = [
     runtimeBinaries.server,
     runtimeBinaries.localbuddy,
     runtimeBinaries.remotebuddy,
+    runtimeBinaries.workerpals,
     runtimeBinaries.sourceControlManager
   ];
   let downloadedCount = 0;
@@ -1999,6 +2020,83 @@ function applyResolvedGitBinaryToRuntimeEnv(env, resolvedGitBinary, platform = p
   }
   return env;
 }
+function resolveRuntimeGitExecutableCandidates(env, platform = process.platform) {
+  const candidates = [];
+  const seen = new Set;
+  const pushCandidate = (value) => {
+    const trimmed = String(value ?? "").trim();
+    if (!trimmed)
+      return;
+    const key = platform === "win32" ? trimmed.toLowerCase() : trimmed;
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    candidates.push(trimmed);
+  };
+  pushCandidate(env.PUSHPALS_GIT_BIN ?? "");
+  pushCandidate(env.PUSHPALS_GIT_BIN_ABSOLUTE ?? "");
+  pushCandidate(platform === "win32" ? "git.exe" : "git");
+  pushCandidate("git");
+  return candidates;
+}
+function resolveWindowsShellExecutableCandidatesForEnv(env, platform = process.platform) {
+  if (platform !== "win32")
+    return [];
+  const candidates = [];
+  const seen = new Set;
+  const pushCandidate = (value) => {
+    const trimmed = String(value ?? "").trim();
+    if (!trimmed)
+      return;
+    const key = trimmed.toLowerCase();
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    candidates.push(trimmed);
+  };
+  const comSpec = String(env.ComSpec ?? env.COMSPEC ?? process.env.ComSpec ?? process.env.COMSPEC ?? "").trim();
+  const systemRoot = String(env.SystemRoot ?? env.SYSTEMROOT ?? process.env.SystemRoot ?? process.env.SYSTEMROOT ?? "").trim();
+  pushCandidate(comSpec);
+  if (systemRoot) {
+    pushCandidate(pathWin32.join(systemRoot, "System32", "cmd.exe"));
+    pushCandidate(pathWin32.join(systemRoot, "Sysnative", "cmd.exe"));
+  }
+  pushCandidate("cmd.exe");
+  return candidates;
+}
+function resolveWindowsWhereExecutableCandidatesForEnv(env, platform = process.platform) {
+  if (platform !== "win32")
+    return [];
+  const candidates = [];
+  const seen = new Set;
+  const pushCandidate = (value) => {
+    const trimmed = String(value ?? "").trim();
+    if (!trimmed)
+      return;
+    const key = trimmed.toLowerCase();
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    candidates.push(trimmed);
+  };
+  const systemRoot = String(env.SystemRoot ?? env.SYSTEMROOT ?? process.env.SystemRoot ?? process.env.SYSTEMROOT ?? "").trim();
+  if (systemRoot) {
+    pushCandidate(pathWin32.join(systemRoot, "System32", "where.exe"));
+    pushCandidate(pathWin32.join(systemRoot, "Sysnative", "where.exe"));
+  }
+  pushCandidate("where.exe");
+  pushCandidate("where");
+  return candidates;
+}
+function quoteWindowsCmdArg(value) {
+  const text = String(value ?? "");
+  if (!text.length)
+    return '""';
+  if (!/[ \t"]/.test(text))
+    return text;
+  const escaped = text.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/g, "$1$1");
+  return `"${escaped}"`;
+}
 function isOptionalEmbeddedService(name) {
   return name === "source_control_manager";
 }
@@ -2017,12 +2115,107 @@ async function canSpawnCommand(command, cwd, env) {
     return false;
   }
 }
-async function repoHasRemote(repoRoot, remote) {
-  const normalizedRemote = remote.trim();
-  if (!normalizedRemote)
+async function canSpawnGitViaWindowsShell(commandArgs, cwd, env, platform = process.platform) {
+  if (platform !== "win32")
     return false;
-  const result = await runGit(["remote", "get-url", normalizedRemote], repoRoot);
-  return result.ok && Boolean(result.stdout);
+  const commandLine = commandArgs.map((arg) => quoteWindowsCmdArg(arg)).join(" ");
+  for (const shellExecutable of resolveWindowsShellExecutableCandidatesForEnv(env, platform)) {
+    try {
+      const proc = Bun.spawn([shellExecutable, "/d", "/s", "/c", commandLine], {
+        cwd,
+        env,
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore"
+      });
+      const exitCode = await proc.exited;
+      return exitCode === 0;
+    } catch {}
+  }
+  return false;
+}
+async function resolveSourceControlManagerGitProbe(cwd, env, platform = process.platform) {
+  const candidates = resolveRuntimeGitExecutableCandidates(env, platform);
+  for (const candidate of candidates) {
+    if (await canSpawnCommand([candidate, "--version"], cwd, env)) {
+      return { ok: true, detail: candidate };
+    }
+  }
+  if (platform === "win32") {
+    for (const candidate of candidates) {
+      if (await canSpawnGitViaWindowsShell([candidate, "--version"], cwd, env, platform)) {
+        return { ok: true, detail: `${candidate} via shell` };
+      }
+    }
+  }
+  return {
+    ok: false,
+    detail: candidates.join(", ") || "git"
+  };
+}
+async function precheckSourceControlManagerGitAvailability(opts) {
+  const platform = opts.platform ?? process.platform;
+  const env = buildEmbeddedRuntimeEnv(opts.baseEnv ?? process.env, {
+    repoRoot: opts.repoRoot,
+    runtimeRoot: opts.runtimeRoot,
+    useRuntimeConfig: opts.preflightUsesEmbeddedRuntime,
+    sessionId: opts.sessionId
+  });
+  if (env.PUSHPALS_GIT_BIN) {
+    applyResolvedGitBinaryToRuntimeEnv(env, env.PUSHPALS_GIT_BIN, platform);
+  }
+  const remoteStatus = opts.gitRemoteCheckFn ? await opts.gitRemoteCheckFn(opts.repoRoot, opts.remote, env) : opts.repoHasRemoteFn ? await opts.repoHasRemoteFn(opts.repoRoot, opts.remote) ? { status: "ok", remote: opts.remote } : { status: "missing_remote", remote: opts.remote } : await checkGitRemoteConfigured(opts.repoRoot, opts.remote, env);
+  if (remoteStatus.status === "missing_remote") {
+    return {
+      status: "skipped",
+      detail: `git remote "${opts.remote}" is not configured`,
+      env
+    };
+  }
+  if (remoteStatus.status === "error") {
+    return {
+      status: "failed",
+      detail: `git remote "${opts.remote}" could not be inspected: ${remoteStatus.detail}`,
+      env
+    };
+  }
+  const gitLookupCommand = typeof env.PUSHPALS_GIT_BIN === "string" && env.PUSHPALS_GIT_BIN.trim() ? env.PUSHPALS_GIT_BIN.trim() : platform === "win32" ? "git.exe" : "git";
+  const resolvedGitBinary = await (opts.resolveCommandPathFn ?? resolveCommandPath)(gitLookupCommand, opts.repoRoot, env);
+  if (resolvedGitBinary) {
+    applyResolvedGitBinaryToRuntimeEnv(env, resolvedGitBinary, platform);
+  }
+  const gitProbe = await (opts.gitProbeFn ?? resolveSourceControlManagerGitProbe)(opts.repoRoot, env, platform);
+  if (!gitProbe.ok) {
+    return {
+      status: "failed",
+      detail: gitProbe.detail,
+      env
+    };
+  }
+  return {
+    status: "ok",
+    detail: gitProbe.detail,
+    env
+  };
+}
+async function checkGitRemoteConfigured(repoRoot, remote, env) {
+  const normalizedRemote = String(remote ?? "").trim();
+  if (!normalizedRemote) {
+    return { status: "missing_remote", remote: normalizedRemote };
+  }
+  const result = await runGitWithEnv(["remote", "get-url", normalizedRemote], repoRoot, env ?? {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: "0",
+    GCM_INTERACTIVE: "Never"
+  });
+  if (result.ok && result.stdout) {
+    return { status: "ok", remote: normalizedRemote };
+  }
+  const detail = result.stderr || result.stdout || `exit ${result.exitCode}`;
+  if (/no such remote/i.test(detail)) {
+    return { status: "missing_remote", remote: normalizedRemote };
+  }
+  return { status: "error", remote: normalizedRemote, detail };
 }
 async function checkPushpalsBranchOnRemote(repoRoot, remote, branch) {
   const normalizedRemote = String(remote ?? "").trim();
@@ -2030,10 +2223,18 @@ async function checkPushpalsBranchOnRemote(repoRoot, remote, branch) {
   if (!normalizedRemote || !normalizedBranch) {
     return { status: "ok" };
   }
-  const hasRemote = await repoHasRemote(repoRoot, normalizedRemote);
-  if (!hasRemote) {
+  const remoteStatus = await checkGitRemoteConfigured(repoRoot, normalizedRemote);
+  if (remoteStatus.status === "missing_remote") {
     return { status: "missing_remote", remote: normalizedRemote };
   }
+  if (remoteStatus.status === "error") {
+    return {
+      status: "error",
+      remote: normalizedRemote,
+      branch: normalizedBranch,
+      detail: remoteStatus.detail
+    };
+  }
   const ref = `refs/heads/${normalizedBranch}`;
   const result = await runGit(["ls-remote", "--heads", normalizedRemote, ref], repoRoot);
   if (!result.ok) {
@@ -2070,6 +2271,151 @@ async function enforcePushpalsRemoteBranchPrecheck(repoRoot, remote, branch) {
   console.error(`[pushpals] Precheck failed: could not verify remote branch "${result.remote}/${result.branch}": ${result.detail}`);
   return false;
 }
+function isPathEqualOrWithin(parentPath, childPath) {
+  const parent = normalizeRepoPathForComparison(parentPath);
+  const child = normalizeRepoPathForComparison(childPath);
+  return child === parent || child.startsWith(`${parent}/`);
+}
+function appendCliClearTarget(targets, label, pathValue) {
+  const resolvedPath = String(pathValue ?? "").trim();
+  if (!resolvedPath)
+    return;
+  const normalized = normalizeRepoPathForComparison(resolvedPath);
+  if (targets.some((target) => normalizeRepoPathForComparison(target.path) === normalized))
+    return;
+  targets.push({ label, path: resolve4(resolvedPath) });
+}
+function buildCliClearTargets(opts) {
+  const targets = [];
+  const dataDir = resolve4(opts.config.paths.dataDir);
+  appendCliClearTarget(targets, "runtime data", dataDir);
+  const scmStateDir = resolve4(opts.config.sourceControlManager.stateDir);
+  if (!isPathEqualOrWithin(dataDir, scmStateDir)) {
+    appendCliClearTarget(targets, "SourceControlManager state", scmStateDir);
+  }
+  const scmRepoPath = resolve4(opts.config.sourceControlManager.repoPath);
+  if (normalizeRepoPathForComparison(scmRepoPath) !== normalizeRepoPathForComparison(opts.repoRoot) && isPathEqualOrWithin(opts.repoRoot, scmRepoPath)) {
+    appendCliClearTarget(targets, "SourceControlManager worktree", scmRepoPath);
+  }
+  appendCliClearTarget(targets, "CLI state file", opts.cliStatePath ?? null);
+  appendCliClearTarget(targets, "client monitor state file", resolveGitStateFilePath(opts.repoRoot, "pushpals-client-state.json"));
+  appendCliClearTarget(targets, "runtime bootstrap logs", join2(opts.runtimeRoot, "logs", "bootstrap"));
+  return targets;
+}
+function removeCliClearTarget(target) {
+  if (!existsSync4(target.path))
+    return "missing";
+  try {
+    rmSync(target.path, { recursive: true, force: true });
+    return "removed";
+  } catch (err) {
+    return {
+      ...target,
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function requestLocalRuntimeShutdownForClear(serverUrl, repoRoot) {
+  if (!await probeServer(serverUrl)) {
+    return { attempted: false, accepted: false };
+  }
+  try {
+    await ensureServerRepoAffinity(serverUrl, repoRoot);
+  } catch (err) {
+    return {
+      attempted: false,
+      accepted: false,
+      detail: `skipping shutdown because ${String(err)}`
+    };
+  }
+  try {
+    const response = await fetchWithTimeout(`${serverUrl}/admin/shutdown`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ reason: "pushpals --clear" })
+    }, 5000);
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      return {
+        attempted: true,
+        accepted: false,
+        detail: `HTTP ${response.status}${detail ? ` ${detail}` : ""}`
+      };
+    }
+    return { attempted: true, accepted: true };
+  } catch (err) {
+    return {
+      attempted: true,
+      accepted: false,
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function clearPushpalsState(opts) {
+  console.log("[pushpals] Clear requested. Removing repo-local PushPals state.");
+  const shutdown = await requestLocalRuntimeShutdownForClear(opts.serverUrl, opts.repoRoot);
+  if (shutdown.attempted && shutdown.accepted) {
+    console.log("[pushpals] Local runtime shutdown accepted; waiting for services to exit...");
+    await Bun.sleep(1500);
+  } else if (shutdown.attempted) {
+    console.warn(`[pushpals] Local runtime shutdown request was not accepted${shutdown.detail ? `: ${shutdown.detail}` : "."}`);
+  } else if (shutdown.detail) {
+    console.warn(`[pushpals] ${shutdown.detail}`);
+  }
+  const targets = buildCliClearTargets({
+    repoRoot: opts.repoRoot,
+    runtimeRoot: opts.runtimeRoot,
+    config: opts.config,
+    cliStatePath: opts.cliStatePath
+  });
+  const removed = [];
+  const missing = [];
+  let failed = [];
+  for (const target of targets) {
+    const result = removeCliClearTarget(target);
+    if (result === "removed") {
+      removed.push(target);
+      continue;
+    }
+    if (result === "missing") {
+      missing.push(target);
+      continue;
+    }
+    failed.push(result);
+  }
+  if (failed.length > 0 && shutdown.accepted) {
+    await Bun.sleep(1000);
+    const retryFailures = [];
+    for (const failure of failed) {
+      const retry = removeCliClearTarget(failure);
+      if (retry === "removed") {
+        removed.push({ label: failure.label, path: failure.path });
+        continue;
+      }
+      if (retry === "missing") {
+        missing.push({ label: failure.label, path: failure.path });
+        continue;
+      }
+      retryFailures.push(retry);
+    }
+    failed = retryFailures;
+  }
+  for (const target of removed) {
+    console.log(`[pushpals] Cleared ${target.label}: ${target.path}`);
+  }
+  for (const target of missing) {
+    console.log(`[pushpals] Nothing to clear for ${target.label}: ${target.path}`);
+  }
+  for (const failure of failed) {
+    console.error(`[pushpals] Failed to clear ${failure.label}: ${failure.path} (${failure.detail})`);
+  }
+  if (failed.length > 0) {
+    console.error("[pushpals] Clear completed with errors.");
+    return 1;
+  }
+  console.log("[pushpals] Clear completed.");
+  return 0;
+}
 async function probeServer(serverUrl) {
   try {
     const response = await fetchWithTimeout(`${serverUrl}/healthz`, {}, HTTP_TIMEOUT_MS);
@@ -2284,6 +2630,7 @@ async function autoStartRuntimeServices(opts) {
     useRuntimeConfig: opts.preparedRuntime.preflightUsesEmbeddedRuntime,
     sessionId: opts.sessionId
   });
+  runtimeEnv.PUSHPALS_WORKERPALS_BIN = runtimeBinaries.workerpals;
   if (runtimeEnv.PUSHPALS_GIT_BIN) {
     applyResolvedGitBinaryToRuntimeEnv(runtimeEnv, runtimeEnv.PUSHPALS_GIT_BIN);
   }
@@ -2374,27 +2721,25 @@ ${tail}` : ""}`);
   };
   reportRemoteBuddyAutonomousEngineState();
   const scmHealthy = await probeSourceControlManager(opts.sourceControlManagerPort);
-  const scmRemoteAvailable = await repoHasRemote(opts.repoRoot, opts.sourceControlManagerRemote);
-  const gitForScm = typeof runtimeEnv.PUSHPALS_GIT_BIN === "string" && runtimeEnv.PUSHPALS_GIT_BIN.trim() ? runtimeEnv.PUSHPALS_GIT_BIN.trim() : typeof runtimeEnv.PUSHPALS_GIT_BIN_ABSOLUTE === "string" && runtimeEnv.PUSHPALS_GIT_BIN_ABSOLUTE.trim() ? runtimeEnv.PUSHPALS_GIT_BIN_ABSOLUTE.trim() : "git";
-  const gitProbeCommand = [gitForScm, "--version"];
-  const gitAvailableForScm = await canSpawnCommand(gitProbeCommand, opts.repoRoot, runtimeEnv);
-  if (!scmHealthy && scmRemoteAvailable) {
-    if (!gitAvailableForScm) {
+  const scmGitProbe = await resolveSourceControlManagerGitProbe(opts.repoRoot, runtimeEnv, process.platform);
+  const scmRemoteStatus = await checkGitRemoteConfigured(opts.repoRoot, opts.sourceControlManagerRemote, runtimeEnv);
+  if (!scmHealthy) {
+    if (!scmGitProbe.ok) {
       console.warn("[pushpals] Git is not available to embedded SourceControlManager; skipping SCM startup.");
-      appendRuntimeServicesLogLine(runtimeServicesLogPath, "[pushpals] source_control_manager skipped: git is unavailable in embedded runtime env.");
-    } else {
-      console.log(`[pushpals] Embedded SourceControlManager git=${gitForScm}`);
+      appendRuntimeServicesLogLine(runtimeServicesLogPath, `[pushpals] source_control_manager skipped: git is unavailable in embedded runtime env (${scmGitProbe.detail}).`);
+    } else if (scmRemoteStatus.status === "error") {
+      console.warn(`[pushpals] Could not inspect SourceControlManager git remote "${opts.sourceControlManagerRemote}"; skipping SCM startup.`);
+      appendRuntimeServicesLogLine(runtimeServicesLogPath, `[pushpals] source_control_manager skipped: remote "${opts.sourceControlManagerRemote}" could not be inspected (${scmRemoteStatus.detail}).`);
+    } else if (scmRemoteStatus.status === "ok") {
+      console.log(`[pushpals] Embedded SourceControlManager git=${scmGitProbe.detail}`);
       console.log("[pushpals] Starting embedded SourceControlManager...");
       const sourceControlManagerService = spawnRuntimeService("source_control_manager", [runtimeBinaries.sourceControlManager, "--skip-clean-check"], opts.repoRoot, runtimeEnv, serviceLogPaths.source_control_manager, runtimeServicesLogPath);
       services.push(sourceControlManagerService);
       console.log(`[pushpals] source_control_manager log: ${sourceControlManagerService.logPath}`);
+    } else {
+      console.log(`[pushpals] Repo has no git remote "${opts.sourceControlManagerRemote}"; skipping embedded SourceControlManager.`);
+      appendRuntimeServicesLogLine(runtimeServicesLogPath, `[pushpals] source_control_manager skipped: repo has no remote "${opts.sourceControlManagerRemote}".`);
     }
-  } else if (!scmRemoteAvailable) {
-    console.log(`[pushpals] Repo has no git remote "${opts.sourceControlManagerRemote}"; skipping embedded SourceControlManager.`);
-    appendRuntimeServicesLogLine(runtimeServicesLogPath, `[pushpals] source_control_manager skipped: repo has no remote "${opts.sourceControlManagerRemote}".`);
-  } else if (!gitAvailableForScm) {
-    console.warn("[pushpals] Git is not available to embedded SourceControlManager; skipping SCM startup.");
-    appendRuntimeServicesLogLine(runtimeServicesLogPath, "[pushpals] source_control_manager skipped: git is unavailable in embedded runtime env.");
   } else {
     console.log("[pushpals] SourceControlManager already healthy; skipping embedded start.");
     appendRuntimeServicesLogLine(runtimeServicesLogPath, "[pushpals] source_control_manager already healthy; embedded start skipped.");
@@ -2461,7 +2806,10 @@ ${tail}` : ""}`);
       }
       console.log("[pushpals] Embedded runtime is ready.");
       appendRuntimeServicesLogLine(runtimeServicesLogPath, "[pushpals] embedded runtime is ready.");
-      return services;
+      return {
+        services,
+        pushpalsLogPath: runtimeServicesLogPath
+      };
     }
     await Bun.sleep(DEFAULT_RUNTIME_BOOT_POLL_MS);
   }
@@ -2492,6 +2840,7 @@ function readCliState(pathValue) {
       localAgentUrl: typeof parsed.localAgentUrl === "string" ? parsed.localAgentUrl : undefined,
       sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId : undefined,
       repoRoot: typeof parsed.repoRoot === "string" ? parsed.repoRoot : undefined,
+      pushpalsLogPath: typeof parsed.pushpalsLogPath === "string" ? parsed.pushpalsLogPath : undefined,
       updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined
     };
   } catch {
@@ -3006,6 +3355,19 @@ async function main() {
     runtimeRoot: parsed.runtimeRoot,
     runtimeTag: parsed.runtimeTag
   });
+  const config = preparedRuntime.runtimePreflight.config;
+  const statePath = resolveCliStatePath(repoRoot);
+  if (parsed.clear) {
+    const serverUrl2 = normalizeLoopbackUrl(parsed.serverUrl ?? process.env.PUSHPALS_SERVER_URL, config.server.url);
+    const exitCode = await clearPushpalsState({
+      repoRoot,
+      runtimeRoot: preparedRuntime.runtimeRoot,
+      config,
+      serverUrl: serverUrl2,
+      cliStatePath: statePath
+    });
+    process.exit(exitCode);
+  }
   console.log("[pushpals] Running runtime preflight...");
   console.log(`[pushpals] runtimeRoot=${preparedRuntime.runtimeRoot}`);
   if (preparedRuntime.runtimeTag) {
@@ -3019,12 +3381,21 @@ async function main() {
   if (!preparedRuntime.runtimePreflight.ok) {
     process.exit(1);
   }
-  const config = preparedRuntime.runtimePreflight.config;
   if (config.remotebuddy.autonomy.enabled) {
     console.log("[pushpals] RemoteBuddy autonomy is enabled for CLI.");
   } else {
     console.warn("[pushpals] RemoteBuddy autonomy is disabled in config (remotebuddy.autonomy.enabled=false); continuing.");
   }
+  const scmGitPrecheck = await precheckSourceControlManagerGitAvailability({
+    repoRoot,
+    remote: config.sourceControlManager.remote,
+    runtimeRoot: preparedRuntime.runtimeRoot,
+    preflightUsesEmbeddedRuntime: preparedRuntime.preflightUsesEmbeddedRuntime
+  });
+  if (scmGitPrecheck.status === "failed") {
+    console.error(`[pushpals] Precheck failed: embedded SourceControlManager git command is unavailable (${scmGitPrecheck.detail}).`);
+    process.exit(1);
+  }
   const precheckPassed = await enforcePushpalsRemoteBranchPrecheck(repoRoot, config.sourceControlManager.remote, config.sourceControlManager.mainBranch);
   if (!precheckPassed) {
     process.exit(1);
@@ -3042,6 +3413,7 @@ async function main() {
     repoRoot
   };
   let autoStartedServices = [];
+  let pushpalsLogPath;
   const stopAutoStartedServices = () => {
     if (autoStartedServices.length === 0)
       return;
@@ -3057,7 +3429,7 @@ async function main() {
   if (!serverHealthy) {
     if (!parsed.noAutoStart) {
       try {
-        autoStartedServices = await autoStartRuntimeServices({
+        const startedRuntime = await autoStartRuntimeServices({
           repoRoot,
           serverUrl,
           localAgentUrl,
@@ -3068,6 +3440,8 @@ async function main() {
           requestedRuntimeTag: parsed.runtimeTag,
           startLocalBuddy: resolveCliLocalBuddyAutostart(parsed.runtimeOnly, Boolean(config.localbuddy.enabled))
         });
+        autoStartedServices = startedRuntime.services;
+        pushpalsLogPath = startedRuntime.pushpalsLogPath;
         serverHealthy = await probeServer(serverUrl);
       } catch (err) {
         console.error(`[pushpals] Auto-start failed: ${String(err)}`);
@@ -3119,8 +3493,8 @@ async function main() {
     }
     process.exit(1);
   }
-  const statePath = resolveCliStatePath(repoRoot);
   const saved = statePath ? readCliState(statePath) : {};
+  pushpalsLogPath = pushpalsLogPath || (typeof saved.pushpalsLogPath === "string" ? saved.pushpalsLogPath : undefined);
   const preferredHubUrl = normalizeUrl(parsed.monitoringHubUrl ?? process.env.PUSHPALS_MONITOR_URL ?? saved.monitoringHubUrl ?? "");
   const monitorPort = parsePositiveInt(process.env.PUSHPALS_CLIENT_PORT, DEFAULT_MONITOR_PORT);
   const monitoringHub = await resolveMonitoringHub({
@@ -3136,7 +3510,8 @@ async function main() {
       serverUrl,
       localAgentUrl,
       sessionId: activeSessionId,
-      repoRoot
+      repoRoot,
+      pushpalsLogPath
     });
   } else {
     console.warn("[pushpals] Could not resolve git metadata dir; skipping CLI state persistence.");
@@ -3153,6 +3528,7 @@ async function main() {
   console.log(`[pushpals] serverUrl=${serverUrl}`);
   console.log(`[pushpals] sessionId=${activeSessionId}`);
   console.log(`[pushpals] repoRoot=${repoRoot}`);
+  console.log(`[pushpals] pushpalsLog=${pushpalsLogPath ?? "unavailable"}`);
   console.log(`[pushpals] cliStateFile=${statePath ?? "unavailable"}`);
   if (parsed.runtimeOnly) {
     console.log("[pushpals] runtimeOnly=true");
@@ -3253,6 +3629,7 @@ ${line}
       console.log(`[pushpals] serverUrl=${serverUrl}`);
       console.log(`[pushpals] sessionId=${activeSessionId}`);
       console.log(`[pushpals] repoRoot=${repoRoot}`);
+      console.log(`[pushpals] pushpalsLog=${pushpalsLogPath ?? "unavailable"}`);
       console.log(monitoringHubUrl ? `[pushpals] monitoringHubUrl=${monitoringHubUrl}` : "[pushpals] monitoringHubUrl=unavailable");
       rl.prompt();
       continue;
@@ -3291,12 +3668,17 @@ if (import.meta.main) {
 }
 export {
   startEmbeddedMonitoringHub,
+  resolveWindowsWhereExecutableCandidatesForEnv,
+  resolveWindowsShellExecutableCandidatesForEnv,
+  resolveRuntimeGitExecutableCandidates,
+  resolvePreferredRuntimeReleaseTag,
   resolveCommandPath,
   resolveCliStatePath,
   resolveCliLocalBuddyAutostart,
   resolveBundledRuntimeAssetSource,
   resolveBundledMonitoringHubRoot,
   prepareCliRuntime,
+  precheckSourceControlManagerGitAvailability,
   normalizeRepoPathForComparison,
   normalizeCliInteractiveMessage,
   normalizeChildProcessEnv,
@@ -3312,5 +3694,6 @@ export {
   buildOpenMonitoringHubCommand,
   buildEmbeddedRuntimeEnv,
   buildEmbeddedMonitoringHubHtml,
+  buildCliClearTargets,
   applyResolvedGitBinaryToRuntimeEnv
 };

package/package.json

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