bosun 0.28.2 → 0.28.4

package/.env.example

@@ -303,6 +303,74 @@ TELEGRAM_MINIAPP_ENABLED=false
 # Optional free-form constraints/scoping notes
 # PROJECT_REQUIREMENTS_NOTES=
 
+# ─── Branch Strategy ──────────────────────────────────────────────────
+# How agents work on branches for each task:
+#
+#   worktree (default) — Each task gets an isolated ve/<id>-<slug> sub-branch
+#                         that PRs back into the module/base branch.
+#                         Best for: independent, high-parallelism work.
+#
+#   direct             — Agents push directly onto the module branch
+#                         (no ve/ sub-branch). All work is sequential on that
+#                         branch. Conflicts are resolved in real time.
+#                         Best for: fast iteration on a well-scoped module.
+#
+# TASK_BRANCH_MODE=worktree
+#
+# Auto-detect origin/<module> as base_branch from conventional commit task titles
+# e.g. "[m] feat(veid): add verification" → base_branch = origin/veid
+# TASK_BRANCH_AUTO_MODULE=true
+#
+# Prefix used when building module branch refs (default: origin/)
+# MODULE_BRANCH_PREFIX=origin/
+#
+# Default upstream target branch (main branch) for upstream sync and PRs
+# DEFAULT_TARGET_BRANCH=main
+#
+# Merge origin/main into module branches before each push (keeps branches in
+# sync with upstream continuously). Conflicts abort the merge and are resolved
+# by the next agent working on that branch. Default: true
+# TASK_UPSTREAM_SYNC_MAIN=true
+
+# ─── GitHub App (Bosun[botswain] Identity + Auth) ────────────────────────────
+# App: https://github.com/apps/bosun-botswain  (slug: bosun-botswain)
+# Bot identity: bosun-botswain[bot]  (appears as contributor on every agent commit)
+#
+# Numeric App ID (shown on the App settings page under "About"):
+# BOSUN_GITHUB_APP_ID=2911413
+#
+# OAuth Client ID (from App settings → Client ID):
+# BOSUN_GITHUB_CLIENT_ID=Iv23liZpVhGePGka9gcL
+#
+# OAuth Client Secret (only needed for callback-based OAuth, not for Device Flow):
+# BOSUN_GITHUB_CLIENT_SECRET=
+#
+# Webhook secret (set this in App settings → Webhook, and keep in sync):
+# BOSUN_GITHUB_WEBHOOK_SECRET=
+#
+# Path to the PEM private key downloaded from App settings → Generate a private key:
+# BOSUN_GITHUB_PRIVATE_KEY_PATH=/path/to/bosun-botswain.pem
+#
+# ─── Authentication Method ───────────────────────────────────────────────
+# RECOMMENDED: Device Flow (like VS Code / Roo Code — no public URL needed!)
+#   1. Set BOSUN_GITHUB_CLIENT_ID above
+#   2. Enable "Device Flow" in GitHub App settings (Settings → Optional features)
+#   3. Go to Settings → GitHub in the Bosun UI and click "Sign in with GitHub"
+#   4. That's it — no callback URL, no tunnel URL, no client secret needed
+#
+# ALTERNATIVE: OAuth Callback (requires a stable public URL)
+#   Set BOSUN_GITHUB_CLIENT_ID + BOSUN_GITHUB_CLIENT_SECRET
+#   Register callback URL in App settings:
+#     https://<your-bosun-public-url>/api/github/callback
+#
+# WEBHOOKS (optional — for real-time PR/issue sync):
+#   Register webhook URL in App settings:
+#     https://<your-bosun-public-url>/api/webhooks/github/app
+#   Webhooks require a stable public URL. Without them, Bosun polls instead.
+#
+# Leave BOSUN_GITHUB_APP_ID unset to disable co-author trailer injection.
+# BOSUN_GITHUB_APP_ID=
+
 # ─── Kanban Backend ──────────────────────────────────────────────────────────
 # Task-board backend:
 #   internal - local task-store source of truth (recommended primary)

package/README.md

@@ -10,7 +10,7 @@ Bosun is a production-grade supervisor for AI coding agents. It routes tasks acr
 </p>
 
 <p align="center">
-  <img src="site/social-banner.png" alt="bosun — AI agent supervisor" width="100%" />
+  <img src="site/social-card.png" alt="bosun — AI agent supervisor" width="100%" />
 </p>
 
 <p align="center">

