feat(subagent): distillation telemetry + route force-summary content to output

[esengine]

What

Two paired changes to make spawn_subagent measurable end-to-end:

1. New SubagentTelemetry collector. Wire one pre-bound onSpawnComplete callback into registerSubagentTool and every spawn auto-populates per-spawn SpawnDistillation records plus a session-level SubagentSessionSummary (compression ratio, useful-spawn rate, spawn-storm count). No behavior change to the parent loop; no SessionStats touch.
2. Force-summary content now lands in output, not error. Discriminate the two forcedSummary paths on parentSignal.aborted: the user-abort placeholder still routes to error, but storm-breaker / context-guard partials populate final and set a new SubagentResult.forcedSummary flag. formatSubagentResult gets a { success: false, partial: true, output, note } branch so the parent agent sees the partial answer with a clear marker.

Numbers

Seven rounds of live-API probes (scripts/probe-*, ~$1.20 of DeepSeek spend). Pre vs post on the same 12-turn × 3-repeat read-heavy script:

	Pre-patch	Post-patch
Median SUB session cost vs FLAT	+24% (loss)	−13% (win)
Useful-spawn rate (non-empty output)	54%	73%
Force-summary content recovered into output	0%	9.1%
Spawn storms observed (≥3 spawns / turn)	2	2

37-point swing in expected cost direction on identical workload. Variance is still real (one of three post-patch runs still cost +14.6%) — exposing the metric is partly so users can see that when it happens.

The 46% empty-output rate from the pre-patch baseline decomposed cleanly in Round 5:

• ~⅓ paused (budget exhaustion; recoverable via resume_session — separate issue)
• ~⅓ force-summary content stranded in error — fixed here
• rest: probe-side read_file truncation (probe artifact, not real-Reasonix)

Full investigation walk-through in docs/rfcs/0001-multi-context-orchestrator.issue.md.

Wiring (caller-side)

const telemetry = new SubagentTelemetry();
registerSubagentTool(registry, {
  client,
  onSpawnComplete: telemetry.record,  // pre-bound
});

// ... agent runs, spawn_subagent fires populate telemetry automatically ...
telemetry.summary;       // SubagentSessionSummary
telemetry.stormCount();  // turns with ≥3 spawns

Commits

70fbeb1  fix(subagent): route forceSummary content to output, not error
fcd103c  feat(telemetry): expose sub-agent distillation as first-class metric
fcb83c3  chore(probes): live-API probes for sub-agent distillation rounds 1-7
32a1108  docs(rfcs): RFC-0001 + issue draft for multi-context distillation

Non-goals

• TUI cell for the new metric — separate UX-shaped PR.
• Auto-wiring into CacheFirstLoop.stats — SubagentResultLike structural type is exported so rolling the collector into SessionStats later stays cycle-free, but doing it now would widen this PR.
• Default maxToolIters bump — Round 7 swept 4/8/16/24/32 and DEFAULT_PAUSE_EVERY = 16 is the empirical knee. No change.
• Orchestrator-as-default topology — out of scope; the metric exists so that decision can be data-supported when revisited.

Test plan

• npm run lint clean (biome on src tests)
• npm run typecheck clean
• 22 new tests: 16 in tests/subagent-distillation.test.ts, 6 in tests/subagent.test.ts (2 for onSpawnComplete, 4 for the forcedSummary formatter branch)
• Public-API snapshot covers the 10 new public names
• Live-API end-to-end (scripts/probe-session-e2e-post-patch.mts): median 12-turn session moved from SUB +24% to SUB −13%
• Reviewer sanity-check on the structural SubagentResultLike type — that's the door open for SessionStats integration; comments welcome on whether the shape is right