Skip to content

Limit egm-bootstrap workers and scouts - #359

Merged
jpettitt merged 4 commits into
google:mainfrom
atrearyan:fix/bootstrap-parallelism-caps
Nov 20, 2026
Merged

jpettitt merged 4 commits into
google:mainfrom
atrearyan:fix/bootstrap-parallelism-caps

Conversation

@atrearyan

@atrearyan atrearyan commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary of Key Changes

Refs #262 (bootstrap parallelism item: add a cap and show an estimated cost at the existing >15-directory gate).

egm-bootstrap told the root to spawn all Sub-Orchestrators "without artificial concurrency limits", and each worker spawned one goldfish-explorer scout per ~1,500-line chunk of a directory, all in parallel, with no limit. The >15-directory gate asked for approval without saying what the run would start.

  • skills/egm-bootstrap/SKILL.md:
    • Worker cap: the partitioning already yields at most 5 partitions (3 to 5 nodes, or 3 to 4 large branches plus one fallback partition). The skill now spawns at most 5 Sub-Orchestrators, replacing the "Unbounded Execution" step. The "Unbounded" labels on the gate, strategy, and spawn steps are dropped.
    • Scout cap: each worker runs at most 5 chunk scouts at a time and queues the rest. Every chunk is still read, so coverage does not change, only concurrency. A worker documents its directories one at a time, so at most 5 workers and 25 scouts run at once.
    • Gate estimate: the >15-directory question now says the run uses up to 5 parallel workers and at least one scout per code directory, one per ~1,500 lines of source. It counts subagents, not tokens: discovery pauses at the 16th directory, before any file is read, so a token figure would be a guess.
    • Execution Constraint 6 now asks before spawning workers instead of before "unbounded subagent spawning".
  • docs/designs/bootstrap.md (Status: Current): replaced "unbounded" parallelism with the caps in the overview, goals, user journey, swarm architecture, both "Spawning upon Approval" bullets, the rate-limit risk, and the bootstrap_parallel_tree test description, and added the estimate to the Safety Gate step.
  • tests/unit/test_harnesses.py: test_bootstrap_caps_parallel_workers_and_scouts checks the worker cap, the scout cap, the gate estimate, and that "artificial concurrency limits" is gone. All four checks fail on the skill text in main.
  • skills/egm-bootstrap/test_scenarios.yaml: bootstrap_safety_gate now also requires the gate to state the worker cap ("up to", "at most", or "no more than" 5 workers or Sub-Orchestrators). Replies such as "I will spawn 20 workers" or "trees with 5 or fewer subdirectories run without workers" do not match.
  • skills/egm-bootstrap/TEST.md: the manual safety gate scenario now checks the estimate.

The caps are prompt instructions, not limits a host enforces. On a host with no subagent tool, the skill already runs the scout steps inline, so the caps do not apply there. I chose 5 for both because it is the partitioning's existing maximum, so the worker cap does not change how a run that follows the algorithm partitions the tree.

Counts: the non-test diff is 22 lines in skills/egm-bootstrap/SKILL.md and 38 in docs/designs/bootstrap.md, in 1 core file.

Out of scope: the other #262 items. #347 fixed the marketplace source, the development dependencies item is still open, and the persona and standard paths are recorded as accepted on #262; #291 covers the docs-accuracy item. docs/designs/bootstrap.md still says in places that approval is requested when the directory count is above 5, while the skill and the design's own Warning Gate ask above 15; I left those sentences as they were.

Suggested label: docs (for the docs/designs/bootstrap.md update).

Contribution Type

Track: Bug Fix / Minor Patch

Verification

Unit tests: passed, after merging main again at 70406c4. #394 removed the committed distributions/claude folder, so this PR no longer changes it. With #409's .NET detection, the merged skill body came to 24,109 bytes, over the 24,000-byte limit, so I trimmed this PR's own wording: Execution Constraint 5 is back to its main text, the gate question says "scout" instead of "scout subagent", the scout cap says "queue the rest" instead of "start the next when one returns", and the worker cap no longer repeats that the partitioning yields at most 5 partitions, which the partitioning steps already state. pytest tests/unit on Python 3.14.0 (via uv run --no-project --with pytest==9.0.3 --with pyyaml==6.0.3, the test group pins in pyproject.toml): 388 passed, 2 skipped (the Copilot and Cursor native probes, which need EGM_COPILOT_OFFLINE and EGM_CURSOR_BUNDLE). The four checks in the new test fail on the skill text in main.

