Tree: smarter sub-Bot allocation (lead+children, reuse, deeper placement) maintained by auto-prune/merge #447

Problem

The tree has no real placement logic. Every new Bot lands flat under whichever Bot created it, and in practice that is almost always Chief. Chief then fills up to maxChildren (8) with unrelated specialists. When the owner later asks for a coherent sub-team ("a dedicated team for the FlyBot repo: dev, test, maintenance, repo management"), there is no room and no way to restructure. Chief then works around the cap (see #446).

How placement works today (main at 753b7e9)

• Always under the caller. create_child_bot(name, role_description) has no parent argument. The parent is always the calling Bot (tools.js, tree.js#L144-L161). Chief cannot create "FlyBot Lead" and then put Dev/Test under it in one step. It has to create the lead, then message the lead and hope the lead creates the right children.
• Adoption is flat. Every pre-existing or UI-created Bot without tree fields becomes a direct child of Chief until the cap is reached. Any further ones stay outside the tree with only a log warning (tree.js#L85-L104).
• No move/reparent. There is no tool or UI to move a Bot under another parent. Reparenting only happens when a Bot is deleted, and then its children go to the grandparent (onBotRemoved).
• Reuse only looks one level deep. The coordinator prompt says to create a child "ONLY when no existing child fits (check list_children first)" (prompt.js#L26-L29). But list_children returns direct children only, and the prompt says "you cannot see deeper levels". The duplicate check also covers only sibling names (limits.js#L20). A "Tester" two levels down is invisible, so a second one gets created.
• No balancing. No logic or prompt guidance tells Chief to group related Bots under a lead before it reaches the cap. The only rule when the cap is hit is "use the closest child".
• Placement is not visible or confirmable. The owner finds out where a Bot went only from the sidebar afterwards. Non-tree Bots are also drawn under Chief (client.js#L308-L311), so the sidebar can be wrong as well.

Owner decision (2026-10-19 ~19:45 Asia/Shanghai)

Align allocation with #446's automatic prune/merge direction:

• Allocation should produce a healthy tree (lead+children, reuse, deeper placement) that prune/merge can maintain.
• Prune/merge (Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446) is the safety net when structure goes wrong (over capacity, orphans, misplaced bots).
• Keep strong ideas from the prior proposal where they still fit; soften/drop "outside-tree bots stay outside forever / never auto-adopt" — orphans are candidates for automatic reparent/merge/prune.
• Do not frame the design as a pure "ask owner when full" model.

Proposed behavior

1. Reuse before create. Before creating, Chief checks existing Bots with a matching role across the whole tree, by name and role. Add a read-only find_bots(query) or tree_overview() tool for the root, giving name, role, parent and depth. If a match exists, reuse (or propose merge into) that Bot instead of creating a duplicate.
2. Group by project or role. When a request names a project plus several roles, the default plan is a lead plus children: Chief → FlyBot Lead → {Dev, Test, Maintenance, Repo}, not four flat children of Chief. This costs one slot under Chief, not four — and matches what auto-prune/merge should restore toward when the tree has drifted flat.
3. Placement-aware creation. Allow the root (and only ancestors) to create a Bot under a descendant it owns: create_child_bot(name, role_description, parent?), where parent must be the caller or one of its descendants. Limits and depth are checked at the target parent, and the existing per-parent lock still applies.
4. Reparent / move as part of healthy structure (with Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446). Prefer automatic reparent/merge/prune when the tree is over capacity or orphans exist (Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446). A move_bot tool or sidebar "Move under…" remains useful for explicit owner-driven reshapes; model-proposed moves for large new plans can still use a plan card. Do not require owner confirmation for every safety-net reorganize that Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446 runs to restore caps.
5. Balancing + safety net. When a parent is near the cap (e.g. ≥ 6/8), the coordinator prefers grouping related children under a lead rather than adding another flat child. When full or when orphans appear, Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446 auto-prune/merge runs — not "ask the owner / leave outside forever".
6. Optional plan card for large creates. For a request that would create several new Bots (or a new lead subtree), Chief may show a short plan card (reuse / create / resulting paths) with Approve / Edit / Cancel. A single new leaf under a parent with room can proceed without a card, but the reply should still name the tree path. Plan cards are for forward allocation clarity, not the primary fix for an already-broken tree.

Recommendation: ship 1, 2, 3 and 6 as the allocation change, designed so the resulting trees stay maintainable by #446's auto-prune/merge. Implement move/reparent APIs so both explicit moves and automatic reorganization can share them. Drop any design that permanently parks orphans outside the tree.

Acceptance criteria

• Asking Chief for "a team for project X with roles A/B/C/D" yields (optionally via plan card) Chief → X Lead → {A,B,C,D} and creates exactly that (one new slot under Chief) when approved or when the single-leaf auto path applies.
• Chief reuses (or merges into) an existing Bot with a matching role anywhere in its tree instead of creating a duplicate; covered by a test with the match at depth 3.
• create_child_bot with parent accepts only the caller or its descendants and checks limits at the target; a test covers a non-descendant parent being refused.
• Allocation docs and prompts state that overcapacity and orphans are handled by Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446 auto-prune/merge; orphans are reparent/merge/prune candidates, not permanent outside-tree.
• Shared reparent/merge primitives exist so Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446 automatic reorganization and any explicit move UI use the same limit checks and prompt/trace refresh.
• docs/subsystems/tree.md documents the placement rules and the link to auto-prune/merge (Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446).

Related: child-cap bypass / auto-prune-merge #446, #6 (tree), #16 (who may create children), #56 (resource bounds).
Verified against main at 753b7e9.
Owner decision recorded 2026-10-19 ~19:45 Asia/Shanghai.