@swarmclawai/swarmclaw 1.5.60 → 1.5.62

package/README.md

@@ -399,6 +399,23 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.62 Highlights
+
+Hardens parallel sub-agent dispatch with a concurrency cap, a quorum join policy, and a cycle check — so a fan-out can't accidentally saturate providers, melt a mission budget, or wedge the runtime on a delegation loop.
+
+- **`spawn_subagent` swarm/batch actions now accept `maxConcurrency`, `joinPolicy`, `quorum`, and `cancelRemaining`.** Parallel mode fans out at most 4 branches at a time by default (hard-capped at 16). Task buckets share an `executionGroupKey` so the existing per-execution serial lock enforces the cap with zero new scheduler code. `joinPolicy: 'quorum'` resolves once `quorum` branches succeed and (by default) cancels the remaining in-flight branches. `joinPolicy: 'first'` resolves on the first success. `joinPolicy: 'all'` stays the default.
+- **Cycle detection in `spawnSubagent`.** Before creating a child session, the runtime walks the `parentSessionId` ancestry and rejects the spawn when the requested `agentId` already appears higher in the chain. Clear error message with an `allowCycle: true` escape hatch. Orthogonal to the existing depth cap.
+- **Per-agent and per-mission overrides.** `Agent.maxParallelDelegations` and `MissionBudget.maxParallelBranches` plumb into the swarm resolver. Precedence: explicit tool arg > agent cap > mission cap > system default (4). Both are validated by `AgentUpdateSchema` and the mission budget schemas, and normalized on load via `storage-normalization.ts`.
+- **Swarm snapshot exposes the effective cap.** `SwarmSnapshot.maxConcurrency` lands in the persisted snapshot payload so the UI and external tooling can surface the active concurrency level. Verified live via a 3-branch quorum run: `totalCompleted: 2`, `totalCancelled: 1`, `maxConcurrency: 2`, `joinPolicy: "quorum"`.
+
+### v1.5.61 Highlights
+
+Adds an opt-in per-agent planning mode that rides on the existing `[MAIN_LOOP_PLAN]` token machinery.
+
+- **`Agent.planningMode: 'off' | 'strict' | null`** — new optional field on the Agent type. Defaults to `null` (off) so existing agents are unaffected. Validated by `AgentCreateSchema` / `AgentUpdateSchema` and surfaced through `createAgent` in `agent-service.ts`.
+- **Strict planning prompt section.** New `buildPlanningModeSection` in `prompt-sections.ts` injects a short contract into the system prompt when `planningMode === 'strict'`: before any multi-step work, emit a single-line `[MAIN_LOOP_PLAN]{"steps":...}` block. The existing parser in `main-agent-loop.ts` reads these blocks into `MainLoopState.planSteps` / `currentPlanStep` / `completedPlanSteps` with no additional wiring. Skipped in minimal prompt mode and for heartbeat turns.
+- **Test coverage.** `prompt-sections.planning-mode.test.ts` covers the null / off / strict / minimal / missing-agent paths (6 cases).
+
 ### v1.5.60 Highlights
 
 Adds a turn-snapshot primitive for external replay and comparison tooling, without touching the execution flow.
@@ -425,25 +442,6 @@ This release broadens the built-in evaluation harness so SwarmClaw runs can be b
 - **Auto-skill drafting is stricter and rate-limited.** `shouldAutoDraftSkillSuggestion` in `chat-turn-finalization.ts` now requires at least 3 tool events in the completed turn (was 1), and a new per-agent daily cap limits automatic drafts to 3 per day per agent to prevent suggestion-inbox spam. Both thresholds are named constants (`AUTO_DRAFT_MIN_TOOL_EVENTS`, `AUTO_DRAFT_DAILY_LIMIT`). Agents with `autoDraftSkillSuggestions = false` are unaffected (auto-drafting remains opt-in per agent).
 - **Hello World demo mission template.** New `hello-world-demo` entry in `BUILT_IN_MISSION_TEMPLATES` — a bounded, zero-setup mission that reads three files in the working directory and writes a one-paragraph markdown summary to `hello-world-report.md`. Budgets (USD 0.25, 20k tokens, 30 turns, 15 min) are small enough to run on a local Ollama model without cost. Intended as the first thing a new user watches an agent complete end to end.
 
