bosun 0.35.1 → 0.35.3

package/README.md

@@ -46,13 +46,26 @@ Requires:
 
 ## What Bosun does
 
-- Routes work across Codex, Copilot, and Claude executors
+- Routes work across Codex, Copilot, Claude, and OpenCode executors
 - Automates retries, failover, and PR lifecycle management
 - Auto-labels attached PRs with `bosun-needs-fix` when CI fails (`Build + Tests`)
+- Merges passing PRs automatically through the **Bosun PR Watchdog** with a mandatory review gate (prevents destructive merges)
+- Persists workflow runs to disk and auto-resumes on restart
 - Monitors runs and recovers from stalled or broken states
 - Provides Telegram control and a Mini App dashboard
 - Integrates with GitHub, Jira, and Vibe-Kanban boards
 
+### Executor quick-start
+
+| Executor          | `primaryAgent` value | Key env vars                                                                          |
+| ----------------- | -------------------- | ------------------------------------------------------------------------------------- |
+| Codex (OpenAI)    | `codex-sdk`          | `OPENAI_API_KEY`                                                                      |
+| Copilot (VS Code) | `copilot-sdk`        | VS Code session                                                                       |
+| Claude            | `claude-sdk`         | `ANTHROPIC_API_KEY`                                                                   |
+| OpenCode          | `opencode-sdk`       | `OPENCODE_MODEL` (e.g. `anthropic/claude-opus-4-5`), `OPENCODE_PORT` (default `4096`) |
+
+Set `primaryAgent` in `.bosun/bosun.config.json` or choose an executor preset during `bosun --setup`.
+
 ---
 
 ## Telegram weekly report

package/agent-hooks.mjs

