feat(agents): peer-to-peer messaging and idle notice (#16948, #16949)

[mrveiss]

Thinking Path

#16947 gave every agent kind a live, named presence entry with a busy/idle
signal but no way to reach another entry directly -- a peer could only be
observed, not addressed. #16948/#16949 add that address book and the two
things it needs to be safe: delivery that respects tenancy and turn
boundaries, and a push notice for the busy->idle transition so a waiter
doesn't have to poll presence.

The two hard calls, both made explicit in the assignment and carried through
here:

• A peer message is never human approval. protocols/peer_inbox.py
  delivers into a per-(kind, tenant_id, name) inbox with no side channel
  into any approval path. A sensitive tool call a peer message triggers goes
  through the exact same gate a human-triggered one does --
  AI_STACK's enforce_work_item_approval (already unconditional on every
  tool call, so it needed no new gating code) and SESSION's own
  approval_handler/assess_command_risk, unchanged.
• Delivery happens at the real per-turn boundary, not mid-task. The drain
  call sits at the one seam each kind's production callers all share:
  AI_STACK's chat_workflow/tool_handler.py::_dispatch_tool_call and
  SESSION's services/agent_terminal/service.py::execute_command -- the same
  seams mapped and confirmed for feat(agents): live presence — one registry of named agents with busy/idle state, across all three kinds #16947's busy/idle wiring, reused rather than
  re-derived. A message that arrives after one drain sits queued until the
  next.

protocols/idle_notice.py (#16949) is built on the existing events/bus.py
transport rather than a new one: AgentPresenceRegistry.report() now
publishes EVT_AGENT_IDLE on exactly a busy=True -> busy=False transition,
and wait_for_idle() is the one-shot subscriber -- resolves immediately for
an already-idle target, otherwise waits for one matching event or a bounded
timeout (AUTOBOT_IDLE_NOTICE_TIMEOUT_SECONDS), always unsubscribing.

What Changed

• protocols/peer_inbox.py (new): PeerMessageEntry, PeerInbox (deliver/
  drain), PeerInboxDirectory.send() -- addresses by the presence registry's
  own (kind, name), resolves the recipient's real tenant from the matched
  PresenceEntry (never from the caller), refuses when the name isn't live
  (RecipientNotAddressableError); EXTERNAL and UNKNOWN_TENANT are never
  reachable because list_live() never surfaces them.
• chat_workflow/tool_dispatch_guards.py: new enforce_peer_messages(ctx) --
  drains the chat AI_STACK inbox into ctx.context["peer_messages"], a
  no-op with no ctx.
• chat_workflow/tool_handler.py: _dispatch_tool_call calls the new guard
  first, alongside the existing six unconditional guards.
• services/agent_terminal/service.py: new _drain_peer_messages(session),
  called at the top of execute_command before command assessment; keys the
  inbox lookup by session.tenant_id or UNKNOWN_TENANT, mirroring
  sync_session_presence's own derivation exactly (a raw None key would
  silently miss anything send() actually authorized).
• protocols/idle_notice.py (new): notify_agent_idle() (fire-and-forget
  publish, safe no-op with no running loop), wait_for_idle(),
  IdleWaitExpiredError.
• protocols/agent_presence.py: report() now calls notify_agent_idle()
  on a busy: True -> False transition only.
• autobot_shared/env_registry_agent_runtime.py: registers
  AUTOBOT_IDLE_NOTICE_TIMEOUT_SECONDS (default 300s); docs/developer/ENV_VARS.md
  regenerated from the registry.
• New tests: protocols/peer_inbox_test.py (9), protocols/idle_notice_test.py
  (9), chat_workflow/peer_messages_dispatch_16948_test.py (4, including the
  AC4 mid-task-vs-next-boundary case), services/agent_terminal/peer_messages_dispatch_16948_test.py
  (5, including an execute_command-level integration test and the
  UNKNOWN_TENANT key-matching regression).
• scripts/python_file_size_known_large.py / repo_tests/python_file_size_ratchet_baseline.py:
  services/agent_terminal/service.py ceiling lowered 956 -> 951 (comment
  trimming offset the new drain call and helper).

Verification

PYTHONPATH="..:.:$PYTHONPATH" python3 -m pytest autobot-backend/protocols/ \
  autobot-backend/chat_workflow/peer_messages_dispatch_16948_test.py \
  autobot-backend/services/agent_terminal/peer_messages_dispatch_16948_test.py \
  autobot-backend/services/agent_terminal/running_command_task_busy_signal_16947_test.py \
  autobot-backend/chat_workflow/manager_is_processing_16947_test.py \
  autobot-backend/services/agent_terminal/session_manager_tenant_16975_test.py -q
