bosun 0.36.29 → 0.37.1

package/.env.example

@@ -4,8 +4,8 @@
 # All variables are optional unless marked [REQUIRED].
 # Boolean flags use true/false (preferred). Legacy 1/0 is still accepted.
 # Profile guidance:
-#  - Local development: DEVMODE=true, DEVMODE_MONITOR_MONITOR_ENABLED=true, *_TRANSPORT=sdk
-#  - End-user stable:  DEVMODE=false, DEVMODE_MONITOR_MONITOR_ENABLED=false, *_TRANSPORT=sdk
+#  - Local development: DEVMODE=true, *_TRANSPORT=sdk
+#  - End-user stable:  DEVMODE=false, *_TRANSPORT=sdk
 
 # ─── Task Claims and Coordination ─────────────────────────────────────────────
 # Shared state manager enables distributed task coordination across multiple
@@ -222,10 +222,6 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # SENTINEL_RESTART_BACKOFF_SEC=5
 # After manual /stop, suppress auto-restart for this many minutes (default: 10)
 # SENTINEL_MANUAL_STOP_HOLD_MIN=10
-# In devmode, validate monitor-monitor freshness before restart decisions (default: 1)
-# SENTINEL_MONITOR_MONITOR_CHECK_ENABLED=true
-# Max acceptable monitor-monitor age in minutes (default: 20)
-# SENTINEL_MONITOR_MONITOR_MAX_AGE_MIN=20
 
 # ─── Notification Batching (RECOMMENDED) ─────────────────────────────────────
 # Batch notifications into periodic summaries instead of spamming individual messages
@@ -776,31 +772,6 @@ VK_RECOVERY_PORT=54089
 # scripts check for this and exit silently if not present, preventing
 # hooks from firing in standalone Copilot/Codex/Claude sessions.
 
-# ─── Devmode Monitor-Monitor (24/7 reliability guardian) ───────────────────
-# Prompt is injected directly from bosun source (no .github/agents file required).
-# Enabled by default in devmode source checkouts. Set to false to disable.
-# DEVMODE_MONITOR_MONITOR_ENABLED=true
-# Poll interval for monitor-monitor runs (milliseconds). Default: 300000 (5 min)
-# DEVMODE_MONITOR_MONITOR_INTERVAL_MS=300000
-# Status stream update interval (milliseconds). Default: 1800000 (30 min)
-# DEVMODE_MONITOR_MONITOR_STATUS_INTERVAL_MS=1800000
-# Per-run timeout before watchdog abort/failover (milliseconds).
-# Default is 21600000 (6h) for long-running reliability analysis sessions.
-# 30 minutes (1800000) is safe if you prefer faster failover on stuck runs.
-# Watchdog abort triggers at timeout+60s, then accelerated force-reset at +120s.
-# Set this explicitly to avoid inherited shell
-# defaults (for example DEVMODE_AUTO_CODE_FIX_TIMEOUT_MS=300000).
-# DEVMODE_MONITOR_MONITOR_TIMEOUT_MS=1800000
-# Optional timeout bounds (applied only when set):
-# DEVMODE_MONITOR_MONITOR_TIMEOUT_MIN_MS=600000
-# DEVMODE_MONITOR_MONITOR_TIMEOUT_MAX_MS=7200000
-# Optional override for Claude tool access (comma-separated)
-# DEVMODE_MONITOR_MONITOR_CLAUDE_ALLOWED_TOOLS=Read,Write,Edit,Grep,Glob,Bash,WebSearch,Task,Skill
-# Legacy alias: DEVMODE_AUTO_CODE_FIX=true also enables this subsystem.
-# Legacy timeout fallback: if DEVMODE_MONITOR_MONITOR_TIMEOUT_MS is unset and
-# DEVMODE_AUTO_CODE_FIX_TIMEOUT_MS is set, monitor-monitor will use it (and
-# still apply DEVMODE_MONITOR_MONITOR_TIMEOUT_MIN_MS/MAX_MS bounds if provided).
-
 # ─── Copilot SDK (Primary Agent) ─────────────────────────────────────────────
 # Requires GitHub Copilot CLI installed and authenticated.
 # Set to true to disable Copilot SDK (primary agent) usage.
