Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
29.7 KB
Raw Blame
//! The #469 channel half: what co-resident root sessions SAY to each other,
//! on top of what presence.zig knows (WHO is out there, liveness-probed).
//!
//! Claude-style pull (token-maxxing): history does not eat the room. Bodies
//! park in peer_inbox.zig; the model reads them with `action=inbox` and
//! discovers who is live with `action=list`. deliverInbound injects a
//! one-line `[peer]` wake and still paints the full lines for the human.
//!
//! Surfaces:
//!   - peer_message: send (default), list, inbox, claim, release, handoff, status.
//!   - /tell <session> <text>: the user's own line into a peer's inbox.
//!   - /sessions: the saved-session list gains a "live now" section.
//!   - deliverInbound: drain + park at every root step boundary. The human
//!     tally paints there (#469). The history wake waits until idle (#1136).

const std = @import("std");

const Io = std.Io;
const Allocator = std.mem.Allocator;

const agent_mod = @import("agent.zig");
const tools_mod = @import("tools.zig");
const engine_sink = @import("engine_sink.zig");
const presence = @import("presence.zig");
const presence_chan = @import("presence_chan.zig");
const worktree_lease = @import("worktree_lease.zig");
const repl = @import("repl.zig");
const peer_context = @import("peer_context.zig");
const peer_inbox = @import("peer_inbox.zig");
const peer_target = @import("peer_target.zig");
const peer_idle = @import("peer_idle.zig");

const Agent = agent_mod.Agent;
const ToolCall = tools_mod.ToolCall;
const ExecResult = tools_mod.ExecResult;
const Owner = worktree_lease.Owner;

pub const tool_name = "peer_message";
pub const tool_desc = "Ping a co-resident session, list who is live, read parked inbound, direct one as supervisor, or transfer an artifact claim. action=list | inbox | send (default) | direct | claim | release | handoff | status. session is a DM (visible title, saved-session base, id/pid/name/goal); omit for this folder's room (send only). Presence is device-local. Not \"all\".";
pub const tool_schema =
    \\{"type": "object", "properties": {"action": {"type": "string", "enum": ["send", "list", "inbox", "direct", "claim", "release", "handoff", "status"], "description": "send (default): ping a peer. list: who is live. inbox: read+clear parked inbound. direct: supervisor control of one named session. claim/release/handoff/status: repository-scoped artifact ownership (kind+key)."}, "session": {"type": "string", "description": "who to ping, direct, or hand a claim to: exact visible title, exact saved-session base, unique normalized title/slug, id, pid, unique name fragment, or unique goal fragment (omit = this folder's room for send). Named targets are DMs. Presence is device-local. Not \"all\"."}, "text": {"type": "string", "description": "one or two sentences of coordination intent (required for send and direct)"}, "fyi": {"type": "boolean", "description": "send: true for a status or scope update that needs no action or reply. Recipients read it on their next turn; it does not start one."}, "kind": {"type": "string", "enum": ["branch", "issue", "commit", "pull_request", "publication"], "description": "artifact kind for claim/release/handoff/status"}, "key": {"type": "string", "description": "artifact key: branch name, issue number, commit SHA, or PR number"}, "repo": {"type": "string", "description": "GitHub repository for claim/release/handoff/status, as owner/name or host/owner/name; defaults to the workspace CLI repository. Use the same repository for release or handoff."}}}
;

/// Whether the named session sits in MY worktree (routes the post: worktree
/// room when local, device room when not).
fn isLocal(peers: []const Owner, session_id: []const u8, my_identity: []const u8) bool {
    for (peers) |p| {
        if (std.mem.eql(u8, p.session_id, session_id)) return std.mem.eql(u8, p.identity, my_identity);
    }
    return true;
}

fn peerListText(arena: Allocator, peers: []const Owner) []const u8 {
    var buf: std.ArrayList(u8) = .empty;
    for (peers) |p| {
        const line = std.fmt.allocPrint(arena, "\"{s}\" (pid {d}, goal: {s})", .{ p.session_id, p.pid, if (p.goal.len > 0) p.goal else "?" }) catch continue;
        buf.appendSlice(arena, line) catch {};
        buf.appendSlice(arena, ", ") catch {};
    }
    const items = buf.items;
    return if (items.len >= 2) items[0 .. items.len - 2] else items;
}