# 63 passed

• python3 scripts/check_python_file_size.py --audit-ceilings -- 5563 files
  scanned, 488 grandfathered, all live and at size.
• python3 pipeline-scripts/check_env_var_registry.py -- exit 0.
• python3 -m black --check, isort --check, flake8, bandit -q on every
  changed/new file -- all clean.
• bash pipeline-scripts/detect-hardcoded-values.sh on every changed/new file --
  SSOT Coverage: pass (new=0, ...).
• detect-secrets scan (no baseline write) on every changed/new file -- no
  findings; .secrets.baseline unmodified.
• Local jscpd@5.0.6 reproduction of the duplication-guard's exact invocation:
  11718 duplicated lines, under the 11723 pin, unchanged from the pre-PR
  baseline -- no new duplication.
• Verified wait_for_idle()/notify_agent_idle() end to end against the real
  EventBus (not mocked): caught and fixed a real bug where the in-process
  listener payload is nested as {"type", "payload"} by
  EventManager.publish, which the first draft's listener didn't unwrap and
  would have silently never matched in production.
• Pre-push hook re-ran the touched-test set and confirmed green before this
  push.

Risks

• AI_STACK's busy signal (feat(agents): live presence — one registry of named agents with busy/idle state, across all three kinds #16947) is per-process, not per-role
  (ChatWorkflowManager is a lazy_singleton with no persistent per-role
  run), so a peer message can only be drained on the next inbound chat
  message for that process, not proactively woken -- tracked separately as
  decision(agents): should a peer message wake an idle AI-stack agent to start a new run? #16991 (needs-decision).
• COMPANY_OS is explicitly out of this PR's scope (no internal per-step seam
  exists in the heartbeat scheduler) -- tracked as feat(agents): deliver a peer message at the start of a Company OS agent's next heartbeat run #16992, blocked_by #16948.
