feat(FN-1498): merge fusion/fn-1498

.changeset/utility-ai-slot-bypass.md

@@ -0,0 +1,19 @@
+---
+"@gsxdsm/fusion": patch
+---
+
+Document that `maxConcurrent` governs task execution lanes only; utility AI workflows bypass the limit
+
+**What changed:**
+- `maxConcurrent` / `AgentSemaphore` now explicitly applies to task-lane work only: triage specification, task execution, and merge operations
+- Utility AI workflows run on a separate control-plane lane and are NOT gated by `maxConcurrent`:
+  - AI planning mode
+  - Subtask breakdown
+  - Mission, milestone, and slice interviews
+  - Agent heartbeat / chat wake runs
+  - Title summarization
+
+**Behavior:**
+- Dashboard planning, subtask, and interview features remain responsive even when all task execution slots are saturated
+- Agent wake-on-message and title summarization continue to work regardless of `maxConcurrent` settings
+- Existing task-lane concurrency limits (executor, triage, merge) are unchanged

AGENTS.md

@@ -1588,6 +1588,34 @@ The dashboard Settings modal shows scope indicators (🌐 global, 📁 project)
 
 The following settings are available in the fn configuration:
 
+### `maxConcurrent` (default: `2`)
+
+Controls the maximum number of **task-lane** AI agents that can run concurrently. The engine uses `AgentSemaphore` to enforce this limit.
+
+**Task-lane activities that ARE gated by `maxConcurrent`:**
+- Triage specification (AI spec generation for tasks in triage column)
+- Task execution (executor agent implementing tasks)
+- Merge operations
+
+**Utility AI workflows that are NOT gated (run on a separate control-plane lane):**
+- AI planning mode (`/api/planning/*`)
+- Subtask breakdown (`/api/subtasks/*`)
+- Mission/milestone/slice interviews (`/api/missions/*/interview/*`)
+- Agent chat/heartbeat wake (`/api/agents/:id/runs`, wake-on-message)
+- Title summarization (`/api/ai/summarize-title`)
+
+**Rationale:** Utility workflows remain responsive even when task pipelines are saturated. This ensures users can still plan, break down tasks, and receive AI assistance without waiting for running tasks to complete.
+
+**Configuration:**
+
+```json
+{
+  "settings": {
+    "maxConcurrent": 3
+  }
+}
+```
+
 ### `autoResolveConflicts` (default: `true`)
 
 When enabled, the auto-merge system will intelligently resolve common merge conflict patterns without requiring manual intervention:

README.md

@@ -771,7 +771,7 @@ Project settings override global settings. Configure in the dashboard under **Se
 | `ntfyTopic` | Global | - | ntfy.sh topic for notifications |
 | `ntfyDashboardHost` | Global | - | Dashboard URL for notification deep links |
 | `modelOnboardingComplete` | Global | false | Tracks completion of first-run model onboarding wizard |
-| `maxConcurrent` | Project | 2 | Concurrent task execution limit |
+| `maxConcurrent` | Project | 2 | Concurrent task execution lanes (triage, executor, merge). Utility AI workflows (planning, subtask breakdown, interviews, heartbeat wake, title summarization) bypass this limit. |
 | `autoMerge` | Project | true | Auto-merge completed tasks |
 | `smartConflictResolution` | Project | true | Auto-resolve lock/generated files |
 | `requirePlanApproval` | Project | false | Manual approval for AI specs |

docs/settings-reference.md

@@ -66,7 +66,7 @@ Defaults from `DEFAULT_PROJECT_SETTINGS`; key scope from `PROJECT_SETTINGS_KEYS`
 |---|---|---:|---|
 | `globalPause` | `boolean` | `false` | Hard stop: terminate active engine sessions and pause scheduling. |
 | `enginePaused` | `boolean` | `false` | Soft pause: stop dispatching new work but allow active sessions to finish. |
-| `maxConcurrent` | `number` | `2` | Max concurrent AI tasks. |
+| `maxConcurrent` | `number` | `2` | Max concurrent task-lane AI agents (triage, executor, merge). Utility AI workflows run on a separate control-plane lane and are not gated by this limit. |
 | `maxWorktrees` | `number` | `4` | Max git worktrees. |
 | `pollIntervalMs` | `number` | `15000` | Scheduler poll interval (ms). |
 | `groupOverlappingFiles` | `boolean` | `true` | Serialize execution when file scopes overlap. |

docs/storage.md

@@ -84,7 +84,7 @@ API endpoints reviewed:
 |---|---|---|---|
 | `globalPause` | Project | `GET/PUT /api/settings` | Hard stop for engine activity |
 | `enginePaused` | Project | `GET/PUT /api/settings` | Soft pause for dispatch |
-| `maxConcurrent` | Project | `GET/PUT /api/settings` | Max concurrent agents |
+| `maxConcurrent` | Project | `GET/PUT /api/settings` | Max concurrent task-lane agents. Utility AI workflows bypass this limit. |
 | `maxWorktrees` | Project | `GET/PUT /api/settings` | Worktree cap |
 | `pollIntervalMs` | Project | `GET/PUT /api/settings` | Scheduler poll interval |
 | `groupOverlappingFiles` | Project | `GET/PUT /api/settings` | Serialize overlapping file work |

packages/cli/skill/fusion/references/fusion-capabilities.md

@@ -110,7 +110,7 @@ Triage → Todo → In Progress → In Review → Done → Archived
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `maxConcurrent` | 2 | Concurrent task execution |
+| `maxConcurrent` | 2 | Concurrent task execution lanes (triage, executor, merge). Utility AI workflows such as planning, subtask breakdown, interviews, and title summarization bypass this limit. |
 | `autoMerge` | true | Auto-merge completed tasks |
 | `requirePlanApproval` | false | Manual approval for specs |
 | `prCompletionMode` | direct | Completion: direct/pr-first |

packages/cli/skill/fusion/references/task-structure.md

@@ -134,6 +134,8 @@ What the task should accomplish.
 }
 ```
 
+> **Note:** `maxConcurrent` applies to task-lane agents (triage, execution, merge) only. Utility AI workflows—planning mode, subtask breakdown, mission interviews, agent heartbeat/chat wake, and title summarization—run outside this limit on a dedicated control-plane lane.
+
 ## Global Settings
 
 User-level settings at `~/.pi/fusion/settings.json`: