feat(agents): rate limit, fan-out cap, and cross-project refusal

[eneskirca]

PR 4 of the agent-messaging plan: flow control. It ships inert — parseControlRequest still
refuses send and reply as unknown verbs (asserted by running it), so nothing in this PR is
reachable by any agent until PR 5 lands the verbs. It builds directly on #207's decidePreProbe,
the 16-member outcome union, and RETRYABLE.

The pair limit is keyed by the PAIR, and the two alternatives each break something

checkPairRate(src, dst, now), PAIR_MIN_INTERVAL_MS = 10_000 (#98's number, now enforced).

Keying	What it produces
by SENDER	An orchestrator fanning out to four workers starves itself: four sends inside a second, three refused for being correct behaviour. (That shape is the right one for a turn cap, which is what the second limit is — with a much larger allowance.)
by TARGET	One node's window is held shut by whoever wrote to it last, and every other conversation with that node pays for it. Trivially abusable: a flooder makes a target unreachable for everyone.
by PAIR	The budget belongs to the conversation. A to B says nothing about A to C, and — asserted explicitly — nothing about B to A, so a reply is never throttled by the message it answers.

The map key writes its separator as the six-character escape (backslash-u-0000), never a raw byte:
a raw NUL makes git, grep and ripgrep skip the entire source file in silence (commit 4c0e8c3,
twice).

What identifies a turn

checkFanOut(src, now), FANOUT_PER_TURN = 4, reset by noteNewTurn(nodeId).

A turn is the budget entry itself — created by the turn's first send, destroyed by the sender's
own newTurn. That is the same edge the renderer's per-turn fan-out already uses (normalize.ts:
"true only for a genuine new turn … so the renderer can clear per-turn fan-out without clearing on
every mid-turn tool event"). The three things that look like turn ids and are not:

• A state transition (working to done) flips several times inside one turn on a tool-event
  burst. A cap that resets mid-turn is not a cap.
• The session id spans hours and hundreds of turns: four messages per session is a permanent
  block wearing a budget's clothes.
• A wall-clock window refills in the middle of a long turn and refuses at the start of a short
  one.

Only the SOURCE's own newTurn resets it — if the target's did, every delivery would refill the
budget that sent it, because a delivery is what starts the target's turn.

Where the state lives, and which way it fails

Process memory, module scope, swept on read. Nothing persisted, deliberately:

• A lost limiter is a brief over-send. After a restart, one extra message per pair inside its
  10 s window and a full fan-out budget. Bounded, self-healing, invisible.
• A stuck limiter is a permanently silent agent — the failure this module refuses to have. So
  every path that could produce one fails OPEN:
  • entries are evicted, not filtered at read time (a limiter that decides expiry on read while
    the map grows looks correct to every test that reads through the same bound, and leaks);
  • a clock jumping backwards drops the entry instead of parking it in the future (an NTP step
    would otherwise silence an agent for the length of the step);
  • a fan-out budget whose reset signal never arrives expires by itself after TURN_STALE_MS
    (5 min) — so a shell that forgets to wire noteNewTurn over-sends four messages per idle five
    minutes instead of silencing every sender for the rest of the run.

Both limits are pre-probe: they answer from a Map, so a refusal costs no tmux round-trip and,
on an SSH project whose ControlMaster has died, no real login. Asserted by running a delivery with a
probe that counts its calls (0 when rate-limited, 1 on the control). Both refuse with the existing
rateLimited member, so RETRYABLE already answers for them. A fan-out refusal reports the pair
interval as retryAfterMs — a floor, not a promise: 0 would be read as "no limit" by
decidePreProbe, whose refusal is retryAfterMs > 0, and the cap would silently stop existing.

A check never starts a window. Only noteSent records, and only a delivery that actually reached
a pane calls it. Otherwise a delivery refused as targetBusy — a RETRYABLE outcome the caller was
told to come back from — would burn the budget it never used, and four such retries would silence
the sender for its whole turn. The cost of that choice: refusals themselves are unthrottled, which
is acceptable precisely because they are free.

Cross-project, resolved off the store

resolveDeliveryScope(projects, src, dst) takes the serialized projects array — the same one
routeControlSource and storedNodeListing read — and has no parameter for a live node list.
That is the guarantee, and the test checks it by effect: a node the live canvas has but the store
does not is refused. It fails closed (a source in no known project, a target in no known
project, and a target in an unshared project are all cross-project, which is not retryable),
resolves a duplicate node id from a cloned project.json to the sender's own project, and does not
filter closed projects — their tmux sessions keep running and a delivery goes to a pane.

send/reply are declared outside needsLiveCanvas, so a delivery can never travel the camera:
travelling would hijack the human's view on a background agent's say-so and the setActive on the
way would clear that node's unread badge — a message silently erasing the signal a human relies on
(G5).

The self-send half was already landed by #207 (decidePreProbe, ahead of everything but an
explicit notPermitted) and is not re-implemented here. It is verified by running it, including
that both guards produce the identical notPermitted{reason:'self-send'} so a trace cannot depend
on which one fired, and that the backstop sits ahead of the rate limiter so a self-send is never
reported as a wait. The guard is exactly as strong as the plan describes; its only softness is that
it skips when either id is absent, which is documented in #207 and is the correct reading of
"absent" (a caller that supplies neither id has not made a self-send claim to check).

Three surfaces

• Desktop (Electron): the only surface with the verbs, so the only one that consumes budget.
• Server Edition: both modules ship (src/core ships on both shells) with no consumer —
  messaging does not exist there, and Task 5.3 makes that a named terminal refusal rather than a
  throttle-shaped one.
• Mobile (phone): never a sender, so it never consumes budget. It is a valid target
  (Correction C1) and is covered like any other: the budget belongs to the pair, so two
  orchestrators messaging one phone-spawned node get two independent windows.

Mutation results

24 mutations applied one at a time (revert, run, restore) against the five suites this PR touches.
24/24 killed. One SURVIVED on the first pass and is the false green: dropping the separator from
pairKey entirely left the collision test green, because its id set contained no pair that collides
under plain concatenation ('a-b'+'c' is not 'a'+'b-c'). Adding 'ab'/'bc' — which do collide —
makes it red. The test looked exhaustive (81 pairs, all distinct) and proved nothing about the thing
it was named for.

Also caught while writing this: the test file itself was written with raw NUL bytes in that same
test — the exact hazard the key's docblock warns about, reproduced by the tool writing the file.
Both files were scanned for raw NULs before commit; there are none.

Killed mutations, in groups: pairKey without a separator; sweep without pair eviction; sweep
without the clock-backwards guard; sweep without turn-budget expiry; retryAfterMs reporting the
whole interval instead of the remainder; the fan-out cap off by one; the fan-out cap disabled;
noteSent forgetting the pair window; noteSent not incrementing; noteNewTurn as a no-op;
noteNewTurn resetting every sender; FANOUT_RETRY_AFTER_MS = 0; checkFlowLimits forgetting
either half; resetMessageFlow forgetting a map; flowStats returning a constant; the scope
resolver without its self-send arm, admitting any known target, resolving the owner off the target,
always claiming the target exists, and never refusing; #207's self-send backstop removed; and send
or reply dropped from the store-answered set.

One branch was deleted rather than kept: checkFlowLimits originally picked the larger of the
two waits, and the "pair is larger" arm is unreachable while FANOUT_RETRY_AFTER_MS equals
PAIR_MIN_INTERVAL_MS. It is now a fixed precedence (fan-out first) with a test pinning the
constant relationship that makes the precedence sound.

Tests

New: agent-message-flow.test.ts (29), agent-message-scope.test.ts (15). Extended:
controlRouting.test.ts (+1), canvas-control-core.test.ts (+1). npm run typecheck clean; full
npx vitest run = 6199 passed, 4 failed — the 3 node-pty-patch and 1 webgl-addon-pair
assertions that are environmental on this Linux host and fail identically on origin/main.

Deviation from the plan

Tasks 4.1 and 4.2 are one commit, not two: the sweep, the eviction contract and the failure
directions are shared between the two limits, and splitting the file down the middle would have
produced a first commit that could not state its own invariants.

Review fixes (commit 633a8e6)

FIX A — non-finite now. sweep now clears both maps when now is not finite. Every
comparison in it is false for NaN, so an entry became immortal and the budgets then failed in
opposite directions: the pair limiter open by accident (retryAfterMs is NaN, and
decidePreProbe refuses on > 0), the fan-out cap closed forever once at the cap — a permanently
silent sender, the failure the header claims immunity from. NaN is the only value the line is
load-bearing for; +Infinity is dropped by the staleness arm and -Infinity by the future arm, so
!Number.isFinite vs Number.isNaN is an equivalent mutation (measured), and the test now says
that instead of claiming to pin it.

FIX B — isSafeNodeId at the boundary. resolveDeliveryScope refuses either id outside
[A-Za-z0-9._-], ahead of the self-send arm, as its own reason unaddressable-node-id rather
than cross-project — such an id can be listed in the sender's own project, so the scope word would
be a false statement about the reason (new member on NotPermittedReason; RETRYABLE is keyed by
outcome kind, so nothing else changes). This closes the separator collision in pairKey and the
v/1 vs v_1 tmux fold. Did the widened id set kill the separator mutation? No — and it could
not: with a NUL separator only a NUL-bearing id can collide, and no id in that 81-pair set can
contain one. The false green did move one layer down, exactly as the review said. It is now killed
by an explicit test that exhibits the collision (built with String.fromCharCode(0), so no escape
survives a file write) and then pins the validator that makes the premise true.

FIX C — the two false comments. Corrected in place, not coded around: the duplicate-id note now
says it is a routing answer and not an isolation guarantee (sessions key on the bare node id, so a
project.json listing another project's id lands in that node's one global pane), and records that
PR 5's delivery call must run isSafeNodeId(targetNodeId) before paneOwner. The
needsLiveCanvas rationale now names the right half: Canvas routes by SOURCE, so the declaration
stops a trip to the sender's project; never travelling to the target's is resolveDeliveryScope
having no live-node parameter. Both files cross-reference each other so PR 5 cannot inherit the
wrong model.

Also added: the fan-out floor's known cost (30 refused attempts before the backstop opens when
newTurn never arrives), and a note that ScopeProject.nodes is required — a synthesised array
without it throws rather than failing closed, which is the caller's to own.

Mutations after the fixes: the original 24 re-run and all still red; 8 new ones on the fixed
lines, 7 red (guard removed, guard clears only one map, validator removed, validator checks only the
source, only the target, reports cross-project, runs after the self-send arm) and 1 equivalent
(Number.isFinite to Number.isNaN), documented in the code rather than papered over. 31 killed,
1 equivalent, 0 survivors.

Tests: agent-message-flow.test.ts 33, agent-message-scope.test.ts 36,
controlRouting.test.ts 13, canvas-control-core.test.ts 25. Full run 6223 passed, same 4
environmental failures.

🤖 Generated with Claude Code