pub fn handleMessage(self: *Agent, call: ToolCall) !ExecResult {
    const obj = tools_mod.json_args.object(call.input) orelse return .{
        .text = "peer_message needs an object input",
        .is_error = true,
    };
    const action = tools_mod.json_args.str(obj, "action") orelse "send";
    if (std.mem.eql(u8, action, "claim") or std.mem.eql(u8, action, "release") or std.mem.eql(u8, action, "handoff") or std.mem.eql(u8, action, "status")) {
        if (obj.get("repo")) |repo| if (repo != .string) return .{ .text = "claim repo must be a repository name", .is_error = true };
        return @import("artifact_claim.zig").handleToolIn(
            self.arena,
            self.io,
            action,
            tools_mod.json_args.str(obj, "kind") orelse "publication",
            tools_mod.json_args.str(obj, "key") orelse "",
            tools_mod.json_args.str(obj, "session") orelse "",
            self.agent_cwd orelse ".",
            tools_mod.json_args.str(obj, "repo"),
        );
    }
    if (std.mem.eql(u8, action, "list")) {
        const everyone = presence.liveAllPeers(self.io, self.arena);
        return .{ .text = peer_inbox.formatList(self.arena, everyone, presence.ownIdentity()), .is_error = false };
    }
    if (std.mem.eql(u8, action, "inbox")) {
        const text = peer_inbox.takeAll(self.arena) catch return .{
            .text = "peer_message: inbox read failed; messages and dropped count retained — retry action=inbox",
            .is_error = true,
        };
        peer_idle.noteInboxConsumed();
        return .{ .text = text, .is_error = false };
    }
    if (std.mem.eql(u8, action, "direct")) {
        return @import("daddy.zig").send(self, tools_mod.json_args.str(obj, "session") orelse "", tools_mod.json_args.str(obj, "text") orelse "");
    }
    if (!std.mem.eql(u8, action, "send")) return .{
        .text = "peer_message action must be send, list, inbox, direct, claim, release, handoff, or status",
        .is_error = true,
    };
    const said = tools_mod.json_args.str(obj, "text") orelse "";
    if (said.len == 0) return .{ .text = "peer_message: empty text — say what you want the peer to know", .is_error = true };
    // #1137: an update that needs nothing from the peer must not wake it.
    const fyi = tools_mod.json_args.flag(call.input, "fyi");
    const text = if (fyi and !peer_inbox.isFyi(said)) try std.fmt.allocPrint(self.arena, "{s}{s}", .{ peer_inbox.fyi_marker, said }) else said;
    const want = tools_mod.json_args.str(obj, "session") orelse "";
    const local = presence.liveTreePeers(self.io, self.arena);
    if (want.len == 0 and local.len == 0) return .{
        .text = "no live co-resident graff sessions in this worktree — the presence registry says you are alone here (a peer shows up via the startup warning when one starts)",
        .is_error = true,
    };
    // Named `session` is a DM: only that peer hears it. Bare posts stay a
    // room. Cross-folder names ride the device room. Model "all" is retired.
    if (std.mem.eql(u8, want, "all")) return .{
        .text = "\"all\" is retired for sessions — hearing is folder-scoped now. Post bare for this folder's room, or name one session (possibly in another folder) to reach it directly.",
        .is_error = true,
    };
    const to: []const u8 = if (want.len == 0) "" else switch (peer_target.resolvePeer(presence.liveAllPeers(self.io, self.arena), want)) {
        .one => |p| p.session_id,
        .none => return .{
            .text = try std.fmt.allocPrint(self.arena, "no live peer matches \"{s}\" — live here: {s}", .{ want, peerListText(self.arena, local) }),
            .is_error = true,
        },
        .ambiguous => return .{
            .text = try std.fmt.allocPrint(self.arena, "more than one live peer matches — name one with `session` (title, base, id, or pid): {s}", .{peerListText(self.arena, presence.liveAllPeers(self.io, self.arena))}),
            .is_error = true,
        },
    };
    const cross_folder = to.len > 0 and !isLocal(presence.liveAllPeers(self.io, self.arena), to, presence.ownIdentity());
    const posted = if (cross_folder)
        presence.postToDevice(self.io, self.arena, text, to, false)
    else
        presence.postTo(self.io, self.arena, text, to);
    if (!posted) return .{
        .text = "delivery failed — the presence registry is unavailable (this session may never have announced itself)",
        .is_error = true,
    };
    if (fyi) return .{
        .text = if (to.len == 0) "posted to this folder's room as fyi — sessions here read it on their next turn; it starts none." else "sent as fyi — the peer reads it on its next turn; it starts none.",
        .is_error = false,
    };
    if (to.len == 0) return .{
        .text = "posted to this folder's room — every live idle session here starts a turn. A busy one reads it when that turn ends. Set session to DM one peer instead.",
        .is_error = false,
    };
    const via: []const u8 = if (cross_folder) "device room" else "this folder";
    return .{
        .text = try std.fmt.allocPrint(self.arena, "DM to \"{s}\" via the {s} — only they hear it. An idle root starts a turn; a busy one waits until that turn ends. Re-ping with session=\"{s}\".", .{ to, via, to }),
        .is_error = false,
    };
}

