bosun 0.33.7 → 0.33.9

package/.env.example

@@ -920,6 +920,14 @@ COPILOT_CLOUD_DISABLED=true
 # stale-task-followup. Configure/enable in bosun.config.json under triggerSystem.
 # TASK_TRIGGER_SYSTEM_ENABLED=false
 
+# ─── Workflow Automation (event-driven) ──────────────────────────────────────
+# Enables automatic Workflow Engine trigger evaluation from monitor events
+# (task.assigned, task.completed, task.failed, pr.opened, pr.merged, etc).
+# Enabled by default. Set to false to disable event-driven automation.
+# WORKFLOW_AUTOMATION_ENABLED=true
+# Optional dedup window to avoid event storms (milliseconds).
+# WORKFLOW_EVENT_DEDUP_WINDOW_MS=15000
+
 # ─── GitHub Issue Reconciler ─────────────────────────────────────────────────
 # Periodically reconciles open GitHub issues against open/merged PRs.
 # Hybrid close policy:

package/agent-endpoint.mjs

@@ -31,6 +31,7 @@ const DEFAULT_PORT = 18432;
 const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
 const REQUEST_TIMEOUT_MS = 30_000; // 30 seconds
 const ACCESS_DENIED_COOLDOWN_MS = 10 * 60 * 1000; // 10 minutes
+const BOSUN_ROOT_HINT = __dirname.toLowerCase().replace(/\\/g, '/');
 
 // Valid status transitions when an agent self-reports
 const VALID_TRANSITIONS = {
@@ -175,6 +176,41 @@ function isAlreadyExitedProcessError(err) {
   );
 }
 