• Message signing/HMAC (security(agents): authenticate agent-bus messages — a per-agent key issued at registration, HMAC on every message #16962) and delegation/authority files (fix(security): a delegated agent inherits its parent's authority; the originator survives relays (#16950) #16966,
  fix(security): A2A trust keyed on the verified pair, capabilities enforced where they apply (#16957, #16950) #16969) are out of scope by explicit instruction.

Model Used

Claude Sonnet 5 (claude-sonnet-5)

Issue Link

Refs #16948

Changelog fragment

• Added changelog/unreleased/16948-16949-peer-messaging.md

Checklist

• Tests added/updated
• Docs regenerated where applicable (ENV_VARS.md)
• No hardcoded values, no secrets, no new duplication (see Verification)
• File-size ratchet respected (lowered, never raised)

🤖 Generated with Claude Code

Single-issue rationale

This PR closes no issue yet. #16949 (the idle-notice half) has been split
out into #17015, which lands independently. #16948's own send side is
blocked by #16986 (protocols/agent_communication's consolidation, per
the review's "consolidate, never fork" ruling on peer_inbox.py) --
tracked as a blocked_by edge on issue #16948. This PR stays on Refs
until #16986 lands and an end-to-end test through the real transport
passes.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• main
• release

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 31f26a5f-1dc7-4cff-bd11-9a47e4f1e662

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mrveiss]

Code-reviewer pass complete. One HIGH finding, fixed:

AI_STACK peer-message drain was hardcoded to "chat"; "rag"/"system_commands" silently lost messages. sync_ai_stack_presence (#16947) reports every AgentHealthRegistry role as its own addressable AI_STACK presence entry, but only "chat" has a drain wired at chat_workflow/tool_dispatch_guards.py::enforce_peer_messages -- rag_agent.py/system_command_agent.py run their own StandardizedAgent.process_request flow, unrelated to that seam. send() succeeded for "rag"/"system_commands" (they're live in presence) but nothing ever drained their inbox -- silent message loss, not even a refusal.

Fixed in 4d831776b: PeerInboxDirectory.send() now refuses any AI_STACK name outside {"chat"} with RecipientNotAddressableError, so misaddressing fails loud instead of losing the message. Filed #16997 (sub-issue of #16946) to map rag_agent.py/system_command_agent.py's own real turn boundary and lift the restriction once wired -- that's a separate seam-mapping exercise, the same shape as #16992's for COMPANY_OS, not a same-PR fix.

Everything else the review checked out sound: the recipient-tenant-key resolution in send(), the report() lock/notify race, and the EventManager payload-unwrap in idle_notice.py's listener (all three were things caught and fixed during development, and the review independently confirmed each is correct). One LOW/observational note (pre-existing PersistStrategy.NONE channel fan-out behavior, not introduced by this PR) needs no action here.

Re-verified after the fix: 64 tests passing, file-size ratchet clean (--audit-ceilings), duplication unchanged at 11718/11723, black/isort/flake8/bandit clean, no secrets, no new hardcoded values.

[github-actions]

Notice: 29 open PRs — past the runaway threshold (25)

There is no PR queue limit, and this is not a request to defer this PR. Work proceeds one issue at a time without a cap on open PRs; review capacity is the constraint.

This notice only means the count is high enough to be worth a glance for a runaway — something opening PRs in a loop, or a merge pipeline that has stalled so nothing is draining.

Currently open:

• fix(hooks): use stdin JSON instead of $TOOL_ARGS in settings.json hooks (#17024) #17044 fix(hooks): use stdin JSON instead of $TOOL_ARGS in settings.json hooks (Suspected dead hooks in .claude/settings.json: $TOOL_ARGS may not be a real env var #17024)
• security: guessable-default fixes for #16299 (baseline-reasons guard, generate-on-first-run secrets) #17037 security: guessable-default fixes for security: guessable default credentials ship in templates, ansible defaults and the compose file #16299 (baseline-reasons guard, generate-on-first-run secrets)
• chore(hooks): track the commit-msg hook, install it, and enforce the subject convention (#17029) #17032 chore(hooks): track the commit-msg hook, install it, and enforce the subject convention (commit-msg hook should reject a subject with no issue reference #17029)
• fix(ops): long-running operations — create works and records its creator, creator-or-admin access, the panel reads real data, unimplemented starts answer 501 (#17017) #17027 fix(ops): long-running operations — create works and records its creator, creator-or-admin access, the panel reads real data, unimplemented starts answer 501 (long-running: the four start routes cannot create an operation — create_operation gets estimated_items/context it does not accept (TypeError → 500) #17017)
• fix(security): authenticate nine WebSocket endpoints before accept, owner-scope the overseer and workflow sockets, admin-only /api/long-running (#17009, #17010) #17018 fix(security): authenticate nine WebSocket endpoints before accept, owner-scope the overseer and workflow sockets, admin-only /api/long-running (security(ws): nine WebSocket endpoints accept without authentication — PTY execution, workflow control and KB writes among them #17009, security: /api/long-running has no authentication — anyone can start test runs, scans and KB population, or cancel any operation #17010)
• security(kb): re-scope #16985 to a guard -- every connector already reaches store_fact #17016 security(kb): re-scope security(secrets): wire credential redaction into the remaining 11 KB connectors (#13708 follow-up) #16985 to a guard -- every connector already reaches store_fact
• feat(agents): one-shot idle notice (#16949) #17015 feat(agents): one-shot idle notice (feat(agents): subscribe once to be told when a peer is next idle #16949)
• feat(ci): add an open-PR cap to the pre-push gate (#17006) #17008 feat(ci): add an open-PR cap to the pre-push gate (Open-PR cap: refuse new-branch pushes at/above AUTOBOT_OPEN_PR_CAP (default 40) #17006)
• security(websocket): authenticate /api/intelligent_agent/stream before processing (#17000) #17003 security(websocket): authenticate /api/intelligent_agent/stream before processing (security(websocket): /api/intelligent_agent/stream runs agent goals with no authentication — an unauthenticated bypass of POST /process #17000)
• fix(agents): the peer channel delivers to the recipient, not the sender; broadcast reaches every other agent (#16986) #17001 fix(agents): the peer channel delivers to the recipient, not the sender; broadcast reaches every other agent (agents: the peer channel never delivers to the recipient — a request lands in the sender's own inbox and the sender answers itself #16986)
• fix(test): give result.metadata a real dict in 3 multimodal perf/scalability mocks (#16990) #16995 fix(test): give result.metadata a real dict in 3 multimodal perf/scalability mocks (bug(test): 3 multimodal performance/scalability tests fail — metadata Mock lacks __setitem__ since #15234 #16990)
• feat(auth): SLM API keys only on declared routes, 403 elsewhere, every key request audited; main backend accepts none (#16040, #16294, #16999) #16989 feat(auth): SLM API keys only on declared routes, 403 elsewhere, every key request audited; main backend accepts none (API key scopes are stored and displayed but never enforced — keys inherit full user authority #16040, feat(auth): decide which routes accept API keys, and wire X-API-Key through the #16040 mechanism #16294, docs(api): the public API docs tell integrators to send a user API key to the main backend, which accepts none #16999)
• fix(ci): bump the mcp CI floor mirror to match the backend's declared floor (#16449) #16983 fix(ci): bump the mcp CI floor mirror to match the backend's declared floor (chore(mcp): autobot-backend/mcp/ shadows the real mcp PyPI SDK, making it unreachable by name #16449)
• fix(deploy): enable rendered nginx sites on self-update, not just full provision #16980 fix(deploy): enable rendered nginx sites on self-update, not just full provision
• feat(agents): capture a terminal session's tenant at creation (#16975) #16978 feat(agents): capture a terminal session's tenant at creation (feat(agents): capture a terminal session's tenant at creation — it cannot be recovered afterwards #16975)
• feat(security): bound every Company OS run by its org role, per adapter (#16950) #16974 feat(security): bound every Company OS run by its org role, per adapter (security(agents): an agent refused an action can get another agent to do it — no per-peer identity #16950)
• fix(deploy): the user-frontend build sites publish through a staged swap (#15603) #16970 fix(deploy): the user-frontend build sites publish through a staged swap (bug(deploy): the user-frontend build sites still publish their own failures, and three SLM build sites sit outside the shared staged publish #15603)
• fix(security): A2A trust keyed on the verified pair, capabilities enforced where they apply (#16957, #16950) #16969 fix(security): A2A trust keyed on the verified pair, capabilities enforced where they apply (security(a2a): three of four trust-matrix capabilities are enforced nowhere — a level that denies them denies nothing #16957, security(agents): an agent refused an action can get another agent to do it — no per-peer identity #16950)
• fix(security): a delegated agent inherits its parent's authority; the originator survives relays (#16950) #16966 fix(security): a delegated agent inherits its parent's authority; the originator survives relays (security(agents): an agent refused an action can get another agent to do it — no per-peer identity #16950)
• feat(agents): live presence registry, one query across all three agent kinds (#16947) #16965 feat(agents): live presence registry, one query across all three agent kinds (feat(agents): live presence — one registry of named agents with busy/idle state, across all three kinds #16947)
• feat(agents): wire QuotaHeadroomStore's read side, add provider/cpu/queue claim kinds (#16951) #16964 feat(agents): wire QuotaHeadroomStore's read side, add provider/cpu/queue claim kinds (feat(agents): coordinate agents competing for shared resources — API limits, CPU time, queues #16951)
• fix(infra): gate doc-sync to main-at-origin-tip, move it off post-commit (#16934) #16959 fix(infra): gate doc-sync to main-at-origin-tip, move it off post-commit (bug(kb): the doc-sync commit hook re-embeds every doc into the live KB from any worktree, because its hash cache is per-checkout #16934)
• test(security): a delegated subagent runs a write its parent is held from (#16950) #16958 test(security): a delegated subagent runs a write its parent is held from (security(agents): an agent refused an action can get another agent to do it — no per-peer identity #16950)
• test(security): the ungated-router list may only shrink, so a new entry fails (#16375) #16955 test(security): the ungated-router list may only shrink, so a new entry fails (security(api): 44 config-registered routers declare no auth gate, triaged by exposure (found by widening the router-auth guard, #16368) #16375)
• fix(multimodal): the response says whether a result was stored, and if not, why (#16926) #16954 fix(multimodal): the response says whether a result was stored, and if not, why (bug(multimodal): a tenancy-refused write still returns HTTP 200 success — the persisted flag has no consumer #16926)
• fix(tests): prune SKIP dirs during the walk, not after rglob returns (#16601) #16952 fix(tests): prune SKIP dirs during the walk, not after rglob returns (ci(python-suite): intermittent hang in shard 10 — one of the 223 modules it runs on main (hit #16284 and batch 2b) #16601)
• fix(admin): add the missing adminMenuItems entries for pricing/mcp-servers (#16933) #16944 fix(admin): add the missing adminMenuItems entries for pricing/mcp-servers (bug(admin): the MCP-servers and pricing admin screens merged unreachable — no admin menu entry #16933)
• security(websocket): every authenticated WebSocket echoes the bearer subprotocol through one helper (#16457) #16939 security(websocket): every authenticated WebSocket echoes the bearer subprotocol through one helper (security(websocket): auth token travels in the URL query string, not a header/subprotocol #16457)
• fix(ci): chain formatter dispatch after the branch guard in pre-commit (#16923) #16938 fix(ci): chain formatter dispatch after the branch guard in pre-commit (ci(hooks): no local hook runs black/isort/ruff — formatting is first checked in CI #16923)

If the queue is draining normally, ignore this. Otherwise:

1. Check whether CI is dispatching at all — see the ci-dispatch-watchdog status on these PRs
2. Merge the ones whose CI has finished and review has passed: gh pr merge <number> --squash --delete-branch
3. Look for a loop opening near-identical PRs

Warn-only runaway detector — .github/workflows/pr-queue-gate.yml. It never blocks a merge.