/// The receiving half, called at every step boundary of a root agent's turn:
/// drain the rooms and park heard bodies. Paint and the one-line `[peer]`
/// wake wait until idle — a mid-turn inject aborts tools (#1136). Never
/// fails a turn — delivery trouble is silence, not an error, because a
/// peer must never break our session.
/// The room tail a late joiner parks; anything older is seek-skipped.
pub const backlog_tail_max = 10;
var g_backlog_tail_cut = false;

/// Resume already restored the room cursor — the next drain is incremental,
/// never a first-join backlog replay.
pub fn markCaughtUp() void {
    g_backlog_tail_cut = true;
}

/// Of a first-drain backlog the REPL prints only this many trailing lines;
/// the rest still lands in history (the model coordinates from it) behind a
/// "delivered to context" marker. Live drains are unaffected.
pub const backlog_repl_show = 2;

const DisplayWindow = struct { start: usize, hidden: usize };

fn displayWindow(is_backlog: bool, count: usize) DisplayWindow {
    if (!is_backlog or count <= backlog_repl_show) return .{ .start = 0, .hidden = 0 };
    return .{ .start = count - backlog_repl_show, .hidden = count - backlog_repl_show };
}

pub fn deliverInbound(root: *Agent) void {
    if (root.sub) return;
    var local_msgs = presence.drainChannel(root.io, root.arena);
    var device_msgs = presence.drainDevice(root.io, root.arena);
    // Only the process's FIRST drain carries the rooms' whole backlog; later
    // drains are incremental and must never be capped — those are live.
    var omitted: usize = 0;
    const is_backlog_drain = !g_backlog_tail_cut;
    if (is_backlog_drain) {
        g_backlog_tail_cut = true;
        const dl = presence_chan.backlogDrop(local_msgs.len, backlog_tail_max);
        const dd = presence_chan.backlogDrop(device_msgs.len, backlog_tail_max);
        omitted = dl + dd;
        local_msgs = local_msgs[dl..];
        device_msgs = device_msgs[dd..];
    }
    const own = presence.ownSession();
    // Named worktree posts are DMs; the JSONL still has the line.
    var tree_heard: std.ArrayList(presence.Message) = .empty;
    var skipped: usize = 0;
    for (local_msgs) |m| {
        if (peer_target.treeHears(m, own)) tree_heard.append(root.arena, m) catch break else skipped += 1;
    }
    local_msgs = tree_heard.items;
    var heard: std.ArrayList(presence.Message) = .empty;
    for (device_msgs) |m| {
        if (peer_target.deviceHears(m, own)) heard.append(root.arena, m) catch break else skipped += 1;
    }
    device_msgs = heard.items;
    if (local_msgs.len == 0 and device_msgs.len == 0 and omitted == 0 and skipped == 0) return;
    const newly = peer_inbox.parkHeard(local_msgs, device_msgs);
    // Park always. Paint the human tally at this step boundary (#469).
    // History inject waits until idle (#1136): a mid-turn user-role wake
    // aborts tools. ADR 0134 / #430 / ADR 0147.
    paintHeard(root, own, is_backlog_drain, omitted, skipped, local_msgs, device_msgs);
    if (!shouldAnnounce(peer_idle.isBusy(), newly)) return;
    // History gets the wake only (ADR 0004). Bodies wait in the ring.
    root.messages.append(@import("session_wake.zig").message(root.arena, peer_context.capInject(peer_inbox.formatWake(root.arena))) catch return) catch {};
}

