Token optimization levers — claim-scoped briefing, payload caps, role-scoped optimal, notification-spawn cooldown (#292)

* feat(gateway): claim-scoped context briefing — heavy sections only on context-acquisition verbs

* feat(gateway): cap unbounded LLM-facing payloads — embedded diffs, notification bodies, handoff journal content, north star

* feat(mcp): role-scope the optimal server's tool groups; index management becomes dev/test-only

* feat(mcp): cap per-result content on kb/error/learning search, mentor sources, rag citations

* refactor(gateway): extract heavy-briefing sections + clip helper to keep xenon ranks

* feat(orchestrator): cross-tick cooldown for notification-triggered spawns

* feat(usage,orchestrator): scope spawn-waste to anthropic sessions; cap agent Bash output via settings env

* docs: claim-scoped briefing, payload caps, optimal role-scoping, notification-spawn cooldown

* test(mcp): type the mixed-item cap fixture explicitly

* fix(orchestrator): lazy-init the notification-spawn cooldown store

* fix(lifecycle): admin-override claim reconciliation + PM request_changes verb (S6 postmortem B3+B4)

B3 — admin_set_status now reconciles claim ownership when leaving BLOCKED:
review/queue targets clear claimed_by/claimed_at/active_claimant_id and
consume the pre-block snapshot (a stale escalation claim was stranding the
next claimant: give_me_work handed the task out while note() bounced
not_authorized — the live b8fe0494 wedge). The pending/in_progress restore
path also syncs active_claimant_id, and a REST PATCH unassign releases the
claim with it.

B4 — new PM verb request_changes: awaiting_pm_review -> needs_revision with
concrete issues. The PM previously had no reject at merge review (only
complete/escalate), so an AC/scope violation looped i_am_blocked->escalate
4x live. Full vertical: lifecycle transition + ActionSpec + IntentSpec,
TaskService.request_changes (routes like a QA fail — original dev for a
leaf, revision PM for assembled; issues appended to dev_notes), verb-runner
compose, choreographer verb (spec gate + non-empty issues + soup check +
a2a delivery of the reject reason), HTTP routes on both PM flows, MCP tool,
journal:decision tracing, PM prompts, regenerated lifecycle artifacts.

* fix(panel): stop scorecard fetches for fallback-roster placeholder ids

useAgents() serves the static AGENT_ROSTER (ids "1".."22") while agent
definitions load; the Scorecards tab fetched a member scorecard per row
immediately, firing 22 guaranteed-422 requests per refetch cycle. Through
the browser's per-origin connection limit those queued every metrics-page
query behind them (~10s of skeletons on every tab). Gate the fetch on a
real member id (agent UUID or the "ceo" alias).

* Upgraded uv.lock

* fix(sequencing): declared deps become real edges + full loop-breaker coverage + assembled-branch freshness (S6 postmortem B1/B2/B6 + breaker)

B1a — code delegations REQUIRE a collision surface: new TASK_AT_DELEGATE
completeness spec (conditional FieldRequirement, when=('task_type','code'))
enforced at the gateway delegate gate. A no-surface code sibling is
'parallel to everything' by analyzer design, which is how two devs ran the
CEO's explicitly-ordered work out of order (f3e1afc5: seq#1 started before
seq#0, zero dependency edges). PM prompts updated; REST/manual creation
(TASK_AT_CREATE) unchanged.

B1b — the CEO's declared 'Depends on' lists become real edges: DraftSurface
gains declared_depends_on; SequencingService.analyze unions declared edges
(validated: self/out-of-range rejected) with the derived collision rules,
cycle-checked by the existing toposort. confirm_live_batch/preview_batch
map each draft's depends_on through (string indices coerced); intake tool
doc + prompter role prompt instruct verbatim copying. The live S6 root got
1 of its 3 declared in-batch edges and started alongside still-running R3.

Breaker coverage — the progress-aware respawn circuit breaker
(_pm_respawn_should_gate: strike counting, status-advance reset,
tracing-gap budget, DB durability, one-shot CEO notification) was consulted
by only 3 spawn paths; the doc/QA/dev/PR-review/PR-gate/revision/board
paths spawned unguarded at fixed cadence (the 26-respawn fe-doc loop,
~$7.20). Now consulted at every task-keyed spawn site (14 total).

B2 — assembled-branch freshness: submit_up/submit_root auto-sync the
assembled branch when it has fallen behind its base (children are terminal
at submit time, so the rebase is safe; master is never written). A rebase
conflict is a hard reject naming the files instead of a blind re-review —
kills the needs_revision↔awaiting_pr_review ping-pong of re-submitting a
stale head. Leaf i_am_done already had the behind-base gate; claim-time
fetch-fresh cut already existed.

B6 — documenter revision-pass loop: the awaiting_documentation bail
rejections (i_am_blocked/unclaim) now name the actual exit (i_documented
re-affirm) and the documenter prompt gets an explicit revision-pass rule.

* fix(orchestration): assembly-integrity gate + dispatcher heartbeat (incidents #11, #1)

Assembly integrity — submit_up/submit_root refuse when a completed child's
commits are not patch-present in the assembled branch (git cherry —
rebase-safe; branch pruned after merge or any git error fails open). Live
incident #11: a completed revert subtask's merge was lost from the cell
branch and the review gate re-flagged the exact violation the revert fixed,
spawning another revision cycle.

Dispatcher heartbeat — a dispatcher.alive audit row every 5 minutes from
the dispatch loop. The 2026-07-01 outage was 4h25m of fleet-wide silence
with no way to distinguish 'loop dead' from 'no work'; the loop's stdout
died with the container while audit_log survives. CHANGELOG for tonight's
full sweep included.

* style: ruff format for the orchestration sweep

* refactor(gateway): fold the assembled-submit guards + trim complexity under the xenon gate

_assembled_submit_guards combines the #11 integrity check and B2 freshen for
submit_up/submit_root; lifecycle's invalid-source remediate and git's
per-child cherry probe extracted into helpers. Test harnesses built via
__new__ stub the respawn tracker (the breaker now runs on their paths).

---------

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

panel/lib/lifecycle.json

@@ -309,6 +309,19 @@
       "pre_side_effects": [],
       "side_effects": []
     },
+    {
+      "allowed_roles": [
+        "cell_pm",
+        "main_pm"
+      ],
+      "composes": [
+        "request_changes"
+      ],
+      "description": "Reject the merge review with concrete issues. Transitions awaiting_pm_review -> needs_revision, routed back like a QA fail (original developer for a leaf, revision PM for an assembled task). Use this for an AC/scope violation caught at merge review \u2014 never i_am_blocked/escalate, which have no revision routing.",
+      "name": "request_changes",
+      "pre_side_effects": [],
+      "side_effects": []
+    },
     {
       "allowed_roles": [
         "cell_pm",
@@ -504,6 +517,15 @@
       "source": "awaiting_pm_review",
       "target": "completed"
     },
+    {
+      "action": "request_changes",
+      "roles": [
+        "cell_pm",
+        "main_pm"
+      ],
+      "source": "awaiting_pm_review",
+      "target": "needs_revision"
+    },
     {
       "action": "pr_pass",
       "roles": [

panel/src/hooks/__tests__/use-observability-member-id.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { isScorecardMemberId } from "../use-observability";
+
+// The static fallback roster (use-agents AGENT_ROSTER) carries placeholder
+// ids "1".."22" while agent definitions load. Fetching scorecards for those
+// fired 22 guaranteed-422 requests per refetch cycle, clogging the browser's
+// connection pool and delaying every metrics tab by ~10s.
+describe("isScorecardMemberId", () => {
+  it("rejects the static fallback roster placeholder ids", () => {
+    for (let i = 1; i <= 22; i++) {
+      expect(isScorecardMemberId(String(i))).toBe(false);
+    }
+  });
+
+  it("accepts real agent UUIDs", () => {
+    expect(isScorecardMemberId("00000000-0000-0000-0002-000000000001")).toBe(
+      true,
+    );
+    expect(isScorecardMemberId("A1B2C3D4-E5F6-7890-ABCD-EF0123456789")).toBe(
+      true,
+    );
+  });
+
+  it("accepts the ceo alias (the CEO card's member endpoint)", () => {
+    expect(isScorecardMemberId("ceo")).toBe(true);
+  });
+
+  it("rejects empty and junk ids", () => {
+    expect(isScorecardMemberId("")).toBe(false);
+    expect(isScorecardMemberId("main-pm")).toBe(false);
+    expect(isScorecardMemberId("not-a-uuid-at-all")).toBe(false);
+  });
+});

panel/src/hooks/use-observability.ts

@@ -86,12 +86,23 @@ export function useCeoScorecard(days = 30) {
   });
 }
 
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Only real member ids may fetch a scorecard: an agent UUID or the "ceo"
+ * alias. The static fallback roster carries placeholder ids ("1".."22")
+ * while agent definitions load — fetching those fired 22 guaranteed-422
+ * requests per cycle and queued the whole metrics page behind them. */
+export function isScorecardMemberId(agentId: string): boolean {
+  return agentId === "ceo" || UUID_RE.test(agentId);
+}
+
 /** Per-member rollup scorecard (+ live in-flight overlay). */
 export function useMemberScorecard(agentId: string, days = 30) {
   return useQuery<MemberScorecard>({
     queryKey: observabilityKeys.memberScorecard(agentId, days),
     queryFn: () => observabilityApi.getMemberScorecard(agentId, days),
-    enabled: Boolean(agentId),
+    enabled: isScorecardMemberId(agentId),
     refetchInterval: 60_000,
   });
 }

panel/src/types/index.ts

@@ -1398,6 +1398,8 @@ export interface SpawnWasteResponse {
   unproductive_pct: number;
   by_role: RoleWasteRow[];
   respawn_strikes: RespawnStrikeRow[];
+  /** Counting scope — non-Anthropic transcripts don't populate output tokens. */
+  basis?: string;
   period: string;
 }