@@ -144,7 +144,7 @@ export const HOOK_EVENTS = Object.freeze([
  * Canonical SDK names.
  * @type {readonly string[]}
  */
-const VALID_SDKS = Object.freeze(["codex", "copilot", "claude"]);
+const VALID_SDKS = Object.freeze(["codex", "copilot", "claude", "opencode"]);
 
 /**
  * Wildcard indicating a hook applies to all SDKs.
@@ -715,6 +715,12 @@ export function registerBuiltinHooks(options = {}) {
     });
   }
 
+  // NOTE: Blind PostPR auto-merge has been intentionally removed.
+  // Use the "Bosun PR Watchdog" workflow template (template-bosun-pr-watchdog)
+  // to opt-in to automatic merging of bosun-attached PRs after CI passes.
+  // This prevents accidental merges in public repos and repos without the
+  // required GitHub branch-protection settings for auto-merge.
+
   console.log(`${TAG} built-in hooks registered`);
 }
 

package/agent-pool.mjs

@@ -355,6 +355,12 @@ function shouldFallbackForSdkError(error) {
   if (message.includes("overloaded") || message.includes("server error")) {
     return true;
   }
+  // Spawn failures: binary not found on Windows (.cmd resolution)
+  if (message.includes("enoent")) return true;
+  if (message.includes("file not found") || message.includes("file specified")) return true;
+  if (message.includes("os error 2")) return true;
+  if (message.includes("spawn failed")) return true;
+  if (message.includes("codex exec exited")) return true;
   return false;
 }
 
@@ -635,6 +641,16 @@ function shouldApplySdkCooldown(error) {
   if (message.includes("enotfound")) return true;
   if (message.includes("connection reset")) return true;
   if (message.includes("etimedout")) return true;
+  // Spawn failures (binary not found) — apply cooldown so we try fallback SDK
+  if (message.includes("enoent")) return true;
+  if (message.includes("file not found") || message.includes("file specified")) return true;
+  if (message.includes("os error 2")) return true;
+  if (message.includes("spawn failed")) return true;
+  // Spawn failures: codex binary not found on Windows (.cmd not resolved)
+  if (message.includes("enoent")) return true;
+  if (message.includes("file not found") || message.includes("file specified")) return true;
+  if (message.includes("os error 2")) return true;
+  if (message.includes("spawn failed")) return true;
   return false;
 }
 

package/agent-prompts.mjs

@@ -206,11 +206,17 @@ You generate production-grade backlog tasks for autonomous executors.
 - Every task title starts with one size label: [xs], [s], [m], [l], [xl], [xxl].
 - Prefer task sets that can run in parallel with low file overlap.
 - Do not call any kanban API, CLI, or external service to create tasks.
-- Output must be machine-parseable JSON in a fenced json block.
+  The workflow will automatically materialize your output into kanban tasks.
+- Output must be machine-parseable JSON — see Output Contract below.
 
-## Output Contract (Mandatory)
+## Output Contract (MANDATORY — STRICT)
 
-Return exactly one fenced json block with this shape:
+Your ENTIRE response must be a single fenced JSON block. Do NOT include any
+text, commentary, explanations, or markdown before or after the JSON block.
+The downstream parser extracts JSON from fenced blocks — any deviation causes
+task creation to fail silently.
+
+Return exactly this shape:
 
 \`\`\`json
 {
@@ -228,7 +234,8 @@ Return exactly one fenced json block with this shape:
 \`\`\`
 
 Rules:
-- Provide at least the requested task count unless blocked by duplicate safeguards.
+- The \`tasks\` array MUST contain at least the requested task count.
+- Do NOT output partial JSON, truncated arrays, or commentary mixed with JSON.
 - 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
@@ -236,6 +243,185 @@ Rules:
   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.
+`,
+  taskManager: `# Bosun Task Manager Agent
+
+You are a task management agent for Bosun, an AI orchestrator. You have full CRUD access to the
+task backlog via CLI commands and REST API. Use these tools to create, read, update, and delete tasks.
+
+## Available Interfaces
+
+You have **three ways** to manage tasks. Use whichever fits your context:
+
+### 1. CLI Commands (preferred for agents with shell access)
+
+\`\`\`bash
+# List tasks
+bosun task list                              # all tasks
+bosun task list --status todo --json         # filtered, JSON output
+bosun task list --priority high --tag ui     # by priority and tag
+bosun task list --search "provider"          # text search
+
+# Create tasks
+bosun task create --title "[s] fix(cli): Handle exit codes" --priority high --tags "cli,fix"
+bosun task create '{"title":"[m] feat(ui): Dark mode","description":"Add dark mode toggle","tags":["ui"]}'
+
+# Bulk create from JSON array
+bosun task create '[{"title":"[s] fix: Bug A"},{"title":"[m] feat: Feature B"}]'
+
+# Get task details
+bosun task get <id>                          # full ID or prefix (e.g. "abc123")
+bosun task get abc123 --json                 # JSON output
+
+# Update tasks
+bosun task update abc123 --status todo --priority critical
+bosun task update abc123 '{"tags":["ui","urgent"],"baseBranch":"origin/ui-rework"}'
+
+# Delete tasks
+bosun task delete abc123
+
+# Statistics
+bosun task stats
+bosun task stats --json
+
+# Bulk import from JSON file
+bosun task import ./backlog.json
+
+# Trigger AI task planner
+bosun task plan --count 5 --reason "Sprint planning"
+\`\`\`
+
+### 2. REST API (port 18432 — always available when bosun daemon runs)
+
+\`\`\`bash
+# List tasks
+curl http://127.0.0.1:18432/api/tasks
+curl "http://127.0.0.1:18432/api/tasks?status=todo"
+
+# Get task detail
+curl "http://127.0.0.1:18432/api/tasks/detail?id=<task-id>"
+
+# Create task
+curl -X POST http://127.0.0.1:18432/api/tasks/create \\
+  -H "Content-Type: application/json" \\
+  -d '{"title":"[s] fix(cli): Exit code","priority":"high","tags":["cli"]}'
+
+# Update task
+curl -X POST http://127.0.0.1:18432/api/tasks/update \\
+  -H "Content-Type: application/json" \\
+  -d '{"taskId":"<id>","status":"todo","priority":"critical"}'
+
+# Edit task fields
+curl -X POST http://127.0.0.1:18432/api/tasks/edit \\
+  -H "Content-Type: application/json" \\
+  -d '{"taskId":"<id>","title":"Updated title","description":"Updated desc"}'
+
+# Start task execution
+curl -X POST http://127.0.0.1:18432/api/tasks/start \\
+  -H "Content-Type: application/json" \\
+  -d '{"taskId":"<id>"}'
+\`\`\`
+
+### 3. Direct Node.js API (for scripts and other agents)
+
+\`\`\`javascript
+import { taskCreate, taskList, taskGet, taskUpdate, taskDelete, taskStats, taskImport } from 'bosun/task-cli.mjs';
+
+// Create
+const task = await taskCreate({
+  title: "[m] feat(ui): Dark mode",
+  description: "Add dark mode toggle to settings panel",
+  priority: "high",
+  tags: ["ui", "theme"],
+  baseBranch: "main"
+});
+
+// List with filters
+const todos = await taskList({ status: "todo", priority: "high" });
+
+// Update
+await taskUpdate(task.id, { status: "todo", priority: "critical" });
+
+// Delete
+await taskDelete(task.id);
+
+// Bulk import from file
+const result = await taskImport("./backlog.json");
+\`\`\`
+
+## Task Schema
+
+Every task has these fields:
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| \`title\` | string | yes | — | \`[size] type(scope): description\` format |
+| \`description\` | string | — | \`""\` | Full task description (markdown). Primary agent prompt. |
+| \`status\` | string | — | \`"draft"\` | \`draft\` → \`todo\` → \`inprogress\` → \`inreview\` → \`done\` |
+| \`priority\` | string | — | \`"medium"\` | \`low\`, \`medium\`, \`high\`, \`critical\` |
+| \`tags\` | string[] | — | \`[]\` | Lowercase labels for categorization |
+| \`baseBranch\` | string | — | \`"main"\` | Target git branch for this task |
+| \`workspace\` | string | — | cwd | Path to workspace directory |
+| \`repository\` | string | — | \`""\` | Repository identifier (e.g. \`org/repo\`) |
+| \`draft\` | boolean | — | \`true\` | Draft tasks are not picked up by executors |
+
+### Structured Description Fields (accepted by create/import)
+
+When creating tasks, you can provide structured fields that get formatted into the description:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`implementation_steps\` | string[] | Ordered steps for the agent to follow |
+| \`acceptance_criteria\` | string[] | Binary pass/fail conditions |
+| \`verification\` | string[] | Commands to run to verify completion |
+
+These get appended to the description as markdown sections automatically.
+
+### Valid Status Transitions
+
+\`\`\`
+draft → todo → inprogress → inreview → done
+                    ↓            ↓
+                 blocked      blocked
+\`\`\`
+
+- **draft**: Not yet ready for execution. Agents will not pick these up.
+- **todo**: Ready for execution. Next idle agent will claim it.
+- **inprogress**: Agent is actively working on it.
+- **inreview**: Agent completed, PR created, awaiting review.
+- **done**: Task completed and merged.
+- **blocked**: Stuck on external dependency.
+
+## Title Conventions
+
+\`\`\`
+[size] type(scope): Concise action-oriented description
+\`\`\`
+
+### Size Labels
+| Label | Time | Scope |
+|-------|------|-------|
+| \`[xs]\` | < 30 min | Single-file fix |
+| \`[s]\` | 30 min – 2 hr | Small feature, one module |
+| \`[m]\` | 2 – 6 hr | Multi-file feature |
+| \`[l]\` | 6 – 16 hr | Cross-module work |
+| \`[xl]\` | 1 – 3 days | Major feature |
+
+### Conventional Commit Types
+\`feat\`, \`fix\`, \`docs\`, \`style\`, \`refactor\`, \`perf\`, \`test\`, \`build\`, \`ci\`, \`chore\`
+
+## Tips for Effective Task Management
+
+1. **Match task sizes to project maturity** — If the codebase is still early stage, prioritize [xl] and [l]
+   tasks to build core functionality. Switch to [m] and [s] for refinement. Avoid [xs] unless urgent.
+2. **Be specific** — The description is the agent's primary prompt. Include file paths and concrete actions.
+3. **Minimize file overlap** — Tasks editing the same files cause merge conflicts during parallel execution.
+4. **Set baseBranch** — If a task targets a module branch, set \`baseBranch\` to route correctly.
+5. **Use tags** — Tags help filter and organize. Use lowercase, comma-separated.
+6. **Draft first** — Create as \`draft\`, review, then promote to \`todo\` when ready.
+7. **Module branch routing** — When a task title follows conventional commit format
+   \`feat(module):\` or \`fix(module):\`, set \`baseBranch\` to \`origin/<module>\` to route the task
+   to the module's dedicated branch for parallel, isolated development.
 `,
   monitorMonitor: `# Bosun-Monitor Agent
 

package/agent-sdk.mjs

@@ -10,7 +10,7 @@
 
 import { readCodexConfig } from "./codex-config.mjs";
 
-const SUPPORTED_PRIMARY = new Set(["codex", "copilot", "claude"]);
+const SUPPORTED_PRIMARY = new Set(["codex", "copilot", "claude", "opencode"]);
 const DEFAULT_PRIMARY = "codex";
 
 const DEFAULT_CAPABILITIES_BY_PRIMARY = {
@@ -29,6 +29,11 @@ const DEFAULT_CAPABILITIES_BY_PRIMARY = {
     subagents: true,
     vscodeTools: false,
   },
+  opencode: {
+    steering: true,
+    subagents: true,
+    vscodeTools: false,
+  },
 };
 
 const DEFAULT_CAPABILITIES = {

package/agent-work-analyzer.mjs

@@ -64,8 +64,9 @@ const activeSessions = new Map();
 const alertCooldowns = new Map();
 const ALERT_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes between same alert
 const FAILED_SESSION_ALERT_MIN_COOLDOWN_MS = 60 * 60 * 1000; // Keep noisy failed-session summaries coarse-grained
+const FAILED_SESSION_TRANSIENT_ALERT_MIN_COOLDOWN_MS = 2 * 60 * 60 * 1000; // Transient API/provider failures should back off longer
 const ALERT_COOLDOWN_RETENTION_MS = Math.max(
-  FAILED_SESSION_ALERT_MIN_COOLDOWN_MS * 3,
+  FAILED_SESSION_TRANSIENT_ALERT_MIN_COOLDOWN_MS * 3,
   3 * 60 * 60 * 1000,
 ); // keep cooldown history bounded
 const ALERT_COOLDOWN_REPLAY_MAX_BYTES = Math.max(
@@ -78,6 +79,9 @@ function getAlertCooldownMs(alert) {
   if (type === "failed_session_high_errors") {
     return Math.max(ALERT_COOLDOWN_MS, FAILED_SESSION_ALERT_MIN_COOLDOWN_MS);
   }
+  if (type === "failed_session_transient_errors") {
+    return Math.max(ALERT_COOLDOWN_MS, FAILED_SESSION_TRANSIENT_ALERT_MIN_COOLDOWN_MS);
+  }
   return Math.max(0, ALERT_COOLDOWN_MS);
 }
 
@@ -99,12 +103,35 @@ function deriveAlertScopeId(alert) {
 function buildAlertCooldownKey(alert) {
   const type = String(alert?.type || "unknown").trim().toLowerCase() || "unknown";
   const scopeId = deriveAlertScopeId(alert);
-  if (scopeId && (type === "failed_session_high_errors" || type === "stuck_agent")) {
+  if (
+    scopeId &&
+    (
+      type === "failed_session_high_errors" ||
+      type === "failed_session_transient_errors" ||
+      type === "stuck_agent"
+    )
+  ) {
     return `${type}:task:${scopeId}`;
   }
   return `${type}:${String(alert?.attempt_id || "unknown")}`;
 }
 
+function isTransientFailureFingerprint(value) {
+  const text = String(value || "").toLowerCase();
+  if (!text) return false;
+  return (
+    text.includes("reconnect") ||
+    text.includes("stream disconnected") ||
+    text.includes("response.failed") ||
+    text.includes("rate limit") ||
+    text.includes("high demand") ||
+    text.includes("provisioned throughput") ||
+    text.includes("timeout") ||
+    text.includes("econnreset") ||
+    text.includes("temporarily unavailable")
+  );
+}
+
 function pruneStaleAlertCooldowns(nowMs = Date.now()) {
   const now = Number(nowMs) || Date.now();
   const cutoff = now - ALERT_COOLDOWN_RETENTION_MS;
@@ -124,7 +151,11 @@ async function hydrateAlertCooldownsFromLog() {
     const start = Math.max(0, fileStat.size - ALERT_COOLDOWN_REPLAY_MAX_BYTES);
     const stream = createReadStream(ALERTS_LOG, { start, encoding: "utf8" });
     const rl = createInterface({ input: stream, crlfDelay: Infinity });
-    const maxCooldownMs = Math.max(ALERT_COOLDOWN_MS, FAILED_SESSION_ALERT_MIN_COOLDOWN_MS);
+    const maxCooldownMs = Math.max(
+      ALERT_COOLDOWN_MS,
+      FAILED_SESSION_ALERT_MIN_COOLDOWN_MS,
+      FAILED_SESSION_TRANSIENT_ALERT_MIN_COOLDOWN_MS,
+    );
     const cutoff = Date.now() - maxCooldownMs;
     for await (const line of rl) {
       const trimmed = String(line || "").trim();
@@ -514,17 +545,25 @@ async function analyzeSessionEnd(session, event) {
     completion_status === "failed" &&
     session.errors.length >= ERROR_LOOP_THRESHOLD
   ) {
+    const errorFingerprints = [...new Set(session.errors.map((e) => e.fingerprint))];
+    const transientErrorCount = errorFingerprints.filter((fp) => isTransientFailureFingerprint(fp)).length;
+    const transientOnlySession = transientErrorCount > 0 && transientErrorCount === errorFingerprints.length;
+    const alertType = transientOnlySession
+      ? "failed_session_transient_errors"
+      : "failed_session_high_errors";
+    const recommendation = transientOnlySession
+      ? "switch_sdk_or_backoff_retry"
+      : "analyze_root_cause";
+
     await emitAlert({
-      type: "failed_session_high_errors",
+      type: alertType,
       attempt_id: session.attempt_id,
       task_id: session.taskId,
       executor: session.executor,
       error_count: session.errors.length,
-      error_fingerprints: [
-        ...new Set(session.errors.map((e) => e.fingerprint)),
-      ],
-      recommendation: "analyze_root_cause",
-      severity: "high",
+      error_fingerprints: errorFingerprints,
+      recommendation,
+      severity: transientOnlySession ? "medium" : "high",
     });
   }
 }

package/autofix.mjs

@@ -555,12 +555,14 @@ export function runCodexExec(
         env: codexEnv,
       };
       if (process.platform === "win32") {
-        // On Windows, avoid spawning via a shell with a concatenated command
-        // string. Instead, invoke the binary directly with an argument array
-        // just like on POSIX platforms to prevent command injection.
+        // On Windows, spawn with shell: true so cmd.exe can resolve .cmd/.ps1
+        // shims (e.g. codex.cmd installed by npm). Without shell: true, Node's
+        // spawn() looks for a literal "codex" executable which doesn't exist
+        // on Windows — only codex.cmd does — causing ENOENT (os error 2).
+        // Arguments are passed as an array so shell word-splitting is safe.
         child = spawn("codex", args, {
           ...spawnOptions,
-          shell: false,
+          shell: true,
         });
       } else {
         child = spawn("codex", args, {
@@ -620,14 +622,13 @@ export function runCodexExec(
     });
 
     const timer = setTimeout(() => {
-      stream.write(`\n\n## TIMEOUT after ${timeoutMs}ms\n`);
+      try { stream.write(`\n\n## TIMEOUT after ${timeoutMs}ms\n`); } catch { /* best effort */ }
       try {
         child.kill("SIGTERM");
       } catch {
         /* best effort */
       }
-      stream.end();
-      promiseResolve({
+      resolveOnce({
         success: false,
         output: stdout,
         error: "timeout after " + timeoutMs + "ms",
@@ -635,27 +636,40 @@ export function runCodexExec(
       });
     }, timeoutMs);
 
-    child.on("error", (err) => {
+    // Guard against double-resolution: on Windows ENOENT spawns fire
+    // both "error" and "exit" events — the second promiseResolve is harmless
+    // but stream.end() must only be called once.
+    let resolved = false;
+    function resolveOnce(result) {
+      if (resolved) return;
+      resolved = true;
       clearTimeout(timer);
-      stream.write(`\n\n## ERROR: ${err.message}\n`);
-      stream.end();
-      promiseResolve({
+      try { stream.end(); } catch { /* best effort */ }
+      promiseResolve(result);
+    }
+
+    child.on("error", (err) => {
+      try { stream.write(`\n\n## ERROR: ${err.message}\n`); } catch { /* best effort */ }
+      const errorMsg = err.code === "ENOENT"
+        ? `Codex Exec exited with code 1: Error: The system cannot find the file specified. (os error 2) — is the 'codex' CLI installed and on PATH?`
+        : err.message;
+      resolveOnce({
         success: false,
         output: stdout,
-        error: err.message,
+        error: errorMsg,
         logPath,
       });
     });
 
     child.on("exit", (code) => {
-      clearTimeout(timer);
-      stream.write(`\n\n## Exit code: ${code}\n`);
-      stream.write(`\n## stderr:\n${stderr}\n`);
-      stream.end();
-      promiseResolve({
+      try {
+        stream.write(`\n\n## Exit code: ${code}\n`);
+        stream.write(`\n## stderr:\n${stderr}\n`);
+      } catch { /* best effort */ }
+      resolveOnce({
         success: code === 0,
         output: stdout + (stderr ? "\n" + stderr : ""),
-        error: code !== 0 ? `exit code ${code}` : null,
+        error: code !== 0 ? `Codex Exec exited with code ${code}${stderr ? ": " + stderr.trim().slice(0, 200) : ""}` : null,
         logPath,
       });
     });

package/bosun.schema.json

@@ -38,7 +38,7 @@
     "codexEnabled": { "type": "boolean" },
     "primaryAgent": {
       "type": "string",
-      "enum": ["codex-sdk", "copilot-sdk", "claude-sdk"]
+      "enum": ["codex-sdk", "copilot-sdk", "claude-sdk", "opencode-sdk"]
     },
     "vkSpawnEnabled": { "type": "boolean" },
     "kanban": {

package/kanban-adapter.mjs

@@ -293,8 +293,41 @@ function _issueListCacheKey(state, limit) {
 }
 
 /** Build a cache key for the shared-state cache (per adapter instance). */
-function _sharedStateCacheKey(num) {
-  return String(num);
+function _sharedStateCacheKey(num, repoKey = "") {
+  const normalizedNum = String(num || "").trim();
+  const normalizedRepo = String(repoKey || "").trim().toLowerCase();
+  return normalizedRepo ? `${normalizedRepo}#${normalizedNum}` : normalizedNum;
+}
+
+function parseIssueLocator(issueNumber, defaultOwner, defaultRepo, issueUrl = "") {
+  const urlText = String(issueUrl || issueNumber || "").trim();
+  const urlMatch = urlText.match(
+    /github\.com\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)(?:\b|$)/i,
+  );
+  if (urlMatch) {
+    const owner = String(urlMatch[1] || "").trim();
+    const repo = String(urlMatch[2] || "")
+      .trim()
+      .replace(/\.git$/i, "");
+    const number = String(urlMatch[3] || "").trim();
+    return {
+      owner,
+      repo,
+      number,
+      repoKey: `${owner}/${repo}`.toLowerCase(),
+    };
+  }
+  const number = String(issueNumber || "")
+    .trim()
+    .replace(/^#/, "");
+  const owner = String(defaultOwner || "").trim();
+  const repo = String(defaultRepo || "").trim();
+  return {
+    owner,
+    repo,
+    number,
+    repoKey: `${owner}/${repo}`.toLowerCase(),
+  };
 }
 
 function isGhRateLimitError(text) {
@@ -2361,7 +2394,9 @@ class GitHubIssuesAdapter {
           for (const task of filtered) {
             try {
               const sharedState = normalizeSharedStatePayload(
-                await this.readSharedStateFromIssue(task.id),
+                await this.readSharedStateFromIssue(task.id, null, {
+                  issueUrl: task?.meta?.url || task?.taskUrl || null,
+                }),
               );
               if (sharedState) {
                 task.meta.sharedState = sharedState;
@@ -3234,8 +3269,15 @@ ${stateJson}
    *   console.log(`Task claimed by ${state.ownerId}`);
    * }
    */
-  async readSharedStateFromIssue(issueNumber, cachedComments = null) {
-    const num = String(issueNumber).replace(/^#/, "");
+  async readSharedStateFromIssue(issueNumber, cachedComments = null, options = {}) {
+    const issueUrl = String(options?.issueUrl || "").trim();
+    const locator = parseIssueLocator(
+      issueNumber,
+      this._owner,
+      this._repo,
+      issueUrl,
+    );
+    const num = locator.number;
     if (!/^\d+$/.test(num)) {
       throw new Error(`Invalid issue number: ${issueNumber}`);
     }
@@ -3243,7 +3285,7 @@ ${stateJson}
     // If no pre-fetched comments, check the instance-level shared-state cache
     // to avoid a separate API call per issue during bulk listTasks cycles.
     if (!cachedComments) {
-      const cacheKey = _sharedStateCacheKey(num);
+      const cacheKey = _sharedStateCacheKey(num, locator.repoKey);
       const cached = this._sharedStateCache.get(cacheKey);
       if (cached && Date.now() - cached.ts < GH_SHARED_STATE_CACHE_TTL_MS) {
         return cached.data;
@@ -3251,7 +3293,8 @@ ${stateJson}
     }
 
     try {
-      const comments = cachedComments ?? await this._getIssueComments(num);
+      const comments =
+        cachedComments ?? await this._getIssueComments(num, { issueUrl });
       const stateComment = Array.isArray(comments)
         ? comments
             .slice()
@@ -3263,7 +3306,7 @@ ${stateJson}
         // Cache the null result too so repeated calls within the TTL skip the API
         if (!cachedComments) {
           this._sharedStateCache.set(
-            _sharedStateCacheKey(num),
+            _sharedStateCacheKey(num, locator.repoKey),
             { data: null, ts: Date.now() },
           );
         }
@@ -3298,7 +3341,7 @@ ${stateJson}
       // Cache the result for the TTL window
       if (!cachedComments) {
         this._sharedStateCache.set(
-          _sharedStateCacheKey(num),
+          _sharedStateCacheKey(num, locator.repoKey),
           { data: state, ts: Date.now() },
         );
       }
@@ -3424,18 +3467,25 @@ To re-enable bosun for this task, remove the \`${this._codexLabels.ignore}\` lab
    * Get all comments for an issue.
    * @private
    */
-  async _getIssueComments(issueNumber) {
+  async _getIssueComments(issueNumber, options = {}) {
+    const issueUrl = String(options?.issueUrl || "").trim();
+    const locator = parseIssueLocator(
+      issueNumber,
+      this._owner,
+      this._repo,
+      issueUrl,
+    );
     try {
       const result = await this._gh([
         "api",
-        `/repos/${this._owner}/${this._repo}/issues/${issueNumber}/comments`,
+        `/repos/${locator.owner}/${locator.repo}/issues/${locator.number}/comments`,
         "--jq",
         ".",
       ]);
       return Array.isArray(result) ? result : [];
     } catch (err) {
       console.warn(
-        `[kanban] failed to fetch comments for #${issueNumber}: ${err.message}`,
+        `[kanban] failed to fetch comments for ${locator.owner}/${locator.repo}#${locator.number}: ${err.message}`,
       );
       return [];
     }