package/agent-prompts.mjs

@@ -173,11 +173,12 @@ Return exactly one fenced json block with this shape:
 {
   "tasks": [
     {
-      "title": "[m] Example task title",
+      "title": "[m] feat(veid): example task title",
       "description": "Problem statement and scope",
       "implementation_steps": ["step 1", "step 2"],
       "acceptance_criteria": ["criterion 1", "criterion 2"],
-      "verification": ["test/check 1", "test/check 2"]
+      "verification": ["test/check 1", "test/check 2"],
+      "base_branch": "origin/veid"
     }
   ]
 }
@@ -187,6 +188,11 @@ Rules:
 - Provide at least the requested task count unless blocked by duplicate safeguards.
 - Keep titles unique and specific.
 - Keep file overlap low across tasks to maximize parallel execution.
+- **Module branch routing:** When the task title follows conventional commit format
+  \`feat(module):\` or \`fix(module):\`, set \`base_branch\` to \`origin/<module>\`.
+  This routes the task to the module's dedicated branch for parallel, isolated development.
+  Examples: \`feat(veid):\` → \`"base_branch": "origin/veid"\`, \`fix(market):\` → \`"base_branch": "origin/market"\`.
+  Omit \`base_branch\` for cross-cutting tasks that span multiple modules.
 `,
   monitorMonitor: `# Bosun-Monitor Agent
 
@@ -240,14 +246,14 @@ You are running as a **Bosun-managed task agent**.  Environment variables
 **After committing:**
 - If a precommit hook auto-applies additional formatting changes, add those
   to a follow-up commit before pushing.
-- Merge any upstream changes from the base branch before pushing:
-  \`git fetch origin && git merge origin/<base-branch> --no-edit\`
-  Resolve any conflicts that arise.
+- Merge any upstream changes — BOTH from the base (module) branch AND from main:
+  \`git fetch origin && git merge origin/<base-branch> --no-edit && git merge origin/main --no-edit\`
+  Resolve any conflicts that arise before pushing.
 - Push: \`git push --set-upstream origin {{BRANCH}}\`
 - After a successful push, open a Pull Request:
   \`gh pr create --title "{{TASK_TITLE}}" --body "Closes task {{TASK_ID}}"\`
 - **Do NOT** run \`gh pr merge\` — the orchestrator handles merges after CI.
-
+{{COAUTHOR_INSTRUCTION}}
 **Do NOT:**
 - Bypass pre-push hooks (\`git push --no-verify\` is forbidden).
 - Use \`git add .\` — stage files individually.

package/agent-work-analyzer.mjs

@@ -12,8 +12,8 @@
  * - Cost anomaly detection (unusually expensive sessions)
  */
 
-import { readFile, writeFile, appendFile, stat, watch } from "fs/promises";
-import { createReadStream, existsSync } from "fs";
+import { readFile, writeFile, appendFile, stat, watch, mkdir } from "fs/promises";
+import { createReadStream, existsSync, mkdirSync } from "fs";
 import { createInterface } from "readline";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -73,30 +73,54 @@ export async function startAnalyzer() {
 
   console.log("[agent-work-analyzer] Starting...");
 
-  // Ensure alerts log exists
-  if (!existsSync(ALERTS_LOG)) {
-    await writeFile(ALERTS_LOG, "");
+  // Ensure parent directory and alerts log exist
+  try {
+    const alertsDir = dirname(ALERTS_LOG);
+    if (!existsSync(alertsDir)) {
+      await mkdir(alertsDir, { recursive: true });
+    }
+    if (!existsSync(ALERTS_LOG)) {
+      await writeFile(ALERTS_LOG, "");
+    }
+  } catch (err) {
+    console.warn(`[agent-work-analyzer] Failed to init alerts log: ${err.message}`);
   }
 
   // Initial read of existing log
   if (existsSync(AGENT_WORK_STREAM)) {
     filePosition = await processLogFile(filePosition);
+  } else {
+    // Ensure the stream file exists so the watcher doesn't throw
+    try {
+      await writeFile(AGENT_WORK_STREAM, "");
+    } catch {
+      // May fail if another process creates it first — that's fine
+    }
   }
 
-  // Watch for changes
+  // Watch for changes — retry loop handles the case where the file
+  // is deleted and recreated (e.g. log rotation).
   console.log(`[agent-work-analyzer] Watching: ${AGENT_WORK_STREAM}`);
 
-  const watcher = watch(AGENT_WORK_STREAM, { persistent: true });
-
-  try {
-    for await (const event of watcher) {
-      if (event.eventType === "change") {
-        filePosition = await processLogFile(filePosition);
+  while (isRunning) {
+    try {
+      const watcher = watch(AGENT_WORK_STREAM, { persistent: true });
+      for await (const event of watcher) {
+        if (!isRunning) break;
+        if (event.eventType === "change") {
+          filePosition = await processLogFile(filePosition);
+        }
+      }
+    } catch (err) {
+      if (!isRunning) break;
+      if (err.code === "ENOENT") {
+        // File was deleted — wait a bit and retry
+        await new Promise((r) => setTimeout(r, 5000));
+        continue;
       }
-    }
-  } catch (err) {
-    if (err.code !== "ENOENT") {
       console.error(`[agent-work-analyzer] Watcher error: ${err.message}`);
+      // Wait before retrying to avoid busy-loop
+      await new Promise((r) => setTimeout(r, 10000));
     }
   }
 }

package/cli.mjs

@@ -979,7 +979,10 @@ async function main() {
           const logDir = monitorPath ? resolve(dirname(monitorPath), "logs") : resolve(__dirname, "logs");
           const daemonLog = existsSync(DAEMON_LOG) ? DAEMON_LOG : resolve(logDir, "daemon.log");
           const monitorLog = resolve(logDir, "monitor.log");
-          const logFile = existsSync(daemonLog) ? daemonLog : monitorLog;
+          // Prefer monitor.log — that's where the real activity goes.
+          // daemon.log only has the startup line; monitor.mjs intercepts
+          // all console output and writes to monitor.log.
+          const logFile = existsSync(monitorLog) ? monitorLog : daemonLog;
 
           if (existsSync(logFile)) {
             console.log(

package/codex-config.mjs

@@ -373,11 +373,18 @@ function normalizeWritableRoots(input, { repoRoot } = {}) {
     if (repo) {
       addRoot(repo);
       addRoot(resolve(repo, ".git"));
+      // Worktree checkout paths (used by task-executor)
+      addRoot(resolve(repo, ".cache", "worktrees"));
+      // Cache directories for agent work logs, build artifacts, etc.
+      addRoot(resolve(repo, ".cache"));
       const parent = dirname(repo);
       if (parent && parent !== repo) addRoot(parent);
     }
   }
 
+  // /tmp is needed for sandbox temp files, pip installs, etc.
+  addRoot("/tmp");
+
   return Array.from(roots);
 }
 

package/monitor.mjs

@@ -157,6 +157,7 @@ import { WorkspaceMonitor } from "./workspace-monitor.mjs";
 import { VkLogStream } from "./vk-log-stream.mjs";
 import { VKErrorResolver } from "./vk-error-resolver.mjs";
 import { createAnomalyDetector } from "./anomaly-detector.mjs";
+import { resolvePwshRuntime } from "./pwsh-runtime.mjs";
 import {
   getWorktreeManager,
   acquireWorktree,
@@ -311,7 +312,10 @@ function startAgentWorkAnalyzer() {
   if (agentWorkAnalyzerActive) return;
   if (process.env.AGENT_WORK_ANALYZER_ENABLED === "false") return;
   try {
-    void startAnalyzer();
+    startAnalyzer().catch((err) => {
+      console.warn(`[monitor] agent-work analyzer async error: ${err.message}`);
+      agentWorkAnalyzerActive = false;
+    });
     agentWorkAnalyzerActive = true;
     console.log("[monitor] agent-work analyzer started");
   } catch (err) {
@@ -1530,8 +1534,9 @@ async function handleMonitorFailure(reason, err) {
 
     if (telegramToken && telegramChatId) {
       try {
+        const shortMsg = message.length > 200 ? message.slice(0, 200) + "…" : message;
         await sendTelegramMessage(
-          `⚠️ bosun exception (${reason}). Attempting recovery (count=${failureCount}).`,
+          `⚠️ bosun exception (${reason}): ${shortMsg}\n\nAttempting recovery (count=${failureCount}).`,
         );
       } catch {
         /* suppress Telegram errors during failure handling */
@@ -7550,17 +7555,47 @@ async function buildPlannerRuntimeContext(reason, details, numTasks) {
   };
 }
 
+/**
+ * Extract a conventional-commit scope from a task title and return the
+ * corresponding module branch ref (e.g. "origin/veid").
+ * Respects TASK_BRANCH_AUTO_MODULE env var (default: true) and
+ * MODULE_BRANCH_PREFIX (default: "origin/").
+ */
+function extractModuleBaseBranchFromTitle(title) {
+  const enabled = (process.env.TASK_BRANCH_AUTO_MODULE ?? "true") !== "false";
+  if (!enabled || !title) return null;
+  const match = String(title).match(
+    /(?:^\[[^\]]+\]\s*)?(?:feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\(([^)]+)\)/i,
+  );
+  if (!match) return null;
+  const scope = match[1].toLowerCase().trim();
+  // Exclude generic scopes that don't map to real module branches
+  const generic = new Set(["deps", "app", "sdk", "cli", "api"]);
+  if (generic.has(scope)) return null;
+  const prefix = (process.env.MODULE_BRANCH_PREFIX || "origin/").replace(/\/*$/, "/");
+  return `${prefix}${scope}`;
+}
+
 function buildPlannerTaskDescription({
   plannerPrompt,
   reason,
   numTasks,
   runtimeContext,
+  userPrompt,
 }) {
   return [
     "## Task Planner — Auto-created by bosun",
     "",
     `**Trigger reason:** ${reason || "manual"}`,
     `**Requested task count:** ${numTasks}`,
+    ...(userPrompt
+      ? [
+          "",
+          "### User Planning Prompt",
+          "",
+          userPrompt,
+        ]
+      : []),
     "",
     "### Planner Prompt (Injected by bosun)",
     "",
@@ -7610,8 +7645,13 @@ function buildPlannerTaskDescription({
     "4. Prioritize reliability and unblockers first when errors/review backlog is elevated.",
     "5. Avoid duplicates with existing todo/inprogress/review tasks and open PRs.",
     "6. Prefer task sets that can run in parallel with minimal file overlap.",
-    "7. If a task should target a non-default epic/base branch, include `base_branch` in the JSON task object.",
-  ].join("\n");
+    "7. **Module branch routing (important):** When a task's title follows conventional commit format",
+    "   `feat(module):` or `fix(module):`, ALWAYS set `base_branch` to `origin/<module>` in the JSON.",
+    "   This enables parallel branch-per-module execution where all work for a module accumulates on",
+    "   its dedicated branch and integrates upstream changes continuously.",
+    "   Examples: `feat(veid):` → `origin/veid`, `fix(market):` → `origin/market`.",
+    "   Do NOT set base_branch for cross-cutting tasks that modify many modules.",
+    "8. If a task should target a non-default epic/base branch for other reasons, include `base_branch` in the JSON task object.",].join("\n");
 }
 
 function normalizePlannerTitleForComparison(title) {
@@ -7788,7 +7828,12 @@ async function materializePlannerTasksToKanban(projectId, tasks) {
       title: task.title,
       description: task.description,
       status: "todo",
-      ...(task.baseBranch ? { baseBranch: task.baseBranch } : {}),
+      // Honour explicit baseBranch from planner JSON, then fall back to
+      // module auto-detection via conventional commit scope in the title.
+      ...(() => {
+        const b = task.baseBranch || task.base_branch || extractModuleBaseBranchFromTitle(task.title);
+        return b ? { baseBranch: b } : {};
+      })(),
     });
     if (createdTask?.id) {
       created.push({ id: createdTask.id, title: task.title });
@@ -8689,6 +8734,7 @@ async function triggerTaskPlanner(
   details,
   {
     taskCount,
+    userPrompt,
     notify = true,
     preferredMode,
     allowCodexWhenDisabled = false,
@@ -8724,6 +8770,7 @@ async function triggerTaskPlanner(
       try {
         result = await triggerTaskPlannerViaKanban(reason, details, {
           taskCount,
+          userPrompt,
           notify,
         });
       } catch (kanbanErr) {
@@ -8753,6 +8800,7 @@ async function triggerTaskPlanner(
         }
         result = await triggerTaskPlannerViaCodex(reason, details, {
           taskCount,
+          userPrompt,
           notify,
           allowWhenDisabled: allowCodexWhenDisabled,
         });
@@ -8761,6 +8809,7 @@ async function triggerTaskPlanner(
       try {
         result = await triggerTaskPlannerViaCodex(reason, details, {
           taskCount,
+          userPrompt,
           notify,
           allowWhenDisabled: allowCodexWhenDisabled,
         });
@@ -8784,6 +8833,7 @@ async function triggerTaskPlanner(
 
         result = await triggerTaskPlannerViaKanban(reason, details, {
           taskCount,
+          userPrompt,
           notify,
         });
       }
@@ -8818,7 +8868,7 @@ async function triggerTaskPlanner(
 async function triggerTaskPlannerViaKanban(
   reason,
   details,
-  { taskCount, notify = true } = {},
+  { taskCount, userPrompt, notify = true } = {},
 ) {
   const defaultPlannerTaskCount = Number(
     process.env.TASK_PLANNER_DEFAULT_COUNT || "30",
@@ -8844,12 +8894,15 @@ async function triggerTaskPlannerViaKanban(
     );
   }
 
-  const desiredTitle = `[${plannerTaskSizeLabel}] Plan next tasks (${reason || "backlog-empty"})`;
+  const desiredTitle = userPrompt
+    ? `[${plannerTaskSizeLabel}] Plan next tasks (${reason || "backlog-empty"}) — ${userPrompt.slice(0, 60)}${userPrompt.length > 60 ? "…" : ""}`
+    : `[${plannerTaskSizeLabel}] Plan next tasks (${reason || "backlog-empty"})`;
   const desiredDescription = buildPlannerTaskDescription({
     plannerPrompt,
     reason,
     numTasks,
     runtimeContext,
+    userPrompt,
   });
 
   // Check for existing planner tasks to avoid duplicates
@@ -8941,7 +8994,7 @@ async function triggerTaskPlannerViaKanban(
 async function triggerTaskPlannerViaCodex(
   reason,
   details,
-  { taskCount, notify = true, allowWhenDisabled = false } = {},
+  { taskCount, userPrompt, notify = true, allowWhenDisabled = false } = {},
 ) {
   if (!codexEnabled && !allowWhenDisabled) {
     throw new Error(
@@ -8973,6 +9026,17 @@ async function triggerTaskPlannerViaCodex(
     "## Execution Context",
     `- Trigger reason: ${reason || "manual"}`,
     `- Requested task count: ${numTasks}`,
+    ...(userPrompt
+      ? [
+          "",
+          "## User Planning Prompt",
+          "",
+          userPrompt,
+          "",
+          "Incorporate the above user prompt into any relevant planning decisions.",
+        ]
+      : []),
+    "",
     "Context JSON:",
     "```json",
     safeJsonBlock(runtimeContext),
