Same-status content changes produce no signal — how should consumers detect "screen changed but agent_status didn't"?

[waynewu411]

Problem

pane.agent_status_changed (and agent wait --until <state>) is edge-triggered on coarse AgentStatus value equality. Two consecutive same-status screens with genuinely different content produce zero events — blocked→blocked, working→working, done→done, etc.

Motivating case: a pane is blocked on approval dialog #1; the dialog is dismissed and immediately replaced by a different pending approval dialog (tool call #2 of a queued batch). No event fires, and a caller has no way to tell the pane moved on to a different question.

Impact

Any consumer built on pane.agent_status_changed or agent wait --until <state> silently misses every same-status transition whenever the underlying screen content changes without an intervening different status. The blocked→blocked case is the sharpest: a human or supervising agent believes the pane is still waiting on the original question when it has moved to an unrelated one.

Not hypothetical for me: I orchestrate an agent team locally on top of these primitives. A public Herdr plugin (waynewu411/herdr-event-log) hooks pane.agent_status_changed and persists each event to a durable, cursor-resumable log; an orchestrator (scripts/herdr-ewait.sh) tails that log and re-verifies every hit against herdr agent get. The blind spot defeats both layers: no event means no log line, and the verification sweep sees agent_status stay constant — so even the agent get re-check can't tell dialog #1 was replaced by a different question. Today the only reliable detection is diffing raw pane content by hand.

Candidate directions

1. Expose a content-change counter on AgentInfo (implemented) — the screen detector already bumps a counter once per non-empty PTY read batch; expose it as AgentInfo.detection_content_seq: Option<u64>, parallel to revision. Pollers of agent get/agent list compare it across reads to detect "screen changed, status didn't". Minimal API surface; no event-semantics change. Fits the periodic agent get verification sweep in my consumer above (bounded latency up to the sweep interval), but it is invisible to purely event-driven consumers and doesn't restore event immediacy.
2. Actually emit pane.output_changed — the event kind already exists in the schema (EventData::PaneOutputChanged { pane_id, workspace_id, revision: u64 }) but is never emitted by any production code path; plugin manifests hooking it currently get a link-time warning. Wiring it to the detector's counter would give subscribers a real content-change event.
   • What the event carries (and doesn't): the payload is a bare "content changed to revision N" notification — it does not include the new content or a diff; consumers still read the pane (agent read) for specifics. It could optionally carry agent_status (and other state metadata, mirroring pane.agent_status_changed) so consumers don't need a follow-up agent get for status.
   • Design questions: frequency/coalescing (PTY is a byte stream; emission should ride the detection-reclassify path, not per-read-batch) and plugin hook semantics (currently a warning-only stub; hook invocation is per-event, so high-frequency emission needs a policy).
3. Thread a content-change flag through the publish/dedup layers so pane.agent_status_changed itself re-fires on same-status content changes. Most faithful to today's contract, but touches the per-pane detection hot loop and ~40 StateChanged call sites.

Orthogonal note: durability

Replacing the file-log pattern entirely is a separate question: events.subscribe is live-only with no history, which is exactly why the plugin exists (the server invokes hooks for the session's life, giving durable, resume-from-any-offset history). A server-side event history/replay API would be an independent feature, orthogonal to the content-change signal above.

Related prior art

• #1716 (open) — same "dedup swallows a real transition" family, via the hook-reported-state path.
• #2115 (closed) — related event gap (pane.updated), different event kind.

Full implementation, tests, and docs for option 1 are in waynewu411/herdr#2 (the fork-side issue waynewu411/herdr#1 has the detailed root-cause trace). I implemented option 1 as the minimal step, but as the author of the event-log consumer above my preference leans toward direction 2; happy to adapt.

[waynewu411]

Following up on the fork-side issue that led to this post — I've since found that this problem family already has substantial prior art here that my earlier search (issues only) missed:

• Pane output revisions: race-free detection of new output over the socket API #1277 (Pane output revisions…) is the closest thread: its proposed pane_output_changed event + per-pane revision is essentially direction 1+2 here, with three independent integrators confirming the same gaps (pane.read reports revision: 0; the pane.list revision doesn't track content).
• thomaswitt's point there — "a revision that moves tells me that something changed; I still can't get what changed" — matches the payload boundary I noted for direction 2: a change signal is not a diff; specifics still require reading the pane.
• One divergence to flag: Pane output revisions: race-free detection of new output over the socket API #1277 asks for revisions monotonic across respawn/live handoff, while the counter behind direction 1 (detection_content_seq) resets to 0 across handoff — worth reconciling in whatever shape lands.
• For the durability half of my post: Per-pane session recording + replay #908 (per-pane recording + replay) and events.subscribe replays retained historical events for new subscribers instead of streaming live only #1270 (subscribe replay semantics) are the relevant threads.

My post's specific angle — the same-status blind spot (blocked→blocked approval-dialog swaps produce zero events) — complements #1277's new-output-detection framing. Happy to fold this work into whichever direction the maintainers prefer from that thread.