[idea] Support OSC 7501 program status for Pi and read-only dashboards

[Ancienttwo]

idea / problem

Pi 1.1.0 added OSC 7501 program-status reporting and normally waits for the terminal's support-query reply before sending it: https://github.com/earendil-works/pi/releases/tag/v1.1.0

Could Herdr consume this protocol so panes and external dashboards can distinguish working, waiting for input, completion, and failure without relying on screen text?

The OSC observer at master commit 4dc23bb currently handles 0/2/9:

herdr/src/pane/osc.rs

Lines 494 to 528 in 4dc23bb

	pub(super) struct AgentOscStateTracker {
	collector: OscStreamCollector,
	latest_title: Option<String>,
	terminal_title: Option<String>,
	latest_progress: Option<String>,
	}
	impl AgentOscStateTracker {
	pub(super) fn observe(&mut self, bytes: &[u8]) -> bool {
	let (collector, latest_title, terminal_title, latest_progress) = (
	&mut self.collector,
	&mut self.latest_title,
	&mut self.terminal_title,
	&mut self.latest_progress,
	);
	let mut terminal_title_changed = false;
	collector.observe(bytes, |body| {
	let Some((command, payload)) = parse_agent_osc_body(body) else {
	return;
	};
	match command {
	b"0" | b"2" => {
	let title = sanitize_agent_osc_string(payload, AGENT_OSC_MAX_CHARS);
	let title = (!title.is_empty()).then_some(title);
	terminal_title_changed |= *terminal_title != title;
	*terminal_title = title.clone();
	*latest_title = title;
	}
	b"9" => {
	*latest_progress =
	Some(sanitize_agent_osc_string(payload, AGENT_OSC_MAX_CHARS));
	}
	_ => {}
	}
	});

. This is a source-based feature request, not a reproduced runtime bug.

Moving the request to Ideas as directed in #5069: #5069. Related dialog-detection discussion: #1346.

requested change

Support the OSC 7501 query/reply handshake and bounded parsing of its six state values: idle, working, blocked, done, error, and clear (which removes records).

Preserve typed blocked reasons (permission/question/auth), safe display text, record IDs, and pane/source provenance. Follow the protocol's replacement, clearing, process-exit, shell-prompt, and reset lifetimes so stale state cannot leak into a new session.

Define precedence and deduplication with existing Pi lifecycle hooks and screen detection, including how to avoid duplicate notifications. Expose the resulting status, reason, provenance, and freshness through pane snapshots and change events for read-only consumers.

Protocol reference: https://www.superlogical.com/rex/docs/build/program-status

why you want this

A read-only Kanban/status view could show which panes are running, need attention, or have a result to inspect, with a structured reason instead of guessing from terminal output. Program-reported done/error would remain a status signal; accepting a task as complete still needs separate validation. Existing integrations should continue to work.

[VictorGob]

Claude just added support too

[flavour]

Duplicated by #5106

[acarril]

Suggest treating this as the umbrella for OSC 7501 itself, independent of any one agent. The Program Status spec (Mitchell Hashimoto, rationale) is general-purpose; Pi 1.1.0 and Claude Code 2.1.295 already emit it, both gated on a reply to OSC 7501 ; ?.

Related threads asking for the same thing per agent: #5106 (Claude Code), #5107 (ZCode, see comments), and the closed #5069.

@Ancienttwo would you consider retitling to "Support the Program Status Protocol (OSC 7501) as an agent-agnostic state source"?

Minimal ask:

1. Answer the OSC 7501 ; ? capability query.
2. Map reported states to agent_status (working / blocked / idle / done; error → TBD).
3. Keep screen manifests as the fallback, with 7501 taking precedence while a program is actively reporting.

[deephbz]

+1. A concrete case this would fix: #1853 (pane stays in the wrong state during pi compaction).
It was closed because herdr could not detect compaction start/end, and failed or
cancelled compactions could leave the status stuck on working.

Pi 1.1.0's OSC 7501 reporter covers this without a herdr-side pi integration:

• compaction_start -> working with message Compacting context
• compaction_end -> idle if aborted, error (first line) if failed,
  done after a successful manual /compact; inside a run, the run's final state wins

Every compaction start has a matching end report, so the stuck-working case cannot occur.
Source: packages/coding-agent/src/modes/interactive/program-status-reporter.ts in earendil-works/pi v1.1.0.

Note that pi only emits after the terminal answers OSC 7501 ; ?, so herdr needs the
query reply for this to work.

[yingzhi0808]

Field report from a Pi-inside-herdr setup, in case it helps scope the receiver.

We run pi 1.1.0 inside herdr 0.9.3 (TERM_PROGRAM=herdr), several panes, plus background subagent runs. Two independent reasons nothing shows today:

1. herdr never answers OSC 7501 ; ?, so conforming programs keep the protocol off — as Support Claude Code's Program Status Protocol (OSC 7501) for agent state #5106 and the comment above describe.

2. Even a record sent without the handshake is dropped. I verified this directly by writing a well-formed record straight to a pane's tty:

   ESC ] 7501 ; state=working : id=subagents/testprobe : msg=OSC7501-test ESC \\

   Result: no status, no passthrough to the outer terminal (Ghostty, which does support the protocol), and no printed garbage — consistent with the OSC observer handling only 0/2/9.

What it would buy us concretely: pi-subagents 0.77.0 reports each background subagent run's state through this protocol (working / blocked / done / error; record ids subagents/<run>, workflow children as subagents/<parent>.<key>; bounded at 64 records, 2 KB message, 192 B title). Today we infer "still working / waiting on me / finished" from pane text or by polling our own logs; a socket-visible status would replace that.

One note for the handshake work: answering the query is the gate, consuming the records is the value. Answering without consuming would make every conforming program emit into a void — harmless, but screen detection would remain the only source, so the structured state this discussion asks for still would not exist.