enhancement: armory substrate consumes ~59% of subagent context window before work begins

[rz1989s]

Evidence (gathered while dogfooding, 2026-08-04)

While watching a live subagent run (a code-review subagent) in the /fleet widget, the tok/ctx% readout showed a static 575K tok 59% that didn't tick up and was the same across sessions. Investigating the run log (.pi/fleet/conversations/fl-msdvkaeh-z6a4mu.jsonl, model Ollama/glm-5.2:cloud, contextWindow 976,000) showed the actual message_end usage:

Turn	input	output
1	574,535	48
2	574,633	46
3	575,998	49
4	576,076	53
5	576,170	49

contextTokens = input + output + cacheRead + cacheWrite ≈ 575K = 59% of the 976K window from turn 1. Per-turn deltas are tiny (+98/+1365/+78/+94 tokens), so the displayed 575K/59% barely moves — it looks frozen and is the same across sessions.

Root cause

The input on turn 1 is dominated by the armory substrate — the system prompt + loaded skills + memory hydration that every armory-native child receives "from birth." This substrate is ~570K and roughly constant regardless of the specific task, so every subagent's turn-1 context converges to ~575K/59%. The widget's tok/ctx% segments are context-occupancy metrics (how full the window is), not work-progress metrics — so they reflect the substrate overhead, not the task's progress.

Impact

• 59% of the context window is consumed by overhead before the subagent does any work, leaving ~400K for actual work + tool results on a 976K-window model. For longer tasks or smaller-window models, this is a real constraint.
• The tok/ctx% readout is uninformative as a progress signal (flat from turn 1), which is confusing to operators ("looks frozen / same every session").

Proposed directions (needs brainstorm → spec → plan, not a hot-patch)

1. Lazy / scoped skill loading — only load the skills the agent's role/lifecycle actually needs, not the full arsenal index.
2. Trim memory hydration — hydrate only the relevant scopes, not the full project memory.
3. Compact system prompt — audit the child's system prompt for bloat.
4. Widget UX — also surface a work-progress signal (turn count, tokenTotal growth, last-event class) alongside context-occupancy, so the row doesn't look frozen. (Overlaps with feat: surface liveness progress for long foreground subagent runs #23 — liveness progress.)

Not a bug

The widget is accurate. This is a design cost of the "armory-native from birth" substrate. Filed to track the optimization + the widget-UX companion.

Measured

• Substrate overhead: ~570K tokens / 59% of 976K (glm-5.2:cloud), turn 1.

[rz1989s]

Skill-loading root cause fixed — PR #42 (merged, main 9d0d3d8)

Addressed direction #1 (lazy/scoped skill loading) from the issue body. Default chosen per RECTOR: (a) none — lean substrate, caller opts in.

What changed

• src/engine/child-loader.ts — extracted resolveChildSkills() (pure, testable). The no-skills branch now returns [] (not cur.skills). An agent that declares specific skills still loads only those (truthy branch unchanged).
• src/tools/subagent.ts — new skills param (Type.Array(Type.String())); callers opt in to specific skills. Threaded as skillsOverride to the direct spawn path (replaces the agent's frontmatter skills; pass [] for zero). For lifecycle dispatches, additive via mergeLifecycleSkills() — the phase's designed skills always load and caller skills merge on top (a caller cannot strip a phase's required skills).

Blast radius (challenge-step verified)

• general-purpose / general-purpose-cc direct dispatches → now load 0 skills (lean). Was ~570K / ~59% of context from turn 1.
• default lifecycle phases (all declare explicit skill bundles) → unaffected (truthy branch).
• verify.ts gate reviewer (passed skills: []) → was also loading all 42 (old else-branch bug); now correctly loads 0. Bonus lean-up, no regression.

Verified

• pnpm typecheck clean; pnpm test:run 623/623 (+8 new).
• Reviewed by a read-only subagent (minimax-m3:cloud, readOnly:true dogfooding feat(subagent): readOnly bypass for foreground single-slot lock (#31) #41, lean-substrate dogfooding enhancement: armory substrate consumes ~59% of subagent context window before work begins #32) — APPROVE, 0 blockers; findings addressed before merge (lifecycle additive merge, [] override lock-in, EOF newlines, description accuracy).

Substrate-token reduction

The actual ~570K → ~? drop will be confirmed via the release-gate smoke (real pi dispatch) at tag time. This PR proves the skill-loading logic only.

What stays open in this issue

The other 3 directions from the issue body remain (this PR was the highest-leverage slice — skills were the bulk of the substrate):

• feat(spec-2): deep armory integration (memory + vision, fleet-owned) #2 Trim memory hydration — hydrate only relevant scopes.
• release: v0.2.0 (switch deps to npm, publish armory-fleet) #3 Compact system prompt — audit the child system prompt for bloat.
• SPEC-3 — cross-harness peers (CC + Pi backends, profile routing, session_key resume) #4 Widget work-progress UX — surface a work-progress signal alongside context-occupancy (overlaps feat: surface liveness progress for long foreground subagent runs #23).

Keeping this issue open for directions #2–#4.