@@ -10590,21 +10654,16 @@ async function startProcess() {
   let orchestratorArgs = [...scriptArgs];
 
   if (scriptLower.endsWith(".ps1")) {
-    const configuredPwsh = String(process.env.PWSH_PATH || "").trim();
-    const bundledPwsh = resolve(__dirname, ".cache", "bosun", "pwsh", "pwsh");
-    const bundledPwshExists = existsSync(bundledPwsh);
-    const pwshCmd = configuredPwsh || (bundledPwshExists ? bundledPwsh : "pwsh");
-    const pwshExists = configuredPwsh
-      ? configuredPwsh.includes("/") || configuredPwsh.includes("\\")
-        ? existsSync(configuredPwsh)
-        : commandExists(configuredPwsh)
-      : bundledPwshExists || commandExists("pwsh");
-    if (!pwshExists) {
-      const pwshLabel = configuredPwsh
-        ? `PWSH_PATH (${configuredPwsh})`
-        : bundledPwshExists
-          ? `bundled pwsh (${bundledPwsh})`
-          : "pwsh on PATH";
+    const pwshRuntime = resolvePwshRuntime({ preferBundled: true });
+    if (!pwshRuntime.exists) {
+      const pwshLabel =
+        pwshRuntime.source === "env"
+          ? `PWSH_PATH (${pwshRuntime.command})`
+          : pwshRuntime.source === "bundled"
+            ? `bundled pwsh (${pwshRuntime.command})`
+            : pwshRuntime.source === "powershell"
+              ? `powershell on PATH`
+              : "pwsh on PATH";
       const pauseMs = Math.max(orchestratorPauseMs, 60_000);
       const pauseMin = Math.max(1, Math.round(pauseMs / 60_000));
       monitorSafeModeUntil = Math.max(monitorSafeModeUntil, Date.now() + pauseMs);
@@ -10622,7 +10681,7 @@ async function startProcess() {
       setTimeout(startProcess, pauseMs);
       return;
     }
-    orchestratorCmd = pwshCmd;
+    orchestratorCmd = pwshRuntime.command;
     orchestratorArgs = ["-File", scriptPath, ...scriptArgs];
   } else if (scriptLower.endsWith(".sh")) {
     const shellCmd =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bosun",
-  "version": "0.28.2",
+  "version": "0.28.4",
   "description": "AI-powered orchestrator supervisor — manages AI agent executors with failover, auto-restarts on failure, analyzes crashes with Codex SDK, creates PRs via Vibe-Kanban API, and sends Telegram notifications. Supports N executors with weighted distribution, multi-repo projects, and auto-setup.",
   "type": "module",
   "license": "Apache 2.0",
@@ -152,6 +152,7 @@
     "sdk-conflict-resolver.mjs",
     "session-tracker.mjs",
     "setup.mjs",
+    "pwsh-runtime.mjs",
     "shared-knowledge.mjs",
     "shared-state-manager.mjs",
     "shared-workspace-cli.mjs",

package/preflight.mjs

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import os from "node:os";
+import { resolvePwshRuntime } from "./pwsh-runtime.mjs";
 
 const isWindows = process.platform === "win32";
 const MIN_FREE_GB = Number(process.env.BOSUN_MIN_FREE_GB || "10");
@@ -179,6 +180,7 @@ function checkToolchain() {
     "node",
     shellMode ? "shell" : "pwsh",
   ]);
+  const pwshRuntime = resolvePwshRuntime({ preferBundled: true });
 
   const tools = [
     checkToolVersion(
@@ -213,7 +215,7 @@ function checkToolchain() {
     ),
     checkToolVersion(
       "pwsh",
-      "pwsh",
+      pwshRuntime.command,
       ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.ToString()"],
       "Install PowerShell 7+ (pwsh) and ensure it is on PATH.",
     ),

package/primary-agent.mjs

@@ -362,9 +362,13 @@ export async function execPrimaryPrompt(userMessage, options = {}) {
       );
 
       if (result) {
+        // Extract human-readable text from structured responses
+        const text = typeof result === "string"
+          ? result
+          : result.finalResponse || result.text || result.message || JSON.stringify(result);
         tracker.recordEvent(sessionId, {
           role: "assistant",
-          content: typeof result === "string" ? result : JSON.stringify(result),
+          content: text,
           timestamp: new Date().toISOString(),
           _sessionType: sessionType,
         });

package/pwsh-runtime.mjs

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_PWSH_PATH = resolve(__dirname, ".cache", "bosun", "pwsh", "pwsh");
+
+function commandExists(cmd) {
+  try {
+    execSync(`${process.platform === "win32" ? "where" : "which"} ${cmd}`, {
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isPathLike(value) {
+  return value.includes("/") || value.includes("\\");
+}
+
+export function resolvePwshRuntime({ preferBundled = true } = {}) {
+  const configured = String(process.env.PWSH_PATH || "").trim();
+  if (configured) {
+    if (isPathLike(configured)) {
+      if (existsSync(configured)) {
+        return { command: configured, source: "env", exists: true };
+      }
+      return { command: configured, source: "env", exists: false };
+    }
+    if (commandExists(configured)) {
+      return { command: configured, source: "env", exists: true };
+    }
+    return { command: configured, source: "env", exists: false };
+  }
+
+  if (preferBundled && existsSync(BUNDLED_PWSH_PATH)) {
+    return { command: BUNDLED_PWSH_PATH, source: "bundled", exists: true };
+  }
+
+  if (commandExists("pwsh")) {
+    return { command: "pwsh", source: "path", exists: true };
+  }
+
+  if (process.platform === "win32" && commandExists("powershell")) {
+    return { command: "powershell", source: "powershell", exists: true };
+  }
+
+  return { command: "pwsh", source: "missing", exists: false };
+}
+
+export function resolvePwshCommand(options = {}) {
+  return resolvePwshRuntime(options).command;
+}
+
+export function hasPwshRuntime(options = {}) {
+  return resolvePwshRuntime(options).exists;
+}
+
+export { BUNDLED_PWSH_PATH };