feat: per-runtime telemetry adapters + per-agent token attribution

[josstei]

Summary

Implements Phase 4 of the gemini-runtime-hardening plan: per-runtime telemetry adapters and per-agent token attribution in transition_phase. Closes finding F2 (token_usage was zero across 5 invocations in the captured Gemini test run).

Stacks on PR #67 (Phase 2: phase.kind discriminator). Once #67 merges, this PR's base will move automatically.

What changed

TelemetryAdapter contract (src/platforms/shared/adapters/telemetry-adapter-{types,factory}.js):

• Canonical Usage shape { input, output, cached } matches the existing transition_phase token_usage parameter — adapter outputs flow into the session-state aggregator without translation.
• defineTelemetryAdapter({ runtime, extractUsage, isAvailable }) enforces typed runtime, function signatures, and defensive ZERO_USAGE fallback when underlying extractUsage returns malformed shape.
• isTelemetryUsage predicate, TELEMETRY_USAGE_FIELDS and TELEMETRY_RUNTIMES exposed as frozen constants.

Per-runtime adapters (src/platforms/{claude,codex,gemini,qwen}/telemetry-adapter.js):

Runtime	Status	Source
Claude	Real	Anthropic SDK Usage envelope (input_tokens, output_tokens, cache_read_input_tokens + cache_creation_input_tokens)
Codex	Real	OpenAI-style prompt_tokens/completion_tokens with input_tokens/output_tokens fallback for older CLI versions; cached_tokens
Gemini	Stub	isAvailable: false — Gemini CLI's invoke_agent envelope returns only textual output. Follow-up candidates documented inline.
Qwen	Stub	Same architecture as Gemini, same TODO.

Each runtime-config.js now exposes its adapter via a canonical telemetry field so the orchestrator has one resolution surface.

Generator allowlist (src/generator/payload-builder.js):

• RUNTIME_PAYLOAD_FILES constant (runtime-config.js, telemetry-adapter.js) replaces the single hardcoded path. Adding a future per-runtime surface (e.g., a tracing-adapter.js) is one line.
• Required so runtime-config.js's require('./telemetry-adapter') resolves in detached payloads (claude/, plugins/maestro/) — without this, generated mirrors would crash at load time.

Per-agent attribution in transition_phase (src/mcp/handlers/session-state-tools.js):

• New optional agent_name parameter (string for solo phases or array for multi-agent batches). Falls back to phase.agents from session state, then to 'unknown' when no attribution is available.
• Multi-agent phases split usage equally with Math.floor. The total_input/output/cached fields preserve exact totals so the per-agent sum may underattribute by up to (n−1) tokens — acceptable for budget tracking.
• Defensive init for legacy state shapes: missing token_usage block, missing by_agent field, or by_agent mutated into an array all fall back to empty {} without throwing.
• Number(...) || 0 coercion protects against malformed counts in legacy YAML.

Tool schema (src/mcp/tool-packs/session/index.js):

• agent_name added with oneOf: [string, array] so clients reading tools/list discover the parameter.

Orchestration steps (src/references/orchestration-steps.md):

• Step 25 now instructs the orchestrator to load the runtime's telemetry adapter via runtime-config.telemetry, call extractUsage(invocationResult), and pass the result as token_usage plus agent_name. Adapters reporting isAvailable: false (Gemini/Qwen) signal the orchestrator to OMIT token_usage rather than recording zeros.

Test plan

• Telemetry contract: 23 unit tests in tests/unit/telemetry-adapter-factory.test.js — frozen constants, factory validation, isTelemetryUsage edge cases, malformed-extractUsage fallback, isAvailable error containment.
• Runtime adapters: 18 unit tests in tests/unit/runtime-telemetry-adapters.test.js — Claude full extraction, Codex prompt_tokens preferred over input_tokens, Gemini/Qwen always-zero stubs, runtime-config telemetry export.
• Generator allowlist: payload-builder tests updated to assert RUNTIME_PAYLOAD_FILES is frozen and contains both runtime-config.js and telemetry-adapter.js.
• Per-agent attribution integration: 10 tests in tests/integration/telemetry-attribution.test.js — single string, array split, phase.agents fallback, empty-array regression guard, "unknown" fallback, missing by_agent, missing token_usage, array by_agent, omitted token_usage, Math.floor underattribution.
• Full suite: 1230 passing (was 1177 on Phase 2 base).
• just check-layers clean.
• just check zero drift.

Verification limit (mention for reviewers)

The Claude/Codex extraction shapes are plan-assumptions, not live-verified against captured SDK responses. The contract structure is what this PR ships; empirical validation that real invocations produce non-zero token_usage requires a follow-up integration run. The Phase 1 fixture pattern (tests/fixtures/runtime-contracts/...) could host real Anthropic/Codex usage envelopes for adapter tests — proposed as a Phase 4 follow-up.

Findings addressed

• F2 — token_usage: { total_input: 0, total_output: 0, total_cached: 0 } across 5 invocations in the original test run. Claude and Codex now extract real usage. Gemini and Qwen explicitly report unavailable so the orchestrator omits token_usage rather than recording false zeros.

Cross-runtime coverage

Runtime	Telemetry adapter	runtime-config exposure
Claude	Real (Anthropic SDK Usage)	✓
Codex	Real (OpenAI-style + fallback)	✓
Gemini	Stub (isAvailable: false)	✓
Qwen	Stub (isAvailable: false)	✓