A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.
Rust agentagent-orchestrationaiai-agentsclaude-codecodexcoding-agentlinuxmacosmultiplayermultiplexerrustterminalterminal-emulatorterminal-multiplexertmuxtuiweztermwindows
//! Agent status detection core.
//!
//! Classifies panes that run coding agents (Claude Code, Codex, …) as
//! Working / Blocked / Idle by arbitrating three signal layers:
//!
//! 1. the `THINKTERM_AGENT` user-var contract ([`contract`]) — the agent
//! (or its hook script) reports identity, session, and state;
//! 2. manifest-driven screen rules ([`engine`]) — the pane's live screen
//! tail plus OSC title/progress, evaluated against herdr-compatible
//! rule files. A matching rule outranks the contract's *state*, because
//! the two known contract gaps (Esc interrupt, permission-prompt
//! cancel) both look like "contract says working, screen shows idle";
//! 3. nothing: when neither speaks, a known agent settles to Idle (never
//! Blocked).
//!
//! Detection runs in the process that **owns** the pane: the predicate is
//! `!is_remote_mirror() && !is_dead()`. A mux server therefore classifies
//! all of its panes (full screen-rule coverage for remote clients), the
//! GUI's embedded mux classifies its local panes, and a ClientPane answers
//! [`Pane::agent_status`] from whatever the owning server pushed. That one
//! predicate is the whole no-double-detection story.
pub mod contract;
pub mod engine;
mod hysteresis;
pub mod identify;
mod proc_match;
#[cfg(test)]
mod manifest_tests;
mod windows_select;
use crate::pane::{Pane, PaneId};
use crate::{Mux, MuxNotification};
use parking_lot::{Mutex, RwLock};
use std::collections::{HashMap, HashSet};
use std::sync::atomic::{AtomicBool, Ordering};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use thinkterm_proto::{
AgentEvidence, AgentState, AgentStatus, ProgramBlockedKind, ProgramReport, ProgramReportChild,
ProgramReportState,
};
use wezterm_term::program_status::{ProgramState, ProgramStatusRecord};
/// Minimum interval between screen reads for one pane even while output
/// is flowing. Must be comfortably larger than EVAL_INTERVAL to do
/// anything at all: at 150ms it equaled the drain cadence and every
/// round of a busy pane paid the full 64-row deep clone under the
/// terminal lock plus a whole-manifest scan, on the main thread.
const SCREEN_READ_FLOOR: Duration = Duration::from_millis(500);
/// How many rows from the bottom of the live screen the rules may see.
/// Large enough to cover a whole typical viewport: manifests address the
/// top of the screen too (`top_non_empty_lines`), and a prompt drawn up
/// there is invisible to every rule if the slice stops short of it.
const TAIL_ROWS: isize = 64;
/// At most one evaluation pass per this interval, process-wide. A leading
/// edge throttle rather than a trailing debounce: an agent that prints
/// continuously must still be classified while it streams.
const EVAL_INTERVAL: Duration = Duration::from_millis(150);
/// Quiet panes emit no PaneOutput, but contract freshness expiry, agents
/// exiting back to a shell, and pane death still need a pulse.
const SAFETY_TICK: Duration = Duration::from_secs(2);
/// How long an unidentified background pane's evaluation may be deferred.
/// Deliberately shorter than SAFETY_TICK: with equal periods the throttle
/// window aliases against the tick and doubles the effective latency.
const BACKGROUND_EVAL_WINDOW: Duration = Duration::from_millis(1500);
struct ScreenCache {
seqno: termwiz::surface::SequenceNo,
title: String,
progress: String,
at: Instant,
/// Manifest generation the verdict was computed under; a rules reload
/// invalidates it even if this cache was written after the reload's
/// sweep by a racing evaluation.
generation: u64,
verdict: CachedVerdict,
}
#[derive(Clone, Copy)]
enum CachedVerdict {
State(AgentState),
Freeze,
NoMatch,
}
struct AgentPaneRecord {
agent_id: String,
session_id: Option<String>,
state: AgentState,
evidence: AgentEvidence,
since_unix: u64,
ended: bool,
screen_cache: Option<ScreenCache>,
/// What consumers currently see; publication notifies only on change.
published: Option<AgentStatus>,
/// Confirmation window for guarded transitions; see [`hysteresis`].
pending: hysteresis::Pending,
/// The raw contract string last seen, and the foreground leader
/// observed when it changed: together they prove the emitter is still
/// alive when the contract itself has gone stale.
contract_raw: Option<String>,
contract_leader: Option<String>,
/// Source of the last accepted report, so an unnamed successor cannot
/// inherit this pane's previous program name.
report_process_group: Option<u32>,
report_orphaned: bool,
}
lazy_static::lazy_static! {
static ref REGISTRY: RwLock<HashMap<PaneId, AgentPaneRecord>> = RwLock::new(HashMap::new());
static ref PENDING: Mutex<HashSet<PaneId>> = Mutex::new(HashSet::new());
/// When each pane was last actually evaluated; lets the drain hold
/// background panes to the safety-tick cadence without a record.
static ref LAST_EVAL: Mutex<HashMap<PaneId, Instant>> = Mutex::new(HashMap::new());
static ref PROCESS_PREFERENCE: RwLock<Option<Box<dyn Fn() -> bool + Send + Sync>>> =
RwLock::new(None);
/// Who filed each pane's OSC 7501 root. Kept apart from the registry:
/// a report must stay pinned to its program across the records the
/// registry drops and makes. A pane's entry goes when its root does, or
/// with the pane.
static ref REPORT_FILERS: Mutex<HashMap<PaneId, ReportFiler>> = Mutex::new(HashMap::new());
}
static TICK_SCHEDULED: AtomicBool = AtomicBool::new(false);
static INSTALLED: AtomicBool = AtomicBool::new(false);
/// Cached gate consulted on every notification: the full computation
/// (config lookup + preference closure) is too heavy for the pty parser
/// threads' hot path, so it runs only on the refresh points (init, the
/// safety tick, config reload, the settings toggle).
static ENABLED: AtomicBool = AtomicBool::new(false);
/// What a painter needs of an agent's status every frame, without its
/// report's text.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct AgentStatusSummary {
pub state: AgentState,
pub evidence: AgentEvidence,
pub ended: bool,
/// The program's own word on its state, when it gave one.
pub report_state: Option<ProgramReportState>,
/// A finished or failed result nobody has looked at yet.
pub unseen_result: bool,
}
impl AgentStatusSummary {
pub fn of(status: &AgentStatus) -> Self {
Self {
state: status.state,
evidence: status.evidence,
ended: status.ended,
report_state: status.report.as_ref().map(|report| report.state),
unseen_result: status
.report
.as_ref()
.is_some_and(ProgramReport::has_unseen_result),
}
}
}
/// [`status_for_pane`] summarised, copying no text.
pub fn summary_for_pane(pane_id: PaneId) -> Option<AgentStatusSummary> {
REGISTRY
.read()
.get(&pane_id)
.and_then(|record| record.published.as_ref())
.map(AgentStatusSummary::of)
}
/// The status the owning process last published for this pane, if any.
/// This is what `Pane::agent_status`'s default body answers with.
pub fn status_for_pane(pane_id: PaneId) -> Option<AgentStatus> {
REGISTRY
.read()
.get(&pane_id)
.and_then(|record| record.published.clone())
}
/// Install a process-local veto consulted alongside the Lua config option.
/// The GUI wires its native-settings toggle through this so the user-facing
/// switch governs the GUI's own detector; headless servers install nothing
/// and follow `agent_status_detection` alone.
pub fn set_process_preference(preference: impl Fn() -> bool + Send + Sync + 'static) {
*PROCESS_PREFERENCE.write() = Some(Box::new(preference));
refresh_enabled();
}
fn compute_enabled() -> bool {
if !config::configuration().agent_status_detection {
return false;
}
PROCESS_PREFERENCE.read().as_ref().map(|f| f()).unwrap_or(true)
}
/// Re-evaluate the gate. Call after anything it depends on changes: the
/// GUI's settings toggle does, config reload and the safety tick do.
pub fn refresh_enabled() {
ENABLED.store(compute_enabled(), Ordering::Release);
}
pub fn detection_enabled() -> bool {
ENABLED.load(Ordering::Acquire)
}
/// Install the process-wide detector: one mux subscription plus the safety
/// tick. Idempotent; the GUI and standalone server call this only after their
/// main-thread scheduler is ready. CLI proxy and TUI processes never call it.
pub fn initialize_mux(mux: &Mux) {
// Keep a future call-site regression from taking down the whole app. Do
// not claim INSTALLED here: the owner can retry once its scheduler exists.
if !promise::spawn::is_scheduler_configured() {
log::error!("agent status detector initialization deferred: no scheduler is configured");
return;
}
if INSTALLED.swap(true, Ordering::AcqRel) {
return;
}
refresh_enabled();
std::mem::forget(config::subscribe_to_config_reload(|| {
// Deferred, never inline: this callback runs while the config
// reload still holds the global config mutex, and refresh_enabled
// -> config::configuration() would re-lock it — a same-thread
// deadlock that freezes the whole process. Every config
// subscriber in the tree defers for exactly this reason.
promise::spawn::spawn_into_main_thread(async {
refresh_enabled();
})
.detach();
true
}));
// Load the manifests now, off the evaluation path: the first
// evaluation must not do filesystem IO on the main thread.
engine::warm();
mux.subscribe(|notification| {
// The flag-off promise is byte-identical behavior: one atomic
// read per notification and nothing else.
if !detection_enabled() {
return true;
}
match notification {
MuxNotification::PaneOutput(pane_id) | MuxNotification::PaneAdded(pane_id) => {
mark_dirty(pane_id)
}
MuxNotification::Alert { pane_id, alert } if alert_is_interesting(&alert) => {
mark_dirty(pane_id)
}
// Evict only, never publish: this closure runs inside
// Mux::notify, and clients already learn of the pane's demise
// from PaneRemoved itself — a trailing AgentStatusChanged for a
// pane they just unmapped would only trigger wasted resyncs.
MuxNotification::PaneRemoved(pane_id) => {
evict_pane(pane_id);
}
_ => {}
}
true
});
promise::spawn::spawn_into_main_thread(async {
loop {
smol::Timer::after(SAFETY_TICK).await;
// This loop is the only pulse quiet panes get; a panic below
// (including inside the config read) must re-arm the tick, not
// silently end detection for the remaining process lifetime.
let tick = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
refresh_enabled();
if detection_enabled() {
let Some(mux) = Mux::try_get() else {
return;
};
for pane in mux.iter_panes() {
mark_dirty(pane.pane_id());
}
// Also pulse registry entries whose pane the mux no
// longer knows: a PaneRemoved eviction that raced an
// in-flight evaluation can resurrect a record, and
// the drain's get_pane miss is what cleans it up.
let ghosts: Vec<PaneId> = REGISTRY.read().keys().copied().collect();
for pane_id in ghosts {
mark_dirty(pane_id);
}
} else {
// Quiet panes produce no output to trigger the
// enabled→disabled sweep; run it from here so remote
// clients are not left frozen on stale statuses.
drain_and_evaluate();
}
}));
if tick.is_err() {
log::error!("agent status safety tick panicked; detection continues");
}
}
})
.detach();
}
fn alert_is_interesting(alert: &wezterm_term::Alert) -> bool {
use wezterm_term::Alert;
matches!(
alert,
Alert::SetUserVar { .. }
| Alert::Progress(_)
| Alert::WindowTitleChanged(_)
| Alert::TabTitleChanged(_)
| Alert::IconTitleChanged(_)
)
}
fn mark_dirty(pane_id: PaneId) {
if !detection_enabled() {
return;
}
PENDING.lock().insert(pane_id);
if TICK_SCHEDULED.swap(true, Ordering::AcqRel) {
return;
}
// spawn_into_main_thread, not spawn: PaneOutput notifications arrive on
// the pty parser threads, where no local scheduler exists. The timer
// then runs on the main executor alongside everything else.
promise::spawn::spawn_into_main_thread(async {
smol::Timer::after(EVAL_INTERVAL).await;
TICK_SCHEDULED.store(false, Ordering::Release);
// The flag is already reset, so a panic here self-heals on the next
// mark_dirty; catch it anyway so the executor task dies quietly and
// the failure is visible in the log.
if std::panic::catch_unwind(std::panic::AssertUnwindSafe(drain_and_evaluate)).is_err() {
log::error!("agent status evaluation panicked; detection continues");
}
})
.detach();
}
/// Re-judge a pane soon: something its status depends on changed without
/// any output, such as focus retiring a finished program's OSC 7501 result.
pub fn nudge(pane_id: PaneId) {
mark_dirty(pane_id);
}
/// Reload the screen-rule manifests and re-judge every known pane. The
/// engine swap alone is not enough: a pane whose screen has not changed
/// since its last evaluation keeps serving a cached verdict (the
/// seqno-equality reuse), which was computed under the *old* rules and
/// would survive indefinitely. Safe to call from any thread; the caller
/// may run it on a worker since loading reads manifest files. Returns how
/// many manifest files were rejected, so the caller can report a partial
/// reload instead of unconditional success.
pub fn reload_rules() -> usize {
let rejected = engine::reload_manifests();
let panes: Vec<PaneId> = {
let mut registry = REGISTRY.write();
for record in registry.values_mut() {
record.screen_cache = None;
}
registry.keys().copied().collect()
};
for pane_id in panes {
mark_dirty(pane_id);
}
rejected
}
/// Drop a pane's state without telling anyone. Returns whether a published
/// status was dropped so callers outside the notify path can decide to
/// publish the eviction. Deliberately never notifies: the PaneRemoved
/// subscriber runs inside `Mux::notify`, where a synchronous nested notify
/// re-enters the subscriber lock and deadlocks the process.
///
/// Invariant note: every other mutation of a published status enqueues a
/// trailing AgentStatusChanged, which is what lets the client's
/// authoritative snapshot fetch converge against live pushes. This
/// silent path is safe only because the PaneRemoved PDU itself follows
/// on the same dispatch channel; do not add further silent mutations.
fn evict_pane(pane_id: PaneId) -> bool {
identify::forget_pane(pane_id);
LAST_EVAL.lock().remove(&pane_id);
REPORT_FILERS.lock().remove(&pane_id);
REGISTRY
.write()
.remove(&pane_id)
.and_then(|record| record.published)
.is_some()
}
/// Notify consumers that a pane's status changed. Always deferred to a
/// fresh main-thread task, never synchronous: publish sites are reachable
/// from inside Mux subscriber callbacks, and a synchronous notify there
/// re-enters the subscriber lock (see `evict_pane`). Unit tests have no
/// scheduler and record into a log instead.
fn publish_change(pane_id: PaneId) {
#[cfg(test)]
{
tests::record_publish(pane_id);
}
#[cfg(not(test))]
promise::spawn::spawn_into_main_thread(async move {
if let Some(mux) = Mux::try_get() {
mux.notify(MuxNotification::AgentStatusChanged(pane_id));
}
})
.detach();
}
/// Whether some window's active tab contains the pane — i.e. a frontend
/// could be painting it right now. `get_active_tab_for_window` clones the
/// tab Arc and releases the windows guard before the tab's own lock is
/// touched, so this adds no new lock-order pairing. Consulted lazily,
/// after the cheap throttle checks.
pub(crate) fn pane_is_foreground(mux: &Mux, pane_id: PaneId) -> bool {
mux.iter_windows().into_iter().any(|window_id| {
mux.get_active_tab_for_window(window_id)
.is_some_and(|tab| tab.contains_pane(pane_id))
})
}
fn drain_and_evaluate() {
if !detection_enabled() {
// Enabled→disabled edge: evict everything, loudly.
let ids: Vec<PaneId> = REGISTRY.read().keys().copied().collect();
for pane_id in ids {
if evict_pane(pane_id) {
publish_change(pane_id);
}
}
PENDING.lock().clear();
// PaneRemoved is ignored while detection is off, so this sweep is
// the only place orphaned timestamps get reclaimed.
LAST_EVAL.lock().clear();
REPORT_FILERS.lock().clear();
return;
}
let dirty: Vec<PaneId> = PENDING.lock().drain().collect();
let Some(mux) = Mux::try_get() else {
return;
};
let now = Instant::now();
for pane_id in dirty {
let Some(pane) = mux.get_pane(pane_id) else {
if evict_pane(pane_id) {
publish_change(pane_id);
}
continue;
};
if pane.is_remote_mirror() {
continue;
}
if pane.is_dead() {
if evict_pane(pane_id) {
publish_change(pane_id);
}
continue;
}
// Only panes without a live record are throttled in the
// background: their evaluation exists to notice a new agent
// appearing, which can wait — a background `cargo build`
// otherwise costs a full screen read + rule scan every
// EVAL_INTERVAL on the main thread. A recorded pane drives chips
// the GUI renders for every tab (including Blocked transitions
// someone is waiting on), so it always keeps the fast path, and
// so does hysteresis by extension (confirming implies a record).
if !REGISTRY.read().contains_key(&pane_id)
&& LAST_EVAL
.lock()
.get(&pane_id)
.is_some_and(|at| now.duration_since(*at) < BACKGROUND_EVAL_WINDOW)
&& !pane_is_foreground(&mux, pane_id)
{
// Deferred, not dropped: the mark that got us here may have
// been the pane's only one, and the next tick's drain must
// still see it.
PENDING.lock().insert(pane_id);
continue;
}
// A pane whose parser holds its terminal is not read now: the
// evaluation reads the screen and the user variables through that
// lock, on the main thread, and one pane digesting a huge frame
// used to stall everything else on it for as long as the frame
// took. Left pending, the safety tick brings it back.
if pane.render_state_is_contended() {
PENDING.lock().insert(pane_id);
continue;
}
LAST_EVAL.lock().insert(pane_id, now);
if evaluate_pane(pane.as_ref()) {
publish_change(pane_id);
}
}
// Panes mid-confirmation must not stall until the next output or the
// 2s safety tick: re-mark them so the next 150ms round re-checks.
let confirming: Vec<PaneId> = REGISTRY
.read()
.iter()
.filter(|(_, record)| record.pending.is_open())
.map(|(id, _)| *id)
.collect();
for pane_id in confirming {
mark_dirty(pane_id);
}
}
/// Classify one pane and update the registry. Returns whether the
/// published status changed.
fn evaluate_pane(pane: &dyn Pane) -> bool {
let pane_id = pane.pane_id();
let user_vars = pane.copy_user_vars();
let contract_raw = user_vars
.get(contract::USER_VAR_NAME)
.filter(|value| wezterm_term::agent_contract::agent_contract_within_budget(value))
.cloned();
let parsed_contract = contract_raw.as_deref().and_then(contract::parse);
let now_unix = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0);
// Identity, in strict priority order:
// R1: a live foreground process matching a manifest — ground truth
// for what is running *now*; a user var is a message from the
// past and never overrides it.
// R2: otherwise, a contract that has not declared `ended` — either
// still fresh, or (for long-silent native emitters) proven live
// because the pane's foreground leader is unchanged since the
// contract was last emitted.
// R3: otherwise no agent: the record is evicted, so a pane that ran
// claude once stops being classified the moment claude is gone,
// and `cat` output can no longer impersonate a permission
// prompt.
let process_agent = identify::identify_by_process(pane);
let process_backed = process_agent.is_some();
let leader = identify::leader_path(pane);
// OSC 7501. A return from another process group to the shell ends that
// program's reports. The shell can itself be running a builtin or a
// function, so holding the foreground alone does not mean it is idle.
let mut program = pane.program_status();
let foreground = pane.foreground_process_group();
let unsettled: Vec<_> = program
.root
.iter()
.chain(&program.children)
.filter(|record| !record.orphaned)
.collect();
let returned_to_shell = !unsettled.is_empty()
&& unsettled.iter().all(|record| {
matches!((record.process_group, foreground), (Some(then), Some(now)) if then != now)
})
&& pane.shell_is_foreground() == Some(true);
if returned_to_shell {
// Only what was taken in before the look: a report the next command
// files meanwhile is that command's, and alive.
pane.end_program_status(program.latest_serial);
program = pane.program_status();
}
// A live root speaks with its own sub-tasks only: results an earlier
// program left behind are not this one's to show.
let mut children: Vec<ProgramStatusRecord> = match &program.root {
Some(root) if !root.orphaned => program
.children
.iter()
.filter(|child| !child.orphaned)
.cloned()
.collect(),
_ => program.children.clone(),
};
// A root can go while its sub-tasks' results stay -- a prompt drops a
// working root and keeps a failed child -- and the pane then speaks
// through them.
let root = program
.root
.clone()
.or_else(|| root_from_children(&children));
// Who filed it matters only while the root is live: a result left
// behind speaks for nobody running, whatever holds the foreground.
let from_foreground = match root.as_ref() {
Some(root) if !root.orphaned => report_from_foreground(
pane_id,
root,
foreground,
pane.root_process_id(),
),
_ => {
REPORT_FILERS.lock().remove(&pane_id);
true
}
};
if let Some(root) = root.as_ref().filter(|root| !root.orphaned) {
retain_report_children(pane_id, root, &mut children, pane.root_process_id());
}
let contract_identity = parsed_contract.as_ref().and_then(|c| {
if c.ended || process_agent.is_some() {
return None;
}
match REGISTRY.read().get(&pane_id) {
// A known pane must still have the emitter as its foreground
// leader — freshness alone is not liveness. An idle contract
// stays fresh forever and a working one for hours; without
// this check an agent that died without saying `ended=1`
// would pin its identity onto the shell. Only a definite
// mismatch (both sides observed, different) kills the
// identity: a transient probe failure must not evict.
Some(record) if record.agent_id == c.agent_id => {
let emitter_gone = matches!(
(&record.contract_leader, &leader),
(Some(recorded), Some(current)) if recorded != current
);
if emitter_gone {
return None;
}
// An unchanged *observed* leader is liveness — the soul
// case above depends on it. But when no emitter was ever
// observable (ssh/tmux/serial panes record no leader at
// all), the mismatch check can never fire, and the
// contract's own age becomes the only guard there is: a
// non-idle claim past CONTRACT_MAX_AGE with no re-emission
// is a dead agent, not a quiet one. Idle and ts-less
// contracts stay trusted (state_is_fresh), so a live agent
// sitting at its prompt is never aged out.
if record.contract_leader.is_none() && !contract::state_is_fresh(c, now_unix) {
return None;
}
}
// No history for this agent to validate against: only a
// fresh contract may establish identity, so a relic var
// cannot resurrect.
_ => {
if !contract::state_is_fresh(c, now_unix) {
return None;
}
}
}
Some(c.agent_id.clone())
});
let report = root.filter(|root| {
report_applies(
root,
process_agent.as_deref(),
contract_identity.is_some(),
from_foreground,
)
});
let report_state = report.as_ref().map(|root| match root.state {
ProgramState::Working => AgentState::Working,
ProgramState::Blocked => AgentState::Blocked,
ProgramState::Error => AgentState::Error,
ProgramState::Idle | ProgramState::Done | ProgramState::Clear => AgentState::Idle,
});
// R4: a program that reports its own state counts whatever it is. A
// report naming no program keeps an earlier name only when its source
// is still the same observed process group. An orphan cannot name the
// next live program, and an unknown source cannot establish continuity.
let report_identity = report.as_ref().map(|root| match root.app.as_deref() {
Some(app) => agent_id_for_app(Some(app)),
None => REGISTRY
.read()
.get(&pane_id)
.filter(|record| {
record.evidence == AgentEvidence::Report
&& root.process_group.is_some()
&& record.report_process_group == root.process_group
&& (!record.report_orphaned || root.orphaned)
})
.map(|record| record.agent_id.clone())
.unwrap_or_else(|| agent_id_for_app(None)),
});
let agent_id = process_agent.or(contract_identity).or(report_identity);
let Some(agent_id) = agent_id else {
let removed = REGISTRY.write().remove(&pane_id);
let had_record = removed.is_some();
let had_published = removed.and_then(|record| record.published).is_some();
if had_record {
// An agent just left: drop its identity cache entry so the
// next occupant is probed fresh, and clear its retained OSC
// signals so they cannot leak into whatever runs next. For a
// pane that never was an agent, the negative identification
// stays cached for its TTL — dropping it here would force a
// synchronous process probe per shell pane per round.
identify::forget_pane(pane_id);
pane.clear_agent_osc_evidence();
}
return had_published;
};
// Real emissions only: `get_title`/`get_progress` substitute display
// defaults (process basename, cleared progress) that would make the
// manifests' idle rules match unconditionally.
let osc = pane.agent_osc_evidence();
let mut title = osc.title.unwrap_or_default();
let mut progress = osc.progress.unwrap_or_default();
let now = Instant::now();
// Phase 1, read lock only: occupant turnover and verdict reuse. The
// write lock must not be held across the screen read and the manifest
// scan — `Pane::agent_status` is answered from dispatch and session
// handlers that must not stall behind another pane's evaluation.
// Read the seqno before taking the registry lock: get_current_seqno
// takes the terminal lock, and holding registry-then-terminal here
// would be a lock-order trap for any future terminal-then-registry
// path.
let current_seqno = pane.get_current_seqno();
let (turnover, reused_verdict) = {
let registry = REGISTRY.read();
let record = registry.get(&pane_id);
// A different agent or session replaces the record wholesale so
// nothing from the previous occupant carries over — including its
// retained OSC evidence, which the terminal still holds and which
// must not classify the new occupant for even one round.
let turnover = record
.map(|record| {
record.agent_id != agent_id
|| parsed_contract
.as_ref()
.map(|c| {
// Only a contract describing *this* agent can
// declare a session change; a relic var from a
// previous occupant must not tear the record
// down every round (which would also destroy
// the hysteresis window and the OSC evidence).
c.agent_id == record.agent_id
&& c.session_id.is_some()
&& record.session_id != c.session_id
})
.unwrap_or(false)
})
.unwrap_or(false);
let reused_verdict = if turnover {
None
} else {
record.and_then(|record| {
// While a guarded transition is being confirmed, the
// age-based reuse clause is suspended: counting a cached
// verdict as a confirmation would confirm against a stale
// observation and halve the effective debounce. Reuse on
// an unchanged seqno stays — an unmoved screen genuinely
// is evidence of stability.
let confirming = record.pending.is_open();
record
.screen_cache
.as_ref()
.filter(|c| {
c.generation == engine::manifest_generation()
&& c.title == title
&& c.progress == progress
&& (c.seqno == current_seqno
|| (!confirming
&& now.duration_since(c.at) < SCREEN_READ_FLOOR))
})
.map(|c| c.verdict)
})
};
(turnover, reused_verdict)
};
if turnover {
REGISTRY.write().remove(&pane_id);
pane.clear_agent_osc_evidence();
title.clear();
progress.clear();
}
// Phase 2, no lock: the screen read and the manifest scan -- unless the
// program has said where it is, which no screen rule can overrule.
let (verdict, fresh_cache) = match reused_verdict {
_ if report_state.is_some() => (CachedVerdict::NoMatch, None),
Some(verdict) => (verdict, None),
None => {
let screen = read_screen_tail(pane);
let verdict = match engine::evaluate(
&agent_id,
&engine::DetectionInput {
screen: &screen,
osc_title: &title,
osc_progress: &progress,
},
) {
engine::ScreenVerdict::State(state) => CachedVerdict::State(state),
engine::ScreenVerdict::Freeze => CachedVerdict::Freeze,
engine::ScreenVerdict::NoMatch => CachedVerdict::NoMatch,
};
// Stamped with the seqno captured *before* the read: output
// landing during evaluation must invalidate this verdict, and
// a pane that then blocks on input never advances the seqno
// again, so a post-read stamp would pin the stale verdict for
// good.
let cache = ScreenCache {
seqno: current_seqno,
title: title.clone(),
progress: progress.clone(),
at: now,
generation: engine::manifest_generation(),
verdict,
};
(verdict, Some(cache))
}
};
let contract_state = parsed_contract.as_ref().filter(|c| c.agent_id == agent_id).and_then(|c| {
if c.ended {
Some(AgentState::Idle)
} else if c.state != AgentState::Unknown && contract::state_is_fresh(c, now_unix) {
Some(c.state)
} else {
None
}
});
// Phase 3, write lock: apply. The registry may have changed while
// unlocked (a PaneRemoved eviction from another thread); re-fetching
// here keeps the apply self-consistent. A lost race can re-create a
// record for a removed pane; the safety tick pulses every registry id,
// so the next drain's get_pane miss evicts it.
let mut registry = REGISTRY.write();
let registry = &mut *registry;
// Before the placeholder insert below: a brand-new pane must present
// as "no previous state", not as the placeholder's Unknown.
let previous_state = registry.get(&pane_id).map(|r| r.state);
if let Some(cache) = fresh_cache {
if let Some(record) = registry.get_mut(&pane_id) {
record.screen_cache = Some(cache);
} else {
registry.insert(
pane_id,
AgentPaneRecord {
agent_id: agent_id.clone(),
session_id: None,
state: AgentState::Unknown,
evidence: AgentEvidence::Fallback,
since_unix: now_unix,
ended: false,
screen_cache: Some(cache),
published: None,
pending: Default::default(),
contract_raw: None,
contract_leader: None,
report_process_group: None,
report_orphaned: false,
},
);
}
}
let (state, evidence) = match verdict {
_ if report_state.is_some() => (
report_state.unwrap_or(AgentState::Idle),
AgentEvidence::Report,
),
CachedVerdict::State(state) => (state, AgentEvidence::Screen),
CachedVerdict::Freeze => match previous_state {
Some(state) => (state, AgentEvidence::Screen),
None => match contract_state {
Some(state) => (state, AgentEvidence::Contract),
None => (AgentState::Idle, AgentEvidence::Fallback),
},
},
CachedVerdict::NoMatch => match contract_state {
Some(state) => (state, AgentEvidence::Contract),
None => (AgentState::Idle, AgentEvidence::Fallback),
},
};
let record = registry.entry(pane_id).or_insert_with(|| AgentPaneRecord {
agent_id: agent_id.clone(),
session_id: None,
state,
evidence,
since_unix: now_unix,
ended: false,
screen_cache: None,
published: None,
pending: Default::default(),
contract_raw: None,
contract_leader: None,
report_process_group: None,
report_orphaned: false,
});
record.agent_id = agent_id;
record.report_process_group = report.as_ref().and_then(|root| root.process_group);
record.report_orphaned = report.as_ref().is_some_and(|root| root.orphaned);
if record.contract_raw != contract_raw {
// A (re-)emission: snapshot who the foreground leader was, so a
// later staleness check can tell "silent but alive" from "gone".
record.contract_raw = contract_raw;
record.contract_leader = leader;
}
match parsed_contract.as_ref() {
// Contract fields describe *this* agent only; a relic var from a
// previous occupant must not decorate the new one.
Some(c) if c.agent_id == record.agent_id => {
if c.session_id.is_some() {
record.session_id = c.session_id.clone();
}
// A live process outranks a claimed ending: `ended` is a
// farewell, and the process still being foreground means it
// was premature or belongs to a finished sub-session.
record.ended = c.ended && !process_backed;
}
_ => {
record.session_id = None;
}
}
// Guarded transitions keep publishing the held state until the raw
// observation proves stable; the first classification is never held.
let (state, evidence) = if record.published.is_some()
&& record.pending.should_hold(record.state, state, evidence, now)
{
(record.state, record.evidence)
} else {
(state, evidence)
};
if record.state != state {
record.state = state;
record.since_unix = now_unix;
}
record.evidence = evidence;
let status = AgentStatus {
agent_id: record.agent_id.clone(),
state: record.state,
evidence: record.evidence,
session_id: record.session_id.clone(),
since_unix: record.since_unix,
ended: record.ended,
report: program_report(report.as_ref(), &children),
};
if record.published.as_ref() == Some(&status) {
false
} else {
record.published = Some(status);
true
}
}
/// The agent id an OSC 7501 `app` stands for: the id ThinkTerm already
/// knows an agent by where the two differ, the app's own name otherwise.
fn agent_id_for_app(app: Option<&str>) -> String {
match app {
Some("claude-code") => "claude".to_string(),
Some(app) => app.to_string(),
None => "program".to_string(),
}
}
/// The process group a pane's OSC 7501 root came from.
struct ReportFiler {
/// Each receipt counts, including an identical payload sent again.
serial: u64,
/// The group in the foreground then; `None` where none could be seen.
group: Option<u32>,
/// The foreground last compared with `group`, and whether it descends
/// from it: walking the process table once per change, not per round.
checked: Option<(u32, bool)>,
/// Only groups in the current snapshot (at most MAX_RECORDS); replaced
/// on every evaluation and released with this root or pane.
children: Vec<(Option<u32>, bool)>,
}
/// Whether a pane's OSC 7501 root speaks for whatever holds the foreground
/// now: the program that was in front when the root was filed, or one it
/// handed the foreground to -- a pager, an editor. A root does not speak
/// for an unrelated program that took its place, named in it or not.
fn report_from_foreground(
pane_id: PaneId,
root: &ProgramStatusRecord,
foreground: Option<u32>,
pane_root: Option<u32>,
) -> bool {
let mut filers = REPORT_FILERS.lock();
if !filers.get(&pane_id).is_some_and(|filer| filer.serial == root.serial) {
// The parser recorded the foreground before this deferred evaluation.
// The current foreground may already belong to the next command.
filers.insert(
pane_id,
ReportFiler {
serial: root.serial,
group: root.process_group,
checked: None,
children: Vec::new(),
},
);
}
let Some(filer) = filers.get_mut(&pane_id) else {
return true;
};
match (filer.group, foreground) {
(Some(group), Some(now)) if group != now => match filer.checked {
Some((seen, verdict)) if seen == now => verdict,
_ => {
let verdict = descends_from(now, group, pane_root);
filer.checked = Some((now, verdict));
verdict
}
},
_ => true,
}
}
fn retain_report_children(
pane_id: PaneId,
root: &ProgramStatusRecord,
children: &mut Vec<ProgramStatusRecord>,
pane_root: Option<u32>,
) {
let mut filers = REPORT_FILERS.lock();
let Some(filer) = filers.get_mut(&pane_id) else {
return;
};
let mut checked: Vec<(Option<u32>, bool)> = Vec::with_capacity(children.len());
children.retain(|child| {
if let Some((_, belongs)) = checked.iter().find(|(group, _)| *group == child.process_group) {
return *belongs;
}
let belongs = filer.children
.iter()
.find(|(group, _)| *group == child.process_group)
.map(|(_, belongs)| *belongs)
.unwrap_or_else(|| match (root.process_group, child.process_group) {
(Some(root), Some(child)) if root != child => {
descends_from(child, root, pane_root) || descends_from(root, child, pane_root)
}
_ => true,
});
checked.push((child.process_group, belongs));
belongs
});
filer.children = checked;
}
/// Whether process `pid` is `ancestor` or descends from it, walking up
/// from `pid`: a step per parent, where walking down would collect the
/// ancestor's whole tree. The pane's own first process, `stop`, is as high
/// as a program the pane runs can reach.
#[cfg(not(test))]
fn descends_from(pid: u32, ancestor: u32, stop: Option<u32>) -> bool {
let mut at = pid;
// Deep enough for any wrapper chain; a loop in a racing table ends.
for _ in 0..16 {
if at == ancestor {
return true;
}
if Some(at) == stop || at <= 1 {
return false;
}
match procinfo::LocalProcessInfo::with_root_pid(at) {
Some(info) => at = info.ppid,
None => return false,
}
}
false
}
#[cfg(test)]
fn descends_from(pid: u32, ancestor: u32, _stop: Option<u32>) -> bool {
tests::fake_descends_from(pid, ancestor)
}
/// Whether a pane's OSC 7501 report speaks for what runs in it now.
fn report_applies(
root: &ProgramStatusRecord,
process_agent: Option<&str>,
contract: bool,
from_foreground: bool,
) -> bool {
// A result left behind by a program that has gone describes nothing
// running now: it speaks only while no agent does.
if root.orphaned {
return process_agent.is_none() && !contract;
}
// A report that names another program is not about this one.
if let (Some(agent), Some(app)) = (process_agent, root.app.as_deref()) {
if agent_id_for_app(Some(app)) != agent {
return false;
}
}
from_foreground
}
/// A pane's report when only sub-tasks are left: the most pressing of them
/// -- an error before a wait before work before a result -- stands in for
/// the root.
fn root_from_children(children: &[ProgramStatusRecord]) -> Option<ProgramStatusRecord> {
let rank = |state: ProgramState| match state {
ProgramState::Error => 0,
ProgramState::Blocked => 1,
ProgramState::Working => 2,
ProgramState::Done => 3,
ProgramState::Idle | ProgramState::Clear => 4,
};
// Live sub-tasks speak before results left behind, never mixed with
// them: the stand-in is left behind only when every one of them is.
let live = children.iter().any(|child| !child.orphaned);
let children: Vec<&ProgramStatusRecord> = children
.iter()
.filter(|child| !live || !child.orphaned)
.collect();
let child = children.iter().copied().min_by_key(|child| rank(child.state))?;
Some(ProgramStatusRecord {
serial: child.serial,
process_group: child.process_group,
id: None,
state: child.state,
kind: child.kind,
progress: None,
app: child.app.clone(),
title: None,
msg: child.msg.clone().or_else(|| child.title.clone()),
orphaned: !live,
})
}
/// A pane's OSC 7501 records in the shape every consumer receives them.
fn program_report(
root: Option<&ProgramStatusRecord>,
children: &[ProgramStatusRecord],
) -> Option<ProgramReport> {
fn state(state: ProgramState) -> ProgramReportState {
match state {
ProgramState::Working => ProgramReportState::Working,
ProgramState::Done => ProgramReportState::Done,
ProgramState::Blocked => ProgramReportState::Blocked,
ProgramState::Error => ProgramReportState::Error,
ProgramState::Idle | ProgramState::Clear => ProgramReportState::Idle,
}
}
fn kind(kind: wezterm_term::program_status::ProgramBlockedKind) -> ProgramBlockedKind {
use wezterm_term::program_status::ProgramBlockedKind as Kind;
match kind {
Kind::Permission => ProgramBlockedKind::Permission,
Kind::Question => ProgramBlockedKind::Question,
Kind::Auth => ProgramBlockedKind::Auth,
}
}
let root = root?;
Some(ProgramReport {
state: state(root.state),
kind: root.kind.map(kind),
progress: root.progress,
app: root.app.clone(),
title: root.title.clone(),
msg: root.msg.clone(),
children: children
.iter()
.take(ProgramReport::MAX_CHILDREN)
.filter_map(|child| {
Some(ProgramReportChild {
id: child.id.clone()?,
state: state(child.state),
kind: child.kind.map(kind),
progress: child.progress,
title: child.title.clone(),
msg: child.msg.clone(),
})
})
.take(ProgramReport::MAX_CHILDREN)
.collect(),
})
}
/// The pane's live screen bottom, independent of the user's scroll
/// position: scrollback sits below `physical_top`, so slicing from the
/// physical screen ignores the viewport.
fn read_screen_tail(pane: &dyn Pane) -> String {
let dims = pane.get_dimensions();
if dims.cols == 0 || dims.viewport_rows == 0 {
return String::new();
}
let last = dims.physical_top + dims.viewport_rows as isize;
let start = (last - TAIL_ROWS).max(dims.physical_top);
let (_first, lines) = pane.get_lines(start..last);
let mut text = String::new();
for line in &lines {
text.push_str(&line.as_str());
text.push('\n');
}
text
}
#[cfg(test)]
mod tests {
use super::*;
use crate::pane::{CachePolicy, ForEachPaneLogicalLine, LogicalLine, WithPaneLines};
use crate::renderable::*;
use crate::DomainId;
use parking_lot::MappedMutexGuard;
use rangeset::RangeSet;
use std::ops::Range;
use std::sync::atomic::AtomicUsize;
use std::sync::Arc;
use termwiz::surface::{Line, SequenceNo};
use url::Url;
use wezterm_term::color::ColorPalette;
use wezterm_term::{KeyCode, KeyModifiers, MouseEvent, StableRowIndex, TerminalSize};
static NEXT_PANE_ID: AtomicUsize = AtomicUsize::new(9000);
lazy_static::lazy_static! {
/// A process table for the tests: child pid to parent pid.
static ref FAKE_PARENTS: Mutex<HashMap<u32, u32>> = Mutex::new(HashMap::new());
}
pub(super) fn fake_descends_from(pid: u32, ancestor: u32) -> bool {
let parents = FAKE_PARENTS.lock();
let mut at = pid;
loop {
if at == ancestor {
return true;
}
match parents.get(&at) {
Some(parent) => at = *parent,
None => return false,
}
}
}
lazy_static::lazy_static! {
static ref PUBLISH_LOG: parking_lot::Mutex<Vec<PaneId>> =
parking_lot::Mutex::new(Vec::new());
}
/// Test sink for `publish_change`: no scheduler exists under
/// `cargo test`, so publications are recorded instead of notified.
pub(super) fn record_publish(pane_id: PaneId) {
PUBLISH_LOG.lock().push(pane_id);
}
/// Tests run in parallel and share the log; filter by the caller's
/// unique pane id.
fn publishes_for(pane_id: PaneId) -> usize {
PUBLISH_LOG.lock().iter().filter(|id| **id == pane_id).count()
}
/// One dirty-pane step exactly as `drain_and_evaluate` performs it.
fn drain_step(pane: &dyn Pane) {
if pane.render_state_is_contended() {
PENDING.lock().insert(pane.pane_id());
return;
}
if evaluate_pane(pane) {
publish_change(pane.pane_id());
}
}
/// Sequence tests run in microseconds, so the `SCREEN_READ_FLOOR`
/// reuse clause would serve every frame from cache and mask the very
/// transitions under test. Age the cache as a real 150ms round gap
/// would, then step.
fn drain_step_next_round(pane: &dyn Pane) {
if let Some(cache) = REGISTRY
.write()
.get_mut(&pane.pane_id())
.and_then(|record| record.screen_cache.as_mut())
{
if let Some(aged) = cache.at.checked_sub(SCREEN_READ_FLOOR * 2) {
cache.at = aged;
}
}
drain_step(pane);
}
struct FakeAgentPane {
id: PaneId,
screen: parking_lot::Mutex<String>,
title: parking_lot::Mutex<String>,
osc_evidence: parking_lot::Mutex<wezterm_term::AgentOscEvidence>,
user_vars: parking_lot::Mutex<HashMap<String, String>>,
seqno: AtomicUsize,
process: parking_lot::Mutex<Option<String>>,
argv: parking_lot::Mutex<Option<Vec<String>>>,
argv_probes: AtomicUsize,
probes: AtomicUsize,
remote_mirror: bool,
dead: AtomicBool,
/// When set, the next `get_lines` returns the current screen and
/// then applies this content and bumps the seqno -- emulating
/// output that lands while an evaluation is still running.
swap_after_read: parking_lot::Mutex<Option<String>>,
/// The parser holds the terminal: reading the pane would wait.
contended: AtomicBool,
program: parking_lot::Mutex<wezterm_term::program_status::ProgramStatusRecords>,
/// What `shell_is_foreground` answers.
shell_foreground: parking_lot::Mutex<Option<bool>>,
/// What `foreground_process_group` answers.
foreground_group: parking_lot::Mutex<Option<u32>>,
}
impl FakeAgentPane {
fn new(process: Option<&str>) -> Arc<Self> {
Arc::new(Self {
id: NEXT_PANE_ID.fetch_add(1, Ordering::SeqCst),
screen: parking_lot::Mutex::new(String::new()),
title: parking_lot::Mutex::new(String::new()),
osc_evidence: parking_lot::Mutex::new(Default::default()),
user_vars: parking_lot::Mutex::new(HashMap::new()),
seqno: AtomicUsize::new(1),
process: parking_lot::Mutex::new(process.map(|p| p.to_string())),
argv: parking_lot::Mutex::new(None),
argv_probes: AtomicUsize::new(0),
probes: AtomicUsize::new(0),
remote_mirror: false,
dead: AtomicBool::new(false),
swap_after_read: parking_lot::Mutex::new(None),
contended: AtomicBool::new(false),
program: parking_lot::Mutex::new(Default::default()),
shell_foreground: parking_lot::Mutex::new(None),
foreground_group: parking_lot::Mutex::new(None),
})
}
/// Put process group `group` in the foreground, with whether it is
/// the pane's own shell.
fn set_foreground(&self, group: u32, shell: bool) {
*self.foreground_group.lock() = Some(group);
*self.shell_foreground.lock() = Some(shell);
}
/// File an OSC 7501 report, as the program in the pane would.
fn report(
&self,
state: ProgramState,
app: Option<&str>,
edit: impl FnOnce(&mut wezterm_term::program_status::ProgramStatusReport),
) {
let mut report = wezterm_term::program_status::ProgramStatusReport {
state,
id: None,
kind: None,
progress: None,
app: app.map(str::to_string),
title: None,
msg: None,
};
edit(&mut report);
let group = *self.foreground_group.lock();
self.program.lock().apply_from(report, group);
self.seqno.fetch_add(1, Ordering::SeqCst);
}
fn set_screen(&self, text: &str) {
*self.screen.lock() = text.to_string();
self.seqno.fetch_add(1, Ordering::SeqCst);
}
fn set_contract(&self, value: &str) {
self.user_vars
.lock()
.insert(contract::USER_VAR_NAME.to_string(), value.to_string());
self.seqno.fetch_add(1, Ordering::SeqCst);
}
fn clear_contract(&self) {
self.user_vars.lock().remove(contract::USER_VAR_NAME);
self.seqno.fetch_add(1, Ordering::SeqCst);
}
fn set_osc_title(&self, title: &str) {
self.osc_evidence.lock().title = Some(title.to_string());
self.seqno.fetch_add(1, Ordering::SeqCst);
}
/// Arrange for `text` to land on the screen immediately after the
/// next `get_lines`, as terminal output arriving during an
/// evaluation does.
fn set_screen_after_next_read(&self, text: &str) {
*self.swap_after_read.lock() = Some(text.to_string());
}
/// Change the foreground process and drop the identity cache's
/// memory of this pane, as the 5s TTL would in real time.
fn set_process(&self, process: Option<&str>) {
*self.process.lock() = process.map(|p| p.to_string());
identify::forget_pane(self.id);
self.seqno.fetch_add(1, Ordering::SeqCst);
}
/// The leader's argv, as identification sees it when the leader
/// executable is a generic interpreter.
fn set_argv(&self, argv: &[&str]) {
*self.argv.lock() = Some(argv.iter().map(|a| a.to_string()).collect());
}
}
impl Pane for FakeAgentPane {
fn pane_id(&self) -> PaneId {
self.id
}
fn get_cursor_position(&self) -> StableCursorPosition {
StableCursorPosition::default()
}
fn get_current_seqno(&self) -> SequenceNo {
self.seqno.load(Ordering::SeqCst)
}
fn get_changed_since(
&self,
_lines: Range<StableRowIndex>,
_: SequenceNo,
) -> RangeSet<StableRowIndex> {
unimplemented!();
}
fn with_lines_mut(
&self,
_stable_range: Range<StableRowIndex>,
_with_lines: &mut dyn WithPaneLines,
) {
unimplemented!();
}
fn for_each_logical_line_in_stable_range_mut(
&self,
_lines: Range<StableRowIndex>,
_for_line: &mut dyn ForEachPaneLogicalLine,
) {
unimplemented!();
}
fn get_lines(&self, lines: Range<StableRowIndex>) -> (StableRowIndex, Vec<Line>) {
let all: Vec<Line> = self
.screen
.lock()
.lines()
.map(|l| Line::from_text(l, &Default::default(), 1, None))
.collect();
let start = lines.start.max(0) as usize;
let out: Vec<Line> = all
.into_iter()
.skip(start)
.take((lines.end - lines.start).max(0) as usize)
.collect();
if let Some(next) = self.swap_after_read.lock().take() {
*self.screen.lock() = next;
self.seqno.fetch_add(1, Ordering::SeqCst);
}
(lines.start, out)
}
fn get_logical_lines(&self, _lines: Range<StableRowIndex>) -> Vec<LogicalLine> {
unimplemented!();
}
fn get_dimensions(&self) -> RenderableDimensions {
let rows = self.screen.lock().lines().count().max(1);
RenderableDimensions {
cols: 120,
viewport_rows: rows,
scrollback_rows: rows,
physical_top: 0,
scrollback_top: 0,
..Default::default()
}
}
fn get_title(&self) -> String {
self.title.lock().clone()
}
fn agent_osc_evidence(&self) -> wezterm_term::AgentOscEvidence {
self.osc_evidence.lock().clone()
}
fn clear_agent_osc_evidence(&self) {
*self.osc_evidence.lock() = Default::default();
}
fn program_status(&self) -> wezterm_term::program_status::ProgramStatusSnapshot {
self.program
.lock()
.snapshot(wezterm_term::program_status::ProgramStatusRecords::MAX_RECORDS)
}
fn end_program_status(&self, through: u64) {
self.program.lock().end_of_program_through(through);
}
fn shell_is_foreground(&self) -> Option<bool> {
*self.shell_foreground.lock()
}
fn foreground_process_group(&self) -> Option<u32> {
*self.foreground_group.lock()
}
fn copy_user_vars(&self) -> HashMap<String, String> {
self.user_vars.lock().clone()
}
fn get_foreground_process_name(&self, _policy: CachePolicy) -> Option<String> {
self.probes.fetch_add(1, Ordering::SeqCst);
self.process.lock().clone()
}
fn get_foreground_process_argv(&self, _policy: CachePolicy) -> Option<Vec<String>> {
self.argv_probes.fetch_add(1, Ordering::SeqCst);
self.argv.lock().clone()
}
fn send_paste(&self, _text: &str) -> anyhow::Result<()> {
unimplemented!();
}
fn reader(&self) -> anyhow::Result<Option<Box<dyn std::io::Read + Send>>> {
unimplemented!();
}
fn writer(&self) -> MappedMutexGuard<'_, dyn std::io::Write> {
unimplemented!();
}
fn resize(&self, _size: TerminalSize) -> anyhow::Result<()> {
unimplemented!();
}
fn key_down(&self, _key: KeyCode, _mods: KeyModifiers) -> anyhow::Result<()> {
unimplemented!();
}
fn key_up(&self, _: KeyCode, _: KeyModifiers) -> anyhow::Result<()> {
unimplemented!();
}
fn mouse_event(&self, _event: MouseEvent) -> anyhow::Result<()> {
unimplemented!();
}
fn is_dead(&self) -> bool {
self.dead.load(Ordering::SeqCst)
}
fn render_state_is_contended(&self) -> bool {
self.contended.load(Ordering::SeqCst)
}
fn palette(&self) -> ColorPalette {
unimplemented!();
}
fn domain_id(&self) -> DomainId {
0
}
fn is_remote_mirror(&self) -> bool {
self.remote_mirror
}
fn is_mouse_grabbed(&self) -> bool {
false
}
fn is_alt_screen_active(&self) -> bool {
false
}
fn get_current_working_dir(&self, _policy: CachePolicy) -> Option<Url> {
None
}
}
fn now_unix() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_secs()
}
/// A pane whose parser holds its terminal is not read on the main
/// thread; it stays dirty and is read once the parser lets go.
#[test]
fn a_pane_whose_parser_holds_the_terminal_waits_for_the_next_round() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!(
"v1;agent=soul;state=working;session=s-1;ts={}",
now_unix()
));
pane.contended.store(true, Ordering::SeqCst);
drain_step(pane.as_ref() as &dyn Pane);
assert!(
status_for_pane(pane.pane_id()).is_none(),
"nothing was read through the held lock"
);
assert!(
PENDING.lock().remove(&pane.pane_id()),
"and the pane stays dirty for the next round"
);
pane.contended.store(false, Ordering::SeqCst);
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(
status_for_pane(pane.pane_id()).expect("read once free").agent_id,
"soul"
);
evict_pane(pane.pane_id());
}
#[test]
fn any_program_that_reports_its_state_counts() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/brew"));
pane.report(ProgramState::Working, Some("brew"), |report| {
report.progress = Some(25);
report.msg = Some("Upgrading 3 of 12".to_string());
report.id = None;
});
pane.program.lock().apply(wezterm_term::program_status::ProgramStatusReport {
state: ProgramState::Blocked,
id: Some("fetch".to_string()),
kind: Some(wezterm_term::program_status::ProgramBlockedKind::Auth),
progress: None,
app: None,
title: Some("Fetch".to_string()),
msg: None,
});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "brew");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Report);
let report = status.report.expect("the report travels with it");
assert_eq!(report.progress, Some(25));
assert_eq!(report.msg.as_deref(), Some("Upgrading 3 of 12"));
assert_eq!(report.children.len(), 1);
assert_eq!(report.children[0].kind, Some(ProgramBlockedKind::Auth));
evict_pane(pane.pane_id());
}
#[test]
fn a_program_report_outranks_the_screen() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen("✻ Thinking… (esc to interrupt)\n");
pane.report(ProgramState::Blocked, Some("claude-code"), |report| {
report.kind = Some(wezterm_term::program_status::ProgramBlockedKind::Permission);
report.msg = Some("Bash: npm test".to_string());
});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "claude");
assert_eq!(status.state, AgentState::Blocked);
assert_eq!(status.evidence, AgentEvidence::Report);
assert_eq!(
status.report.and_then(|report| report.kind),
Some(ProgramBlockedKind::Permission)
);
// An error is its own state, not a flavour of waiting.
pane.report(ProgramState::Error, Some("claude-code"), |_| {});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
assert_eq!(
status_for_pane(pane.pane_id()).map(|status| status.state),
Some(AgentState::Error)
);
evict_pane(pane.pane_id());
}
/// A report outlives its program only as a result left behind: once
/// the pane's shell has the foreground back, what was in progress is
/// over, and the result speaks only while nothing else runs.
#[test]
fn only_an_unseen_result_outlives_the_program_that_reported_it() {
// zsh is 9100; brew 9101 runs a pager 9102.
FAKE_PARENTS.lock().insert(9102, 9101);
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/brew"));
pane.set_foreground(9101, false);
pane.report(ProgramState::Working, Some("brew"), |_| {});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
// brew hands the foreground to its pager: it is still going.
pane.set_process(Some("/usr/bin/less"));
pane.set_foreground(9102, false);
evaluate_pane(pane.as_ref() as &dyn Pane);
assert_eq!(
status_for_pane(pane.pane_id()).map(|status| status.state),
Some(AgentState::Working)
);
// brew exits and the shell is back: nothing is in progress any more.
pane.set_process(Some("/bin/zsh"));
pane.set_foreground(9100, true);
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
assert!(status_for_pane(pane.pane_id()).is_none());
assert_eq!(pane.program_status(), Default::default());
// A failed result stays, as brew's own...
pane.set_process(Some("/opt/homebrew/bin/brew"));
pane.set_foreground(9101, false);
pane.report(ProgramState::Error, Some("brew"), |report| {
report.msg = Some("Download failed".to_string());
});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
pane.set_process(Some("/bin/zsh"));
pane.set_foreground(9100, true);
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("the result stays");
assert_eq!(status.agent_id, "brew");
assert_eq!(status.state, AgentState::Error);
// ...but does not speak for the agent started next in the pane.
pane.set_process(Some("/usr/local/bin/claude"));
pane.set_foreground(9103, false);
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("claude is running");
assert_eq!(status.agent_id, "claude");
assert_ne!(status.state, AgentState::Error);
assert_ne!(status.evidence, AgentEvidence::Report);
assert!(status.report.is_none());
evict_pane(pane.pane_id());
}
/// A program that left without the shell ever getting the foreground
/// back -- the next command of a chain took it straight away -- leaves
/// a report that names nobody. It is still not the new program's.
#[test]
fn an_unnamed_report_does_not_speak_for_a_program_that_took_its_place() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/tool"));
pane.set_foreground(9201, false);
pane.report(ProgramState::Done, None, |report| {
report.msg = Some("Built".to_string());
});
evaluate_pane(pane.as_ref() as &dyn Pane);
pane.set_process(Some("/usr/local/bin/claude"));
pane.set_foreground(9202, false);
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("claude is running");
assert_eq!(status.agent_id, "claude");
assert_ne!(status.evidence, AgentEvidence::Report);
assert!(status.report.is_none());
// Its own report speaks at once.
pane.report(ProgramState::Working, Some("claude-code"), |_| {});
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("claude reports");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Report);
evict_pane(pane.pane_id());
}
/// Sub-tasks an earlier program left behind are not the next agent's.
#[test]
fn left_behind_sub_tasks_stay_out_of_the_next_agents_report() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/brew"));
pane.set_foreground(9401, false);
pane.report(ProgramState::Working, None, |_| {});
pane.report(ProgramState::Error, None, |report| {
report.id = Some("fetch".to_string());
});
evaluate_pane(pane.as_ref() as &dyn Pane);
pane.set_process(Some("/bin/zsh"));
pane.set_foreground(9400, true);
evaluate_pane(pane.as_ref() as &dyn Pane);
pane.set_process(Some("/usr/local/bin/claude"));
pane.set_foreground(9402, false);
pane.report(ProgramState::Working, Some("claude-code"), |_| {});
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("claude reports");
assert_eq!(status.evidence, AgentEvidence::Report);
let report = status.report.expect("published");
assert!(report.children.is_empty(), "{:?}", report.children);
evict_pane(pane.pane_id());
}
#[test]
fn a_shell_builtin_keeps_its_report_until_the_prompt() {
let pane = FakeAgentPane::new(Some("/bin/sh"));
pane.set_foreground(9800, true);
pane.report(ProgramState::Blocked, Some("example"), |_| {});
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().state, AgentState::Blocked);
assert!(!pane.program_status().root.unwrap().orphaned);
// OSC 133's prompt marker is an explicit end even when the shell
// never handed its process group to an external command.
pane.program.lock().end_of_program();
evaluate_pane(pane.as_ref());
assert!(status_for_pane(pane.id).is_none());
evict_pane(pane.id);
}
/// OMP's shell tool emits nested OSC 133 command markers. The terminal
/// retires the OSC 7501 record at the `133;A` prompt, just as it does
/// when a real shell gets its prompt back. OMP's process and its
/// state-carrying title still identify and classify the pane.
#[test]
fn omp_title_survives_its_report_being_retired_by_a_nested_prompt() {
let pane = FakeAgentPane::new(Some("/home/u/.bun/bin/bun"));
pane.set_argv(&["bun", "/home/u/.bun/bin/omp", "--no-session"]);
pane.set_foreground(9301, false);
pane.set_osc_title("π ⠋ omp-probe");
pane.report(ProgramState::Working, Some("omp"), |_| {});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("omp reports");
assert_eq!(status.agent_id, "omp");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Report);
// The tool's shell prompt retires the report. The process and the
// title rules have to carry the pane from here.
pane.program.lock().end_of_program();
pane.set_osc_title("π ⠋ omp-probe");
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("omp still identified");
assert_eq!(status.agent_id, "omp");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Screen);
evict_pane(pane.pane_id());
}
#[test]
fn a_command_chain_does_not_attach_old_children_to_the_next_root() {
let pane = FakeAgentPane::new(Some("/usr/bin/example"));
pane.set_foreground(9811, false);
pane.report(ProgramState::Working, Some("example"), |_| {});
for n in 0..ProgramReport::MAX_CHILDREN {
pane.report(ProgramState::Blocked, None, |report| {
report.id = Some(format!("old-{n:02}"));
});
}
evaluate_pane(pane.as_ref());
// The next command reports before a prompt or an evaluator tick.
pane.set_process(Some("/usr/local/bin/claude"));
pane.set_foreground(9812, false);
pane.report(ProgramState::Working, Some("claude-code"), |_| {});
pane.report(ProgramState::Working, None, |report| {
report.id = Some("task".to_string());
});
evaluate_pane(pane.as_ref());
let report = status_for_pane(pane.id).unwrap().report.unwrap();
assert_eq!(report.children.len(), 1);
assert_eq!(report.children[0].id, "task");
// A cached decision has the same ownership boundary.
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().report.unwrap().children.len(), 1);
evict_pane(pane.id);
assert!(!REPORT_FILERS.lock().contains_key(&pane.id));
}
#[test]
fn children_reported_by_a_descendant_stay_with_the_root() {
FAKE_PARENTS.lock().insert(9822, 9821);
let pane = FakeAgentPane::new(Some("/usr/bin/example"));
pane.set_foreground(9821, false);
pane.report(ProgramState::Working, Some("example"), |_| {});
pane.set_foreground(9822, false);
pane.report(ProgramState::Blocked, None, |report| {
report.id = Some("task".to_string());
});
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().report.unwrap().children.len(), 1);
evict_pane(pane.id);
}
/// A program that names itself in some reports only keeps its name.
#[test]
fn a_report_naming_nobody_keeps_the_name_the_program_gave() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/brew"));
pane.set_foreground(9831, false);
pane.report(ProgramState::Working, Some("brew"), |_| {});
evaluate_pane(pane.as_ref() as &dyn Pane);
pane.report(ProgramState::Working, None, |report| {
report.progress = Some(40);
});
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("still brew");
assert_eq!(status.agent_id, "brew");
assert_eq!(status.report.and_then(|report| report.progress), Some(40));
evict_pane(pane.pane_id());
}
#[test]
fn an_unnamed_successor_does_not_borrow_the_previous_programs_name() {
let pane = FakeAgentPane::new(Some("/usr/bin/example"));
pane.set_foreground(9841, false);
pane.report(ProgramState::Working, Some("tool-a"), |_| {});
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().agent_id, "tool-a");
pane.set_foreground(9842, false);
pane.report(ProgramState::Working, None, |_| {});
evaluate_pane(pane.as_ref());
let status = status_for_pane(pane.id).unwrap();
assert_eq!(status.agent_id, "program");
assert_eq!(status.evidence, AgentEvidence::Report);
assert_eq!(status.state, AgentState::Working);
evict_pane(pane.id);
}
#[test]
fn an_unknown_report_source_cannot_inherit_a_program_name() {
let pane = FakeAgentPane::new(None);
pane.report(ProgramState::Working, Some("tool-a"), |_| {});
evaluate_pane(pane.as_ref());
pane.report(ProgramState::Working, None, |_| {});
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().agent_id, "program");
evict_pane(pane.id);
}
#[test]
fn an_orphaned_result_cannot_name_a_new_report_from_the_shell() {
let pane = FakeAgentPane::new(Some("/bin/sh"));
pane.set_foreground(9851, true);
pane.report(ProgramState::Done, Some("tool-a"), |_| {});
evaluate_pane(pane.as_ref());
pane.program.lock().end_of_program();
evaluate_pane(pane.as_ref());
pane.report(ProgramState::Working, None, |_| {});
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().agent_id, "program");
evict_pane(pane.id);
}
#[test]
fn a_report_naming_another_program_does_not_speak_for_the_agent() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.report(ProgramState::Done, Some("make"), |_| {});
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("claude is running");
assert_eq!(status.agent_id, "claude");
assert_ne!(status.evidence, AgentEvidence::Report);
assert!(status.report.is_none());
evict_pane(pane.pane_id());
}
#[test]
fn sub_task_results_speak_once_the_root_has_gone() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/tool"));
pane.set_foreground(9301, false);
pane.report(ProgramState::Working, Some("tool"), |_| {});
pane.report(ProgramState::Error, None, |report| {
report.id = Some("fetch".to_string());
report.msg = Some("404 Not Found".to_string());
});
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
// The shell is back: the working root goes, the failed sub-task
// stays, and still answers to its program's name.
pane.set_process(Some("/bin/zsh"));
pane.set_foreground(9300, true);
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("the sub-task's result");
assert_eq!(status.agent_id, "tool");
assert_eq!(status.state, AgentState::Error);
let report = status.report.expect("published");
assert_eq!(report.msg.as_deref(), Some("404 Not Found"));
assert_eq!(report.children.len(), 1);
evict_pane(pane.pane_id());
}
#[test]
fn contract_only_pane_classifies_from_user_var() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!(
"v1;agent=soul;state=working;session=s-1;ts={}",
now_unix()
));
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "soul");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Contract);
assert_eq!(status.session_id.as_deref(), Some("s-1"));
evict_pane(pane.pane_id());
}
#[test]
fn an_oversized_contract_clears_a_previously_retained_session() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_contract(&format!(
"v1;agent=claude;state=working;session=before;ts={}",
now_unix()
));
evaluate_pane(pane.as_ref() as &dyn Pane);
assert_eq!(
status_for_pane(pane.pane_id())
.unwrap()
.session_id
.as_deref(),
Some("before")
);
pane.set_contract(&format!(
"v1;agent=claude;state=working;session={};ts={}",
"x".repeat(513),
now_unix()
));
evaluate_pane(pane.as_ref() as &dyn Pane);
assert_eq!(status_for_pane(pane.pane_id()).unwrap().session_id, None);
evict_pane(pane.pane_id());
}
#[test]
fn screen_rules_classify_a_process_identified_pane() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "claude");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Screen);
evict_pane(pane.pane_id());
}
/// An npm-installed agent runs as `node <shim>`: the leader executable
/// says only "node", and the agent's name rides in argv. This is the
/// installation style the basename-only identifier was blind to.
#[test]
fn interpreter_wrapped_agent_identifies_through_argv() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/node"));
pane.set_argv(&["node", "/opt/homebrew/bin/claude"]);
pane.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "claude");
assert_eq!(status.state, AgentState::Working);
assert_eq!(status.evidence, AgentEvidence::Screen);
evict_pane(pane.pane_id());
// A plain interpreter with no agent in its argv stays unidentified.
let plain = FakeAgentPane::new(Some("/opt/homebrew/bin/node"));
plain.set_argv(&["node", "/opt/tools/build.js"]);
plain.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(!evaluate_pane(plain.as_ref() as &dyn Pane));
assert!(status_for_pane(plain.pane_id()).is_none());
evict_pane(plain.pane_id());
// A retitled interpreter (`process.title = "claude"` clobbered the
// argv block) identifies by the surviving argv[0].
let retitled = FakeAgentPane::new(Some("/opt/homebrew/Cellar/node/26.7.0/bin/node"));
retitled.set_argv(&["claude"]);
retitled.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(evaluate_pane(retitled.as_ref() as &dyn Pane));
let status = status_for_pane(retitled.pane_id()).expect("classified");
assert_eq!(status.agent_id, "claude");
evict_pane(retitled.pane_id());
}
/// The argv read is lazy: a leader that names the agent directly must
/// never pay for it, and an interpreter leader pays exactly once per
/// identity-cache window, not once per evaluation.
#[test]
fn argv_is_fetched_only_for_interpreter_leaders() {
let direct = FakeAgentPane::new(Some("/usr/local/bin/claude"));
direct.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(evaluate_pane(direct.as_ref() as &dyn Pane));
assert_eq!(direct.argv_probes.load(Ordering::SeqCst), 0);
evict_pane(direct.pane_id());
let wrapped = FakeAgentPane::new(Some("/usr/bin/node"));
wrapped.set_argv(&["node", "/opt/homebrew/bin/claude"]);
wrapped.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(evaluate_pane(wrapped.as_ref() as &dyn Pane));
assert_eq!(wrapped.argv_probes.load(Ordering::SeqCst), 1);
// A second evaluation inside the identity TTL serves the cached
// identity without another argv read (the unchanged verdict means
// evaluate_pane reports no state change — irrelevant here).
wrapped.set_screen("more output\n⏵⏵ Cooking… (esc to interrupt · 13s)\n");
let _ = evaluate_pane(wrapped.as_ref() as &dyn Pane);
assert_eq!(wrapped.argv_probes.load(Ordering::SeqCst), 1);
evict_pane(wrapped.pane_id());
}
/// A self-updating agent replaces its own binary; Linux then reports
/// the leader as `/path/claude (deleted)`. Identification must survive
/// that, or detection silently dies right after every agent update.
#[test]
fn replaced_binary_still_identifies_as_its_agent() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude (deleted)"));
pane.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "claude");
assert_eq!(status.evidence, AgentEvidence::Screen);
evict_pane(pane.pane_id());
}
/// codex draws its trust prompt near the top of the screen and leaves
/// the rest blank; on a 40-row terminal the prompt must still reach
/// the `top_non_empty_lines` rules rather than falling outside the
/// slice of the screen the engine is given.
#[test]
fn tall_screen_top_prompt_reaches_top_region_rules() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/codex"));
let mut screen = String::from(
"> You are in /Users/someone/project\n\
\n\
Do you trust the contents of this directory?\n\
\n\
> 1. Yes, continue\n\
2. No, quit\n",
);
screen.push_str(&"\n".repeat(34));
pane.set_screen(&screen);
drain_step(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(
status.state,
AgentState::Blocked,
"a trust prompt at the top of a tall screen must classify as blocked"
);
evict_pane(pane.pane_id());
}
/// Output that lands between the screen read and the verdict being
/// cached must not pin the stale verdict to the post-write seqno: a
/// pane that then blocks waiting for input emits nothing further, so
/// the seqno never moves again and the reuse clause would serve the
/// stale verdict forever.
#[test]
fn output_landing_during_evaluation_does_not_pin_stale_verdict() {
let blocked_screen = "Do you want to proceed?\n> 1. Yes\n2. No, and esc to cancel\n";
// Sanity: the prompt text below classifies as blocked when read
// normally, so a later failure means staleness, not a bad fixture.
let probe = FakeAgentPane::new(Some("/usr/local/bin/claude"));
probe.set_screen(blocked_screen);
drain_step(probe.as_ref() as &dyn Pane);
assert_eq!(
status_for_pane(probe.pane_id()).expect("probe classified").state,
AgentState::Blocked
);
evict_pane(probe.pane_id());
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
// The prompt lands while the engine is still evaluating the old
// screen: the read returns the working screen, then the write
// applies and the seqno advances before the verdict is cached.
pane.set_screen_after_next_read(blocked_screen);
drain_step(pane.as_ref() as &dyn Pane);
// This round legitimately reports the pre-write screen.
assert_eq!(
status_for_pane(pane.pane_id()).expect("classified").state,
AgentState::Working
);
// The pane now waits for input and emits nothing further. Later
// rounds must notice the prompt instead of serving the stale
// verdict; allow a few rounds for any guarded transition.
let mut state = AgentState::Working;
for _ in 0..4 {
drain_step_next_round(pane.as_ref() as &dyn Pane);
state = status_for_pane(pane.pane_id()).expect("classified").state;
if state == AgentState::Blocked {
break;
}
}
assert_eq!(
state,
AgentState::Blocked,
"the stale pre-write verdict must not survive on an unmoving seqno"
);
evict_pane(pane.pane_id());
}
#[test]
fn screen_verdict_overrides_contract_working() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!(
"v1;agent=claude;state=working;ts={}",
now_unix()
));
// The Esc-interrupt / permission-cancel shape: contract says
// working, the screen shows the idle prompt box.
pane.set_screen(
"previous output\n──────────────────────────────\n❯\n──────────────────────────────\n ? for shortcuts\n",
);
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.state, AgentState::Idle);
assert_eq!(status.evidence, AgentEvidence::Screen);
evict_pane(pane.pane_id());
}
#[test]
fn unidentified_pane_is_never_classified() {
let pane = FakeAgentPane::new(Some("/bin/zsh"));
pane.set_screen("~/src\n❯ \n");
assert!(!evaluate_pane(pane.as_ref() as &dyn Pane));
assert!(status_for_pane(pane.pane_id()).is_none());
}
#[test]
fn evict_pane_clears_the_registry() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!("v1;agent=soul;state=idle;ts={}", now_unix()));
evaluate_pane(pane.as_ref() as &dyn Pane);
assert!(status_for_pane(pane.pane_id()).is_some());
assert!(evict_pane(pane.pane_id()), "a published record was dropped");
assert!(status_for_pane(pane.pane_id()).is_none());
}
/// The PaneRemoved subscriber must evict silently: the notification
/// already tells clients, and publishing from inside Mux::notify
/// deadlocks the subscriber lock.
#[test]
fn pane_removed_evicts_without_publishing() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!("v1;agent=soul;state=working;ts={}", now_unix()));
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
// The subscriber body: evict and deliberately drop the result.
evict_pane(pane.pane_id());
assert_eq!(publishes_for(pane.pane_id()), 1, "eviction must not publish");
assert!(status_for_pane(pane.pane_id()).is_none());
}
const CODEX_QUESTION: &str = "\u{203a} fix the bug\n\n Which approach?\n \u{276f} 1. A\n 2. B\n\n press enter to confirm or esc to cancel\n";
const CLAUDE_QUESTION: &str = "\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\n Do you want to proceed?\n \u{276f} 1. Yes\n 2. No\n esc to cancel \u{b7} enter to confirm\n";
const CLAUDE_PROMPT_BOX: &str = "previous output\n\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\n\u{276f}\n\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\n ? for shortcuts\n";
const CLAUDE_WORKING: &str = "some output\n\u{23f5}\u{23f5} Cooking\u{2026} (esc to interrupt \u{b7} 12s)\n";
/// The user's original bug: switching an option in codex's question
/// form redraws the widget, one evaluation lands on the half-drawn
/// frame, and the published state used to flap Blocked→Idle→Blocked —
/// replaying the needs-input sound each time.
#[test]
fn codex_option_switch_stays_blocked() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/codex"));
pane.set_screen(CODEX_QUESTION);
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Blocked)
);
// Mid-redraw frame: the widget is briefly absent.
pane.set_screen("\u{203a} fix the bug\n");
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1, "transient frame is held");
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Blocked)
);
// Redraw complete: same question, still one waiting episode.
pane.set_screen(CODEX_QUESTION);
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1, "no republish, no re-ring");
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Blocked)
);
evict_pane(pane.pane_id());
}
/// Answering a claude permission form passes through a frame that
/// reads as idle before the spinner appears; that frame must never be
/// published (it used to clear the GUI's attention latch and announce
/// premature completion).
#[test]
fn claude_answer_completion_never_publishes_idle() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen(CLAUDE_QUESTION);
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Blocked)
);
pane.set_screen(CLAUDE_PROMPT_BOX);
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1, "idle frame is held");
for _ in 0..4 {
pane.set_screen(CLAUDE_WORKING);
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_ne!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Idle),
"idle must never surface"
);
}
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Working)
);
assert_eq!(publishes_for(pane.pane_id()), 2, "exactly blocked then working");
evict_pane(pane.pane_id());
}
/// The claude-relic case behind the `cat` misreport: once the agent
/// process is gone and no contract vouches for the pane, it must stop
/// being classified entirely.
#[test]
fn process_gone_without_contract_is_evicted() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen("some output\n\u{23f5}\u{23f5} Cooking\u{2026} (esc to interrupt \u{b7} 12s)\n");
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
// claude exits; the shell takes the foreground back and prints
// text that would match claude's blocked rules.
pane.set_process(Some("/bin/zsh"));
pane.set_screen("do you want to proceed? yes\nwaiting for permission\n");
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 2, "eviction is published");
assert!(status_for_pane(pane.pane_id()).is_none());
}
/// A live process is ground truth: a relic contract from a previous
/// occupant neither renames the agent nor decorates it with sessions.
#[test]
fn process_identity_overrides_contract_agent() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/codex"));
pane.set_contract(&format!(
"v1;agent=soul;state=working;session=s-9;ts={}",
now_unix()
));
drain_step(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.agent_id, "codex");
assert_eq!(status.session_id, None);
evict_pane(pane.pane_id());
}
/// An `ended=1` farewell is ignored while the process is still the
/// pane's foreground: it was premature, and hiding a live agent from
/// the panel would be wrong.
#[test]
fn ended_contract_with_live_process_keeps_screen_rules() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_contract(&format!("v1;agent=claude;state=idle;ts={};ended=1", now_unix()));
pane.set_screen("some output\n\u{23f5}\u{23f5} Cooking\u{2026} (esc to interrupt \u{b7} 12s)\n");
drain_step(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.state, AgentState::Working);
assert!(!status.ended);
evict_pane(pane.pane_id());
}
/// The soul case: a native emitter may sit silent long past contract
/// freshness. Its identity survives while the pane's foreground
/// leader is unchanged, and dies with it.
#[test]
fn contract_survives_while_leader_is_unchanged() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/soul"));
pane.set_contract(&format!("v1;agent=soul;state=working;ts={}", now_unix()));
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.agent_id),
Some("soul".to_string())
);
// Hours pass: the contract re-states something ancient, but the
// same soul binary still owns the pty.
pane.set_contract(&format!(
"v1;agent=soul;state=working;ts={}",
now_unix() - 8 * 60 * 60
));
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.agent_id),
Some("soul".to_string()),
"unchanged leader keeps the stale contract's identity alive"
);
// soul exits: the shell is foreground again, the stale contract
// is now a relic.
pane.set_process(Some("/bin/zsh"));
drain_step(pane.as_ref() as &dyn Pane);
assert!(status_for_pane(pane.pane_id()).is_none());
}
/// A contract-backed agent that dies without `ended=1` must not pin
/// its identity onto the shell: even a *fresh* contract (idle ones
/// never expire) dies with its recorded foreground leader.
#[test]
fn fresh_idle_contract_dies_with_its_leader() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/soul"));
pane.set_contract(&format!("v1;agent=soul;state=idle;ts={}", now_unix()));
drain_step(pane.as_ref() as &dyn Pane);
assert!(status_for_pane(pane.pane_id()).is_some());
// soul crashes; the shell takes the foreground back.
pane.set_process(Some("/bin/zsh"));
drain_step(pane.as_ref() as &dyn Pane);
assert!(
status_for_pane(pane.pane_id()).is_none(),
"a dead emitter's contract must not survive on freshness alone"
);
}
/// On panes that can never observe an emitter (ssh/tmux/serial: no
/// leader is ever recorded), the leader-mismatch crash detector is
/// structurally unreachable — contract age is the only guard left. A
/// stale non-idle claim there is a dead agent; idle and ts-less
/// claims stay trusted so quiet-but-alive agents are not aged out.
#[test]
fn unverifiable_contracts_expire_instead_of_pinning_forever() {
// Established fresh, then the var re-states something ancient —
// the same aging proxy contract_survives_while_leader_is_unchanged
// uses, but with no leader for the mismatch check to ever consult.
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!("v1;agent=soul;state=working;ts={}", now_unix()));
drain_step(pane.as_ref() as &dyn Pane);
assert!(status_for_pane(pane.pane_id()).is_some());
pane.set_contract(&format!(
"v1;agent=soul;state=working;ts={}",
now_unix() - 8 * 60 * 60
));
drain_step(pane.as_ref() as &dyn Pane);
assert!(
status_for_pane(pane.pane_id()).is_none(),
"a stale working claim with no observable emitter must expire"
);
// Idle never expires: a crashed-while-idle agent staying pinned is
// the accepted cost of never evicting a live one at its prompt.
let idle = FakeAgentPane::new(None);
idle.set_contract(&format!("v1;agent=soul;state=idle;ts={}", now_unix()));
drain_step(idle.as_ref() as &dyn Pane);
idle.set_contract(&format!(
"v1;agent=soul;state=idle;ts={}",
now_unix() - 8 * 60 * 60
));
drain_step(idle.as_ref() as &dyn Pane);
assert!(
status_for_pane(idle.pane_id()).is_some(),
"idle claims are trusted indefinitely"
);
evict_pane(idle.pane_id());
// No ts at all: trusted, per the documented contract grammar.
let tsless = FakeAgentPane::new(None);
tsless.set_contract("v1;agent=soul;state=working");
drain_step(tsless.as_ref() as &dyn Pane);
drain_step(tsless.as_ref() as &dyn Pane);
assert!(
status_for_pane(tsless.pane_id()).is_some(),
"a ts-less contract must not be aged out"
);
evict_pane(tsless.pane_id());
}
/// A transient probe failure (leader reads as None) must not evict:
/// only a definite leader change is proof the emitter is gone.
#[test]
fn probe_failure_does_not_evict_a_contract_identity() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/soul"));
pane.set_contract(&format!("v1;agent=soul;state=working;ts={}", now_unix()));
drain_step(pane.as_ref() as &dyn Pane);
assert!(status_for_pane(pane.pane_id()).is_some());
pane.set_process(None);
drain_step(pane.as_ref() as &dyn Pane);
assert!(
status_for_pane(pane.pane_id()).is_some(),
"an unobservable leader is unknown, not dead"
);
}
/// Reloading rules must drop cached screen verdicts: an unchanged
/// screen (same seqno) would otherwise keep serving conclusions
/// computed under the old rules indefinitely.
#[test]
fn reload_rules_clears_cached_screen_verdicts() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen(CLAUDE_WORKING);
drain_step(pane.as_ref() as &dyn Pane);
assert!(REGISTRY
.read()
.get(&pane.pane_id())
.and_then(|r| r.screen_cache.as_ref())
.is_some());
reload_rules();
assert!(
REGISTRY
.read()
.get(&pane.pane_id())
.and_then(|r| r.screen_cache.as_ref())
.is_none(),
"old-rule verdicts must not survive a reload"
);
evict_pane(pane.pane_id());
}
/// A relic contract from a previous occupant must not tear the record
/// down every round: that would republish per round and destroy the
/// hysteresis window, resurrecting the repeated needs-input ring.
#[test]
fn relic_contract_does_not_thrash_the_record() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/codex"));
pane.set_contract(&format!(
"v1;agent=soul;state=working;session=s-9;ts={}",
now_unix() - 60
));
pane.set_screen(CODEX_QUESTION);
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
// The mid-redraw frame must still be held: the relic contract's
// session must not have destroyed the pending window.
pane.set_screen("\u{203a} fix the bug\n");
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1, "hysteresis survives the relic");
pane.set_screen(CODEX_QUESTION);
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1, "no per-round republish");
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Blocked)
);
evict_pane(pane.pane_id());
}
/// A pane that never runs an agent keeps its negative identification
/// cached: repeated evaluations must not re-probe the process table.
#[test]
fn non_agent_pane_probes_are_cached() {
let pane = FakeAgentPane::new(Some("/bin/zsh"));
for _ in 0..3 {
drain_step(pane.as_ref() as &dyn Pane);
}
assert_eq!(
pane.probes.load(Ordering::SeqCst),
1,
"negative identification is cached for the TTL"
);
}
/// Working → Idle publishes only after consecutive confirmations.
#[test]
fn working_to_idle_confirms_before_publishing() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
pane.set_screen(CLAUDE_WORKING);
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
for expect_published in [1, 1, 1, 2] {
pane.set_screen(CLAUDE_PROMPT_BOX);
drain_step_next_round(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), expect_published);
}
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Idle)
);
evict_pane(pane.pane_id());
}
/// A displayable title exists on every pane, but only real OSC
/// emissions may drive the manifests' title/progress rules: with zero
/// evidence and an empty screen, claude must fall through to the
/// Idle fallback (leaving the contract tier reachable), and codex's
/// `osc_title_idle` (`\S`) must not fire.
#[test]
fn empty_osc_evidence_reaches_the_fallback_tier() {
for process in ["/usr/local/bin/claude", "/opt/homebrew/bin/codex"] {
let pane = FakeAgentPane::new(Some(process));
*pane.title.lock() = "zsh".to_string();
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.evidence, AgentEvidence::Fallback, "{process}");
assert_eq!(status.state, AgentState::Idle, "{process}");
evict_pane(pane.pane_id());
}
}
/// The same codex pane with a real (spinner-free) OSC title hits the
/// manifest's `osc_title_idle` rule: evidence flows once it exists.
#[test]
fn real_osc_title_feeds_the_screen_rules() {
let pane = FakeAgentPane::new(Some("/opt/homebrew/bin/codex"));
pane.set_osc_title("auto_order_sys");
evaluate_pane(pane.as_ref() as &dyn Pane);
let status = status_for_pane(pane.pane_id()).expect("classified");
assert_eq!(status.evidence, AgentEvidence::Screen);
assert_eq!(status.state, AgentState::Idle);
evict_pane(pane.pane_id());
}
/// A pane whose agent goes away publishes the eviction exactly once
/// when it happens through the evaluation path.
#[test]
fn dropped_agent_publishes_once() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!("v1;agent=soul;state=working;ts={}", now_unix()));
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 1);
pane.clear_contract();
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 2, "the drop is published");
drain_step(pane.as_ref() as &dyn Pane);
assert_eq!(publishes_for(pane.pane_id()), 2, "and only once");
assert!(status_for_pane(pane.pane_id()).is_none());
}
#[test]
fn republish_only_on_change() {
let pane = FakeAgentPane::new(None);
pane.set_contract(&format!("v1;agent=soul;state=working;ts={}", now_unix()));
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
// Same inputs, same status: no republish.
assert!(!evaluate_pane(pane.as_ref() as &dyn Pane));
pane.set_contract(&format!("v1;agent=soul;state=blocked;ts={}", now_unix()));
assert!(evaluate_pane(pane.as_ref() as &dyn Pane));
assert_eq!(
status_for_pane(pane.pane_id()).map(|s| s.state),
Some(AgentState::Blocked)
);
evict_pane(pane.pane_id());
}
#[test]
fn an_identical_report_from_the_next_process_is_a_new_emission() {
let pane = FakeAgentPane::new(Some("/usr/bin/example"));
pane.set_foreground(9501, false);
pane.report(ProgramState::Working, Some("example"), |_| {});
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().state, AgentState::Working);
// The next command in a chain reports the same initial state.
pane.set_process(Some("/usr/bin/example"));
pane.set_foreground(9502, false);
pane.report(ProgramState::Working, Some("example"), |_| {});
evaluate_pane(pane.as_ref());
assert_eq!(
status_for_pane(pane.id).map(|s| s.state),
Some(AgentState::Working),
"the new program emitted its own report"
);
evict_pane(pane.id);
}
#[test]
fn a_report_received_before_process_turnover_is_not_rebound_on_first_poll() {
let pane = FakeAgentPane::new(Some("/usr/bin/example"));
pane.set_foreground(9601, false);
pane.report(ProgramState::Done, None, |_| {});
// The short command exits before the evaluator gets a turn.
pane.set_process(Some("/usr/local/bin/claude"));
pane.set_foreground(9602, false);
pane.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
evaluate_pane(pane.as_ref());
let status = status_for_pane(pane.id).unwrap();
assert_eq!(status.agent_id, "claude");
assert_eq!(
status.state,
AgentState::Working,
"the report was emitted by the previous command"
);
evict_pane(pane.id);
}
#[test]
fn an_anonymous_result_does_not_override_a_working_successor() {
let pane = FakeAgentPane::new(Some("/usr/bin/example"));
pane.set_foreground(9701, false);
pane.report(ProgramState::Done, None, |_| {});
evaluate_pane(pane.as_ref());
pane.set_process(Some("/usr/local/bin/claude"));
pane.set_foreground(9702, false);
pane.set_screen("some output\n⏵⏵ Cooking… (esc to interrupt · 12s)\n");
evaluate_pane(pane.as_ref());
assert_eq!(status_for_pane(pane.id).unwrap().state, AgentState::Working);
evict_pane(pane.id);
}
}