Orchestration

First reader working: orchestration/ (Claude Code transcripts). How sessions delegate to subagents, what the workers cost, and how much their results weigh on the orchestrator.

• Reads: subagent transcripts and .meta.json, Agent/Task launches, their results and <task-notification> hand-backs, per-call usage, git commit in Bash. Never prompt, result or command text in the output.
• Used for: how much spend goes to workers, whether fan-out pays off, which workers flood the orchestrator's context, whether batches end in commits.

Flags

• worker results above 2000 tokens (the orchestrator carries them on every later turn)
• workers on the most expensive model for small tasks
• wide fan-out without a commit after the batch
• failed or killed workers

Pitfalls

• Teammates and workflow agents have no launch in the session transcript: counted, not linked.
• Result tokens are chars/4 estimates; usage and cost are from logged usage at list price.
• Other harnesses (Codex, OpenCode) log subagents differently; not read yet.

Specs (O-*)

Constants at the top of orchestration.py: DAYS=7, AGENT_TOOLS=(Agent, Task), CHARS_PER_TOKEN=4, HUGE_RESULT_TOKENS=2000, DEEP_DEPTH=2, FANOUT_MIN=3, READOUT_BYTES=400.

• O-sessions: a session is <project>/<sid>.jsonl plus every <project>/<sid>/subagents/**/agent-<id>.jsonl (workflow agents under workflows/wf_*/). Kept if it has a subagent file and any of its files was modified since the window start; a session with no worker is not a record.
• O-scan: per transcript, user/assistant/attachment lines with a timestamp. Usage dedups by message id (lines of one message repeat it); first and last timestamp give the span.
• O-launch: a tool_use named in AGENT_TOOLS is a launch; launches in one assistant message (one turn) form a batch.
• O-link: a worker's .meta.json toolUseId is matched to the transcript holding that launch (orchestrator or another worker); that transcript is its launcher. Depth = spawnDepth (default 1). Unmatched workers stay unlinked.
• O-result: tokens a worker costs its launcher = its tool_result content plus every <task-notification> (user string or queued_command attachment prompt) naming its <tool-use-id>, chars/4.
• O-huge: an orchestrator-launched worker with result tokens > HUGE_RESULT_TOKENS.
• O-error: is_error on the result, toolUseResult.status or a notification <status> in ERROR_STATUS (failed, killed, error, cancelled).
• O-commit: a batch is committed when one of its workers ran git [-C dir] commit, or the orchestrator did between the batch start and the next batch.
• O-fanout: max_batch = most workers in one batch; max_concurrent = most depth-1 workers whose [launch, last line] spans overlap; parallel_share = share of depth-1 workers overlapping another.
• O-cost: cost per message via schemas/cost.py; orchestrator cost = session file, worker cost = subagent files, split by model family. Peak ctx = max(input + cache read + cache write) of one call.
• O-topology: first match of deep (depth >= 2), single-helper (1 worker), fan-out (max_concurrent or max_batch >= 3), serial (max_concurrent <= 1), small-parallel.
• O-summary: totals over sessions: topologies, cost split and by model, max concurrent, worker peak ctx and duration percentiles, result tokens p50/p90 (orchestrator-launched), huge, batches committed, errors, unlinked.
• O-readout: summary subset plus up to 3 findings (biggest result absorber, top worker model share, batches then commit), findings dropped from the end until the JSON is < READOUT_BYTES.