+function normalizeCommandLine(commandLine) {
+  return String(commandLine || "").toLowerCase().replace(/\\/g, "/").trim();
+}
+
+function isLikelyBosunCommandLine(commandLine) {
+  const normalized = normalizeCommandLine(commandLine);
+  if (!normalized) return false;
+
+  if (normalized.includes(BOSUN_ROOT_HINT)) return true;
+
+  if (
+    normalized.includes("/bosun/") &&
+    (normalized.includes("monitor.mjs") ||
+      normalized.includes("cli.mjs") ||
+      normalized.includes("agent-endpoint.mjs") ||
+      normalized.includes("ve-orchestrator"))
+  ) {
+    return true;
+  }
+
+  // Dev-mode often launches monitor as node monitor.mjs from bosun root.
+  if (/\bnode(?:\.exe)?\b/.test(normalized) && /\bmonitor\.mjs\b/.test(normalized)) {
+    return true;
+  }
+
+  return false;
+}
+
+function summarizeCommandLine(commandLine, maxLen = 140) {
+  const compact = String(commandLine || "").replace(/\s+/g, " ").trim();
+  if (!compact) return "command line unavailable";
+  if (compact.length <= maxLen) return compact;
+  return compact.slice(0, maxLen) + "...";
+}
+
 // ── AgentEndpoint Class ─────────────────────────────────────────────────────
 
 export class AgentEndpoint {
@@ -311,7 +347,7 @@ export class AgentEndpoint {
       const { execSync, spawnSync } = await import("node:child_process");
       const isWindows = process.platform === "win32";
       let output;
-      let pids = new Set();
+      const pids = new Set();
 
       // PIDs we must NEVER kill — ourselves, our parent (cli.mjs fork host),
       // and any ancestor in the same process tree.  lsof can return these when
@@ -321,13 +357,43 @@ export class AgentEndpoint {
         String(process.ppid),
       ]);
 
+      const readProcessCommandLine = (pid) => {
+        try {
+          if (isWindows) {
+            const query = `$p = Get-CimInstance Win32_Process -Filter "ProcessId=${pid}" -ErrorAction SilentlyContinue; if ($p) { $p.CommandLine }`;
+            const result = spawnSync(
+              "powershell",
+              ["-NoProfile", "-Command", query],
+              {
+                encoding: "utf8",
+                timeout: 5000,
+                windowsHide: true,
+                stdio: ["ignore", "pipe", "pipe"],
+              },
+            );
+            if (result.error || result.status !== 0) return "";
+            return String(result.stdout || "").trim();
+          }
+
+          const result = spawnSync("ps", ["-p", String(pid), "-o", "args="], {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+          if (result.error || result.status !== 0) return "";
+          return String(result.stdout || "").trim();
+        } catch {
+          return "";
+        }
+      };
+
       if (isWindows) {
         // Windows: netstat -ano | findstr
         output = execSync(`netstat -ano | findstr ":${port}"`, {
           encoding: "utf8",
           timeout: 5000,
         }).trim();
-        const lines = output.split("\n").filter((l) => l.includes("LISTENING"));
+        const lines = output.split("\n").filter((line) => line.includes("LISTENING"));
         for (const line of lines) {
           const parts = line.trim().split(/\s+/);
           const pid = parts[parts.length - 1];
@@ -342,7 +408,7 @@ export class AgentEndpoint {
             encoding: "utf8",
             timeout: 5000,
           }).trim();
-          const pidList = output.split("\n").filter((p) => p.trim());
+          const pidList = output.split("\n").filter((pid) => pid.trim());
           for (const pid of pidList) {
             if (pid && /^\d+$/.test(pid) && !protectedPids.has(pid)) {
               pids.add(pid);
@@ -363,7 +429,23 @@ export class AgentEndpoint {
         }
       }
 
+      const killEligiblePids = new Set();
       for (const pid of pids) {
+        const commandLine = readProcessCommandLine(pid);
+        if (!isLikelyBosunCommandLine(commandLine)) {
+          console.warn(
+            `${TAG} Port ${port} held by non-bosun PID ${pid} (${summarizeCommandLine(commandLine)}); skipping forced kill`,
+          );
+          continue;
+        }
+        killEligiblePids.add(pid);
+      }
+
+      if (killEligiblePids.size === 0) {
+        return;
+      }
+
+      for (const pid of killEligiblePids) {
         console.log(`${TAG} Sending SIGTERM to stale process PID ${pid} on port ${port}`);
         try {
           if (isWindows) {
@@ -421,12 +503,13 @@ export class AgentEndpoint {
           );
         }
       }
+
       // Give the SIGTERM'd processes time to exit gracefully
       await new Promise((r) => setTimeout(r, 2000));
 
       // Escalate: check if any are still alive and SIGKILL them
       if (!isWindows) {
-        for (const pid of pids) {
+        for (const pid of killEligiblePids) {
           try {
             process.kill(Number(pid), 0); // probe — throws if dead
             console.warn(`${TAG} PID ${pid} still alive after SIGTERM — sending SIGKILL`);
@@ -447,7 +530,6 @@ export class AgentEndpoint {
       }
     }
   }
-
   /**
    * Stop the HTTP server.
    * @returns {Promise<void>}

package/agent-pool.mjs

@@ -1923,7 +1923,9 @@ export async function ensureThreadRegistryLoaded() {
 }
 
 // Kick off async load at module init (non-blocking), callers can await explicitly.
-void ensureThreadRegistryLoaded();
+ensureThreadRegistryLoaded().catch((err) => {
+  console.warn(TAG + " thread registry warm-up failed: " + (err?.message || err));
+});
 
 // ---------------------------------------------------------------------------
 // Per-SDK Resume Launchers
@@ -2667,7 +2669,11 @@ export function invalidateThread(taskKey) {
   }
   // If registry hasn't loaded yet, defer invalidation until load completes.
   if (!threadRegistryLoaded) {
-    void invalidateThreadAsync(taskKey);
+    invalidateThreadAsync(taskKey).catch((err) => {
+      console.warn(
+        TAG + " deferred invalidateThreadAsync failed for \"" + taskKey + "\": " + (err?.message || err),
+      );
+    });
   }
 }
 

package/agent-prompts.mjs

@@ -150,6 +150,24 @@ You are an autonomous task orchestrator agent. You receive implementation tasks
 4. Run relevant verification (tests/lint/build) before finalizing.
 5. Use conventional commit messages.
 
+## Code Quality — Hard Rules
+
+These rules are non-negotiable. Violations cause real production crashes.
+
+- **Module-scope caching:** Variables that cache state (lazy singletons, loaded
+  flags, memoization maps) MUST be at module scope, never inside a function body
+  that runs repeatedly.
+- **Async safety:** NEVER use bare \`void asyncFn()\`. Every async call must be
+  \`await\`-ed or have a \`.catch()\` handler. Unhandled rejections crash Node.js.
+- **Error boundaries:** HTTP handlers, timers, and event callbacks MUST wrap async
+  work in try/catch so one failure doesn't kill the process.
+- **No over-mocking in tests:** Mock only external boundaries (network, disk, clock).
+  Never mock the module under test. If a test needs > 3 mocks, refactor the code.
+- **Deterministic tests:** No \`Math.random()\`, real network calls, or \`setTimeout\`
+  for synchronization. Tests must be reproducible and order-independent.
+- **Dynamic \`import()\` must be cached:** Never place \`import()\` inside a
+  frequently-called function without caching the result at module scope.
+
 ## Completion Criteria
 
 - Implementation matches requested behavior.
@@ -270,6 +288,27 @@ Check for relevant skills before implementing:
 - No placeholders/stubs/TODO-only output.
 - Keep behavior stable and production-safe.
 
+## Code Quality — Mandatory Checks
+
+These patterns have caused real production crashes. Treat them as hard rules:
+
+1. **Module-scope caching:** If you declare variables that cache state (lazy
+   singletons, init flags, memoization), place them at **module scope** — never
+   inside a function body that runs per-request or per-event.
+2. **Async fire-and-forget:** Never use bare \`void asyncFn()\`. Always \`await\`
+   or append \`.catch()\`. Unhandled promise rejections crash Node.js (exit 1).
+3. **Error boundaries:** Wrap HTTP handlers, timers, and event callbacks in
+   top-level try/catch. One unguarded throw must not kill the process.
+4. **Dynamic imports:** Cache \`import()\` results at module scope. Never call
+   \`import()\` inside a hot path without caching — it causes repeated I/O.
+5. **Test quality:** Mock only external boundaries (network, disk, clock). Never
+   mock the module under test. No \`setTimeout\`/\`sleep\` for synchronization.
+   Tests must be deterministic and order-independent. Assert on behavior, not
+   implementation details.
+6. **No architectural shortcuts:** Don't force-enable feature flags inline. Don't
+   add config overrides that bypass safety checks. If a feature is behind a flag,
+   respect it.
+
 ## Bosun Task Agent — Git & PR Workflow
 
 You are running as a **Bosun-managed task agent**.  Environment variables
@@ -375,6 +414,13 @@ Review the following PR diff for CRITICAL issues ONLY.
 2. Bugs / correctness regressions
 3. Missing implementations
 4. Broken functionality
+5. Cache/singleton variables declared inside function bodies instead of module scope
+6. Bare \`void asyncFn()\` or async calls without \`await\` / \`.catch()\`
+7. HTTP handlers, timers, or event callbacks missing try/catch error boundaries
+8. Dynamic \`import()\` inside hot paths without module-scope caching
+9. Tests that over-mock (mocking the module under test, > 3 mocks per test)
+10. Flaky test patterns: \`setTimeout\`/sleep for sync, \`Math.random()\`, real network
+11. Force-enabled feature flags or config overrides that bypass safety checks
 
 ## What to ignore
 - Style-only concerns
@@ -399,7 +445,7 @@ Respond with JSON only:
   "issues": [
     {
       "severity": "critical" | "major",
-      "category": "security" | "bug" | "missing_impl" | "broken",
+      "category": "security" | "bug" | "missing_impl" | "broken" | "anti_pattern" | "flaky_test",
       "file": "path/to/file",
       "line": 123,
       "description": "..."

package/agent-work-analyzer.mjs

@@ -434,7 +434,11 @@ async function runStuckSweep() {
 function startStuckSweep() {
   if (stuckSweepTimer) return;
   stuckSweepTimer = setInterval(() => {
-    void runStuckSweep();
+    runStuckSweep().catch((err) => {
+      console.error(
+        "[agent-work-analyzer] Stuck sweep failed: " + (err?.message || err),
+      );
+    });
   }, STUCK_SWEEP_INTERVAL_MS);
   stuckSweepTimer.unref?.();
 }

package/bosun-skills.mjs

@@ -529,6 +529,207 @@ curl -sX POST http://127.0.0.1:$BOSUN_ENDPOINT_PORT/api/tasks/$BOSUN_TASK_ID/err
 | \`BOSUN_ENDPOINT_PORT\` | \`VE_ENDPOINT_PORT\` | API server port |
 | \`BOSUN_SDK\` | \`VE_SDK\` | SDK/executor type (COPILOT/CODEX/CLAUDE_CODE) |
 | \`BOSUN_MANAGED\` | \`VE_MANAGED\` | Set to "1" when running under bosun |
+`,
+  },
+  {
+    filename: "code-quality-anti-patterns.md",
+    title: "Code Quality Anti-Patterns",
+    tags: ["quality", "code", "architecture", "async", "testing", "reliability", "bug", "crash", "scope", "caching", "promise", "module"],
+    scope: "global",
+    content: `# Skill: Code Quality Anti-Patterns
+
+## Purpose
+Prevent common coding mistakes that cause crashes, flaky behavior, memory leaks,
+and hard-to-diagnose production failures. Every pattern below has caused real
+outages — treat each as a hard rule, not a suggestion.
+
+---
+
+## 1. Module-Scope vs Function-Scope — Caching & Singletons
+
+**Rule:** Variables that cache module-level state (lazy singletons, loaded
+configs, memoized results) MUST be declared at **module scope**, never inside
+a function that runs repeatedly.
+
+### Bad — re-initializes on every call
+\`\`\`js
+export function handleRequest(req, res) {
+  let _engine;           // ← reset to undefined on EVERY call
+  let _loaded = false;   // ← never stays true across calls
+  if (!_loaded) {
+    _engine = await loadEngine();
+    _loaded = true;
+  }
+  // ...
+}
+\`\`\`
+
+### Good — persists across calls
+\`\`\`js
+let _engine;
+let _loaded = false;
+
+export function handleRequest(req, res) {
+  if (!_loaded) {
+    _engine = await loadEngine();
+    _loaded = true;
+  }
+  // ...
+}
+\`\`\`
+
+**Why:** Placing cache variables inside a function body causes:
+- Repeated expensive initialization (import, parse, connect) on every call
+- Log spam from repeated init messages
+- Potential memory leaks from orphaned resources
+- Race conditions when multiple concurrent calls all see \`_loaded === false\`
+
+**Checklist:**
+- [ ] Lazy singletons: module scope
+- [ ] Memoization caches: module scope (or a \`Map\`/\`WeakMap\` at module scope)
+- [ ] "loaded" / "initialized" flags: module scope
+- [ ] Config objects read once from disk: module scope
+
+---
+
+## 2. Async Fire-and-Forget — Always Handle Rejections
+
+**Rule:** NEVER use bare \`void asyncFn()\` or call an async function without
+either \`await\`-ing or chaining \`.catch()\`. Unhandled promise rejections crash
+Node.js processes.
+
+### Bad — unhandled rejection → crash
+\`\`\`js
+void dispatchEvent(data);    // if dispatchEvent is async and throws → crash
+asyncCleanup();              // no await, no catch → crash
+\`\`\`
+
+### Good — always handle the rejection
+\`\`\`js
+await dispatchEvent(data);                           // preferred: await it
+dispatchEvent(data).catch(() => {});                  // fire-and-forget OK
+dispatchEvent(data).catch(err => log.warn(err));      // fire-and-forget with logging
+\`\`\`
+
+**Why:** Since Node.js 15+, unhandled promise rejections terminate the process
+with exit code 1. A single \`void asyncFn()\` in a hot path can cause a
+crash → restart → crash loop that takes down the entire system.
+
+**Checklist:**
+- [ ] Every async call is \`await\`-ed OR has a \`.catch()\` handler
+- [ ] No bare \`void asyncFn()\` patterns
+- [ ] Event dispatch functions wrapped in try/catch at the top level
+- [ ] setInterval/setTimeout callbacks that call async functions use \`.catch()\`
+
+---
+
+## 3. Error Boundaries & Defensive Coding
+
+**Rule:** Any function called from a hot path (HTTP handlers, event loops,
+timers) MUST have a top-level try/catch that prevents a single failure from
+crashing the entire process.
+
+### Bad — one bad event kills the server
+\`\`\`js
+router.post('/webhook', async (req, res) => {
+  const data = parsePayload(req.body);
+  await processAllWebhooks(data);
+  res.json({ ok: true });
+});
+\`\`\`
+
+### Good — contained failure
+\`\`\`js
+router.post('/webhook', async (req, res) => {
+  try {
+    const data = parsePayload(req.body);
+    await processAllWebhooks(data);
+    res.json({ ok: true });
+  } catch (err) {
+    log.error('webhook handler failed', err);
+    res.status(500).json({ error: 'internal' });
+  }
+});
+\`\`\`
+
+---
+
+## 4. Testing Anti-Patterns
+
+### Over-Mocking
+**Rule:** Tests should validate real behavior, not just confirm that mocks
+return what you told them to return.
+
+- Mock only external boundaries (network, filesystem, clock).
+- Never mock the module under test.
+- If you need > 3 mocks for a single test, the code under test probably needs
+  refactoring, not more mocks.
+- Prefer integration tests with real instances over unit tests with heavy mocking.
+
+### Flaky Tests
+**Rule:** Tests must be deterministic and reproducible.
+
+- No \`Math.random()\` or \`Date.now()\` without mocking.
+- No network calls to real servers.
+- No \`setTimeout\`/\`sleep\` for synchronization — use proper async patterns.
+- No implicit ordering dependencies between tests.
+- If a test creates global state, clean it up in \`afterEach\`.
+
+### Assertion Quality
+- Test ONE behavior per test case.
+- Assert on observable outputs, not internal state.
+- Check error cases, not just happy paths.
+- Use descriptive test names: \`parseDate_invalidInput_throwsError\`
+  not \`test parseDate 3\`.
+
+---
+
+## 5. Architectural Patterns
+
+### Initialization Guards
+When a module has expensive async initialization, use a promise-based
+deduplication pattern to prevent multiple concurrent initializations:
+
+\`\`\`js
+let _initPromise = null;
+
+async function ensureInit() {
+  if (!_initPromise) {
+    _initPromise = doExpensiveInit(); // called ONCE
+  }
+  return _initPromise;
+}
+\`\`\`
+
+### Import/Require in Module Scope
+Dynamic \`import()\` calls should be cached at module scope.
+Never put \`import()\` inside a frequently-called function without caching.
+
+### Guard Clauses for Optional Features
+When calling into optional subsystems (plugins, workflow engines, etc.),
+always check that the subsystem is enabled before invoking:
+
+\`\`\`js
+if (!config.featureEnabled) return;
+const engine = await getEngine();
+if (!engine) return;
+await engine.process(data);
+\`\`\`
+
+---
+
+## Quick Reference: Red Flags in Code Review
+
+| Pattern | Risk | Fix |
+|---------|------|-----|
+| \`let x\` inside function body used as cache | Re-init every call | Hoist to module scope |
+| \`void asyncFn()\` | Unhandled rejection → crash | \`await\` or \`.catch()\` |
+| Async callback without try/catch | Uncaught exception → crash | Wrap in try/catch |
+| \`import()\` inside hot function, no cache | Repeated I/O, log spam | Cache at module scope |
+| Test mocking the module under test | Test proves nothing | Mock only boundaries |
+| \`setTimeout\`/\`sleep\` in tests | Flaky | Use async events/mocks |
+| No error case tests | False confidence | Add negative test cases |
+| \`git add .\` | Stages unrelated files | Stage files individually |
 `,
   },
 ];

package/kanban-adapter.mjs

@@ -241,6 +241,43 @@ function parseBooleanEnv(value, fallback = false) {
   if (["0", "false", "no", "off"].includes(key)) return false;
   return fallback;
 }
+const GH_TRANSIENT_ERROR_PATTERNS = [
+  /bad gateway/i,
+  /service unavailable/i,
+  /gateway timeout/i,
+  /http\s*502/i,
+  /http\s*503/i,
+  /http\s*504/i,
+  /econnreset/i,
+  /econnrefused/i,
+  /etimedout/i,
+  /socket hang up/i,
+  /network error/i,
+  /temporarily unavailable/i,
+  /invalid character '<' looking for beginning of value/i,
+  /unexpected token </i,
+];
+
+function sleepMs(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isGhRateLimitError(text) {
+  const errText = String(text || "").toLowerCase();
+  if (!errText) return false;
+  return (
+    errText.includes("rate limit") ||
+    errText.includes("api rate limit exceeded") ||
+    (errText.includes("403") && errText.includes("limit"))
+  );
+}
+
+function isGhTransientError(text) {
+  const errText = String(text || "").toLowerCase();
+  if (!errText) return false;
+  if (isGhRateLimitError(errText)) return false;
+  return GH_TRANSIENT_ERROR_PATTERNS.some((pattern) => pattern.test(errText));
+}
 
 function parseRepoSlug(raw) {
   const text = String(raw || "").trim().replace(/^https?:\/\/github\.com\//i, "");
@@ -1115,6 +1152,14 @@ class GitHubIssuesAdapter {
     // Rate limit retry delay (ms) — configurable for tests
     this._rateLimitRetryDelayMs =
       Number(process.env.GH_RATE_LIMIT_RETRY_MS) || 60_000;
+    this._transientRetryDelayMs = Math.max(
+      250,
+      Number(process.env.GH_TRANSIENT_RETRY_MS) || 2_000,
+    );
+    this._transientRetryMax = Math.max(
+      0,
+      Number(process.env.GH_TRANSIENT_RETRY_MAX) || 2,
+    );
   }
 
   /**
@@ -1891,46 +1936,84 @@ class GitHubIssuesAdapter {
     const execFileAsync = promisify(execFile);
 
     const attempt = async () => {
-      const { stdout, stderr } = await execFileAsync("gh", args, {
-        maxBuffer: 10 * 1024 * 1024,
-        timeout: 30_000,
-      });
-      return { stdout, stderr };
+      try {
+        const { stdout, stderr } = await execFileAsync("gh", args, {
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 30_000,
+        });
+        return { stdout, stderr };
+      } catch (err) {
+        const message = String(err?.message || err);
+        const stdout = String(err?.stdout || "");
+        const stderr = String(err?.stderr || "");
+        const ghError = new Error(message);
+        ghError.stdout = stdout;
+        ghError.stderr = stderr;
+        ghError.fullText = [message, stderr, stdout].filter(Boolean).join("\n");
+        ghError.isRateLimit = isGhRateLimitError([message, stderr].join("\n"));
+        ghError.isTransient = isGhTransientError([message, stderr, stdout].join("\n"));
+        throw ghError;
+      }
     };
 
-    let result;
-    try {
-      result = await attempt();
-    } catch (err) {
-      const errText = String(err?.message || err?.stderr || err).toLowerCase();
-      // Rate limit detection: "API rate limit exceeded" or HTTP 403
-      if (
-        errText.includes("rate limit") ||
-        errText.includes("api rate limit exceeded") ||
-        (errText.includes("403") && errText.includes("limit"))
-      ) {
-        console.warn(`${TAG} rate limit detected, waiting 60s before retry...`);
-        await new Promise((resolve) =>
-          setTimeout(resolve, this._rateLimitRetryDelayMs),
-        );
-        try {
-          result = await attempt();
-        } catch (retryErr) {
-          throw new Error(
-            `gh CLI failed (after rate limit retry): ${retryErr.message}`,
+    let usedRateLimitRetry = false;
+    let transientRetries = 0;
+    const maxTransientRetries = Math.max(0, Number(this._transientRetryMax) || 0);
+
+    while (true) {
+      let result;
+      try {
+        result = await attempt();
+      } catch (err) {
+        const message = String(err?.message || err);
+        if (err?.isRateLimit && !usedRateLimitRetry) {
+          usedRateLimitRetry = true;
+          console.warn(
+            `${TAG} rate limit detected, waiting ${this._rateLimitRetryDelayMs}ms before retry...`,
           );
+          await sleepMs(this._rateLimitRetryDelayMs);
+          continue;
         }
-      } else {
-        throw new Error(`gh CLI failed: ${err.message}`);
+        if (err?.isTransient && transientRetries < maxTransientRetries) {
+          transientRetries += 1;
+          console.warn(
+            `${TAG} transient gh failure (attempt ${transientRetries}/${maxTransientRetries}), retrying in ${this._transientRetryDelayMs}ms...`,
+          );
+          await sleepMs(this._transientRetryDelayMs);
+          continue;
+        }
+        if (err?.isRateLimit && usedRateLimitRetry) {
+          throw new Error(`gh CLI failed (after rate limit retry): ${message}`);
+        }
+        throw new Error(`gh CLI failed: ${message}`);
       }
-    }
 
-    const text = String(result.stdout || "").trim();
-    if (!parseJson) return text;
-    if (!text) return null;
-    return JSON.parse(text);
-  }
+      const text = String(result?.stdout || "").trim();
+      if (!parseJson) return text;
+      if (!text) return null;
 
+      try {
+        return JSON.parse(text);
+      } catch (err) {
+        const parseMessage = String(err?.message || err);
+        const parseContext = [parseMessage, result?.stderr || "", text.slice(0, 512)]
+          .filter(Boolean)
+          .join("\n");
+        if (
+          isGhTransientError(parseContext) &&
+          transientRetries < maxTransientRetries
+        ) {
+          transientRetries += 1;
+          console.warn(
+            `${TAG} transient gh JSON parse failure (attempt ${transientRetries}/${maxTransientRetries}), retrying in ${this._transientRetryDelayMs}ms...`,
+          );
+          await sleepMs(this._transientRetryDelayMs);
+          continue;
+        }
+        throw new Error(`gh CLI returned invalid JSON: ${parseMessage}`);
+      }
+    }
+  }
   async _ensureLabelExists(label) {
     const name = String(label || "").trim();
     if (!name) return;
@@ -4865,3 +4948,5 @@ export async function unmarkTaskIgnored(taskId) {
   );
   return false;
 }
+
+