fn paintHeard(
    root: *Agent,
    own: []const u8,
    is_backlog_drain: bool,
    omitted: usize,
    skipped: usize,
    local_msgs: []const presence.Message,
    device_msgs: []const presence.Message,
) void {
    const sink = engine_sink.forAgent(root);
    // The visible block gets one blank line of air on either side: peer lines
    // land mid-stream at a step boundary and used to butt straight against
    // the assistant text above and whatever follows below — one clump.
    const window = displayWindow(is_backlog_drain, local_msgs.len + device_msgs.len);
    const any_visible = local_msgs.len + device_msgs.len > window.start or
        (repl.g_debug and (omitted > 0 or skipped > 0 or window.hidden > 0));
    var markers: std.ArrayList([]const u8) = .empty;
    if (omitted > 0 and repl.g_debug) {
        const marker = std.fmt.allocPrint(root.arena, "[peer channel: {d} older message(s) predating this session omitted]", .{omitted}) catch "";
        if (marker.len > 0) markers.append(root.arena, marker) catch {};
    }
    if (skipped > 0 and repl.g_debug) {
        const marker = std.fmt.allocPrint(root.arena, "[peer channel: {d} message(s) not addressed to this session skipped — folder-scoped hearing]", .{skipped}) catch "";
        if (marker.len > 0) markers.append(root.arena, marker) catch {};
    }
    if (window.hidden > 0 and repl.g_debug) {
        const marker = std.fmt.allocPrint(root.arena, "[peer channel: {d} backlog message(s) showing last {d}]", .{ window.hidden, backlog_repl_show }) catch "";
        if (marker.len > 0) markers.append(root.arena, marker) catch {};
    }
    var lines: std.ArrayList([]const u8) = .empty;
    for ([2][]const presence.Message{ local_msgs, device_msgs }, [2][]const u8{ "", " · device" }) |msgs, scope| {
        for (msgs) |m| {
            const goal = if (m.from_goal.len > 0) std.fmt.allocPrint(root.arena, " (goal: {s})", .{peer_context.clip(m.from_goal, 40)}) catch "" else "";
            const to = if (m.to.len == 0) "" else if (peer_target.addressedTo(m.to, own)) " → you" else std.fmt.allocPrint(root.arena, " → {s}", .{m.to}) catch "";
            const line = std.fmt.allocPrint(root.arena, "[peer message from {s}{s}{s}{s}]: {s}", .{ m.from_session, goal, to, scope, peer_context.clip(m.text, peer_context.line_clip) }) catch continue;
            lines.append(root.arena, line) catch {};
        }
    }
    // Foreground chrome: one tally. Full peer lines stay in /debug and in the
    // parked inbox the model reads. Unrelated coordination must not steal
    // the first screenful of a turn.
    if (repl.g_debug) {
        renderPeerBlock(sink, root.io, any_visible, markers.items, lines.items[window.start..]);
    } else if (any_visible) {
        const n = lines.items.len;
        const summary = if (n == 0)
            ""
        else
            (std.fmt.allocPrint(root.arena, "↯ {d} peer update{s}", .{ n, if (n == 1) "" else "s" }) catch "↯ peer updates");
        if (summary.len > 0)
            renderPeerBlock(sink, root.io, true, &.{}, &.{summary});
    }
}

/// Mid-turn mail stays parked. Announce only when idle and something new landed.
/// A completed turn does not get a task-authoritative wake (#1137).
pub fn shouldAnnounce(busy: bool, newly_parked: usize) bool {
    return @import("peer_wake_loop.zig").shouldInjectAuthoritative(busy, newly_parked);
}

/// Emit the drain's visible half as one bracketed unit: a blank notice, the
/// debug markers and peer lines in drain order, a closing blank. Nothing at
/// all when nothing is visible — a drain that only refreshed history must not
/// paint. Pure aside from the sink, so the bracketing is unit-testable
/// without a live presence registry (a PTY transcript can't tell the fix's
/// blanks apart from a neighbor's, the event sequence can).
fn renderPeerBlock(sink: engine_sink.EngineSink, io: Io, any_visible: bool, markers: []const []const u8, lines: []const []const u8) void {
    if (!any_visible) return;
    sink.emit(io, .{ .session_notice = .{ .text = "", .tone = .plain } });
    for (markers) |m| sink.emit(io, .{ .session_notice = .{ .text = m, .tone = .plain } });
    for (lines) |l| sink.emit(io, .{ .session_notice = .{ .text = l, .tone = .plain } });
    sink.emit(io, .{ .session_notice = .{ .text = "", .tone = .plain } });
}