-### v1.5.57 Highlights
-
-This release closes the org-orchestration feature gap with Paperclip while keeping SwarmClaw's autonomous-assistant focus. Most additions are additive; nothing existing has changed shape.
-
-- **Workspace templates: full export/import bundle.** `src/lib/server/portability/{export,import}.ts` now round-trips agents, skills, schedules, **connectors** (with secret scrubbing), **chatrooms**, **MCP servers**, **projects**, **goals**, and an extension manifest reference. Manifest version bumped to `2`; v1 bundles still import. Connectors and MCP servers re-import with credentials stripped — the response payload now lists which records `needCredentials` so the UI can prompt. ID remapping handles cross-references (chatrooms → agents, schedules → agents, goals → projects/agents).
-- **Per-agent budget enforcement at enqueue.** New `src/lib/server/agents/agent-budget-hook.ts` mirrors the existing mission budget hook. When an agent has `budgetAction: 'block'` and any window (`hourlyBudget`/`dailyBudget`/`monthlyBudget`) is exhausted, autonomous enqueues now fail fast in `session-run-manager` instead of getting blocked deeper in the chat-turn pipeline. User-initiated chats still flow through (so users can talk to an agent that's hit its cap). Default `'warn'` behavior is unchanged.
-- **Goal hierarchy ancestry through Mission.** `Mission.goalId` is a new optional field. When a session has a `missionId` and the bound mission has a `goalId`, `main-agent-loop.ts` now walks `mission → goal → parentGoal → …` so the full Initiative/Project/Goal ancestry flows into the agent system prompt — previously only direct session-level goals were resolved.
-- **Billing codes / cost attribution.** `Mission`, `BoardTask`, `Session`, and `UsageRecord` accept an optional `billingCodes: string[]`. `resolveBillingCodesForSession` combines session + mission codes when usage is appended, and the new `GET /api/usage/by-code?codes=foo,bar&range=7d` endpoint rolls up cost per code (and per agent within each code). Lets users running multiple parallel projects answer "what did Project X cost?" across agents, missions, and ad-hoc chats.
-- **Customizable task workflow states.** New `WorkflowState` collection (`src/lib/server/tasks/workflow-state-repository.ts`) stores team-defined states like "Needs Review" or "Blocked on PM" that are orthogonal to `BoardTaskStatus` lifecycle. `BoardTask.workflowStateId` references one of seven defaults (Triage / Backlog / Todo / In Progress / Needs Review / Done / Cancelled) or any custom state. CRUD via `GET|POST|DELETE /api/task-workflow-states`. Atomic checkout via `task-checkout.ts` was already in place.
-- **Cross-agent delegation refusal policy.** `Chatroom.onRefusal` (`'reroute' | 'escalate' | 'human'`) and `Chatroom.escalationTargetAgentId` formalize what happens when a delegated agent declines work. `chatroom-refusal.ts` reroutes to another room member, escalates to a configured target, or surfaces a `human_loop` approval. Policy management at `POST /api/chatrooms/refusal-policy`; simulation at `PUT` for tests.
-- **Configuration version history.** Every `updateAgent` call now snapshots the prior agent state into `config-versions.json` (capped at 50 versions per entity). `GET /api/config-versions?entityKind=agent&entityId=...` lists history; `POST /api/config-versions/restore` rolls back. Foundation for extending to extensions, connectors, MCP servers, chatrooms, and projects.
-- **Multi-workspace scaffolding.** New `Workspace` registry with `GET|POST|PATCH|DELETE /api/workspaces` and `GET|POST /api/workspaces/active`. The default workspace seeds itself on first read; switching the active workspace persists to `workspace-registry.json`. **Note:** this is metadata only in v1.5.57 — actual data-dir forking per workspace is intentionally deferred (low-risk shipping).
-- **CLI manifest expanded.** New top-level groups: `workspaces`, `workflow-states`, `config-versions`, `cost-attribution`, `chatroom-policy`. Run `swarmclaw workspaces list`, `swarmclaw cost-attribution by-code --query codes=client-a,range=30d`, `swarmclaw config-versions list --query entityKind=agent,entityId=...`, etc. CLI route-coverage test passes.
-
-### v1.5.56 Highlights
-
-- **Fix: TTS error responses are now proper JSON instead of a raw Buffer blob.** `POST /api/tts` and `POST /api/tts/stream` previously returned `500` with the error message wrapped in a `new NextResponse(string, ...)` that the CLI JSON-decoded into `{"type":"Buffer","data":[78,111,...]}`. Both routes now return `NextResponse.json({error}, {status: 500})`. Regression test added.
-- **Zod-validated PUT/PATCH endpoints — hardening sweep.** Extends the v1.5.55 work (agents, tasks, webhooks) to close the same silent-corruption bug class on the remaining vulnerable routes: `PUT /api/secrets/:id`, `POST /api/secrets`, `PATCH /api/goals/:id`, `PUT /api/providers/:id`, `PUT /api/documents/:id`, `PUT /api/external-agents/:id`, and `PUT /api/chatrooms/:id`. Each route validates against a dedicated schema (`SecretUpdateSchema`, `SecretCreateSchema`, `GoalUpdateSchema`, `ProviderUpdateSchema`, `DocumentUpdateSchema`, `ExternalAgentUpdateSchema`, `ChatroomUpdateSchema`) in `src/lib/validation/schemas.ts`, then filters parsed data to the keys actually present in the raw body so Zod defaults can't overwrite untouched stored fields. Endpoints already doing per-field `typeof` guards (knowledge, gateways, projects) were left as-is.
-
 Older releases: https://swarmclaw.ai/docs/release-notes
 
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.60",
+  "version": "1.5.62",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/missions/[id]/route.ts

@@ -23,6 +23,7 @@ const MissionUpdateSchema = z.object({
     maxToolCalls: z.number().positive().int().nullable().optional(),
     maxWallclockSec: z.number().positive().int().nullable().optional(),
     maxTurns: z.number().positive().int().nullable().optional(),
+    maxParallelBranches: z.number().positive().int().nullable().optional(),
     warnAtFractions: z.array(z.number().positive().lt(1)).max(10).optional(),
   }).partial().optional(),
   reportSchedule: z.object({

package/src/app/api/missions/route.ts

@@ -14,6 +14,7 @@ const MissionBudgetSchema = z.object({
   maxToolCalls: z.number().positive().int().nullable().optional(),
   maxWallclockSec: z.number().positive().int().nullable().optional(),
   maxTurns: z.number().positive().int().nullable().optional(),
+  maxParallelBranches: z.number().positive().int().nullable().optional(),
   warnAtFractions: z.array(z.number().positive().lt(1)).max(10).optional(),
 }).strict()
 

package/src/lib/server/agents/agent-service.ts

@@ -178,6 +178,7 @@ export function createAgent(input: {
     memoryTierPreference: (body.memoryTierPreference as Agent['memoryTierPreference']) || undefined,
     proactiveMemory: body.proactiveMemory !== false,
     autoDraftSkillSuggestions: body.autoDraftSkillSuggestions as Agent['autoDraftSkillSuggestions'],
+    planningMode: (body.planningMode as Agent['planningMode']) ?? null,
     projectId: typeof body.projectId === 'string' && body.projectId.trim() ? body.projectId.trim() : undefined,
     avatarSeed: typeof body.avatarSeed === 'string' ? body.avatarSeed : undefined,
     avatarUrl: typeof body.avatarUrl === 'string' ? body.avatarUrl : undefined,

package/src/lib/server/agents/subagent-runtime.ts

@@ -73,6 +73,8 @@ export interface SpawnSubagentInput {
   timeoutSec?: number
   /** Optional shared execution lane key for serializing sibling runs. */
   executionGroupKey?: string
+  /** When true, skip the ancestor-agent cycle check (A → B → A). Default false. */
+  allowCycle?: boolean
 }
 
 export interface SubagentHandle {
@@ -183,6 +185,31 @@ export function getSessionDepth(
   return depth
 }
 
+/**
+ * Collect agentIds of every session in the parent chain including the given
+ * session. Used to detect delegation cycles (A → B → A) before spawning.
+ */
+export function collectAncestorAgentIds(
+  sessionId: string | undefined,
+  sessions: Record<string, unknown>,
+  limit = 32,
+): string[] {
+  if (!sessionId) return []
+  const ids: string[] = []
+  let current: string | undefined = sessionId
+  const visited = new Set<string>()
+  while (current && ids.length < limit && !visited.has(current)) {
+    visited.add(current)
+    const s = sessions[current] as Record<string, unknown> | undefined
+    const agentId = typeof s?.agentId === 'string' ? s.agentId.trim() : ''
+    if (agentId) ids.push(agentId)
+    const parentId = typeof s?.parentSessionId === 'string' ? s.parentSessionId : null
+    if (!parentId) break
+    current = parentId
+  }
+  return ids
+}
+
 // ---------------------------------------------------------------------------
 // Core: Spawn a Native Subagent
 // ---------------------------------------------------------------------------
@@ -215,6 +242,16 @@ async function spawnSubagentImpl(
     log.warn('subagent', 'Spawn rejected: max depth exceeded', { agentId: input.agentId, depth, maxDepth })
     throw new Error(`Max subagent depth (${maxDepth}) reached.`)
   }
+  if (input.allowCycle !== true && context.sessionId) {
+    const ancestorAgentIds = collectAncestorAgentIds(context.sessionId, sessions)
+    if (ancestorAgentIds.includes(input.agentId)) {
+      log.warn('subagent', 'Spawn rejected: delegation cycle', { agentId: input.agentId, chain: ancestorAgentIds })
+      throw new Error(
+        `Delegation cycle: agent "${input.agentId}" is already active higher in this chain. `
+        + 'Pick a different sibling agent, or pass allowCycle=true to override.',
+      )
+    }
+  }
   const parent = context.sessionId ? sessions[context.sessionId] : null
   const parentExtensions = getEnabledCapabilityIds(parent as { tools?: string[] | null, extensions?: string[] | null } | null)
   const spawningResult = await runCapabilitySubagentSpawning(

package/src/lib/server/agents/subagent-swarm.test.ts

@@ -2,8 +2,11 @@ import assert from 'node:assert/strict'
 import { afterEach, describe, it } from 'node:test'
 
 import {
+  _clampSwarmConcurrency,
   _clearSwarmRegistry,
   _resolveSwarmExecutionMode,
+  SWARM_DEFAULT_PARALLEL_CONCURRENCY,
+  SWARM_MAX_CONCURRENCY_HARD_LIMIT,
   getSwarm,
   getSwarmSnapshot,
   listSwarms,
@@ -13,6 +16,7 @@ import {
   type SwarmMember,
   type SwarmSnapshot,
 } from '@/lib/server/agents/subagent-swarm'
+import { collectAncestorAgentIds } from '@/lib/server/agents/subagent-runtime'
 
 /**
  * Unit tests for the swarm layer. Since spawnSubagent depends on storage,
@@ -22,6 +26,17 @@ import {
  */
 
 function fakeSwarmHandle(overrides?: Partial<SwarmHandle>): SwarmHandle {
+  const allSettled = Promise.resolve({
+    swarmId: 'swarm-test-1',
+    parentSessionId: 'parent-sess-1',
+    totalSpawned: 0,
+    totalCompleted: 0,
+    totalFailed: 0,
+    totalCancelled: 0,
+    totalSpawnErrors: 0,
+    durationMs: 0,
+    results: [],
+  })
   const base: SwarmHandle = {
     swarmId: 'swarm-test-1',
     parentSessionId: 'parent-sess-1',
@@ -29,18 +44,10 @@ function fakeSwarmHandle(overrides?: Partial<SwarmHandle>): SwarmHandle {
     status: 'running',
     createdAt: Date.now() - 5000,
     completedAt: null,
-    allSettled: Promise.resolve({
-      swarmId: 'swarm-test-1',
-      parentSessionId: 'parent-sess-1',
-      totalSpawned: 0,
-      totalCompleted: 0,
-      totalFailed: 0,
-      totalCancelled: 0,
-      totalSpawnErrors: 0,
-      durationMs: 0,
-      results: [],
-    }),
+    maxConcurrency: 4,
+    allSettled,
     firstSettled: Promise.resolve({ index: -1, result: null as any }),
+    quorumSettled: async () => allSettled,
     cancelAll: () => {},
     ...overrides,
   }
@@ -357,6 +364,92 @@ describe('subagent-swarm', () => {
   // Reliability fix: firstSettled with zero memberPromises (#15)
   // ---------------------------------------------------------------------------
 
+  // ---------------------------------------------------------------------------
+  // Concurrency cap (v1.5.62+)
+  // ---------------------------------------------------------------------------
+
+  describe('clampSwarmConcurrency', () => {
+    it('returns 1 when task count is 0 or 1', () => {
+      assert.equal(_clampSwarmConcurrency(8, 0), 1)
+      assert.equal(_clampSwarmConcurrency(8, 1), 1)
+    })
+
+    it('uses the default when no explicit cap is given', () => {
+      assert.equal(_clampSwarmConcurrency(undefined, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+    })
+
+    it('honors an explicit finite positive cap', () => {
+      assert.equal(_clampSwarmConcurrency(2, 10), 2)
+      assert.equal(_clampSwarmConcurrency(7, 10), 7)
+    })
+
+    it('enforces the hard limit', () => {
+      assert.equal(_clampSwarmConcurrency(100, 50), SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+    })
+
+    it('rounds and floors the cap to an integer >= 1', () => {
+      assert.equal(_clampSwarmConcurrency(3.9, 10), 3)
+      assert.equal(_clampSwarmConcurrency(0, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+      assert.equal(_clampSwarmConcurrency(-4, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+      assert.equal(_clampSwarmConcurrency(Number.NaN, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+    })
+  })
+
+  // ---------------------------------------------------------------------------
+  // Cycle detection via ancestor agentIds (v1.5.62+)
+  // ---------------------------------------------------------------------------
+
+  describe('collectAncestorAgentIds', () => {
+    it('returns empty when the session is unknown', () => {
+      assert.deepEqual(collectAncestorAgentIds('missing', {}), [])
+      assert.deepEqual(collectAncestorAgentIds(undefined, {}), [])
+    })
+
+    it('walks parent chain and collects agentIds', () => {
+      const sessions: Record<string, unknown> = {
+        root: { id: 'root', agentId: 'agent-root', parentSessionId: null },
+        mid: { id: 'mid', agentId: 'agent-mid', parentSessionId: 'root' },
+        leaf: { id: 'leaf', agentId: 'agent-leaf', parentSessionId: 'mid' },
+      }
+      assert.deepEqual(
+        collectAncestorAgentIds('leaf', sessions),
+        ['agent-leaf', 'agent-mid', 'agent-root'],
+      )
+    })
+
+    it('terminates on a self-loop without infinite recursion', () => {
+      const sessions: Record<string, unknown> = {
+        a: { id: 'a', agentId: 'agent-a', parentSessionId: 'a' },
+      }
+      assert.deepEqual(collectAncestorAgentIds('a', sessions), ['agent-a'])
+    })
+
+    it('detects a cycle candidate (A → B → A is visible in the chain)', () => {
+      const sessions: Record<string, unknown> = {
+        root: { id: 'root', agentId: 'agent-a', parentSessionId: null },
+        child: { id: 'child', agentId: 'agent-b', parentSessionId: 'root' },
+      }
+      const chain = collectAncestorAgentIds('child', sessions)
+      // Attempting to spawn agent-a again would be caught by the cycle check:
+      assert.ok(chain.includes('agent-a'))
+    })
+  })
+
+  // ---------------------------------------------------------------------------
+  // quorumSettled (v1.5.62+)
+  // ---------------------------------------------------------------------------
+
+  describe('quorumSettled shape', () => {
+    it('fakeSwarmHandle exposes the new quorumSettled and maxConcurrency fields', async () => {
+      const swarm = fakeSwarmHandle({ maxConcurrency: 3 })
+      assert.equal(swarm.maxConcurrency, 3)
+      assert.equal(typeof swarm.quorumSettled, 'function')
+      const agg = await swarm.quorumSettled(1)
+      assert.ok(agg)
+      assert.equal(agg.totalSpawned, 0)
+    })
+  })
+
   describe('firstSettled — all spawn errors (zero promises)', () => {
     it('firstSettled resolves with a valid SubagentResult, not null', async () => {
       // Build a swarm where ALL members fail to spawn

package/src/lib/server/agents/subagent-swarm.ts

@@ -63,10 +63,19 @@ export interface SwarmHandle {
   createdAt: number
   /** When all members finished (null if still running) */
   completedAt: number | null
+  /** Effective concurrency cap used to dispatch this swarm. 0 = unbounded (non-serial). */
+  maxConcurrency: number
   /** Promise that resolves when ALL members complete */
   allSettled: Promise<SwarmAggregateResult>
   /** Promise that resolves when the FIRST member completes */
   firstSettled: Promise<{ index: number; result: SubagentResult }>
+  /**
+   * Resolve when `count` members succeed (status === 'completed').
+   * If the swarm cannot reach the quorum (enough members already failed),
+   * resolves with the current aggregate. When `cancelRemaining` is true,
+   * best-effort aborts in-flight members after the quorum is reached.
+   */
+  quorumSettled: (count: number, opts?: { cancelRemaining?: boolean }) => Promise<SwarmAggregateResult>
   /** Cancel all running members */
   cancelAll: () => void
 }
@@ -109,8 +118,29 @@ export interface BatchSpawnInput {
   onSwarmComplete?: (result: SwarmAggregateResult) => void
   /** Execution mode for sibling subagents. Auto defaults to serial for Ollama-backed targets. */
   executionMode?: 'auto' | 'parallel' | 'serial'
+  /**
+   * Maximum number of members allowed to run concurrently when `executionMode`
+   * resolves to `'parallel'`. A value of 0 or `undefined` preserves the legacy
+   * unbounded behavior. Ignored in serial mode (always 1).
+   */
+  maxConcurrency?: number
 }
 
+/** Hard cap on `maxConcurrency` regardless of caller-supplied value. */
+export const SWARM_MAX_CONCURRENCY_HARD_LIMIT = 16
+/** Default concurrency when a parallel swarm does not specify an explicit cap. */
+export const SWARM_DEFAULT_PARALLEL_CONCURRENCY = 4
+
+function clampConcurrency(requested: number | undefined, taskCount: number): number {
+  if (taskCount <= 1) return 1
+  const raw = typeof requested === 'number' && Number.isFinite(requested) && requested > 0
+    ? Math.floor(requested)
+    : SWARM_DEFAULT_PARALLEL_CONCURRENCY
+  return Math.min(SWARM_MAX_CONCURRENCY_HARD_LIMIT, Math.max(1, raw))
+}
+
+export const _clampSwarmConcurrency = clampConcurrency
+
 // ---------------------------------------------------------------------------
 // Batch types (absorbed from subagent-batch)
 // ---------------------------------------------------------------------------
@@ -165,6 +195,7 @@ function persistSwarmSnapshot(swarm: SwarmHandle): void {
       parentSessionId: swarm.parentSessionId,
       status: swarm.status,
       memberCount: swarm.members.length,
+      maxConcurrency: swarm.maxConcurrency,
       createdAt: swarm.createdAt,
       completedAt: swarm.completedAt,
       updatedAt: Date.now(),
@@ -198,9 +229,20 @@ export async function spawnSwarm(
   const createdAt = Date.now()
   const members: SwarmMember[] = []
   const executionMode = _resolveSwarmExecutionMode(input.tasks, input.executionMode)
-  const executionGroupKey = executionMode === 'serial'
-    ? `swarm:${context.sessionId || 'root'}:${swarmId}`
-    : undefined
+  const effectiveConcurrency = executionMode === 'serial'
+    ? 1
+    : clampConcurrency(input.maxConcurrency, input.tasks.length)
+  const parentKey = context.sessionId || 'root'
+
+  // Concurrency is implemented by bucketing tasks across N shared execution
+  // group keys — each bucket serializes through the existing session-run-manager
+  // per-execution lock, so bucket count === effective parallelism.
+  const bucketKeyFor = (index: number): string | undefined => {
+    if (executionMode === 'serial') return `swarm:${parentKey}:${swarmId}`
+    if (effectiveConcurrency >= input.tasks.length) return undefined
+    const bucket = index % effectiveConcurrency
+    return `swarm:${parentKey}:${swarmId}:b${bucket}`
+  }
 
   // Pre-load sessions once for all spawns (avoids N SQLite reads)
   const cachedSessions = context._sessions ?? loadSessions()
@@ -218,7 +260,7 @@ export async function spawnSwarm(
           cwd: task.cwd,
           shareBrowserProfile: task.shareBrowserProfile,
           waitForCompletion: false,
-          executionGroupKey,
+          executionGroupKey: bucketKeyFor(i),
         },
         cachedContext,
       )
@@ -249,8 +291,10 @@ export async function spawnSwarm(
     status: 'running',
     createdAt,
     completedAt: null,
+    maxConcurrency: effectiveConcurrency,
     allSettled: null as unknown as Promise<SwarmAggregateResult>,
     firstSettled: null as unknown as Promise<{ index: number; result: SubagentResult }>,
+    quorumSettled: null as unknown as SwarmHandle['quorumSettled'],
     cancelAll: () => {
       for (const member of members) {
         if (member.handle && !member.result && !member.spawnError) {
@@ -330,6 +374,46 @@ export async function spawnSwarm(
         }
       })
 
+  // quorumSettled — resolves when `count` members succeed. If too many fail to
+  // ever reach the quorum, falls back to allSettled.
+  swarm.quorumSettled = (count, opts) => {
+    const requested = Math.max(1, Math.floor(Number.isFinite(count) ? count : 1))
+    const target = Math.min(requested, swarm.members.length)
+    const cancelRemaining = opts?.cancelRemaining !== false
+    if (target <= 0 || memberPromises.length === 0) return swarm.allSettled
+    return new Promise<SwarmAggregateResult>((resolve) => {
+      let settled = false
+      let successes = 0
+      let finalized = 0
+      const finalize = () => {
+        if (settled) return
+        settled = true
+        if (cancelRemaining) {
+          for (const member of members) {
+            if (member.handle && !member.result && !member.spawnError) {
+              try {
+                member.handle.run.abort()
+                cancelLineageNode(member.handle.lineageId)
+              } catch { /* best-effort */ }
+            }
+          }
+        }
+        swarm.allSettled.then(resolve).catch(() => resolve(buildAggregateResult(swarm)))
+      }
+      for (const p of memberPromises) {
+        p.then(({ result }) => {
+          finalized++
+          if (result.status === 'completed') successes++
+          if (successes >= target) finalize()
+          else if (finalized >= memberPromises.length) finalize()
+        }).catch(() => {
+          finalized++
+          if (finalized >= memberPromises.length) finalize()
+        })
+      }
+    })
+  }
+
   // Register in swarm registry
   swarmRegistry.set(swarmId, swarm)
   notifySwarmChanged()
@@ -575,6 +659,7 @@ export interface SwarmSnapshot {
   memberCount: number
   completedCount: number
   failedCount: number
+  maxConcurrency?: number
   members: SwarmMemberSnapshot[]
 }
 
@@ -622,6 +707,7 @@ function buildSwarmSnapshot(swarm: SwarmHandle): SwarmSnapshot {
     failedCount: members.filter((m) =>
       m.status === 'failed' || m.status === 'timed_out' || m.status === 'spawn_error',
     ).length,
+    maxConcurrency: swarm.maxConcurrency,
     members,
   }
 }

package/src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { buildPlanningModeSection } from './prompt-sections'
+import type { Agent } from '@/types'
+
+function agentWith(partial: Partial<Agent>): Agent {
+  return {
+    id: 'test',
+    name: 'Test',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5',
+    credentialId: null,
+    apiEndpoint: null,
+    soul: null,
+    systemPrompt: null,
+    description: null,
+    tools: [],
+    extensions: [],
+    heartbeatEnabled: false,
+    delegationEnabled: false,
+    delegationTargetMode: 'all',
+    delegationTargetAgentIds: [],
+    skillIds: [],
+    createdAt: 0,
+    updatedAt: 0,
+    ...partial,
+  } as unknown as Agent
+}
+
+test('buildPlanningModeSection returns null when planningMode is undefined', () => {
+  const out = buildPlanningModeSection(agentWith({}), false)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null when planningMode is "off"', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: 'off' }), false)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null when planningMode is null', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: null }), false)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null in minimal prompt mode', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: 'strict' }), true)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null when agent is missing', () => {
+  assert.equal(buildPlanningModeSection(null, false), null)
+  assert.equal(buildPlanningModeSection(undefined, false), null)
+})
+
+test('buildPlanningModeSection emits plan block guidance when strict', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: 'strict' }), false)
+  assert.ok(out, 'should return a non-empty block')
+  assert.match(out!, /## Planning Mode: Strict/)
+  assert.match(out!, /\[MAIN_LOOP_PLAN\]/)
+  assert.match(out!, /"steps":/)
+  assert.match(out!, /current_step/)
+  assert.match(out!, /completed_steps/)
+})

package/src/lib/server/chat-execution/prompt-sections.ts

@@ -81,6 +81,42 @@ export function buildIdentitySection(
   return parts
 }
 
+// ---------------------------------------------------------------------------
+// Planning Mode — opt-in, per-agent
+// ---------------------------------------------------------------------------
+
+/**
+ * When `agent.planningMode === 'strict'`, inject a plan-enforcement section
+ * that tells the model to emit a [MAIN_LOOP_PLAN]{...} block before tool use
+ * on any multi-step turn. The existing main-agent-loop parser in
+ * `parseMainLoopPlan()` consumes these tokens and populates planSteps /
+ * currentPlanStep / completedPlanSteps in MainLoopState.
+ *
+ * Returns null when planning mode is off or minimal prompt mode is active.
+ */
+export function buildPlanningModeSection(
+  agent: Agent | null | undefined,
+  isMinimalPrompt: boolean,
+): string | null {
+  if (!agent || isMinimalPrompt) return null
+  if (agent.planningMode !== 'strict') return null
+  return [
+    '## Planning Mode: Strict',
+    '',
+    'Before any multi-step work (two or more tool calls or file edits), emit a single machine-readable plan block on its own line:',
+    '',
+    '```',
+    '[MAIN_LOOP_PLAN]{"steps":["step 1","step 2","step 3"],"current_step":"step 1","completed_steps":[]}',
+    '```',
+    '',
+    'Rules:',
+    '- Each step should be a short imperative phrase (≤80 chars).',
+    '- Update `current_step` as you advance, and append finished steps to `completed_steps`.',
+    '- Skip the block for trivial single-tool responses or pure Q&A.',
+    '- The block is parsed by the runtime; do not wrap it in prose, code fences, or extra punctuation.',
+  ].join('\n')
+}
+
 // ---------------------------------------------------------------------------
 // Thinking Level Guidance
 // ---------------------------------------------------------------------------

package/src/lib/server/chat-execution/stream-agent-chat.ts

@@ -17,6 +17,7 @@ import { loadRuntimeSettings, getAgentLoopRecursionLimit } from '@/lib/server/ru
 import { truncateToolResultText } from '@/lib/server/chat-execution/tool-result-guard'
 import {
   buildIdentitySection,
+  buildPlanningModeSection,
   buildThinkingSection,
   buildRuntimeOrientationSection,
   buildWorkspaceSection,
@@ -384,6 +385,8 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
   }
 
   // Composable prompt sections — each builder returns string | null (or string[])
+  const planningBlock = buildPlanningModeSection(sessionAgent, isMinimalPrompt)
+  if (planningBlock) promptParts.push(planningBlock)
   const thinkingBlock = buildThinkingSection(agentThinkingLevel, isMinimalPrompt)
   if (thinkingBlock) promptParts.push(thinkingBlock)
   const { rootSessionId } = resolveSessionLineageIds(session)

package/src/lib/server/session-tools/subagent.ts

@@ -34,7 +34,11 @@ import {
   listSwarms,
   aggregateResults,
   waitForAll,
+  SWARM_MAX_CONCURRENCY_HARD_LIMIT,
+  SWARM_DEFAULT_PARALLEL_CONCURRENCY,
 } from '@/lib/server/agents/subagent-swarm'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import { getMission } from '@/lib/server/missions/mission-repository'
 
 const SUBAGENT_ACTIONS = [
   'start',
@@ -73,6 +77,10 @@ const subagentToolSchema = z.object({
   jobIds: z.union([z.array(z.string()), z.string()]).optional(),
   tasks: z.union([z.array(subagentTaskSchema), z.string()]).optional(),
   executionMode: z.enum(['auto', 'parallel', 'serial']).optional(),
+  maxConcurrency: z.union([z.number(), z.string()]).optional(),
+  joinPolicy: z.enum(['all', 'first', 'quorum']).optional(),
+  quorum: z.union([z.number(), z.string()]).optional(),
+  cancelRemaining: z.boolean().optional(),
   waitForCompletion: z.boolean().optional(),
   background: z.boolean().optional(),
   timeoutSec: z.union([z.number(), z.string()]).optional(),
@@ -150,10 +158,12 @@ export function coerceSubagentActionArgs(rawArgs: Record<string, unknown>): Reco
   const normalized = normalizeToolInputArgs(rawArgs)
   const coerced: Record<string, unknown> = { ...normalized }
 
-  for (const key of ['waitForCompletion', 'background', 'shareBrowserProfile'] as const) {
+  for (const key of ['waitForCompletion', 'background', 'shareBrowserProfile', 'cancelRemaining'] as const) {
     coerced[key] = parseBooleanLike(coerced[key])
   }
   coerced.timeoutSec = parseNumberLike(coerced.timeoutSec)
+  coerced.maxConcurrency = parseNumberLike(coerced.maxConcurrency)
+  coerced.quorum = parseNumberLike(coerced.quorum)
 
   const parsedTasks = parseJsonLike(coerced.tasks)
   if (Array.isArray(parsedTasks)) {
@@ -239,6 +249,76 @@ function requireString(args: Record<string, unknown>, key: string): string {
   return val
 }
 
+type JoinPolicy =
+  | { type: 'all' }
+  | { type: 'first' }
+  | { type: 'quorum'; count: number; cancelRemaining: boolean }
+
+function parseJoinPolicy(args: Record<string, unknown>, taskCount: number): JoinPolicy {
+  const raw = typeof args.joinPolicy === 'string' ? args.joinPolicy.trim().toLowerCase() : ''
+  if (raw === 'first') return { type: 'first' }
+  if (raw === 'quorum') {
+    const parsed = typeof args.quorum === 'number' ? args.quorum : Number(args.quorum)
+    const count = Number.isFinite(parsed) && parsed > 0
+      ? Math.min(Math.floor(parsed), taskCount)
+      : Math.max(1, Math.ceil(taskCount / 2))
+    const cancelRemaining = args.cancelRemaining !== false
+    return { type: 'quorum', count, cancelRemaining }
+  }
+  return { type: 'all' }
+}
+
+/**
+ * Resolve the effective maxConcurrency for a swarm dispatch using the
+ * precedence: explicit arg > agent.maxParallelDelegations > mission.budget.maxParallelBranches > system default.
+ */
+function resolveSwarmMaxConcurrency(
+  args: Record<string, unknown>,
+  ctx: ActionContext,
+): number {
+  const pickFinite = (value: unknown): number | null => {
+    const n = typeof value === 'number' ? value : Number(value)
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null
+  }
+  const explicit = pickFinite(args.maxConcurrency)
+  if (explicit !== null) return Math.min(explicit, SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+
+  if (ctx.agentId) {
+    const agent = loadAgents()[ctx.agentId]
+    const agentCap = pickFinite(agent?.maxParallelDelegations)
+    if (agentCap !== null) return Math.min(agentCap, SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+  }
+
+  if (ctx.sessionId) {
+    const session = getSession(ctx.sessionId) as { missionId?: string | null } | null
+    const missionId = typeof session?.missionId === 'string' && session.missionId.trim()
+      ? session.missionId.trim()
+      : null
+    if (missionId) {
+      const mission = getMission(missionId)
+      const missionCap = pickFinite(mission?.budget?.maxParallelBranches)
+      if (missionCap !== null) return Math.min(missionCap, SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+    }
+  }
+
+  return SWARM_DEFAULT_PARALLEL_CONCURRENCY
+}
+
+async function awaitSwarmByPolicy(
+  swarm: Awaited<ReturnType<typeof spawnSwarm>>,
+  policy: JoinPolicy,
+): Promise<ReturnType<typeof spawnSwarm> extends Promise<infer T> ? T extends { allSettled: Promise<infer A> } ? A : never : never> {
+  if (policy.type === 'first') {
+    await swarm.firstSettled
+    swarm.cancelAll()
+    return swarm.allSettled
+  }
+  if (policy.type === 'quorum') {
+    return swarm.quorumSettled(policy.count, { cancelRemaining: policy.cancelRemaining })
+  }
+  return swarm.allSettled
+}
+
 // ---------------------------------------------------------------------------
 // Promise-based wait (no polling when handle exists)
 // ---------------------------------------------------------------------------
@@ -336,9 +416,11 @@ async function handleBatch(args: Record<string, unknown>, ctx: ActionContext): P
   const executionMode = args.executionMode === 'parallel' || args.executionMode === 'serial'
     ? args.executionMode
     : 'auto'
+  const maxConcurrency = resolveSwarmMaxConcurrency(args, ctx)
+  const policy = parseJoinPolicy(args, tasks.length)
 
   // Use spawnSwarm internally — batch is a simplified interface
-  const swarm = await spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
+  const swarm = await spawnSwarm({ tasks, executionMode, maxConcurrency }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
   const jobIds = swarm.members
     .filter((m) => !m.spawnError && m.handle)
     .map((m) => m.handle.jobId)
@@ -349,13 +431,16 @@ async function handleBatch(args: Record<string, unknown>, ctx: ActionContext): P
       status: 'running',
       jobIds,
       taskCount: tasks.length,
+      maxConcurrency: swarm.maxConcurrency,
     })
   }
-  const aggregate = await swarm.allSettled
+  const aggregate = await awaitSwarmByPolicy(swarm, policy)
   return JSON.stringify({
     action: 'batch',
     status: 'completed',
     jobIds,
+    maxConcurrency: swarm.maxConcurrency,
+    joinPolicy: policy.type,
     completed: aggregate.totalCompleted,
     failed: aggregate.totalFailed + aggregate.totalSpawnErrors,
     cancelled: aggregate.totalCancelled,
@@ -397,8 +482,10 @@ async function handleSwarm(args: Record<string, unknown>, ctx: ActionContext): P
   const executionMode = args.executionMode === 'parallel' || args.executionMode === 'serial'
     ? args.executionMode
     : 'auto'
+  const maxConcurrency = resolveSwarmMaxConcurrency(args, ctx)
+  const policy = parseJoinPolicy(args, tasks.length)
 
-  const swarm = await spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
+  const swarm = await spawnSwarm({ tasks, executionMode, maxConcurrency }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
   if (!waitForCompletion) {
     const snapshot = getSwarmSnapshot(swarm.swarmId)
     return JSON.stringify({
@@ -406,15 +493,18 @@ async function handleSwarm(args: Record<string, unknown>, ctx: ActionContext): P
       status: 'running',
       swarmId: swarm.swarmId,
       memberCount: swarm.members.length,
+      maxConcurrency: swarm.maxConcurrency,
       snapshot,
     })
   }
-  const aggregate = await swarm.allSettled
+  const aggregate = await awaitSwarmByPolicy(swarm, policy)
   const snapshot = getSwarmSnapshot(swarm.swarmId)
   return JSON.stringify({
     action: 'swarm',
     ...aggregate,
     status: swarm.status,
+    maxConcurrency: swarm.maxConcurrency,
+    joinPolicy: policy.type,
     snapshot,
   })
 }
@@ -633,6 +723,23 @@ const SubagentExtension: Extension = {
             enum: ['auto', 'parallel', 'serial'],
             description: 'How to schedule sibling subagents. "auto" defaults to serial for Ollama-backed targets and parallel otherwise.',
           },
+          maxConcurrency: {
+            type: 'number',
+            description: 'Max sibling branches that may run at the same time when parallel. Defaults to agent/mission policy or 4. Hard-capped at 16.',
+          },
+          joinPolicy: {
+            type: 'string',
+            enum: ['all', 'first', 'quorum'],
+            description: 'How to wait. "all" (default) waits for every branch. "first" resolves when one succeeds and cancels the rest. "quorum" resolves when `quorum` branches succeed.',
+          },
+          quorum: {
+            type: 'number',
+            description: 'Required when joinPolicy="quorum" — number of successful branches needed before resolving.',
+          },
+          cancelRemaining: {
+            type: 'boolean',
+            description: 'When joinPolicy="quorum", cancel in-flight branches after quorum is reached. Default true.',
+          },
           waitForCompletion: { type: 'boolean' },
           background: { type: 'boolean' },
           timeoutSec: { type: 'number' },

package/src/lib/server/storage-normalization.ts

@@ -399,6 +399,7 @@ function normalizeStoredAgentMissionRecord(value: unknown): unknown {
   budget.maxToolCalls = normalizeFiniteNumber(budget.maxToolCalls)
   budget.maxWallclockSec = normalizeFiniteNumber(budget.maxWallclockSec)
   budget.maxTurns = normalizeFiniteNumber(budget.maxTurns)
+  budget.maxParallelBranches = normalizeFiniteNumber(budget.maxParallelBranches)
   if (!Array.isArray(budget.warnAtFractions)) {
     budget.warnAtFractions = [0.5, 0.8, 0.95]
   } else {
@@ -620,6 +621,7 @@ function normalizeStoredRecordInner(
     if (!Array.isArray(agent.delegationTargetAgentIds)) {
       agent.delegationTargetAgentIds = legacyTargetIds
     }
+    agent.maxParallelDelegations = normalizeFiniteNumber(agent.maxParallelDelegations)
     delete agent.platformAssignScope
     delete agent.subAgentIds
     agent.sandboxConfig = normalizeAgentSandboxConfig(agent.sandboxConfig)

package/src/lib/validation/schemas.ts

@@ -88,6 +88,7 @@ export const AgentCreateSchema = z.object({
   delegationEnabled: z.boolean().optional().default(false),
   delegationTargetMode: z.enum(['all', 'selected']).optional().default('all'),
   delegationTargetAgentIds: z.array(z.string()).optional().default([]),
+  maxParallelDelegations: z.number().int().positive().nullable().optional().default(null),
   tools: z.array(z.string()).optional(),
   extensions: z.array(z.string()).optional().default([]),
   skills: z.array(z.string()).optional().default([]),
@@ -122,6 +123,7 @@ export const AgentCreateSchema = z.object({
   memoryTierPreference: z.enum(['working', 'durable', 'archive', 'blended']).nullable().optional().default(null),
   proactiveMemory: z.boolean().optional().default(true),
   autoDraftSkillSuggestions: z.boolean().optional().default(true),
+  planningMode: z.enum(['off', 'strict']).nullable().optional().default(null),
   projectId: z.string().optional(),
   avatarSeed: z.string().optional(),
   avatarUrl: z.string().nullable().optional().default(null),

package/src/types/agent.ts

@@ -67,6 +67,12 @@ export interface Agent {
   delegationEnabled?: boolean
   delegationTargetMode?: DelegationTargetMode
   delegationTargetAgentIds?: string[]
+  /**
+   * Cap on sibling subagents this agent may dispatch concurrently via
+   * `spawn_subagent` swarm/batch actions. Resolves after the mission-level
+   * cap and before the system default (4). Hard-capped at 16.
+   */
+  maxParallelDelegations?: number | null
   tools?: string[]
   // When 'scoped', the chat turn restricts enabled extensions to the
   // intersection of the universal core list and agent.tools (plus a small
@@ -125,6 +131,14 @@ export interface Agent {
   proactiveMemory?: boolean
   /** Auto-refresh a reviewed skill draft from meaningful chat turns for this agent. */
   autoDraftSkillSuggestions?: boolean
+  /**
+   * Planning enforcement mode.
+   * - 'off' (default): no extra planning guidance
+   * - 'strict': instruct the model to emit a [MAIN_LOOP_PLAN] block before any
+   *   tool call on multi-step turns. The existing main-agent-loop plan parser
+   *   reads these blocks into MainLoopState.planSteps.
+   */
+  planningMode?: 'off' | 'strict' | null
   /** Controls whether file operations are confined to the workspace or allowed anywhere on the host. Default: 'workspace'. */
   filesystemScope?: 'workspace' | 'machine' | null
   /** Per-agent filesystem restrictions. Globs matched against resolved paths. */

package/src/types/mission.ts

@@ -28,6 +28,12 @@ export interface MissionBudget {
   maxToolCalls?: number | null
   maxWallclockSec?: number | null
   maxTurns?: number | null
+  /**
+   * Cap on concurrent sub-agent branches when this mission's agents fan out
+   * via `spawn_subagent` swarm/batch actions. Overrides the system default
+   * (4) when set. Hard-capped at 16 regardless.
+   */
+  maxParallelBranches?: number | null
   warnAtFractions?: number[]
 }