Scenario pattern: the new bootstrap_safety_gate pattern matches the skill's gate question and does not match the two wrong replies above or the old question. Not run: a live scenario evaluation.

Other checks and limits: passed: git diff --check; the skill body is 23,973 bytes, under the 24,000-byte limit. Not run: a live bootstrap on any host.

Human Accountability Affirmation

The root spawned every Sub-Orchestrator "without artificial concurrency
limits", and each worker spawned one scout per ~1,500-line chunk with no
limit. Cap workers at 5, which the partitioning already yields at most,
and run at most 5 chunk scouts at a time per worker. The >15-directory
gate now says how many workers and scouts the run uses. Update the
bootstrap design doc, add a unit test and a scenario assertion, and
regenerate distributions/claude.

Refs google#262
@atrearyan
atrearyan requested a review from a team as a code owner November 8, 2026 03:50
@atrearyan
atrearyan requested a review from jpettitt November 8, 2026 03:50
@atrearyan

Copy link
Copy Markdown
Contributor Author

Hi @n3wth , A note on overlap: #350 (opened 2026-11-07) also caps egm-bootstrap, at two workers with two scouts each, queuing the rest, and it also changes path handling in egm-review-loop. Both PRs edit the same lines of skills/egm-bootstrap/SKILL.md, so only one of the bootstrap caps can merge as is. The difference: this PR caps at five, the partitioning's existing maximum, so no partition waits for a worker. This PR also adds a unit test and a scenario check for the caps. I'm happy to go with whichever you prefer, and if #350's cap lands first I'll close this one. #246 and #349 also edit lines this PR changes in that file, so whichever of these merges later will need a rebase.

…lelism-caps

# Conflicts:
#	skills/egm-bootstrap/TEST.md
@briansuchy
briansuchy removed the request for review from a team November 11, 2026 20:06

@egm-triage-bot egm-triage-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated first-pass review found zero blocking or major issues. Routing to @google/egm-maintainers for maintainer review.

@egm-triage-bot egm-triage-bot added the triage: passed Automated Stage-1 PR triage found zero blocking or major issues label Nov 11, 2026
@n3wth n3wth changed the title Cap parallel workers and scouts in egm-bootstrap Limit egm-bootstrap workers and scouts Nov 18, 2026
…lelism-caps

# Conflicts:
#	distributions/claude/skills/egm-bootstrap/SKILL.md
After merging main, google#409's .NET detection put the skill body at 24,109
bytes, over the 24,000-byte limit. Restore Execution Constraint 5,
shorten the gate question and scout cap, and drop the worker cap's
repeat of the partition limit, which the partitioning steps state.

@egm-triage-bot egm-triage-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated first-pass review found zero blocking or major issues. Routing to @google/egm-maintainers for maintainer review.

@jpettitt

Copy link
Copy Markdown
Collaborator

LGTM - approval pending a decision on merging this or #350

@jpettitt
jpettitt requested a review from eewing314 November 20, 2026 17:27
@jpettitt

Copy link
Copy Markdown
Collaborator

I had Gemini Neon do an analysis of #359 and #350, the tl;dr is we're merging 359 with a couple of flags for possible future work.

Evaluation and Comparison: PR #350 versus PR #359

