Issue for this PR

Closes #38965

Related to #19215 (agent-to-agent communication primitives). Not "Closes" — this is an experimental, flag-gated primitive.

Re-submission of #32693, closed by the automated cleanup bot on 2026-07-17 while still active. The branch has been force-pushed since (rebased onto current dev), so GitHub refuses an author-side reopen — same situation as #35195. No maintainer decision was involved in the closure.

Stacked PR. This branch sits on top of three PRs: #38942 (message tool) → #32425 (subagent interrupt) → #38943 (coordinator-messaging) → this. The diff therefore shows the whole stack, but only the top commits (packages/opencode/src/s2s/*, the s2s tool, the DB tables, the poller/drain wiring) are new here. Review most easily against #38943, or wait until the base PRs land. The four together are a family of messaging primitives: subagent↔parent (#38942), interrupt (#32425), sibling↔sibling (#38943), and session↔session (this one).

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Lets two separate top-level sessions — different windows / OS processes on the same machine — send each other messages. This is distinct from the subagent primitives in the base PRs: there is no parent/child relationship, so the two sides opt in with an explicit mutual-consent handshake first. Gated behind OPENCODE_EXPERIMENTAL_S2S (off by default).

A new s2s tool drives it: invite mints a one-time 10-minute token; the peer runs accept with that token (shared out-of-band), which writes a durable bidirectional consent record; then either side runs msg to send. Peers are addressed by their globally-unique session_id (ses_…), never by slug — slugs are not unique. leave tears the pair down.

How a message actually gets from one process to the other:

• Send persists a versioned capsule row to a new s2s_inbox table in the shared opencode.db (tables: s2s_inbox durable mailbox, s2s_token one-time invites, s2s_allow directional consent).
• Receive has two halves. A session actively taking a turn drains its inbox at the runLoop turn boundary (in-context). An idle session is woken by a small per-instance poller (~2s) that claims its rows and starts a loop to drain them. Delivered rows are hard-deleted; a 60s reaper reopens any row claimed by a process that crashed before draining. Incoming messages render in the recipient transcript as an external-context frame tagged source="sibling-session", and are treated as untrusted input (attributes escaped at the sink).

Why the receive path is built the way it is (the non-obvious part): the messaging/poller services are per-instance — they resolve through a request-scoped context reference that is only present inside a live request/run fiber. An earlier version forked the poller at layer-build time, where that reference is absent, so it died on its first tick and the entire recipient path was silently dead in a real process while every unit test passed (the tests inject the context). The fix is to (a) drain in-context at the runLoop boundary, and (b) lazily fork the per-instance wake-poller from inside SessionPrompt.loop, capturing the live fiber's context — plus making the S2SStore service a direct member of the prompt-serving layer groups so a serviceOption lookup in the forked fiber actually finds it. No service was made process-global.

Addressing by session_id (not slug) is deliberate: session.slug has no uniqueness guarantee — an earlier draft added a UNIQUE index on it and that broke new-session creation on a real DB once the small random-slug space saturated. Slugs stay as parent-owned handles for the subagent primitives only.

How did you verify your code works?

• Live two-process test (the real gate — unit tests structurally can't cover cross-process delivery): two opencode windows, shared DB, invite/accept handshake, then messages both directions. Confirmed at the DB level — consent rows written in both directions, capsule persisted, and the row hard-deleted on delivery on each side; the reply surfaced in the recipient's context as a source="sibling-session" frame. Both halves exercised, including waking a fully idle peer.
• Automated suites: the test/s2s directory (store, poller, capsule, lifecycle, frame-escaping, the cross-process topology repro, and an in-process fork repro pinning the per-instance-context behavior), plus the messaging/coordinator/interrupt suites it shares files with — green locally. bun typecheck clean on the s2s surface (the repo's pre-existing mcp/catalog.ts errors on dev are unrelated).
• Pre-merge review council (independent, cross-family): found 4 must-fix items incl. 2 security (an unescaped attribute sink, and leave not revoking cross-process consent), all fixed and re-reviewed clean.
• Since the original submission this branch has been rebased onto current dev three more times, each with the full suite re-run. One fix landed in that window: several test/s2s files shared Effect's process-global memoMap across files, so a router registered by one suite leaked into another and produced order-dependent failures. A testEffectIsolatedShared helper now allocates a file-local MemoMap, keeping intra-file service identity without the cross-file leak.

Screenshots / recordings

Minor TUI surface (an inbox marker line in the transcript + a session-list tweak), reusing the marker render path from #38942.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR (the only "extra" content is the three base PRs this is stacked on — see the note at the top)