Peer talk v2: make co-resident sessions actually converse

[cursor]

Why this exists

#469 shipped the floor: a worktree JSONL room, a device room, peer_message, /tell, /peek, a presence note when the live set changes, and a one-shot collision gate that tells the model to speak before mutating a shared tree.

That is presence plus a mailbox. It is not a conversation. Two sessions in the same folder can post past each other, the model is still told it can target "all" (it cannot), injected peer lines look like the human spoke, and the TUI has no /tell or /peek at all.

This issue is the speech half of #469. Do not reopen device-wide model "all" — that was retired because it flooded every folder on the box.

What is already true (so we do not rebuild it)

• Wire: append-only JSONL rooms in src/presence_chan.zig. Worktree room is a room (every live session on that tree hears every line). Device room is folder-scoped (deviceHears). to is addressing metadata, not an inbox.
• Model tool: peer_message in src/peer_channel.zig, wired through src/schema.zig / src/agent_tools.zig. One-way. Tool result only confirms the post.
• User REPL: /tell <session|all> <text>, /peek <session> in src/commands_misc.zig.
• Delivery: deliverInbound at every step boundary of agent.runTurn (src/agent.zig). Mid-stream interrupt is Input inversion (Phase 1b): approvals, pickers, mid-turn asks, Esc ownership, readline queries #430 and stays a sibling, not a prerequisite.
• Collision: one-shot pause in src/presence.zig before a mutating tool on a shared tree; the model is told to peer_message first.
• Tests: src/peer_channel.zig unit tests + scripts/test-pty-peer-channel.py.

What is wrong today

1. The docs lie

• tool_schema still documents "all" as a valid to.
• handleMessage rejects "all" (error.BroadcastRetired).
• The presence note (peerNoteIfChanged) still says peer_message to "all" or a name… reaches every session. That is false for the model.

A model that follows the note will get a tool error on the first attempt. That is the cheapest regression and the first slice.

2. One-way firehose, no conversation

There is no reply thread, no ack, no "did they hear." The sender's tool result is "posted." Delivery happens later, at the receiver's next step boundary. The sender never learns that.

/peek is user-only. The model cannot ask what a peer is doing; it only gets a presence list when the set of live sessions changes, not when a peer starts a long bash or finishes a turn.

3. Injected as role: user