@@ -1046,7 +1017,6 @@ COPILOT_CLOUD_DISABLED=true
 # Files in that folder are loaded automatically and are intended for per-project customization.
 # You can also override any prompt path explicitly with env vars:
 # BOSUN_PROMPT_PLANNER=.bosun/agents/task-planner.md
-# BOSUN_PROMPT_MONITOR_MONITOR=.bosun/agents/monitor-monitor.md
 # BOSUN_PROMPT_TASK_EXECUTOR=.bosun/agents/task-executor.md
 # BOSUN_PROMPT_REVIEWER=.bosun/agents/reviewer.md
 # BOSUN_PROMPT_SDK_CONFLICT_RESOLVER=.bosun/agents/sdk-conflict-resolver.md

package/agent-prompts.mjs

@@ -17,16 +17,6 @@ const PROMPT_DEFS = [
     filename: "orchestrator.md",
     description: "Primary task execution prompt for autonomous task agents.",
   },
-  {
-    key: "planner",
-    filename: "task-planner.md",
-    description: "Backlog planning prompt used by task planner runs.",
-  },
-  {
-    key: "monitorMonitor",
-    filename: "monitor-monitor.md",
-    description: "Long-running reliability monitor prompt used in devmode.",
-  },
   {
     key: "taskExecutor",
     filename: "task-executor.md",
@@ -199,68 +189,6 @@ apply patterns discovered by previous agents:
 After completing a task, if you discovered a non-obvious pattern, workaround, or
 domain-specific fact, write or update a skill file at \`.bosun/skills/<module>.md\`
 so the next agent benefits from your investigation.
-`,
-  planner: `# Codex-Task-Planner Agent
-
-You generate production-grade backlog tasks for autonomous executors.
-
-## Mission
-
-1. Analyze current repo and delivery state.
-2. Identify highest-value next work.
-3. Create concrete, execution-ready tasks.
-
-## Requirements
-
-- Avoid vague tasks and duplicate work.
-- Balance reliability fixes, feature delivery, and debt reduction.
-- Every task includes implementation steps, acceptance criteria, and verification plan.
-- 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.
-  The workflow will automatically materialize your output into kanban tasks.
-- Output must be machine-parseable JSON — see Output Contract below.
-- Task objects must be valid for Bosun backlog creation with fields:
-  \'title\', \'description\', \'implementation_steps\', \'acceptance_criteria\',
-  \'verification\', optional \'base_branch\'.
-- Do not emit empty or placeholder tasks. Every task must be actionable and execution-ready.
-
-## Output Contract (MANDATORY — STRICT)
-
-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 hard-fail.
-
-Return exactly this shape:
-
-\`\`\`json
-{
-  "tasks": [
-    {
-      "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"],
-      "base_branch": "origin/veid"
-    }
-  ]
-}
-\`\`\`
-
-Rules:
-- 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.
-- Descriptions must include concrete implementation details, not generic intent text.
-- Include verification commands/checks that a worker can run without additional planning.
-- **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.
 `,
   taskManager: `# Bosun Task Manager Agent
 
@@ -305,8 +233,6 @@ 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)
@@ -440,23 +366,6 @@ draft → todo → inprogress → inreview → done
 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
-
-You are the always-on reliability guardian for bosun in devmode.
-
-## Core Role
-
-- Monitor logs, failures, and agent/orchestrator behavior continuously.
-- Immediately fix reliability regressions and execution blockers.
-- Improve prompt/tool/executor reliability to reduce failure loops.
-- Only when runtime is healthy, perform code-analysis improvements.
-
-## Constraints
-
-- Operate only in devmode.
-- Do not commit/push/initiate PR lifecycle changes in this context.
-- Apply focused fixes, run focused validation, and keep monitoring.
 `,
   taskExecutor: `# {{TASK_ID}} — {{TASK_TITLE}}
 

package/agent-tool-config.mjs

@@ -0,0 +1,327 @@
+/**
+ * agent-tool-config.mjs — Per-Agent Tool Configuration Store
+ *
+ * Manages which tools and MCP servers are enabled for each agent profile.
+ * Persisted as `.bosun/agent-tools.json` alongside the library manifest.
+ *
+ * Schema:
+ *   {
+ *     "agents": {
+ *       "<agentId>": {
+ *         "enabledTools": ["tool1", "tool2"] | null,   // null = all tools
+ *         "enabledMcpServers": ["github", "context7"],  // enabled MCP server IDs
+ *         "disabledBuiltinTools": ["tool3"],             // explicitly disabled builtins
+ *         "updatedAt": "2026-01-01T00:00:00.000Z"
+ *       }
+ *     },
+ *     "defaults": {
+ *       "builtinTools": [...],          // default tool list for all agents
+ *       "updatedAt": "..."
+ *     }
+ *   }
+ *
+ * EXPORTS:
+ *   DEFAULT_BUILTIN_TOOLS         — list of default built-in tools for voice/agents
+ *   loadToolConfig(rootDir)       — load the full config
+ *   saveToolConfig(rootDir, cfg)  — save the full config
+ *   getAgentToolConfig(rootDir, agentId) — get config for one agent
+ *   setAgentToolConfig(rootDir, agentId, config) — update config for one agent
+ *   getEffectiveTools(rootDir, agentId)  — compute final enabled tools list
+ *   listAvailableTools(rootDir)   — list all available tools (builtin + MCP)
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const TAG = "[agent-tool-config]";
+const CONFIG_FILE = "agent-tools.json";
+
+function getBosunHome() {
+  return (
+    process.env.BOSUN_HOME ||
+    process.env.BOSUN_DIR ||
+    resolve(homedir(), ".bosun")
+  );
+}
+
+/**
+ * Default built-in tools available to all voice agents and executors.
+ * Maps to common capabilities that voice/agent sessions can invoke.
+ */
+export const DEFAULT_BUILTIN_TOOLS = Object.freeze([
+  {
+    id: "search-files",
+    name: "Search Files",
+    description: "Search for files in the workspace by name or pattern",
+    category: "Built-In",
+    icon: ":search:",
+    default: true,
+  },
+  {
+    id: "read-file",
+    name: "Read File",
+    description: "Read contents of a file in the workspace",
+    category: "Built-In",
+    icon: ":file:",
+    default: true,
+  },
+  {
+    id: "edit-file",
+    name: "Edit File",
+    description: "Create or edit files in the workspace",
+    category: "Built-In",
+    icon: ":edit:",
+    default: true,
+  },
+  {
+    id: "run-command",
+    name: "Run Terminal Command",
+    description: "Execute shell commands in a terminal",
+    category: "Built-In",
+    icon: ":terminal:",
+    default: true,
+  },
+  {
+    id: "web-search",
+    name: "Web Search",
+    description: "Search the web for information",
+    category: "Built-In",
+    icon: ":globe:",
+    default: true,
+  },
+  {
+    id: "code-search",
+    name: "Semantic Code Search",
+    description: "Search codebase semantically for relevant code",
+    category: "Built-In",
+    icon: ":cpu:",
+    default: true,
+  },
+  {
+    id: "git-operations",
+    name: "Git Operations",
+    description: "Run git commands (commit, push, branch, etc.)",
+    category: "Built-In",
+    icon: ":git:",
+    default: true,
+  },
+  {
+    id: "create-task",
+    name: "Create Task",
+    description: "Create new tasks and issues",
+    category: "Built-In",
+    icon: ":check:",
+    default: true,
+  },
+  {
+    id: "delegate-task",
+    name: "Delegate to Agent",
+    description: "Delegate work to another agent executor",
+    category: "Built-In",
+    icon: ":bot:",
+    default: true,
+  },
+  {
+    id: "fetch-url",
+    name: "Fetch URL",
+    description: "Fetch content from a URL and convert for LLM usage",
+    category: "Built-In",
+    icon: ":link:",
+    default: true,
+  },
+  {
+    id: "list-directory",
+    name: "List Directory",
+    description: "List contents of a directory in the workspace",
+    category: "Built-In",
+    icon: ":folder:",
+    default: true,
+  },
+  {
+    id: "grep-search",
+    name: "Text Search (Grep)",
+    description: "Search for exact text or regex patterns in files",
+    category: "Built-In",
+    icon: ":search:",
+    default: true,
+  },
+  {
+    id: "task-management",
+    name: "Task Management",
+    description: "Track and manage todo items and task status",
+    category: "Built-In",
+    icon: ":clipboard:",
+    default: true,
+  },
+  {
+    id: "notifications",
+    name: "Send Notifications",
+    description: "Send notifications via Telegram, webhook, etc.",
+    category: "Built-In",
+    icon: ":bell:",
+    default: false,
+  },
+  {
+    id: "vision-analysis",
+    name: "Vision Analysis",
+    description: "Analyze images and screenshots",
+    category: "Built-In",
+    icon: ":eye:",
+    default: true,
+  },
+]);
+
+// ── Config File I/O ───────────────────────────────────────────────────────────
+
+function getConfigPath(rootDir) {
+  return resolve(rootDir || getBosunHome(), ".bosun", CONFIG_FILE);
+}
+
+/**
+ * Load the agent tool configuration.
+ * @param {string} [rootDir]
+ * @returns {{ agents: Object, defaults: Object }}
+ */
+export function loadToolConfig(rootDir) {
+  const configPath = getConfigPath(rootDir);
+  if (!existsSync(configPath)) {
+    return {
+      agents: {},
+      defaults: {
+        builtinTools: DEFAULT_BUILTIN_TOOLS.filter((t) => t.default).map((t) => t.id),
+        updatedAt: new Date().toISOString(),
+      },
+    };
+  }
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      agents: parsed.agents || {},
+      defaults: parsed.defaults || {
+        builtinTools: DEFAULT_BUILTIN_TOOLS.filter((t) => t.default).map((t) => t.id),
+        updatedAt: new Date().toISOString(),
+      },
+    };
+  } catch {
+    return {
+      agents: {},
+      defaults: {
+        builtinTools: DEFAULT_BUILTIN_TOOLS.filter((t) => t.default).map((t) => t.id),
+        updatedAt: new Date().toISOString(),
+      },
+    };
+  }
+}
+
+/**
+ * Save the full tool configuration.
+ * @param {string} rootDir
+ * @param {{ agents: Object, defaults: Object }} config
+ */
+export function saveToolConfig(rootDir, config) {
+  const configPath = getConfigPath(rootDir);
+  const dir = resolve(configPath, "..");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Get tool configuration for a specific agent.
+ * @param {string} rootDir
+ * @param {string} agentId
+ * @returns {{ enabledTools: string[]|null, enabledMcpServers: string[], disabledBuiltinTools: string[] }}
+ */
+export function getAgentToolConfig(rootDir, agentId) {
+  const config = loadToolConfig(rootDir);
+  const agentConfig = config.agents[agentId];
+  if (!agentConfig) {
+    return {
+      enabledTools: null,
+      enabledMcpServers: [],
+      disabledBuiltinTools: [],
+    };
+  }
+  return {
+    enabledTools: agentConfig.enabledTools ?? null,
+    enabledMcpServers: agentConfig.enabledMcpServers || [],
+    disabledBuiltinTools: agentConfig.disabledBuiltinTools || [],
+  };
+}
+
+/**
+ * Update tool configuration for a specific agent.
+ * @param {string} rootDir
+ * @param {string} agentId
+ * @param {{ enabledTools?: string[]|null, enabledMcpServers?: string[], disabledBuiltinTools?: string[] }} update
+ * @returns {{ ok: boolean }}
+ */
+export function setAgentToolConfig(rootDir, agentId, update) {
+  const config = loadToolConfig(rootDir);
+  const existing = config.agents[agentId] || {};
+  config.agents[agentId] = {
+    ...existing,
+    enabledTools: update.enabledTools !== undefined ? update.enabledTools : (existing.enabledTools ?? null),
+    enabledMcpServers: update.enabledMcpServers !== undefined ? update.enabledMcpServers : (existing.enabledMcpServers || []),
+    disabledBuiltinTools: update.disabledBuiltinTools !== undefined ? update.disabledBuiltinTools : (existing.disabledBuiltinTools || []),
+    updatedAt: new Date().toISOString(),
+  };
+  saveToolConfig(rootDir, config);
+  return { ok: true };
+}
+
+/**
+ * Compute the effective enabled tools for an agent.
+ * Merges builtin defaults with agent-specific overrides and MCP servers.
+ *
+ * @param {string} rootDir
+ * @param {string} agentId
+ * @returns {{ builtinTools: Array<{ id: string, name: string, enabled: boolean }>, mcpServers: string[] }}
+ */
+export function getEffectiveTools(rootDir, agentId) {
+  const config = loadToolConfig(rootDir);
+  const agentConfig = config.agents[agentId] || {};
+  const disabledSet = new Set(agentConfig.disabledBuiltinTools || []);
+  const defaultIds = new Set(config.defaults?.builtinTools || DEFAULT_BUILTIN_TOOLS.filter((t) => t.default).map((t) => t.id));
+
+  const builtinTools = DEFAULT_BUILTIN_TOOLS.map((tool) => ({
+    ...tool,
+    enabled: !disabledSet.has(tool.id) && (agentConfig.enabledTools === null || agentConfig.enabledTools === undefined
+      ? defaultIds.has(tool.id)
+      : agentConfig.enabledTools.includes(tool.id)),
+  }));
+
+  return {
+    builtinTools,
+    mcpServers: agentConfig.enabledMcpServers || [],
+  };
+}
+
+/**
+ * List all available tools (builtin + installed MCP servers).
+ * @param {string} rootDir
+ * @returns {{ builtinTools: Array<Object>, mcpServers: Array<Object> }}
+ */
+export async function listAvailableTools(rootDir) {
+  let mcpServers = [];
+  try {
+    const { listInstalledMcpServers } = await import("./mcp-registry.mjs");
+    mcpServers = await listInstalledMcpServers(rootDir);
+  } catch {
+    // MCP registry not available
+  }
+
+  return {
+    builtinTools: [...DEFAULT_BUILTIN_TOOLS],
+    mcpServers: mcpServers.map((s) => ({
+      id: s.id,
+      name: s.name,
+      description: s.description || "",
+      tags: s.tags || [],
+      transport: s.meta?.transport || "stdio",
+    })),
+  };
+}

package/bosun.schema.json

@@ -281,7 +281,7 @@
         "turnDetection": {
           "type": "string",
           "enum": ["server_vad", "semantic_vad", "none"],
-          "default": "server_vad",
+          "default": "semantic_vad",
           "description": "Turn detection mode for voice activity detection"
         },
         "instructions": {

package/config.mjs

@@ -506,7 +506,9 @@ function normalizeExecutorModels(executor, models, variant = "DEFAULT") {
     );
     return inferred.length > 0 ? inferred : [...known];
   }
-  return input.filter((model) => known.has(model));
+  // Preserve custom/deployment slugs in addition to known models so user-provided
+  // model routing survives normalization (for example Azure deployment names).
+  return [...new Set(input.filter(Boolean))];
 }
 
 function normalizeExecutorEntry(entry, index = 0, total = 1) {
@@ -540,49 +542,8 @@ function normalizeExecutorEntry(entry, index = 0, total = 1) {
   };
 }
 
-function buildDefaultTriggerTemplates({
-  plannerMode,
-  plannerPerCapitaThreshold,
-  plannerIdleSlotThreshold,
-  plannerDedupHours,
-} = {}) {
+function buildDefaultTriggerTemplates() {
   return [
-    {
-      id: "task-planner",
-      name: "Task Planner",
-      description: "Create planning tasks when backlog/slot metrics indicate replenishment.",
-      enabled: false,
-      action: "task-planner",
-      trigger: {
-        anyOf: [
-          {
-            kind: "metric",
-            metric: "backlogPerCapita",
-            operator: "lt",
-            value: plannerPerCapitaThreshold,
-          },
-          {
-            kind: "metric",
-            metric: "idleSlots",
-            operator: "gte",
-            value: plannerIdleSlotThreshold,
-          },
-          {
-            kind: "metric",
-            metric: "backlogRemaining",
-            operator: "eq",
-            value: 0,
-          },
-        ],
-      },
-      minIntervalMinutes: Math.max(1, Number(plannerDedupHours || 6) * 60),
-      config: {
-        plannerMode,
-        defaultTaskCount: Number(process.env.TASK_PLANNER_DEFAULT_COUNT || "30"),
-        executor: "auto",
-        model: "auto",
-      },
-    },
     {
       id: "daily-review-digest",
       name: "Daily Review Digest",
@@ -1990,32 +1951,8 @@ export function loadConfig(argv = process.argv, options = {}) {
     "summary"
   ).toLowerCase();
 
-  // ── Task Planner ─────────────────────────────────────────
-  // Mode: "codex-sdk" (default) runs Codex directly, "kanban" creates a VK
-  // task for a real agent to plan, "disabled" turns off the planner entirely.
-  const plannerMode = (
-    process.env.TASK_PLANNER_MODE ||
-    configData.plannerMode ||
-    (mode === "generic" ? "disabled" : "codex-sdk")
-  ).toLowerCase();
-  const plannerPerCapitaThreshold = Number(
-    process.env.TASK_PLANNER_PER_CAPITA_THRESHOLD || "1",
-  );
-  const plannerIdleSlotThreshold = Number(
-    process.env.TASK_PLANNER_IDLE_SLOT_THRESHOLD || "1",
-  );
-  const plannerDedupHours = Number(process.env.TASK_PLANNER_DEDUP_HOURS || "6");
-  const plannerDedupMs = Number.isFinite(plannerDedupHours)
-    ? plannerDedupHours * 60 * 60 * 1000
-    : 24 * 60 * 60 * 1000;
-
   const triggerSystemDefaults = Object.freeze({
-    templates: buildDefaultTriggerTemplates({
-      plannerMode,
-      plannerPerCapitaThreshold,
-      plannerIdleSlotThreshold,
-      plannerDedupHours,
-    }),
+    templates: buildDefaultTriggerTemplates(),
     defaults: Object.freeze({
       executor: "auto",
       model: "auto",
@@ -2290,12 +2227,6 @@ export function loadConfig(argv = process.argv, options = {}) {
     telegramCommandEnabled,
     telegramVerbosity,
 
-    // Task Planner
-    plannerMode,
-    plannerPerCapitaThreshold,
-    plannerIdleSlotThreshold,
-    plannerDedupHours,
-    plannerDedupMs,
     triggerSystem,
 
     // GitHub Reconciler
@@ -2349,7 +2280,7 @@ export function loadConfig(argv = process.argv, options = {}) {
         configData.trustedCreators ||
         process.env.BOSUN_TRUSTED_CREATORS?.split(",") ||
         [],
-      // Enforce all new tasks go to backlog unless planner config allows auto-push
+      // Enforce all new tasks go to backlog
       enforceBacklog:
         typeof configData.enforceBacklog === "boolean"
           ? configData.enforceBacklog

package/copilot-shell.mjs

@@ -469,9 +469,26 @@ async function ensureClientStarted() {
   const modeLabel = clientOptions.cliUrl ? "remote" : "local (stdio)";
   console.log(`[copilot-shell] starting client in ${modeLabel} mode`);
 
+  const START_TIMEOUT_MS =
+    Number(process.env.COPILOT_START_TIMEOUT_MS) || 20_000;
+
   await withSanitizedOpenAiEnv(async () => {
     copilotClient = new Cls(clientOptions);
-    await copilotClient.start();
+    await Promise.race([
+      copilotClient.start(),
+      new Promise((_, reject) =>
+        setTimeout(
+          () =>
+            reject(
+              new Error(
+                `Copilot CLI failed to start within ${START_TIMEOUT_MS / 1000}s — ` +
+                  `verify COPILOT_CLI_PATH or run \`gh auth login\``,
+              ),
+            ),
+          START_TIMEOUT_MS,
+        ),
+      ),
+    ]);
   });
   clientStarted = true;
   console.log("[copilot-shell] client started");