/// /tell <session|all> <text…>: the user's line into the channel. `all` (or a
/// target in another folder) rides the device-wide room — every live session
/// hears it; a local target stays on the worktree room.
pub fn tellCommand(root: *Agent, arena: Allocator, line: []const u8, out: *Io.Writer) !bool {
    const rest = std.mem.trim(u8, line["/tell".len..], " \t");
    const everyone = presence.liveAllPeers(root.io, arena);
    const split = std.mem.indexOfAny(u8, rest, " \t");
    const target = if (split) |i| rest[0..i] else "";
    const text = if (split) |i| std.mem.trim(u8, rest[i + 1 ..], " \t") else "";
    if (target.len == 0 or text.len == 0) {
        try out.writeAll("usage: /tell <session|all> <text> — all reaches every live session on this device, any folder\n");
        if (everyone.len == 0) try out.writeAll("  (no live peers right now)\n") else try out.print("  live now: {s}\n", .{peerListText(arena, everyone)});
        try out.flush();
        return true;
    }
    const broadcast = std.mem.eql(u8, target, "all");
    const to: []const u8 = if (broadcast) "" else switch (peer_target.resolvePeer(everyone, target)) {
        .one => |p| p.session_id,
        .none => {
            try out.print("no live peer matches \"{s}\"\n", .{target});
            try out.flush();
            return true;
        },
        .ambiguous => {
            try out.print("more than one live peer matches — live now: {s}\n", .{peerListText(arena, everyone)});
            try out.flush();
            return true;
        },
    };
    const device_wide = broadcast or !isLocal(everyone, to, presence.ownIdentity());
    const posted = if (device_wide)
        presence.postToDevice(root.io, arena, text, to, true) // the user's line crosses folders; a session's does not
    else
        presence.postTo(root.io, arena, text, to);
    if (posted) {
        const addressed = if (to.len > 0) try std.fmt.allocPrint(arena, " (DM to {s})", .{to}) else "";
        const room: []const u8 = if (device_wide) "device-wide room" else if (to.len > 0) "this folder" else "worktree room";
        try out.print("⇢ posted to the {s}{s}\n", .{ room, addressed });
    } else try out.writeAll("delivery failed — presence registry unavailable\n");
    try out.flush();
    return true;
}

/// What a peeked session is up to, summarized from its transcript tail.
pub const PeekSummary = struct {
    last_prompt: []const u8 = "",
    last_said: []const u8 = "",
    last_tool: []const u8 = "",
    messages: usize = 0,
};

/// Pure: parse complete transcript lines (one serialized message each, #441)
/// and pull the last user text, last assistant text, and last tool name. A
/// torn first line (we read a tail window) or last line (writer mid-append)
/// is skipped — the next peek catches up.
pub fn summarizeTranscript(arena: Allocator, text: []const u8) PeekSummary {
    var out: PeekSummary = .{};
    var it = std.mem.splitScalar(u8, text, '\n');
    while (it.next()) |line| {
        if (line.len == 0) continue;
        const msg = std.json.parseFromSliceLeaky(std.json.Value, arena, line, .{ .ignore_unknown_fields = true }) catch continue;
        if (msg != .object) continue;
        const role = if (msg.object.get("role")) |r| (if (r == .string) r.string else "") else "";
        out.messages += 1;
        if (std.mem.eql(u8, role, "user")) {
            if (firstText(msg.object)) |t| out.last_prompt = t;
        } else if (std.mem.eql(u8, role, "assistant")) {
            if (firstText(msg.object)) |t| {
                out.last_said = t;
            } else if (msg.object.get("tool_calls")) |tc| {
                if (tc == .array and tc.array.items.len > 0) {
                    const call = tc.array.items[0];
                    if (call == .object) {
                        if (call.object.get("function")) |f| {
                            if (f == .object) {
                                if (f.object.get("name")) |n| {
                                    if (n == .string) out.last_tool = n.string;
                                }
                            }
                        }
                    }
                }
            }
        } else if (std.mem.eql(u8, role, "tool")) {
            if (msg.object.get("name")) |n| {
                if (n == .string) out.last_tool = n.string;
            }
        }
    }
    return out;
}