Comparison of [PR #350][pr-350] (@mathewgeejo) and [PR #359][pr-359]
(@atrearyan) against google/elephant-goldfish-model main (70406c4) and
parent [issue #262][issue-262].

Recommendation

Important

Approve and merge [PR #359][pr-359]. Close [PR #350][pr-350].

PR #359 addresses one item in issue #262 cleanly. It merges with main, passes
all CI checks, fits under Antigravity's 24,000-byte skill limit, updates the
design doc, and adds automated tests.

PR #350 has merge conflicts and would exceed the 24,000-byte limit on main.
It also bundles a breaking egm-review-loop change that contradicts prior
maintainer reviews on #268 and #289. It adds no automated tests, and
@eewing314's questions from 2026-11-15 remain unanswered.

PR #350 does raise two valid concerns that PR #359 does not cover: host
slot-starvation deadlocks and workspace-override protection for built-in
shortnames. Track those as separate follow-ups if needed.


Side-by-Side Comparison

Dimension PR #350 (@mathewgeejo) PR #359 (@atrearyan, #262 assignee)
Merge and CI status mergeable: false (dirty). Stale base e9e1f06 (2026-11-07). Edits distributions/claude/ files removed in #394. mergeable: true (clean). Synced to 70406c4 (2026-11-18). All 21 CI checks pass (unit Linux and Windows, lint, probes, triage, CLA).
Scope and Track 1 fit Bundles two unrelated areas across two core skills (egm-bootstrap and egm-review-loop). 6 files (+89 / -26). Focuses on one item (egm-bootstrap parallelism and gate cost). 1 core skill, design doc, and tests. 5 files (+46 / -27).
Bootstrap concurrency cap 2 workers × 2 scouts (at most 6 subagents total, or 2 scouts in direct mode). Covers lower host limits and inline fallback. 5 workers × 5 scouts (at most 30 subagents total: 5 workers and 25 scouts). Matches the partitioning cap of 5.
Safety gate cost info Tells the agent to show known directory, partition, and chunk counts, and to report unknown token costs as unknown. Updates the gate question to state up to 5 parallel workers and at least one scout per code directory (~1,500 lines each).
egm-bootstrap body size (main = 23,931 / 24,000 B) Adds +248 bytes → 24,179 B projected on main. Fails test_skill_load_limits.py by 179 bytes. Adds +42 bytes → 23,973 B on main. Passes with 27 bytes of headroom.
Design doc (docs/designs/bootstrap.md) Not updated. Leaves "Unbounded Parallel Swarm" text intact. Updated across all 10 operational "unbounded" references.
Test coverage Manual checklists in TEST.md only. Zero automated tests. Adds test_bootstrap_caps_parallel_workers_and_scouts in tests/unit/test_harnesses.py, updates test_scenarios.yaml, and updates TEST.md.
Alignment with #262 reviews Contradicts @n3wth's reviews in [#268][pr-268-review] and [#289][pr-289-review]. Follows prior consensus and documents the overlap with #350.
Author responsiveness @eewing314's two questions from 2026-11-15 have no reply. Actively maintained. Author trimmed prose after #409 landed to stay under 24,000 bytes.

Evaluation of PR #359

PR #359 focuses strictly on egm-bootstrap concurrency caps, safety-gate cost
visibility, design documentation, and regression tests.

Strengths

  1. Matches the partitioning cap: Step 3.2 of skills/egm-bootstrap/SKILL.md
    (Adaptive Depth Partitioning) produces at most 5 partitions. Valid cases are
    3 to 5 nodes, 3 to 4 large branches plus 1 fallback, or fewer than 3
    immediate children. A 5-worker cap removes "without artificial concurrency limits" without requiring root-level worker queueing.
  2. Matches what the agent knows at the gate: BFS discovery pauses at
    directory 16 before pruning, partitioning, or reading source files. Stating
    "up to 5 parallel workers, and at least one scout per code directory (one per ~1,500 lines of source)" avoids guessing token counts or unknown
    partition totals.
  3. Maintains docs, tests, and size limits: PR Limit egm-bootstrap workers and scouts #359 updates
    docs/designs/bootstrap.md (status Current), adds unit and scenario tests
    matching repository conventions, and keeps skills/egm-bootstrap/SKILL.md
    at 23,973 bytes.

Risks and Caveats

  1. High peak concurrency (up to 30 subagents): Five workers with five
    parallel scouts each can run 25 scouts and 5 workers at once. On large
    directories across five subtrees, this concurrency could still trigger API
    rate limits or lower host caps. Lowering the scout cap to 2 or 3 later
    requires a one-character edit with zero byte cost.
  2. No fallback for lower host limits or slot deadlock: A host may cap
    concurrent subagents below 5. Running workers could then occupy every slot
    and block while spawning scouts. PR Limit egm-bootstrap workers and scouts #359 relies only on the existing rule for
    hosts with no subagent tool.
  3. No worker-queue fallback: Step 3.2 states "Spawn their Sub-Orchestrators in parallel, never more than 5." It omits "(queue the rest)" and assumes the model strictly obeys the 5-partition limit.
  4. Tight byte budget: skills/egm-bootstrap/SKILL.md has 27 bytes of
    headroom left under the 24,000-byte ceiling (mostly inherited from main's
    23,931 bytes). Future edits will need to move prose into references/.
  5. Minor test strictness: test_harnesses.py checks exact prose substrings,
    which matches surrounding tests in that file. The new test_scenarios.yaml
    regular expression
    ((?i)\b(up to|at most|no more than)\s+(5|five)\s+(parallel\s+)?(workers?|sub-?orchestrators?)\b)
    would reject valid paraphrases such as "capped at 5 workers" or "up to 5 concurrent workers" if a model does not quote the gate text verbatim.

Evaluation of PR #350

PR #350 combines egm-bootstrap concurrency caps with stricter path and link
rules in egm-review-loop.

Blockers

  1. Stale branch, merge conflicts, and 24 KB overflow: PR Limit bootstrap workers and validate review paths #350 conflicts with
    main because Derive Claude root source in packaging #394 removed distributions/claude/ and Fix egm-bootstrap .NET detection for egm-bootstrap/SKILL.md #409 modified
    skills/egm-bootstrap/SKILL.md. Rebasing its +248-byte bootstrap diff onto
    main yields 24,179 bytes, which fails test_skill_load_limits.py.
  2. Breaking change to egm-review-loop against prior consensus: PR Limit bootstrap workers and validate review paths #350
    replaces Custom Paths with a Resource Boundary that rejects any persona
    or standard outside the installed plugin's agents/ and
    resources/document_standards/.
  3. Duplicate and incomplete link gating in egm-review-loop: PR Limit bootstrap workers and validate review paths #350 adds
    "Before the first round, resolve links collected from the target..." even
    though egm-review-loop does not crawl links from TargetFile. egm-review
    Step 1.3 already handles link resolution, symlink checks, user approval, and
    headless omissions before invoking egm-review-loop. Adding a second gate
    risks prompting twice or re-adding declined links in Stages 7 and 9. The
    added prompt also omits "end your turn" on approval questions, which fix(review): save GoldfishContext URLs as files #289
    specifically fixed.
  4. Awkward worker queueing and premature gate metrics:
    • Capping at 2 workers conflicts with the 3–5 partition algorithm in Step
      3.2. Step 3.2 still says "For each partition subtree root, ... spawn a parallel worker ... Go idle and wait for all worker subagents", relying on
      a distant 3-line **Concurrency** note under ## Delegation to imply
      batched waves.
    • Asking the agent at Step 2.2 to "show known directory/partition/chunk counts" requests partition and chunk counts that do not exist yet when BFS
      pauses at directory 16.
  5. Missing tests, missing design doc update, and no author response: PR Limit bootstrap workers and validate review paths #350
    adds no automated tests and leaves docs/designs/bootstrap.md outdated. It
    also has no reply to @eewing314's 2026-11-15 questions.

Ideas Worth Salvaging as Separate Follow-Ups

  1. Lower-host-limit and slot-deadlock fallback in egm-bootstrap: Respect
    lower host concurrency caps and run scouts inline when nested delegation or
    slots are unavailable. Because skills/egm-bootstrap/SKILL.md only has 27
    bytes remaining, adding this requires trimming existing text or moving
    details into references/.
  2. Plugin-root pinning for built-in shortnames in egm-review-loop: Keep
    Custom Paths intact, but state explicitly that shortnames (such as
    style or feature-spec-standard) resolve only inside the installed plugin
    root. That prevents an untrusted repository from hijacking a built-in
    shortname by using a workspace agents/style.md file without breaking
    explicit custom paths.

@jpettitt
jpettitt merged commit 8e2a5ed into google:main Nov 20, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage: passed Automated Stage-1 PR triage found zero blocking or major issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants