feat(agents): the send, reply and notify verbs

[eneskirca]

PR 5 of the agent-messaging series: the send, reply and notify verbs, wired end to end through the delivery primitive (#207), flow control (#208) and the paste-buffer transport (#210). The verbs are live but fail-closed: every delivery is additionally gated behind the per-project agentMessaging switch (off by default, shipped by PR 6), so nothing changes for any project until its owner opts in.

Task → commit map

Task 5.1 — send/reply, verified-only from day one → feat(control): send/reply — verified-only, with no override and no legacy path

• requiresVerified in hook-server.ts, checked on the token verdict before identityGate's decision is consulted: the foreign-kid escape (an invented kid is FOREIGN → legacy, invariant 3) defeats the latch and the dated window but never this, and settings.hookIdentityStrict: false releases neither. Flat named refusal, no token/restart advice.
• Canvas.tsx handles the verbs before its source-routing machinery — they are store-answered (needsLiveCanvas false, pre-provisioned), so a background orchestrator can never travel the human's view or clear an unread badge (G5) — and wraps the delivery in guardConcurrentRestart.
• New main-side service (src/main/agent-messaging.ts) is the one caller of deliverAgentMessage: scope off the serialized store (isSafeNodeId first), the switch, checkFlowLimits (budget consumed only by a write that reached the pane), the deps record, the trace through the same board-log router as the IPC handler, and a rendered reply whose retry advice is sourced from RETRYABLE in words.
• Transport: the envelope stays composed by bracketedInjection in core and is moved byte-for-byte by a new framed paste plan (load-buffer stdin → gated copy-mode cancel → paste-buffer -d -r, no -p, no separate Enter) on both the local and SSH legs; assertFramedPayload makes the one unsanitized path refuse anything that is not bracketedInjection output. agent-message.realtty.test.ts now drives this exact plan against a real tmux and a real paste-aware bash. The #{bracket_paste_flag} probe is not reintroduced (fix(tmux): let tmux frame the paste, removing the 3.7 version floor #210's deleted-note stands); the residual is recorded as a TODO at the wiring site.

Task 5.2 — fold in #98's notify, with credit → feat(control): fold in #98's notify — app-owned text, through the one delivery path

• feat(canvas): add linked agent inbox notifications #98 (@parsa222) is superseded, not rejected: the verb, its --node requirement, its exact --text refusal and its 10-second pair throttle (now PAIR_MIN_INTERVAL_MS, shared with send/reply) survive. The body is substituted in main (NOTIFY_BODY) so even a forged IPC request cannot put caller text into the envelope — "the app owns the entire prompt" is now enforced at the boundary, and delivery goes through the identical verified-only, switch-gated, idle-gated pipeline. feat(canvas): add linked agent inbox notifications #98's "configured inbox" wording is dropped (no such product concept); the note points at the linked context instead.

Task 5.3 — the Server Edition's NAMED refusal → test(server): the messaging verbs inherit the NAMED edition refusal — proven on the wire

• The mechanism itself already shipped on main (623b09c, shared with the browser-control work by agreement — one string, one mechanism): /control/* answers 400 control-unsupported-on-this-edition with the literal "do not retry". This PR adds the messaging-plan half still owed: wire-level proof that /control/send gets that refusal for a verified caller, that an unverified send is refused on identity first (also terminal, also not an invitation to retry), and the docs/SERVER.md paragraph naming the interaction.

Task 5.4 — the shim's positional mapping and the skill text → feat(skill): document send/reply and which outcomes are worth retrying

• send|reply join the shim's bare-positional list (proven under real sh, not by grepping the script); --text required by the parser; both agent-facing texts document the verbs, the envelope, and the receiving convention the envelope module said PR 5 owed (only the OUTERMOST frame is authentic). The retry table is rendered from RETRYABLE — and the budgets from PAIR_MIN_INTERVAL_MS/FANOUT_PER_TURN — never re-typed, with a test walking the real table against the text.

Gates

npm run typecheck clean; full npx vitest run: 457 files / 6305 tests passed, 0 failed (including the real-tmux/real-pty suites on this host's tmux 3.4). Every new test was mutation-checked: the verified-only gate (deleted, and rewired through the overridable policy), the switch, noteSent's placement, the framed plan's byte-for-byte body, the no-sanitize refusal, the notify body substitution, the RETRYABLE rendering and the shim glob were each reverted and observed red.

Review round 1 (adversarial review: spec pass, quality changes-required — both findings fixed in 769ae11)

• C1 (fixed): src/main/agent-messaging.test.ts carried a raw NUL byte (the unaddressable-node-id test), so git rendered the whole 15-test service suite as "Binary files differ" and grep/ripgrep skipped it — the 4c0e8c3 trap. The byte is now the \x00 escape; the file diffs as text (327 added lines in this PR's range) and the suite is unchanged.
• I2 (fixed): the per-turn fan-out cap was bypassable by concurrency — checkFlowLimits (read) and noteSent (post-write) were not atomic and every lock is per-target, so N parallel sends to N distinct targets all passed the cap before any recorded. New reserveFlow() checks both budgets and takes a provisional hold in one synchronous step; the hold is released in finally, so refused deliveries still cost nothing. Five core unit tests + a service test firing FANOUT_PER_TURN + 3 concurrent sends at distinct targets (cap asserted at the pane); mutation-checked in both layers (pending-count dropped, and service reverted to the bare read — each red).

Concerns carried forward

• I1 (recorded, deliberately not fixed here): bracketPasteRequested: () => true leaves targetNotPasteAware unreachable in production — forced by fix(tmux): let tmux frame the paste, removing the 3.7 version floor #210's do-not-reintroduce note on the #{bracket_paste_flag} probe. The per-CLI DECSET-2004-at-idle measurement is a gate for PR 7: before the deliver-on-idle queue relies on delivery, measure whether each supported CLI requests bracketed paste at its idle prompt, and either restore a reachable targetNotPasteAware refusal or remove the dead outcome from the agent-facing text. PR 7's implementer inherits this (TODO at the wiring site in src/main/agent-messaging.ts).
• The verbs remain fail-closed behind the per-project switch until PR 6 lands the validated agentMessaging === true read.

🤖 Generated with Claude Code