/// First readable text of a message's content, whether it's a plain string or
/// content blocks. Peer-channel lines we inject are skipped: they quote the
/// peer's doings, they aren't the peer's doings.
fn firstText(obj: std.json.ObjectMap) ?[]const u8 {
    const content = obj.get("content") orelse return null;
    switch (content) {
        .string => |s| return if (s.len > 0 and !peer_context.isPeerInjectContent(s)) s else null,
        .array => |arr| {
            for (arr.items) |blk| {
                if (blk != .object) continue;
                const t = blk.object.get("type") orelse continue;
                if (t == .string and std.mem.eql(u8, t.string, "text")) {
                    if (blk.object.get("text")) |v| {
                        if (v == .string and v.string.len > 0) {
                            if (peer_context.isPeerInjectContent(v.string)) continue;
                            return v.string;
                        }
                    }
                }
            }
            return null;
        },
        else => return null,
    }
}

fn transcriptPath(arena: Allocator, peer: Owner) []const u8 {
    const mine = presence.ownIdentity();
    const base = if (std.mem.eql(u8, peer.identity, mine))
        "."
    else if (std.mem.endsWith(u8, peer.identity, "/.git"))
        peer.identity[0 .. peer.identity.len - "/.git".len]
    else
        peer.identity;
    return std.fmt.allocPrint(arena, "{s}/.graff/sessions/{s}.transcript.jsonl", .{ base, peer.session_id }) catch "";
}

/// /peek <session>: what is the other live session DOING right now — the tail
/// of its append-only transcript, not just its registry goal.
pub fn peekCommand(root: *Agent, arena: Allocator, line: []const u8, out: *Io.Writer) !bool {
    const target = std.mem.trim(u8, line["/peek".len..], " \t");
    const everyone = presence.liveAllPeers(root.io, arena);
    if (target.len == 0) {
        try out.writeAll("usage: /peek <session> — what a live session is doing right now\n");
        if (everyone.len == 0) try out.writeAll("  (no live peers right now)\n") else try out.print("  live now: {s}\n", .{peerListText(arena, everyone)});
        try out.flush();
        return true;
    }
    const peer = switch (peer_target.resolvePeer(everyone, target)) {
        .one => |p| p,
        .none => {
            try out.print("no live peer matches \"{s}\"\n", .{target});
            try out.flush();
            return true;
        },
        .ambiguous => {
            try out.print("more than one live peer matches — live now: {s}\n", .{peerListText(arena, everyone)});
            try out.flush();
            return true;
        },
    };
    const path = transcriptPath(arena, peer);
    const text = Io.Dir.cwd().readFileAlloc(root.io, path, arena, .limited(1024 * 1024)) catch {
        try out.print("{s} · pid {d} · goal: {s}\n  transcript not reachable from here ({s})\n", .{ peer.session_id, peer.pid, if (peer.goal.len > 0) peer.goal else "?", peer.identity });
        try out.flush();
        return true;
    };
    // Keep the tail: a long transcript's beginning is ancient history.
    const window = if (text.len > 64 * 1024) blk: {
        const tail = text[text.len - 64 * 1024 ..];
        const first_nl = std.mem.indexOfScalar(u8, tail, '\n') orelse 0;
        break :blk tail[first_nl + 1 ..];
    } else text;
    const sum = summarizeTranscript(arena, window);
    const goal = if (peer.goal.len > 0) peer.goal else "?";
    try out.print("⚡ {s} · pid {d} · goal: {s}\n", .{ peer.session_id, peer.pid, goal });
    if (sum.last_prompt.len > 0) try out.print("  last prompt: {s}\n", .{peer_context.clip(sum.last_prompt, 120)});
    if (sum.last_said.len > 0) try out.print("  last said: {s}\n", .{peer_context.clip(sum.last_said, 120)});
    if (sum.last_tool.len > 0) try out.print("  last tool: {s}", .{sum.last_tool});
    if (sum.messages > 0)
        try out.print("{s}{d} transcript messages\n", .{ if (sum.last_tool.len > 0) " · " else "  ", sum.messages })
    else if (sum.last_tool.len > 0)
        try out.writeAll("\n");
    if (sum.messages == 0) try out.writeAll("  (transcript is empty — it just started)\n");
    try out.flush();
    return true;
}

/// The "live now" section /sessions appends under the saved-session list:
/// this worktree first, then the rest of the device.
pub fn writeLiveSection(root: *Agent, arena: Allocator, out: *Io.Writer) !void {
    try @import("peer_live.zig").write(arena, out, presence.liveAllPeers(root.io, arena), presence.ownIdentity(), @import("util.zig").unixMs(root.io));
}