Inbound peer lines are stuffed into history as a user message ([peer message from X]: …). Compaction, cache, and /peek all treat that as the human. /peek already special-cases the [peer message prefix to skip it — that is a smell, not a protocol.

4. Room vs DM is easy to confuse

Worktree room: everyone on the tree hears every line; to is rendered, not enforced.
Device room: to is enforced (deviceHears).
Same tool, two topologies. Nothing in the prompt explains the difference in one sentence the model will keep.

5. TUI is missing the verbs

TUI/catalog.zig has no /tell or /peek. A TUI session can be told (delivery still runs) but the human cannot speak or inspect from the pager.

6. Targeting is a substring

Session-name / pid match. Ambiguous names error. No stable id the model can hold across turns. A rename or a second graff in the same folder breaks the address.

7. No structured claims

The collision gate asks the model to talk, then hopes free text is enough. There is no locking src/foo.zig the gate can parse, so two models can both "announce" and both edit.

8. Backlog is a wall

backlog_tail_max = 10. REPL /peek shows the last 2 user lines. No threads, no fork, no "since I last looked."

What "better" means (acceptance, not vibes)

A pair of sessions on the same worktree should be able to:

1. See who else is live, and a one-line "what they last did" without the human /peeking.
2. Say something to a named peer (or the room) and get a tool result that distinguishes posted from heard at the receiver's next step.
3. Hear inbound speech as a first-class channel event, not a fake user utterance. /peek and compaction must not treat it as the human.
4. Do that from the TUI with the same /tell / /peek the line REPL already has.
5. Not be lied to by the schema or the presence note.

Out of scope for this issue: mid-turn preemption (#430), a full Slack-like pane, device-wide model broadcast.

Proposed slices (ship in this order)

Each slice should land with tests that zig build test actually reaches (src/main.zig and/or TUI/root.zig import). Suite count goes up. Hand-written files stay ≤ 600 LOC.

Slice A — tell the truth (small, do first)

• Drop "all" from peer_message schema. Document worktree-room vs device-room in one sentence.
• Rewrite peerNoteIfChanged so it matches handleMessage. Name the live peers. Do not mention "all".
• Stop putting #469 in user-visible strings ([#469 presence], "issue Session presence + inter-session channel: co-resident graffs on one device talk to each other (cloud relay later) #469"). The issue number is for us, not the model.
• Keep user /tell all (human broadcast is still valid).

Slice B — TUI /tell and /peek

• Same verbs as src/commands_misc.zig, wired through TUI/catalog.zig + the TUI command path.
• Drive with TUI/sim.zig Term (no PTY, no Ghostty window). Assert the catalog lists them and a /tell from the pager appends a room line the other session would hear.

Slice C — typed channel events

• Stop injecting peer speech as role: user.
• Engine event + a history representation that is not the human (dedicated prefix/role the compact/peek paths already understand).
• Update /peek to show peer lines as peer lines, instead of skipping the prefix as if it were noise.

Slice D — peer_peek (or a richer presence note)

• Model-callable: live peers + last user prompt + last tool name + last peer line they sent.
• Reuse summarizeTranscript / the same fields /peek already walks. Do not invent a second transcript parser.
• Presence note can stay as the "set changed" ping; peer_peek is "what are they doing right now."

Slice E — ack / thread id

• Optional in_reply_to on peer_message.
• Sender tool result: posted vs delivered (delivered = receiver crossed a step boundary and deliverInbound ran).
• Enough to stop "I told them, why are they still editing."

Later (own issues once A–E exist)

• Mid-turn inject (Input inversion (Phase 1b): approvals, pickers, mid-turn asks, Esc ownership, readline queries #430).
• Structured lock claims the collision gate can parse (path + intent), so two announces cannot both proceed.
• TUI peer pane (live list + last line), not just slash commands.
• Stable session ids that survive a rename.

Files that will move

• src/peer_channel.zig, src/presence.zig, src/presence_chan.zig
• src/schema.zig (and python3 sdk/generate.py --harness ./zig-out/bin/graff after)
• src/commands_misc.zig, TUI/catalog.zig, TUI command dispatch
• src/agent.zig (deliverInbound call sites — do not change timing until Input inversion (Phase 1b): approvals, pickers, mid-turn asks, Esc ownership, readline queries #430)
• scripts/test-pty-peer-channel.py + new TUI/sim.zig cases

Non-goals

• Replacing the JSONL room with a socket/dbus/server.
• Letting the model broadcast to every folder on the device.
• Building a chat product. This is two agents in one tree not stepping on each other.

Related

• Session presence + inter-session channel: co-resident graffs on one device talk to each other (cloud relay later) #469 — presence + channel (shipped). This is the follow-up.
• Input inversion (Phase 1b): approvals, pickers, mid-turn asks, Esc ownership, readline queries #430 — mid-generation inbound (sibling; do not block A–E on it).

[justrach]

Follow-up after looking at how the inject actually lands in history and how compact treats it.

The other half of "better talk": a working set, not a firehose

Slice C/D/E make speech richer. That is also how you drown the model. A co-resident session that talks every step currently appends a new role: user blob at every deliverInbound, and that blob lives until generic compaction. Compaction then treats it as the human: cleanUserTurn is true, so recentContextStart will keep the peer firehose in the ~8k verbatim suffix (and summarize the real user prompt away), and emergencyCutIndex can restart the conversation on "hold off gui/src".

We already measured this once. presence.drainChannel seeks -p one-shots to the tail because ~4k tokens of stale chatter on the first step made ephemeral workers answer old messages and burn turns on coordination theater. Interactive sessions still dump up to backlog_tail_max = 10 lines into history (the REPL only shows 2).

The room JSONL is the log. History should not be a second copy of the log.

Why you cannot just delete

Peer lines sit in the same array as the real conversation. Careless removal:

1. Prompt cache. Deleting a message in the middle busts the prefix the provider already cached.
2. Replied-to inbound. If the assistant already turned after a peer note, mutating that note rewrites the past — the reply no longer matches what it answered.
3. Pending inbound. If the last message is a peer inject (compact between step drain and the model's reply), dropping it eats a message nobody has heard yet.
4. Live claims. "I"m locking src/foo.zig" is perishable and load-bearing until the peer is gone or the collision gate fires again. There is no structured claim to keep yet (that is the later lock-claim issue). The gate stays the safety net; we do not invent a parser in this slice.
5. Pairing. Never splice out a peer line from between a function_call and its output. We only drop whole user-role injects.

So: do not surgically edit live history. Forget at compact (the prefix is already invalid). Stub/drop only spent injects (something already followed them). Keep a trailing unreplied inject even if the whole history was summarized.

Slice F — context budget and careful forget (do with C, not after a richer protocol)

This has to land before we add peer_peek / threads / acks, or those will just write more durable user turns.

Inject less

• First-drain history tail matches the working set (history_tail_max = 3), not the room (backlog_tail_max = 10). REPL show-count stays 2. The omitted count is one marker, not the missing lines.
• Byte-cap the inject blob (~800). Clip each line. The tool already asks for one or two sentences — enforce it on the receiving side too.
• Presence note is a roster (who, goal, where), not a coordination essay, and it must not mention "all" (Slice A). Re-inject after compact is correct: that is how the roster survives a rewrite. It must stay one short line, not a re-dump of the room.
• -p tail-seek stays. Unattended sessions must not replay the room.

Forget at compact, not mid-turn

• cleanUserTurn is false for peer injects (including [#469 presence] / [presence] / [peer message…]). Emergency trim and recentContextStart may only cut/keep at a human user turn.
• dropPriorTurnReasoning uses the last real user turn, not a peer ping — otherwise a mid-history inject becomes the fence and we drop the Responses reasoning the API still needs.
• The summarizer never sees peer injects (strip them from summary_messages). persists_note says so: do not transcribe [peer message] lines; the harness drops them.
• The kept ~8k suffix drops spent peer injects (an assistant/tool/user turn already followed them) and keeps a trailing unreplied one.
• durableState restates the live peer roster from the presence registry (who is here now), not quoted speech. The JSONL room on disk is the greppable log, same honesty rule as Post-compaction note: tell the model what durable state survived (files, goal, todos, transcript) #411.

Not in this slice

• /forget peers (nice later; compact is the forget).
• Stubbing spent lines in live history (cache-bust every step). Same shape as Codex/gpt-5.x sessions brick near the context cap: compaction WriteFails (sends full over-cap history) and emergency-trim can't recover a tool-churn history #163, but only worth it if a long session talks more than compact runs.
• Structured lock claims (own issue, after E).

Acceptance

• A first drain of 10 room lines puts at most 3 in history.
• cleanUserTurn("[peer message from x]: hold") is false; an emergency trim whose midpoint is that line cuts at the next real user turn (or refuses), never starts the conversation there.
• Compact of a history that is mostly peer injects does not ask the summarizer to hoard them, and does not drop an unreplied trailing inject.
• After compact, the handoff’s durable note names live peers when any exist, and does not paste old [peer message] bodies.
• Suite count goes up; peer_context.zig is in the test root.

This is the dual of "make them converse": they have to be able to stop conversing in context, or the conversation is just another tool-output leak.

[justrach]

Exact ping, not a standing liaison

The ask was: ping the one agent that is doing the work, or keep a continual subagent whose only job is to ping others and that is idle until needed.

A standing liaison is the wrong shape:

1. Children never hear the channel. deliverInbound returns on root.sub. A subagent cannot be the mailbox without a new runtime.
2. Idle still costs. A looper that clock_sleeps or polls is another model in the room (ADR 0004). "Only active when needed" is a wake, not a parked process.
3. The collision gate already wakes the root when two sessions share a tree. That is the on-demand moment. Spawning a third agent there is a full extra turn to do what peer_message already does.

What we want instead: a named ping is a real DM, and you can name the peer by what they are doing.

• Bare peer_message = this folder's room (everyone here).
• session set = DM. Only that session injects it. Bystanders get silence (the JSONL still has the line).
• session resolves in order: exact id, pid, unique name fragment, unique goal fragment — so you can ping peer_channel and hit the session whose goal is "rewrite the peer_channel targeting".
• Tool result returns the resolved id (Re-ping with session="session-aaa") so the next ping is exact.
• A DM's inbound hint is reply with peer_message session="their-id", not "everyone here hears it".

That is "only active when needed": the main agent talks when it has something to say; nobody else pays for it; there is no third model sitting in the room waiting.

A later one-shot liaison spawn on the collision gate (tiny prompt, dies after one ping) is still on the table if the root model keeps refusing to call peer_message. It should not be a continual process.

[justrach]

Closing: the leftovers that were actually broken now work.

• Slice A — schema / collision gate already refused model "all". The remaining lie was the 0.0.244 changelog treating peer_message and /tell as the same broadcast. Fixed on TUI /tell and /peek use the existing peer mailbox (#563 leftovers) #648.
• Slice B — TUI /tell and /peek are in the catalog and /help, and they post through the existing mailbox (tellCommand / peekCommand), not a second channel. TUI /tell and /peek use the existing peer mailbox (#563 leftovers) #648.
• Pull / forget — ADR 0004 already on main: one-line [peer] wake, bodies in the inbox, compact does not treat injects as the human. That is the Slice C/F working set, not a new protocol.

#469 is the floor and was already closed. Not reopening model "all".

Left for their own issues if we want them later: model peer_peek (D), posted-vs-delivered / in_reply_to (E), mid-turn inject (#430), structured lock claims.