fix(swarm): gate recursive spawning on deep roots

Author: 1jehuang

crates/jcode-app-core/src/server/comm_session.rs

@@ -1243,6 +1243,7 @@ async fn ensure_spawn_coordinator_swarm(
         swarm_id,
         from_name,
         is_root,
+        root_session_id,
         coordinator_id,
         coordinator_is_stale,
         live_member_count,
@@ -1260,6 +1261,10 @@ async fn ensure_spawn_coordinator_swarm(
             .get(req_session_id)
             .and_then(|member| member.report_back_to_session_id.clone())
             .is_none();
+        let root_session_id = super::swarm::swarm_ancestors(&members, req_session_id)
+            .last()
+            .cloned()
+            .unwrap_or_else(|| req_session_id.to_string());
         // Count both all live members for the absolute hard cap and live spawned
         // agents for the configurable RAM-safety cap. User-created roots do not
         // consume worker slots; every recursively spawned descendant does.
@@ -1303,6 +1308,7 @@ async fn ensure_spawn_coordinator_swarm(
             swarm_id,
             from_name,
             is_root,
+            root_session_id,
             coordinator_id,
             coordinator_is_stale,
             live_member_count,
@@ -1319,6 +1325,26 @@ async fn ensure_spawn_coordinator_swarm(
         return None;
     };
 
+    // Light and ad hoc swarms are deliberately one-level fan-out: only the root
+    // session may create workers. Recursive spawning is an explicit deep-swarm
+    // capability, keyed from the root's effort rather than the requesting
+    // child's effort so a worker cannot opt itself into unbounded growth.
+    if !is_root {
+        let root_is_deep = crate::session_effort::session_effort(&root_session_id)
+            .as_deref()
+            .is_some_and(crate::prompt::is_deep_swarm_effort);
+        if !root_is_deep {
+            let _ = client_event_tx.send(ServerEvent::Error {
+                id,
+                message: format!(
+                    "Recursive swarm spawning is disabled for light and ad hoc swarms. Only the root session ({root_session_id}) may spawn agents unless that root is running in swarm-deep mode."
+                ),
+                retry_after_secs: None,
+            });
+            return None;
+        }
+    }
+
     // Keep an absolute hard ceiling even when the configurable limit is disabled.
     if live_member_count >= super::MAX_SWARM_MEMBERS {
         let _ = client_event_tx.send(ServerEvent::Error {
@@ -1333,7 +1359,7 @@ async fn ensure_spawn_coordinator_swarm(
     }
 
     // `swarm_max_concurrent_agents` is the machine-safety budget shared by
-    // run_plan and ad hoc recursive spawning. Previously only run_plan obeyed it,
+    // run_plan and deep recursive spawning. Previously only run_plan obeyed it,
     // so nested agents could grow to the 1000-member hard cap and exhaust RAM.
     let live_agent_limit = (configured_live_agent_limit > 0)
         .then(|| configured_live_agent_limit.min(super::MAX_SWARM_MEMBERS));
@@ -1352,9 +1378,8 @@ async fn ensure_spawn_coordinator_swarm(
     // Coordinator-slot election is now only about the swarm-level coordinator used
     // for shared plan operations (propose/approve/assign). Only a root session
     // (depth 0, no spawner) claims it, and only when the slot is empty or stale.
-    // Non-root spawners coordinate their own subtree via report-back ownership and
-    // never disturb the swarm-level coordinator slot. Crucially, the presence of a
-    // live coordinator no longer blocks anyone from spawning.
+    // Authorized deep-swarm descendants coordinate their own subtree via
+    // report-back ownership and never disturb the swarm-level coordinator slot.
     if is_root && coordinator_id.as_deref() != Some(req_session_id) {
         let should_claim = coordinator_id.is_none() || coordinator_is_stale;
         if should_claim {

crates/jcode-app-core/src/server/comm_session_tests.rs

@@ -816,32 +816,102 @@ async fn spawn_bootstraps_coordinator_when_swarm_has_none() {
 }
 
 #[tokio::test]
-async fn nested_agent_can_spawn_while_live_coordinator_exists() {
-    // Recursive spawning (option A): a spawned child (depth 1, owned by `coord`)
-    // may spawn its own children even though a live swarm-level coordinator
-    // exists. It must not steal the swarm-level coordinator slot.
+async fn nested_agent_cannot_spawn_when_root_is_light_or_normal() {
+    // Both explicit light-swarm effort and ordinary ad hoc swarm use are
+    // one-level fan-out. A spawned child cannot grow another generation.
+    for (root_id, effort) in [
+        ("light-root-no-recursion", Some("swarm")),
+        ("normal-root-no-recursion", None),
+    ] {
+        crate::session_effort::forget_session_effort(root_id);
+        crate::session_effort::record_session_effort(root_id, effort);
+        let swarm_id = format!("swarm-{root_id}");
+        let child_id = format!("child-{root_id}");
+        let swarm_members = Arc::new(RwLock::new(HashMap::new()));
+        let swarms_by_id = Arc::new(RwLock::new(HashMap::from([(
+            swarm_id.clone(),
+            HashSet::from([child_id.clone(), root_id.to_string()]),
+        )])));
+        let swarm_coordinators = Arc::new(RwLock::new(HashMap::from([(
+            swarm_id.clone(),
+            root_id.to_string(),
+        )])));
+        let swarm_plans = Arc::new(RwLock::new(HashMap::<String, VersionedPlan>::new()));
+        let (mut child_member, _child_rx) = member(&child_id, Some(&swarm_id), "agent");
+        child_member.report_back_to_session_id = Some(root_id.to_string());
+        let (root_member, _root_rx) = member(root_id, Some(&swarm_id), "coordinator");
+        let mut members = swarm_members.write().await;
+        members.insert(child_id.clone(), child_member);
+        members.insert(root_id.to_string(), root_member);
+        drop(members);
+        let (client_event_tx, mut client_event_rx) = mpsc::unbounded_channel();
+
+        let refused = ensure_spawn_coordinator_swarm(
+            2,
+            &child_id,
+            &client_event_tx,
+            &swarm_members,
+            &swarms_by_id,
+            &swarm_coordinators,
+            &swarm_plans,
+            32,
+        )
+        .await;
+
+        crate::session_effort::forget_session_effort(root_id);
+        assert!(refused.is_none());
+        assert_eq!(
+            swarm_coordinators
+                .read()
+                .await
+                .get(&swarm_id)
+                .map(String::as_str),
+            Some(root_id)
+        );
+        assert_eq!(
+            swarm_members
+                .read()
+                .await
+                .get(&child_id)
+                .map(|member| member.role.as_str()),
+            Some("agent")
+        );
+        assert!(matches!(
+            client_event_rx.recv().await,
+            Some(ServerEvent::Error { message, .. })
+                if message.contains("Recursive swarm spawning is disabled")
+                    && message.contains(&format!("Only the root session ({root_id}) may spawn agents"))
+        ));
+    }
+}
+
+#[tokio::test]
+async fn nested_agent_can_spawn_when_root_is_deep() {
+    let root_id = "deep-root-recursive";
+    crate::session_effort::record_session_effort(root_id, Some("swarm-deep"));
+
     let swarm_members = Arc::new(RwLock::new(HashMap::new()));
     let swarms_by_id = Arc::new(RwLock::new(HashMap::from([(
-        "swarm-1".to_string(),
-        HashSet::from(["child".to_string(), "coord".to_string()]),
+        "swarm-deep".to_string(),
+        HashSet::from(["deep-child".to_string(), root_id.to_string()]),
     )])));
     let swarm_coordinators = Arc::new(RwLock::new(HashMap::from([(
-        "swarm-1".to_string(),
-        "coord".to_string(),
+        "swarm-deep".to_string(),
+        root_id.to_string(),
     )])));
     let swarm_plans = Arc::new(RwLock::new(HashMap::<String, VersionedPlan>::new()));
-    let (mut child_member, _child_rx) = member("child", Some("swarm-1"), "agent");
-    child_member.report_back_to_session_id = Some("coord".to_string());
-    let (coord_member, _coord_rx) = member("coord", Some("swarm-1"), "coordinator");
+    let (mut child_member, _child_rx) = member("deep-child", Some("swarm-deep"), "agent");
+    child_member.report_back_to_session_id = Some(root_id.to_string());
+    let (root_member, _root_rx) = member(root_id, Some("swarm-deep"), "coordinator");
     let mut members = swarm_members.write().await;
-    members.insert("child".to_string(), child_member);
-    members.insert("coord".to_string(), coord_member);
+    members.insert("deep-child".to_string(), child_member);
+    members.insert(root_id.to_string(), root_member);
     drop(members);
     let (client_event_tx, mut client_event_rx) = mpsc::unbounded_channel();
 
-    let swarm_id = ensure_spawn_coordinator_swarm(
-        2,
-        "child",
+    let allowed = ensure_spawn_coordinator_swarm(
+        3,
+        "deep-child",
         &client_event_tx,
         &swarm_members,
         &swarms_by_id,
@@ -851,46 +921,29 @@ async fn nested_agent_can_spawn_while_live_coordinator_exists() {
     )
     .await;
 
-    assert_eq!(swarm_id.as_deref(), Some("swarm-1"));
-    // The swarm-level coordinator slot is untouched.
-    assert_eq!(
-        swarm_coordinators
-            .read()
-            .await
-            .get("swarm-1")
-            .map(String::as_str),
-        Some("coord")
-    );
-    // The child keeps its agent role; it coordinates its own subtree via
-    // report-back ownership, not the swarm-level coordinator slot.
-    assert_eq!(
-        swarm_members
-            .read()
-            .await
-            .get("child")
-            .map(|member| member.role.as_str()),
-        Some("agent")
-    );
+    crate::session_effort::forget_session_effort(root_id);
+    assert_eq!(allowed.as_deref(), Some("swarm-deep"));
     assert!(client_event_rx.try_recv().is_err());
 }
 
 #[tokio::test]
 async fn spawn_allowed_at_arbitrary_depth_without_depth_cap() {
-    // Build a deep chain root -> a -> b -> c -> d -> e -> f. There is no depth
-    // cap anymore, so even a deeply nested agent may still spawn.
+    // Deep-swarm mode still allows recursive decomposition at arbitrary depth.
+    let root_id = "deep-root-arbitrary-depth";
+    crate::session_effort::record_session_effort(root_id, Some("swarm-deep"));
     let swarm_members = Arc::new(RwLock::new(HashMap::new()));
     let swarms_by_id = Arc::new(RwLock::new(HashMap::new()));
     let swarm_coordinators = Arc::new(RwLock::new(HashMap::from([(
         "swarm-1".to_string(),
-        "root".to_string(),
+        root_id.to_string(),
     )])));
     let swarm_plans = Arc::new(RwLock::new(HashMap::<String, VersionedPlan>::new()));
     {
         let mut members = swarm_members.write().await;
-        let (root, _rx) = member("root", Some("swarm-1"), "coordinator");
-        members.insert("root".to_string(), root);
+        let (root, _rx) = member(root_id, Some("swarm-1"), "coordinator");
+        members.insert(root_id.to_string(), root);
         let chain = [
-            ("a", "root"),
+            ("a", root_id),
             ("b", "a"),
             ("c", "b"),
             ("d", "c"),
@@ -918,6 +971,7 @@ async fn spawn_allowed_at_arbitrary_depth_without_depth_cap() {
         32,
     )
     .await;
+    crate::session_effort::forget_session_effort(root_id);
     assert_eq!(allowed.as_deref(), Some("swarm-1"));
 }
 

crates/jcode-app-core/src/server/swarm.rs

@@ -25,10 +25,10 @@ fn status_age_secs(last_status_change: Instant) -> u64 {
 
 /// Maximum number of live members (agents) in a single swarm. Re-exported from
 /// `jcode_swarm_core` so the server, tools, and prompts all agree on the one
-/// runaway-prevention cap for the task-graph model. There is intentionally no
-/// spawn-depth limit and no per-node fan-out limit: the spawn tree may nest and
-/// fan out freely until the swarm reaches this many live members, at which point
-/// further spawns are refused.
+/// runaway-prevention cap for the task-graph model. Normal and light swarms are
+/// root-only, one-level fan-out. Deep-swarm roots may create recursive trees with
+/// no depth limit, but both the configurable live-worker budget and this absolute
+/// cap still apply.
 pub(super) use jcode_swarm_core::MAX_SWARM_MEMBERS;
 
 /// Walk the `report_back_to_session_id` chain upward from `session_id`,

crates/jcode-app-core/src/tool/communicate.rs

@@ -1787,7 +1787,7 @@ pub struct CommunicateTool {
 
 impl CommunicateTool {
     pub fn new() -> Self {
-        const BASE_DESCRIPTION: &str = "Coordinate agents. Any agent can spawn child agents, and those children can spawn their own, forming a recursive spawn tree with no depth limit (growth is bounded only by the total swarm member cap). For spawn, prefer providing a prompt so the new agent starts with a concrete task instead of idling. Spawned/assigned agents automatically report their final response back to the agent that spawned them; you can stop any agent in the subtree you spawned.\n\nCommunication: prefer structural dataflow (task-graph artifacts via complete_node) over chat, and DMs for point-to-point coordination. broadcast reaches only your spawned subtree (whole swarm for the coordinator) and should be rare; channels and shared-context are discouraged legacy primitives.";
+        const BASE_DESCRIPTION: &str = "Coordinate agents. In light-swarm and normal ad hoc use, only the root session may spawn agents, keeping execution to one level of fan-out. Recursive spawning is enabled only when the root session is running in swarm-deep mode; deep descendants may then spawn their own children, bounded by the configured live-agent limit and the absolute swarm member cap. For spawn, prefer providing a prompt so the new agent starts with a concrete task instead of idling. Spawned/assigned agents automatically report their final response back to the agent that spawned them; you can stop any agent in the subtree you spawned.\n\nCommunication: prefer structural dataflow (task-graph artifacts via complete_node) over chat, and DMs for point-to-point coordination. broadcast reaches only your spawned subtree (whole swarm for the coordinator) and should be rare; channels and shared-context are discouraged legacy primitives.";
         let swarm_prompt = crate::prompt::load_swarm_prompt(None);
         let description = if swarm_prompt.is_empty() {
             BASE_DESCRIPTION.to_string()

crates/jcode-app-core/src/tool/communicate_tests.rs

@@ -1097,6 +1097,14 @@ fn description_includes_swarm_prompt_guidance() {
         description.contains("Swarm prompt"),
         "description should embed the swarm prompt section"
     );
+    assert!(
+        description.contains("only the root session may spawn agents"),
+        "description should advertise the enforced light/ad hoc spawn boundary"
+    );
+    assert!(
+        description.contains("Recursive spawning is enabled only when the root session is running in swarm-deep mode"),
+        "description should reserve recursive spawning for deep-swarm roots"
+    );
 }
 
 #[test]

crates/jcode-base/src/prompt/swarm_prompt.md

@@ -21,12 +21,9 @@ Structure guidance for spawned swarm agents:
 - Always pass `label` when spawning (e.g. `label: "api reviewer"`) so the swarm
   UI shows what each agent is for. The explicit `spawn` action rejects missing or
   blank labels.
-- Any agent may spawn children; the spawner owns them (children report back to
-  it, and it may stop them). There is no special "manager" role: a manager is
-  just an agent whose prompt tells it to decompose work, delegate via spawn,
-  and synthesize the reports.
-- When you are a worker with focused work of your own and want to delegate more
-  than 2-3 subtasks, do not fan them out directly. Spawn one manager agent with
-  a prompt like "own X: decompose it, spawn workers for the pieces, synthesize
-  their reports, and report back", and let it own that subtree. This keeps your
-  own context on your task and keeps report-back traffic structured.
+- In normal and light-swarm mode, only the root session may spawn agents. Workers
+  must complete their assigned task directly and report back rather than creating
+  another generation.
+- Recursive spawning is reserved for a root running in `swarm-deep` mode. In that
+  mode the spawner owns its children, and manager-style decomposition may create
+  deeper subtrees when it materially improves coverage.

crates/jcode-base/src/prompt_tests.rs

@@ -281,6 +281,8 @@ fn test_default_swarm_prompt_mentions_model_and_list_models() {
     assert!(DEFAULT_SWARM_PROMPT.contains("list_models"));
     assert!(DEFAULT_SWARM_PROMPT.contains("model"));
     assert!(DEFAULT_SWARM_PROMPT.contains("effort"));
+    assert!(DEFAULT_SWARM_PROMPT.contains("only the root session may spawn agents"));
+    assert!(DEFAULT_SWARM_PROMPT.contains("swarm-deep"));
 }
 
 #[test]

docs/SWARM_ARCHITECTURE.md

@@ -19,12 +19,17 @@ coordinate, plan, communicate, and integrate work with optional git worktrees.
 
 ## Roles
 
-### Recursive spawning (unbounded-depth tree)
+### Mode-gated spawning
 
-Spawning is recursive. Any swarm member can spawn child agents, and those
-children can spawn their own children, forming a spawn tree. There is no depth
-cap: growth is bounded only by the total swarm member cap. The root session
-that first spawns in a repo is depth 0.
+Normal ad hoc swarms and light-swarm mode are one-level fan-out: only the root
+session may spawn agents. Workers report their result to the root and cannot
+create another generation. This keeps opportunistic swarm use bounded by
+construction.
+
+Recursive spawning is reserved for roots running in `swarm-deep` mode. Their
+descendants may spawn children at arbitrary depth, subject to the configurable
+live-worker budget and the absolute swarm member cap. The root session that first
+spawns in a repo is depth 0.
 
 The spawn/parent edge is encoded by `report_back_to_session_id`: a child spawned
 by `P` reports back to `P`. Walking that chain reconstructs ancestry and depth,
@@ -42,7 +47,8 @@ report-back coherent across member churn.
 The single per-swarm "coordinator" slot still exists, but only for shared,
 swarm-level plan operations (propose/approve/assign/task-control on the one
 shared plan). Only a root session claims that slot, and only when it is empty or
-stale. A live coordinator no longer blocks anyone else from spawning.
+stale. Authorized deep descendants do not claim or disturb this slot when they
+spawn.
 
 Nested owners coordinate their own subtree through spawn prompts, direct
 messages, and stop, not through the shared plan. Plan/task operations
@@ -76,10 +82,9 @@ concurrently would make the shared plan incoherent.
 - Propose plan updates when they discover issues or new requirements.
 - Coordinate directly with other agents via DM or channels.
 - Emit lifecycle events when they start, finish, or stop unexpectedly.
-- May spawn their own child agents (no depth cap; bounded only by the total
-  swarm member cap) and stop any
-  agent in the subtree they spawned. Stopping agents outside their own subtree
-  still requires `force=true`.
+- In a deep swarm, may spawn child agents and stop any agent in the subtree they
+  spawned. In light and ad hoc swarms, workers cannot spawn. Stopping agents
+  outside their own subtree still requires `force=true`.
 
 ## Agent Lifecycle States
 

docs/SWARM_TASK_GRAPH.md

@@ -75,7 +75,8 @@ the scheduler or dataflow.
   a modest quality bump, without going extreme. Goal is just to run independent
   units in parallel. Mostly flat (one level of fan-out); decomposition is optional
   (agent's choice); the critique/verify gate is off, or at most a single optional
-  final check; recursion is discouraged/disabled; the handoff artifact is
+  final check; only the root may spawn agents, so recursive growth is disabled;
+  the handoff artifact is
   lightweight and may be free-form. Small worker cap (e.g. 4-16). Low cost and
   latency. This is essentially today's spawn-and-fan-out behavior kept cheap.
   Examples: "run these 5 independent edits in parallel".
@@ -149,9 +150,10 @@ flowchart TB
   Dj --> E[Task E downstream of D]
 ```
 
-Recursion is bounded only by a single **total-member cap** (1000 agents per swarm,
-section 10). There is intentionally no depth limit and no per-node fan-out limit:
-the spawn tree may nest and fan out freely until the swarm hits the member cap.
+In **deep mode**, recursion has no fixed depth or per-node fan-out limit. Growth
+is bounded by the configurable live-worker budget and the absolute total-member
+cap (1000 agents per swarm, section 10). Light mode disables recursive spawning:
+only its root may create the flat worker fan-out.
 
 ---