test {
    _ = @import("peer_live.zig");
}

test "summarizeTranscript: last prompt, last words, last tool, from complete lines only" {
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    const text =
        \\{"role":"user","content":"refactor the digest job"}
    ++ "\n" ++
        \\{"role":"assistant","content":null,"tool_calls":[{"function":{"name":"edit_file"}}]}
    ++ "\n" ++
        \\{"role":"tool","name":"edit_file","content":"ok"}
    ++ "\n" ++
        \\{"role":"assistant","content":[{"type":"text","text":"switched the query to display_name"}]}
    ++ "\n" ++
        \\{"role":"user","content":"[peer message from s-2]: hold off"}
    ++ "\n" ++ "{\"role\":\"user\",\"content\":\"a torn last line";
    const sum = summarizeTranscript(arena, text);
    try std.testing.expectEqualStrings("refactor the digest job", sum.last_prompt); // peer-channel quotes are not the peer's doings
    try std.testing.expectEqualStrings("switched the query to display_name", sum.last_said);
    try std.testing.expectEqualStrings("edit_file", sum.last_tool);
    try std.testing.expectEqual(5, sum.messages); // the torn tail is skipped
}

test "#1136 shouldAnnounce: park during a turn, announce only when idle" {
    @import("peer_idle.zig").resetForTest();
    defer @import("peer_idle.zig").resetForTest();
    // Paint is not gated here — deliverInbound paints at the step boundary
    // even while busy (#469). This flag is the history-wake latch only.
    try std.testing.expect(!shouldAnnounce(true, 3));
    try std.testing.expect(!shouldAnnounce(true, 0));
    try std.testing.expect(!shouldAnnounce(false, 0));
    try std.testing.expect(shouldAnnounce(false, 1));
}

test "displayWindow: only a backlog drain is windowed, to its trailing lines" {
    // Live incremental drains render every line, however many.
    try std.testing.expectEqualDeep(DisplayWindow{ .start = 0, .hidden = 0 }, displayWindow(false, 25));
    // A backlog at or under the show-count renders in full — no marker noise.
    try std.testing.expectEqualDeep(DisplayWindow{ .start = 0, .hidden = 0 }, displayWindow(true, backlog_repl_show));
    // A longer backlog prints only the tail; the rest is context-only.
    try std.testing.expectEqualDeep(DisplayWindow{ .start = 8, .hidden = 8 }, displayWindow(true, 10));
}

fn recordNoticeText(ctx: *anyopaque, ev: engine_sink.Stamped) void {
    const rec: *std.ArrayList([]const u8) = @ptrCast(@alignCast(ctx));
    if (ev.event == .session_notice)
        rec.append(std.testing.allocator, ev.event.session_notice.text) catch {};
}

test "renderPeerBlock: blank notices bracket the block; silence when nothing is visible" {
    // emit(undefined, ...) is sound only while json_mode is false (no lock
    // taken): pin it so a leaky earlier test can never turn this into UB.
    const main_mod = @import("main.zig");
    const protocol_seq = @import("protocol_seq.zig");
    const saved_json = main_mod.json_mode;
    main_mod.json_mode = false;
    defer main_mod.json_mode = saved_json;
    protocol_seq.resetForTest();
    defer protocol_seq.resetForTest();
    var rec: std.ArrayList([]const u8) = .empty;
    defer rec.deinit(std.testing.allocator);
    const vt: engine_sink.VTable = .{ .emit = recordNoticeText, .durable = false };
    const sink: engine_sink.EngineSink = .{ .ctx = &rec, .vt = &vt };
    const markers = [_][]const u8{"[presence] 1 other live session"};
    const lines = [_][]const u8{ "[peer message from a]: one", "[peer message from b]: two" };
    renderPeerBlock(sink, undefined, true, &markers, &lines);
    try std.testing.expectEqualDeep(&[_][]const u8{
        "", "[presence] 1 other live session", lines[0], lines[1], "",
    }, rec.items);
    // A history-only drain paints nothing — no stray blank pair.
    rec.clearRetainingCapacity();
    renderPeerBlock(sink, undefined, false, &markers, &lines);
    try std.testing.expectEqual(@as(usize, 0), rec.items.len);
}