forge_workspace/

session_task.rs

//! Per-session actor. Owns one `Arc<AgentHandle>`'s event drain
//! (`AgentHandle::take_events`) plus a per-session `Command`
//! receiver. Translates each [`AgentEvent`] into the matching
//! [`SessionUpdate`] envelope and emits onto the workspace-wide
//! fan-out, which hands one update to every subscriber. Mutates
//! [`DomainSession`] inline before each
//! emit so workspace-side projections stay current.
//!
//! `SessionTask::run` is the sole consumer of the AgentHandle event
//! stream.

use std::sync::Arc;

use forge_agent::AgentHandle;
use forge_agent::client::AgentEvent;
use forge_primitives::SessionId;

use parking_lot::Mutex;
use tokio::sync::mpsc;
use tracing::Instrument;

use crate::SessionSlot;
use crate::domain_session::{DomainSession, PendingAutoContinue};
use crate::handoff;
use crate::protocol::{
    Command, NoticeSeverity, PendingInteractionSlot, PromptSource, SessionUpdate,
};
use crate::update_fanout::UpdateFanout;

pub(crate) struct SessionTask {
    pub(crate) key: SessionSlot,
    pub(crate) handle: Arc<AgentHandle>,
    pub(crate) command_rx: mpsc::UnboundedReceiver<Command>,
    pub(crate) domain: Arc<Mutex<DomainSession>>,
    pub(crate) update_tx: UpdateFanout,
    /// Tracks whether the first `Connected` has been emitted. The
    /// second-and-beyond Connected on the same task drives
    /// `SessionUpdate::SessionReplaced` instead (covers `/new`,
    /// login, logout flows).
    pub(crate) connected_once: bool,
    /// Weak reference to the parent [`crate::Workspace`]. Used inside
    /// [`Self::translate_event`]'s `Connected` arm to call back into
    /// `Workspace::record_connected_session`
    /// so the project catalog stays current as freshly-spawned
    /// sessions reach Connected. `Weak` avoids the Workspace<->Task
    /// reference cycle (Workspace holds Task's command_tx; Task
    /// holds Workspace).
    pub(crate) workspace: std::sync::Weak<crate::Workspace>,
    /// Compactions this run has crossed, for the handoff policy's
    /// `after_compactions` backstop.
    pub(crate) compaction_count: u32,
    /// The handoff this session arrived by, while its first ten turns are
    /// measured. `None` for a session that arrived another way - the counts
    /// exist to tune the trigger, and a session nobody handed to has
    /// nothing to compare against.
    pub(crate) successor: Option<handoff::SuccessorWatch>,
    /// Fires as this task drops - after `run`'s exit path has disconnected
    /// the subprocess (waited it out up to the close-wait budget, then
    /// SIGKILLed it) - so a despawn can hold its worktree removal until
    /// the session's own child is reaped. Held for every exit, early
    /// returns and panics included, so a waiter never hangs on a task that
    /// ended some other way.
    pub(crate) teardown_done: Option<tokio::sync::watch::Sender<bool>>,
}

impl SessionTask {
    pub(crate) async fn run(mut self) {
        tracing::debug!(
            target: "forge_workspace::session_task",
            slot = %self.key.display(),
            "session task started"
        );
        // Take the agent's event receiver. The bridge seeds it on
        // spawn; if it's already been taken (future refactor double-
        // tapping), surface as ConnectionFailed + return.
        let Some(mut event_rx) = self.handle.take_events() else {
            tracing::error!(
                target: "forge_workspace::session_task",
                slot = %self.key.display(),
                "AgentHandle::take_events returned None; session task aborting"
            );
            self.emit(SessionUpdate::ConnectionFailed {
                key: self.key.clone(),
                message: "agent event receiver unavailable".to_owned(),
                fatal: false,
            });
            return;
        };

        // Forge-side display_name is known the instant the workspace
        // picks an account. Emit ForgeAccountIdentity now so welcome
        // rendering shows the right label from the first frame.
        if let Some(display_name) = self.handle.display_name() {
            self.emit(SessionUpdate::ForgeAccountIdentity { key: self.key.clone(), display_name });
        }

        loop {
            tokio::select! {
                maybe_event = event_rx.recv() => {
                    let Some(event) = maybe_event else { break; };
                    let event = self.declared_models_for_session(event);
                    if !self.translate_event(event) {
                        break;
                    }
                }
                maybe_cmd = self.command_rx.recv() => {
                    let Some(cmd) = maybe_cmd else { break; };
                    self.execute_command(cmd);
                }
            }
        }
        tracing::info!(
            target: "forge_workspace::session_task",
            slot = %self.key.display(),
            "session task exiting (agent event channel closed)"
        );
        // The agent-event / command channel closed - this session's
        // subprocess is gone. Release it from the pool + command_senders
        // so a later cron fire / projects-pane click sees it as
        // not-running and re-spawns cleanly, instead of dispatching a
        // `Command::Prompt` to the now-closed channel (which fails with
        // `SessionClosed` and is silently dropped, quietly stopping
        // durable crons for the project). Guarded on handle identity so
        // a superseded task (its session re-spawned under the same key)
        // doesn't wipe its successor's live entries.
        if let Some(workspace) = self.workspace.upgrade() {
            workspace.release_session_if_current(&self.key, &self.handle);
        }
        // Take the bridge's client slot and run the SDK's graceful
        // shutdown. Without this, release / despawn / reader-death left
        // the `claude` subprocess (and its reader/writer/stderr tasks)
        // alive until forge exited - the bridge holds the `Client` and
        // `Client` has no `Drop` of its own.
        self.handle.disconnect().await;
    }

    /// Replace a Connected event's CLI-advertised `available_models`
    /// with the session's org's declared models before `translate_event`
    /// sees it (covering both the `Connected` and `SessionReplaced`
    /// emits). Synchronous - the rows are read from config, not fetched.
    fn declared_models_for_session(&self, event: AgentEvent) -> AgentEvent {
        let AgentEvent::Connected {
            session_id,
            cwd,
            current_model,
            available_models: _,
            mode,
            history_updates,
            compaction_count,
        } = event
        else {
            return event;
        };
        // Declared models replace discovery: the picker rows are the
        // org's accounts' declared models, authored in forge.toml.
        let (available_models, canonical_model) = match self.workspace.upgrade() {
            Some(workspace) => (
                workspace.declared_models_for_session(&self.key),
                workspace.canonical_model_for_session(&self.key),
            ),
            None => (Vec::new(), None),
        };
        // The project's declared model names the session: it is what
        // forge stamped into the CLI's model slots and what every
        // model-name surface must show, rather than the id the CLI
        // resolved on its own.
        let current_model = match canonical_model {
            Some(model) => forge_primitives::CurrentModel {
                requested_id: Some(model.clone()),
                display_name_short: model.clone(),
                display_name_long: model,
                ..current_model
            },
            None => current_model,
        };
        AgentEvent::Connected {
            session_id,
            cwd,
            current_model,
            available_models,
            mode,
            history_updates,
            compaction_count,
        }
    }

    /// Translate one `AgentEvent` into the matching `SessionUpdate`.
    /// Updates `DomainSession` in-place before each emit.
    ///
    /// Returns `true` to keep the run loop running; `false` when the
    /// event is terminal for this task and the loop must exit (so the
    /// exit path releases the session and disconnects the subprocess).
    pub(crate) fn translate_event(&mut self, event: AgentEvent) -> bool {
        // **A frame is stamped as it crosses, before either half reads it.**
        // The CLI stamps assistant frames and tool results and nothing else -
        // not the prompt that OPENS a turn, not a system frame, not the result
        // that ends one - so a page served those rows had no stamp to anchor a
        // running turn's clock on, and read 0.0s until an assistant frame
        // landed. The stamp is this task's own receipt: a frame that carries
        // one keeps it.
        let mut event = event;
        if let AgentEvent::SdkMessage { msg, .. } = &mut event {
            msg.stamp_if_absent(&crate::install::rfc3339_now());
        }
        // First, update DomainSession in-place.
        let nudge_armed;
        // Whether this event closed a turn normally, which is the one
        // boundary a handoff may act on. Captured here because the domain
        // lock is released before the handoff runs.
        let turn_completed;
        let turn_cancelled;
        let turn_ended;
        let repo_nudge;
        let lost_prompts;
        {
            let mut guard = self.domain.lock();
            let moved = apply_event_to_domain(&mut guard, &event);
            nudge_armed = moved.nudge;
            repo_nudge = moved.repo_nudge;
            turn_completed = matches!(moved.turn_ended, Some(MovedTurnEnd::Complete { .. }));
            turn_cancelled = matches!(moved.turn_ended, Some(MovedTurnEnd::Cancelled));
            turn_ended = moved.turn_ended.is_some();
            lost_prompts = moved.lost_prompts;
            // The two sets that move whole are announced from the scope the
            // fold wrote in, so what goes out is what the core now holds -
            // and only when the fold moved it.
            if moved.monitors {
                self.emit(SessionUpdate::MonitorsChanged {
                    key: self.key.clone(),
                    monitors: guard.monitors.clone(),
                });
            }
            if moved.background_tasks {
                self.emit(SessionUpdate::BackgroundTasksChanged {
                    key: self.key.clone(),
                    tasks: guard.task_rows(),
                });
            }
            if moved.commands {
                self.emit(SessionUpdate::SlashCommandsChanged {
                    key: self.key.clone(),
                    commands: guard.available_commands.clone(),
                });
            }
            if moved.agents {
                self.emit(SessionUpdate::SubagentsChanged {
                    key: self.key.clone(),
                    subagents: guard.available_agents.clone(),
                });
            }
            if moved.cards {
                self.emit(SessionUpdate::SubagentCardsChanged {
                    key: self.key.clone(),
                    cards: guard.cards_snapshot.clone(),
                });
            }
            if moved.processes {
                self.emit(SessionUpdate::ProcessesChanged {
                    key: self.key.clone(),
                    // The walk the store now holds, which the clear left
                    // empty: the shape a client draws no section from.
                    snapshot: forge_agent::env::processes::ProcessSnapshot {
                        processes: Vec::new(),
                        scanned_at: std::time::SystemTime::now(),
                    },
                });
            }
            if let Some(ended) = &moved.turn_ended {
                match ended {
                    MovedTurnEnd::Complete { terminal_reason } => {
                        self.emit(SessionUpdate::TurnComplete {
                            key: self.key.clone(),
                            terminal_reason: *terminal_reason,
                        });
                    }
                    MovedTurnEnd::Cancelled => {
                        self.emit(SessionUpdate::TurnCancelled { key: self.key.clone() });
                    }
                }
            }
        }
        // The turn settled at the fold - completed, failed or cancelled - so
        // the seat is open with nothing in flight. **Written before the
        // boundary hooks**: `after_turn_ended` can start the next turn
        // synchronously (a parked handoff's judgment prompt goes through
        // `route` and commits `InTurn`), and an Idle write after it would
        // erase the turn now running.
        if turn_ended && let Some(workspace) = self.workspace.upgrade() {
            workspace.record_seat_state(&self.key, crate::store::sessions::SeatState::Idle);
        }
        // The CLI reported a repository mutation: re-read the seat's tree on
        // the frame, and for a published change look the PR up again.
        if let Some(pr_stale) = repo_nudge
            && let Some(workspace) = self.workspace.upgrade()
        {
            if pr_stale {
                workspace.note_code_change_published(&self.key);
            } else {
                workspace.note_repository_activity(&self.key);
            }
        }
        // A handoff acts only on a turn boundary: never mid-turn, and never
        // on a transport-died one. A cancelled judgment turn is the reader
        // stopping the prompt the brief was coming from, which ends the
        // handoff rather than finishing it.
        if turn_completed {
            self.after_turn_ended();
        }
        if turn_cancelled {
            self.abort_cancelled_handoff();
        }

        // Mirror Connected into the project catalog so the Projects
        // pane's drilldown reflects newly-spawned sessions without
        // forcing a full disk re-scan.
        if let AgentEvent::Connected { session_id, cwd, .. } = &event
            && !cwd.is_empty()
            && let Some(workspace) = self.workspace.upgrade()
        {
            // Skip the catalog mirror for workers. The projects pane
            // draws a project's own sessions from this catalog and its
            // workers from `live_workers`, so a mirrored worker would be
            // listed as one of the project's sessions - and it arrives
            // here before its JSONL carries the forge:worker tag that
            // keeps the boot scan from listing it.
            if workspace.worker_lookup_for_session(&self.key).is_none() {
                workspace.record_connected_session(cwd, session_id, None);
            }
        }

        match event {
            AgentEvent::Connected {
                session_id,
                cwd,
                current_model,
                available_models,
                mode,
                history_updates,
                compaction_count,
            } => {
                let read = history_updates.unwrap_or_default();
                // **The read becomes a window HERE, and the update carries
                // it.** A resume hands over the whole transcript, and every
                // consumer of it - the transport's copy seeded from the
                // update, every subscriber taking a clone of the update -
                // cuts it to the same window anyway. So the read's own size
                // (2.5GiB on the seat #2150 was filed from) may not ride the
                // update or be paid again per consumer: one cut, and the
                // window is what is handed over.
                let (mut window, shed) = crate::conversation_window::Window::tail_of(&read);
                let left_behind = shed.frames;
                // **The handover has no page to fold into yet.** The debt the
                // cut took from the newest turn rides the frames, so the
                // first counter it still carries absorbs it before the update
                // crosses - a resume of a thought-heavy turn otherwise serves
                // only the suffix.
                window.carry_thinking(shed);
                // **And the cut itself rides along.** A consumer holding the
                // window alone reads it as the conversation's front, and a
                // client's walk below the window would stop there rather than
                // crossing into the transcript - the floor a cursor below the
                // window is measured against is exactly what the window left
                // behind.
                //
                // The read goes before the window's second copy is taken, so
                // the peak is the window's rather than the transcript plus it.
                drop(read);
                let history = window.messages().to_vec();
                self.compaction_count = compaction_count;
                // The slot the task was spawned under, which the CLI's
                // own id never moves: it names the occupant, this names
                // the seat.
                let key = self.key.clone();
                // The session came up, so whatever failed here last is
                // over. This arm is where that clears rather than the
                // spawn entry: production hoists a domain straight into
                // `domain_handles` and never registers one, so a clear on
                // registration would never run at all.
                //
                // **A death the reader has not been shown does not hold
                // this record down.** It rides `died` and its own reason on
                // the row, so the lifecycle goes back to telling the truth
                // about NOW - a recovered, working seat reading Failed is
                // the same lie the issue was filed against, mirrored.
                if let Some(workspace) = self.workspace.upgrade() {
                    workspace.clear_spawn_failure(&key);
                    workspace.note_seat_connected(&key);
                }
                // Nothing re-keys on `Connected`: the task is
                // registered under the slot the CLI never moves, so
                // `pool`, `command_senders` and `domain_handles` are
                // already under the key every `Command` addresses. The
                // id is recorded against the slot's row below, which is
                // what a restart resumes the occupant from.
                // Worker sessions get their tag JSONL row written by
                // `apply_worker_tag_or_rollback`, which spawns a
                // detached tokio task. The helper checks live_workers
                // for a matching entry; for leads + non-worker
                // sessions this is a no-op (early return on
                // `worker_lookup_for_session` returning None).
                //
                // Critical: the helper fires on BOTH first-Connected
                // and subsequent Connecteds (the /new / login /
                // logout flow that enters via `connected_once`).
                // Each Connected carries a fresh session_id and the
                // worker's tag must travel to the new JSONL - a
                // post-/new JSONL left untagged is listed by the boot
                // scan as one of the project's own sessions instead of
                // being hidden as a worker's. Captured before the
                // if/else because both branches consume the `cwd` field.
                //
                // The detached task does an initial retry loop on
                // `Io(NotFound)` (claude writes the JSONL lazily on
                // first turn, so an idle-spawned worker has no file
                // at Connected). If retries exhaust on NotFound, the
                // worker still transitions to Running with
                // `needs_tag = true`; the opportunistic retry in
                // `handle_deliver_worker_prompt` catches the tag
                // when the first turn arrives. Non-NotFound errors
                // (permission denied, disk full, etc.) DO roll back:
                // release session + emit Removed.
                //
                // TODO(ved): lead sessions are currently never tagged
                // with `forge:lead`, which the catalog tolerates but
                // nobody relies on. Explicit lead tagging is a spec gap
                // we should close (apply the same retry pattern via a
                // sibling `apply_lead_tag_or_warn` that does NOT roll
                // back on failure - just warns).
                let cwd_for_tag = cwd.clone();
                // Captured before the branches below set it: a `/new`,
                // login or logout arrives as a Connected on a task that
                // has already connected once, and its row predates it.
                let replacing = self.connected_once;
                if replacing {
                    // A successor that is replaced before its ten turns is
                    // no longer the session the handoff wrote for. A
                    // reconnect of that same occupant keeps the watch: the
                    // ten prompts are still its own.
                    if self.successor.as_ref().is_none_or(|watch| watch.to != session_id) {
                        self.successor = None;
                    }
                    // A running handoff needs no separate end here: the
                    // connect's own `clear_runtime_identity` drops it with
                    // the occupant it belonged to, and the gate below hands
                    // back what the swap held.
                }
                if self.connected_once {
                    // Drop oneshots from the previous identity so parked
                    // forwarder tasks exit instead of waiting on
                    // tool_call_ids the new session will never produce.
                    // Each one is announced: a view drawing a dock from the
                    // request it folded would otherwise keep offering a
                    // prompt the core has let go.
                    let dropped: Vec<(String, Option<u64>)> = self
                        .domain
                        .lock()
                        .pending_interactions
                        .drain()
                        .map(|(tool_id, slot)| {
                            // A question names the round it was parked as, so
                            // the views dropping it drop the same one.
                            let question_index = match slot {
                                PendingInteractionSlot::Question { request, .. } => {
                                    Some(request.question_index)
                                }
                                PendingInteractionSlot::Permission { .. } => None,
                            };
                            (tool_id, question_index)
                        })
                        .collect();
                    for (tool_id, question_index) in dropped {
                        self.emit(SessionUpdate::PendingInteractionResolved {
                            key: self.key.clone(),
                            tool_id,
                            question_index,
                            answered_with: None,
                        });
                    }
                    // Everything parked for the replaced identity has no
                    // session left to drain it, so the bucket is dropped
                    // and any message in it is acknowledged back to its
                    // sender.
                    if let Some(workspace) = self.workspace.upgrade() {
                        workspace.expire_parked_for_slot(
                            &self.key,
                            crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                        );
                    }
                    // Same reason: the replaced identity never produces a
                    // Result, so the buffer this turn's review actions sit
                    // in would never be drained.
                    let caller = self.domain.lock().key.clone();
                    self.drain_review_activity_for(&caller);
                    // Session-scoped `/dictate` state dies with the
                    // identity too: a view mints a blank bucket for
                    // the replaced session, so an override left here
                    // would style a session that no longer exists
                    // while the readout claims the crate defaults.
                    // The device pick is NOT here - it is workspace
                    // state shared by every session and outlives the
                    // replacement.
                    {
                        let mut domain = self.domain.lock();
                        domain.dictate_overrides = crate::dictate::DictateOverrides::default();
                    }
                    // The store is not the first-Connected path's alone:
                    // every replacement adopts an id forge did not choose,
                    // and a boot resolves this session from its row.
                    if let Some(workspace) = self.workspace.upgrade() {
                        workspace.note_running_session_id(&self.key, &session_id);
                        // The listener set is keyed by seat, so a swap leaves
                        // it alone: the successor has to be told it is heard.
                        workspace.voice_occupant_changed(&self.key);
                    }
                    self.emit(SessionUpdate::SessionReplaced {
                        key: key.clone(),
                        session_id: SessionId::new(session_id.clone()),
                        cwd,
                        current_model,
                        available_models,
                        mode,
                        history,
                        dropped: left_behind,
                        compaction_count,
                    });
                    // After SessionReplaced so the echo lands on the
                    // bucket it kept: the cleared values re-affirm the
                    // blank state.
                    self.emit(SessionUpdate::DictateOverrides {
                        key: key.clone(),
                        overrides: crate::dictate::DictateOverrides::default(),
                    });
                    // **Only the successor the brief names consumes it.** A
                    // login or logout can replace the occupant while the swap
                    // is in flight, and that session is not the one the brief
                    // was written for - so it neither takes the brief nor
                    // draws a row it did not join. The gate closes either way:
                    // the seat is no longer the handoff's, and what it held is
                    // handed to whoever is here now.
                    let awaited_successor = self.workspace.upgrade().is_some_and(|workspace| {
                        workspace
                            .pending_brief_for(&key)
                            .is_some_and(|brief| brief.to == session_id)
                    });
                    // The swap's gate opens before the brief is delivered, so
                    // the brief itself is not taken by it - and what waited
                    // during the swap follows the brief, in arrival order.
                    let held = self.workspace.upgrade().map(|workspace| workspace.end_swap(&key));
                    if awaited_successor {
                        self.deliver_pending_brief(&key, &session_id);
                    }
                    // **The successor's measurement is armed HERE**, on the
                    // connect a handoff actually lands as - the replacement
                    // branch, not the first connect a boot would take. Its
                    // brief turn is the next boundary and is not one of the
                    // ten. A later reconnect of the same occupant keeps the
                    // watch it already has rather than restarting the ten.
                    if awaited_successor || self.successor.is_none() {
                        self.successor = self.workspace.upgrade().and_then(|workspace| {
                            workspace.handoff_for_successor(&key, &session_id).map(
                                |(record, predecessor_reads)| handoff::SuccessorWatch {
                                    to: record.to,
                                    turns: 0,
                                    predecessor_reads,
                                    measure_at_boundary: false,
                                },
                            )
                        });
                    }
                    if let (Some(workspace), Some(held)) = (self.workspace.upgrade(), held) {
                        for prompt in held {
                            let sender = prompt.sender.clone();
                            let first = prompt.text.lines().next().unwrap_or_default().to_owned();
                            // **The id the hold carried, not a fresh one.** The
                            // delivery frame and the transcript row already
                            // share it, and a cron's pairing is stored under
                            // it - a new id here would orphan the row's
                            // schedule (#1815).
                            //
                            // `route`, not `dispatch`: this is a re-delivery of
                            // words already recorded, not a new press, so it
                            // takes no dispatch entry's command handling.
                            let uuid = prompt.uuid;
                            if let Err(error) = workspace.route(Command::PromptUnder {
                                key: key.clone(),
                                text: prompt.text,
                                attachments: prompt.attachments,
                                uuid,
                                source: prompt.source,
                                dispatch_id: None,
                            }) {
                                tracing::warn!(
                                    target: "forge_workspace::session_task",
                                    event_name = "handoff_held_prompt_delivery_failed",
                                    slot = %key.display(),
                                    %error,
                                    "a prompt held during the handoff could not be delivered",
                                );
                                if let Some(sender) = sender {
                                    workspace.notice_undelivered_message(
                                        &sender,
                                        &key,
                                        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                                    );
                                } else {
                                    self.emit(SessionUpdate::Notice {
                                        key: key.clone(),
                                        severity: NoticeSeverity::Error,
                                        text: format!(
                                            "a prompt held during the handoff could not be delivered: {first}"
                                        ),
                                    });
                                }
                            }
                        }
                    }
                } else {
                    // **A git worker whose worktree is gone is failed BEFORE
                    // it is kicked, announced or handed its parked prompts.**
                    // Those are this branch's side effects, and doing them
                    // first announced a dead worker live and dispatched
                    // crons, Gotify, Slack and peer prompts into a session
                    // the failure then released (#1593).
                    if self
                        .workspace
                        .upgrade()
                        .is_some_and(|workspace| workspace.fail_worker_without_worktree(&self.key))
                    {
                        return false;
                    }
                    self.connected_once = true;
                    // When the connecting session is a project's lead and
                    // persists workers that are not live yet, dispatch
                    // one SpawnWorker per row. Idempotent via the
                    // live_workers gate - a reconnect after a transient
                    // failure skips re-spawn.
                    if let Some(workspace) = self.workspace.upgrade() {
                        let force_new = self.domain.lock().spawned_force_new;
                        maybe_respawn_workers_on_connected(&workspace, &self.key, force_new);
                        maybe_kick_worker_on_connected(&workspace, &self.key);
                        maybe_kick_lead_on_connected(&workspace, &self.key, &self.domain);
                        // A session that arrived by a handoff is measured for
                        // its first ten turns, which is what says whether the
                        // brief carried enough. This is the boot/resume
                        // path: any brief turn is already in the transcript,
                        // so nothing is skipped here.
                        self.successor = workspace
                            .handoff_for_successor(&self.key, &session_id)
                            .map(|(record, predecessor_reads)| handoff::SuccessorWatch {
                                to: record.to,
                                turns: 0,
                                predecessor_reads,
                                measure_at_boundary: false,
                            });
                    }
                    // A boot resolves a session from the store, so the id
                    // the CLI adopted is recorded rather than left to the
                    // next boot to guess wrong.
                    if let Some(workspace) = self.workspace.upgrade() {
                        workspace.note_running_session_id(&self.key, &session_id);
                        // A `/resume` on a seat with no live task arrives
                        // here rather than through `SessionReplaced`, so the
                        // successor is told it is heard on this path too.
                        workspace.voice_occupant_changed(&self.key);
                    }
                    self.emit(SessionUpdate::Connected {
                        key: key.clone(),
                        session_id: SessionId::new(session_id.clone()),
                        cwd,
                        current_model,
                        available_models,
                        mode,
                        history,
                        dropped: left_behind,
                        compaction_count,
                    });
                    // Everything parked for this session's slot while
                    // it was asleep, delivered in arrival order: peer
                    // prompts, then crons, then Gotify, then Slack. Each
                    // re-dispatches as a regular `Command::Prompt` so the
                    // prompt-delivery path handles it uniformly with
                    // user-typed prompts.
                    self.drain_parked();
                }
                // A connect on a slot whose last occupant died is not a
                // silent swap: the reader is told which session died and
                // whether this one resumed it or replaced it under a new id.
                // Announced once, by the first connect that answers the
                // death, whichever id it lands under; the record itself
                // stays until a reader is shown the seat AND this
                // announcement has gone out.
                if let Some(workspace) = self.workspace.upgrade()
                    && let Some(dead) = workspace.unannounced_death(&key)
                {
                    let text = if dead.as_str() == session_id.as_str() {
                        format!("The agent's session ended; forge resumed it ({session_id}).")
                    } else {
                        format!(
                            "The agent's session ended; forge restarted it under a new id ({dead} -> {session_id})."
                        )
                    };
                    self.emit(SessionUpdate::Notice {
                        key: key.clone(),
                        severity: NoticeSeverity::Error,
                        text,
                    });
                }
                // Re-tag must fire on BOTH first-Connected and
                // post-/new Connected paths: a /new writes a fresh
                // JSONL, and an untagged one is listed by the boot scan
                // as one of the project's own sessions.
                if let Some(workspace) = self.workspace.upgrade() {
                    // The spawn's row provenance rides the domain, so a
                    // rollback can tell a row this spawn minted from one
                    // a resume inherited. A replacement Connected is a
                    // `/new` re-tag of an established worker, whose row
                    // predates this connection and is not this one's to
                    // take.
                    let minted_row = !replacing && self.domain.lock().spawn_wrote_row;
                    workspace.apply_worker_tag_or_rollback(
                        &key,
                        &session_id,
                        &cwd_for_tag,
                        minted_row,
                    );
                }
                // **After the occupant's own frame**: a replacement resets the
                // page's conversation, so a row drawn before it would be
                // wiped before the reader saw it.
                self.settle_lost_queued(lost_prompts);
            }
            AgentEvent::ConnectionFailed { message, kind } => {
                let key = self.key.clone();
                // Before the release below takes the session with it: a
                // view reading the slot afterwards has nothing left to say
                // the attempt happened.
                if let Some(workspace) = self.workspace.upgrade() {
                    workspace.record_spawn_failure(&key, &message);
                    // An occupant that had been up and ended here died; the
                    // connect that next lands on the slot is told so and says
                    // which session it answers for. What rides on the row
                    // until a reader is shown the seat is the DEATH, not this
                    // failure - the recovering connect clears the failure as
                    // it always did, and `record_death` keeps the reason for
                    // the row. A spawn that never connected records none:
                    // nothing was running.
                    if self.connected_once
                        && let Some(occupant) = self.domain.lock().session_id.clone()
                    {
                        // WARN, and with the slot on it: this is the one line
                        // that says a seat's session ended, and a reader
                        // triaging it needs to know which seat.
                        tracing::warn!(
                            target: "forge_workspace::session_task",
                            event_name = "session_ended",
                            slot = %key.display(),
                            session_id = %occupant,
                            error = %message,
                            "the session's subprocess ended; the seat keeps the death until a reader is shown it",
                        );
                        workspace.note_seat_death(&key, &message);
                        workspace.record_death(&key, occupant, &message);
                    }
                    // **A healing seat's new occupant that never came up is
                    // a failed attempt, not a first spawn to surface.** The
                    // heal progress standing on the slot is what tells the
                    // two apart.
                    if !self.connected_once && workspace.heal_progress(&key).is_some() {
                        workspace.note_seat_death(&key, &message);
                    }
                }
                // A `/new` or `/resume` that fails to respawn ends the
                // live turn without a Result, so flush the turn's own
                // bookkeeping here.
                let caller = self.domain.lock().key.clone();
                self.drain_review_activity_for(&caller);
                // A spawn that never connected still holds everything
                // parked for its slot: drop the bucket and acknowledge any
                // message in it back to its sender, before the
                // user-visible ConnectionFailed lands.
                if let Some(workspace) = self.workspace.upgrade() {
                    workspace.expire_parked_for_slot(
                        &self.key,
                        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                    );
                    // A handoff whose successor never came up has no
                    // occupant to give its brief to; the row stays and
                    // `/resume <old-id>` is the recovery. A prompt held for
                    // that successor is told it did not run rather than
                    // vanishing with the swap.
                    workspace.clear_pending_brief(&self.key);
                    for prompt in workspace.end_swap(&self.key) {
                        // **A peer's sender hears it, the way the parked
                        // bucket answers one.** A cron or a person's prompt
                        // has no sender but the seat, so the seat is told.
                        if let Some(sender) = &prompt.sender {
                            workspace.notice_undelivered_message(
                                sender,
                                &self.key,
                                crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                            );
                            continue;
                        }
                        let first = prompt.text.lines().next().unwrap_or_default();
                        // The composer's mark for this press has no row coming
                        // either, so it is settled here rather than left
                        // saying "sending" for a prompt that never ran.
                        self.emit(SessionUpdate::PromptLifecycle {
                            key: self.key.clone(),
                            uuid: prompt.uuid,
                            state: "cancelled".to_owned(),
                        });
                        self.emit(SessionUpdate::Notice {
                            key: self.key.clone(),
                            severity: NoticeSeverity::Error,
                            text: format!(
                                "the handoff failed before this prompt could run: {first}"
                            ),
                        });
                    }
                    // Worker async spawn failure: classify the
                    // failure, dispatch a typed
                    // WorkerSpawnFailedNotice envelope to the lead's
                    // chat if the classifier identifies a worktree-
                    // creation failure, and roll back the
                    // WorkerEntry regardless of classifier outcome
                    // (parity with the sync rollback in
                    // handle_spawn_worker). Lead-session and
                    // non-worker callers see no behavioural change
                    // - this branch is a no-op for them.
                    workspace.handle_async_worker_spawn_failure(&key, &message, kind);
                }
                // Before the failure frame, while the page's pile is still
                // standing: the row draws over the pile's own card, and the
                // card settles with it.
                self.settle_lost_queued(lost_prompts);
                self.emit(SessionUpdate::ConnectionFailed {
                    key: key.clone(),
                    message,
                    fatal: false,
                });
                // **No machine turn survives the session's death.** A handoff
                // whose successor never came up and a compaction both end with
                // the subprocess, and a seat left holding the blocker would be
                // one nobody can type into. After the failure, so a client
                // reads the death first and the stand-down second.
                self.emit(SessionUpdate::MachineTurn { key: self.key.clone(), machine: None });
                // Terminal for this task: the spawn failed before any
                // Connected, so the pooled handle is dead and must not
                // survive it - otherwise the pool fast path hands the
                // dead handle back to every later click / cron fire /
                // peer ask and the retry "succeeds" into nothing.
                // Release both registrations (the resolved key the
                // workspace maps hold; `release_session_if_current` no-ops
                // on an absent key. The run loop then exits, so Drop's
                // expiry backstop fires too.
                if let Some(workspace) = self.workspace.upgrade() {
                    workspace.release_session_if_current(&self.key, &self.handle);
                }
                return false;
            }
            AgentEvent::PermissionRequest { session_id, request } => {
                let tool_call_id = request.tool_call.tool_call_id.clone();
                let wire_request = request;
                let (response_tx, response_rx) =
                    tokio::sync::oneshot::channel::<forge_primitives::PermissionOutcome>();
                {
                    let mut guard = self.domain.lock();
                    guard.pending_interactions.insert(
                        tool_call_id.clone(),
                        PendingInteractionSlot::Permission {
                            tx: response_tx,
                            request: Box::new(wire_request.clone()),
                        },
                    );
                }
                if let Some(workspace) = self.workspace.upgrade() {
                    workspace.note_ask(&self.key);
                }
                let answerable = self.update_tx.send_answering(SessionUpdate::PermissionRequest {
                    key: self.key.clone(),
                    tool_id: tool_call_id.clone(),
                    request: wire_request,
                });
                // Spawned for both outcomes: the forwarder is the only
                // consumer of `response_rx`, so without it a `Cancelled`
                // sent below is discarded and the bridge waits for ever.
                spawn_permission_response_forwarder(
                    Arc::clone(&self.handle),
                    response_rx,
                    session_id,
                    tool_call_id.clone(),
                );
                if !answerable {
                    // No subscriber can answer a permission prompt -
                    // either none is attached or none renders one.
                    // Send Cancelled through the forwarder's oneshot so
                    // the SDK callback unblocks rather than hanging the
                    // `claude` subprocess turn forever.
                    if let Some(pending) =
                        self.domain.lock().pending_interactions.remove(&tool_call_id)
                        && let PendingInteractionSlot::Permission { tx, .. } = pending
                    {
                        let _ = tx.send(forge_primitives::PermissionOutcome::Cancelled);
                        // An observer that folded the request keeps drawing
                        // it otherwise, and its answer reaches nothing.
                        self.emit(SessionUpdate::PendingInteractionResolved {
                            key: self.key.clone(),
                            tool_id: tool_call_id.clone(),
                            question_index: None,
                            answered_with: None,
                        });
                    }
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        tool_id = %tool_call_id,
                        "no subscriber can answer the PermissionRequest; orphaned oneshot cancelled"
                    );
                }
            }
            AgentEvent::QuestionRequest { session_id, request } => {
                let tool_call_id = request.tool_call.tool_call_id.clone();
                let wire_request = request;
                let (response_tx, response_rx) =
                    tokio::sync::oneshot::channel::<forge_primitives::QuestionOutcome>();
                {
                    let mut guard = self.domain.lock();
                    guard.pending_interactions.insert(
                        tool_call_id.clone(),
                        PendingInteractionSlot::Question {
                            tx: response_tx,
                            request: Box::new(wire_request.clone()),
                        },
                    );
                }
                if let Some(workspace) = self.workspace.upgrade() {
                    workspace.note_ask(&self.key);
                }
                let answerable = self.update_tx.send_answering(SessionUpdate::QuestionRequest {
                    key: self.key.clone(),
                    tool_id: tool_call_id.clone(),
                    request: wire_request,
                });
                // Spawned for both outcomes: the forwarder is the only
                // consumer of `response_rx`, so without it a `Cancelled`
                // sent below is discarded and the bridge waits for ever.
                spawn_question_response_forwarder(
                    Arc::clone(&self.handle),
                    response_rx,
                    session_id,
                    tool_call_id.clone(),
                );
                if !answerable {
                    // No subscriber can answer a question - either none
                    // is attached or none renders one. Send Cancelled
                    // through the forwarder's oneshot so the SDK callback
                    // unblocks rather than hanging the turn.
                    if let Some(pending) =
                        self.domain.lock().pending_interactions.remove(&tool_call_id)
                        && let PendingInteractionSlot::Question { tx, request, .. } = pending
                    {
                        let _ = tx.send(forge_primitives::QuestionOutcome::Cancelled);
                        // An observer that folded the request keeps drawing
                        // it otherwise, and its answer reaches nothing.
                        self.emit(SessionUpdate::PendingInteractionResolved {
                            key: self.key.clone(),
                            tool_id: tool_call_id.clone(),
                            question_index: Some(request.question_index),
                            answered_with: None,
                        });
                    }
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        tool_id = %tool_call_id,
                        "no subscriber can answer the QuestionRequest; orphaned oneshot cancelled"
                    );
                }
            }
            AgentEvent::McpOperationError { error, .. } => {
                self.emit(SessionUpdate::McpOperationError { key: self.key.clone(), error });
            }
            AgentEvent::PromptCancelResolved { uuid, cancelled } => {
                // A confirmed cancel drops the row here as well as at the
                // client: the CLI's own terminal frame for the prompt may be
                // the only other word, and a reader that asked to drop it must
                // not be left guessing.
                if cancelled {
                    self.domain.lock().drop_queued_prompt(&uuid);
                }
                self.emit(SessionUpdate::PromptCancelResolved {
                    key: self.key.clone(),
                    uuid: uuid.clone(),
                    cancelled,
                });
                // **A cancelled judgment prompt ends the handoff.** It can be
                // a real pile row (the client offers Backspace/Delete on it),
                // and a prompt that never runs never produces the turn whose
                // Result would finish the handoff.
                let is_judgment = {
                    let domain = self.domain.lock();
                    domain.handoff.judgment_uuid.as_deref() == Some(uuid.as_str())
                };
                if cancelled && is_judgment {
                    self.abort_handoff("the handoff's brief was cancelled; this session continues");
                }
            }
            AgentEvent::SetModeFailed { mode, message, .. } => {
                self.emit(SessionUpdate::SetModeFailed { key: self.key.clone(), mode, message });
            }
            AgentEvent::SetModelFailed { model, message, .. } => {
                self.emit(SessionUpdate::SetModelFailed { key: self.key.clone(), model, message });
            }
            AgentEvent::TurnError { message, class, .. } => {
                self.emit(SessionUpdate::TurnError {
                    key: self.key.clone(),
                    message,
                    class: Some(class),
                    terminal_reason: None,
                });
            }
            AgentEvent::ContextUsage {
                session_id,
                percentage,
                max_tokens,
                total_tokens,
                effective_max_tokens,
            } => {
                self.emit(SessionUpdate::ContextUsageSnapshot {
                    key: self.key.clone(),
                    percentage,
                    max_tokens,
                });
                self.evaluate_handoff_trigger(
                    &session_id,
                    percentage,
                    total_tokens,
                    effective_max_tokens,
                );
            }
            AgentEvent::McpSnapshot { servers, error, .. } => {
                self.emit(SessionUpdate::McpSnapshot { key: self.key.clone(), servers, error });
            }
            AgentEvent::SdkMessage { msg, .. } => {
                // The judgment turn is forge's own prompt, so the last
                // assistant text before it ends is the half it wrote.
                self.capture_judgment(&msg);
                // A rate-limit window that is not `allowed` proves the
                // bound account exhausted: report it so the gateway
                // cools the account down and drops this session's
                // binding - the CLI's next request re-selects. The
                // trigger is literal: `allowed_warning` and unknown
                // statuses rotate too, because a warning already means
                // the window is closing. The binding is keyed by the
                // segment the child's base URL was stamped with, which
                // is the id the child runs under.
                if let forge_primitives::Message::RateLimitEvent { rate_limit_info, .. } = &msg
                    && rate_limit_info.status != forge_primitives::RateLimitStatus::Allowed
                    && let Some(workspace) = self.workspace.upgrade()
                {
                    let reset_at = rate_limit_info.resets_at.and_then(|t| u64::try_from(t).ok());
                    if let Some(session_id) = self.session_id_string() {
                        workspace.gateway.report_rate_limit(
                            self.key.org(),
                            self.key.project(),
                            &session_id,
                            reset_at,
                        );
                    }
                }
                // Settle ONE turn at the boundary, so the in-flight guards
                // stop refusing once the turn ends. `Message::Result` is the
                // SDK's signal that the assistant turn has fully completed -
                // including a cancelled one, which lands as
                // `error_during_execution` - and `after_turn_ended` already
                // served it; `Message::Error` is the CLI's last-gasp
                // transport failure, after which no Result follows, so it
                // serves its own turn here. A prompt committed before this
                // frame landed stays outstanding: clearing the flag outright
                // would make a running seat read idle.
                if matches!(msg, forge_primitives::Message::Error { .. }) {
                    let mut guard = self.domain.lock();
                    guard.serve_turn();
                }
                if matches!(
                    msg,
                    forge_primitives::Message::Result { .. }
                        | forge_primitives::Message::Error { .. }
                ) {
                    let caller = self.domain.lock().key.clone();
                    // A delivery held off this turn goes out now, where it
                    // starts a turn of its own rather than folding into the
                    // one that just ended. Only a `Result` is a turn
                    // ended on a live session: an `Error` is the transport
                    // dying, and dispatching into it would drop the held
                    // prompt where nobody hears - the death path's own
                    // expiry tells its sender instead.
                    if matches!(msg, forge_primitives::Message::Result { .. })
                        && let Some(workspace) = self.workspace.upgrade()
                    {
                        crate::spawn::drain_turn_held_for_slot(&workspace, &self.key);
                    }
                    // Turn end: flush this session's accumulated review
                    // actions into one batched notice per review, routed to
                    // each review's submit origin.
                    self.drain_review_activity_for(&caller);
                }
                // The init frame is where the CLI says what it can do. The
                // pile needs `msg_lifecycle_v1`: without it nothing settles a
                // queued row, so the seat stops recording them rather than
                // birthing cards that can never drain. Read here rather than
                // in a view, because what a view then draws follows from what
                // the core recorded.
                if let forge_primitives::Message::System { subtype, data, .. } = &msg
                    && subtype == "init"
                {
                    let advertised =
                        data.get("capabilities").and_then(serde_json::Value::as_array).is_some_and(
                            |caps| caps.iter().any(|cap| cap.as_str() == Some("msg_lifecycle_v1")),
                        );
                    let first_sight = {
                        let mut guard = self.domain.lock();
                        let first = guard.lifecycle_frames.is_none();
                        if first {
                            guard.lifecycle_frames = Some(advertised);
                        }
                        first
                    };
                    if first_sight && !advertised {
                        // **The first prompt can already be waiting.** The
                        // capability is only known from this frame, and the
                        // CLI's first user message lands before it - so a
                        // prompt recorded while the flag was `None` would
                        // never be settled by a frame. Draw every person's
                        // row now, the only carrier it will get, and settle
                        // the pile.
                        let held = { self.domain.lock().take_queued_prompts() };
                        for prompt in held {
                            if prompt.source == PromptSource::You {
                                self.emit_prompt_row(
                                    &prompt.text,
                                    &prompt.attachments,
                                    &prompt.uuid,
                                    prompt.source,
                                );
                            }
                            // The state only drains the card and releases the
                            // held row; no CLI frame follows on this seat.
                            self.emit(SessionUpdate::PromptLifecycle {
                                key: self.key.clone(),
                                uuid: prompt.uuid,
                                state: "started".to_owned(),
                            });
                        }
                        tracing::warn!(
                            target: "forge_workspace::session_task",
                            slot = %self.key.display(),
                            event_name = "lifecycle_frames_absent",
                            outcome = "pile_disabled",
                            "this session's CLI does not advertise msg_lifecycle_v1, so queued \
                             prompts cannot be followed here; the pile is not drawn for this seat, \
                             its waiting rows drew on this frame and later prompts draw at dispatch",
                        );
                    }
                }
                // A prompt's queue state is state, not conversation: the
                // prompt's own presence in the record is the transcript's
                // enqueue row and the `queued_command` attachment, and
                // retaining three frames per prompt would put three rows for
                // it into every view's transcript under rule 25. It advances
                // the pile and is emitted, then the conversation path below is
                // skipped entirely.
                if let forge_primitives::Message::CommandLifecycle { command_uuid, state, .. } =
                    &msg
                {
                    // **The judgment prompt's own start is what makes the
                    // next turn end its turn.** Without that, the end of any
                    // other turn (a continuation, a prompt sent before the
                    // decision) would be read as the reply the brief is
                    // built from.
                    let judgment_settled_short = {
                        let mut domain = self.domain.lock();
                        let is_judgment =
                            domain.handoff.judgment_uuid.as_deref() == Some(command_uuid.as_str());
                        let started_before = domain.handoff.judgment_started;
                        if is_judgment && matches!(state.as_str(), "started" | "completed") {
                            domain.handoff.judgment_started = true;
                        }
                        is_judgment
                            && (matches!(state.as_str(), "cancelled" | "discarded" | "refused")
                                // A `completed` with no `started` before it is a
                                // prompt the CLI settled without running.
                                || (state == "completed" && !started_before))
                    };
                    // **The page takes the prompt's row here, when the CLI
                    // starts it** (#2816): the queue announced the words while
                    // they waited, and a row forged at dispatch sat above the
                    // answer the running turn was still writing. Read before
                    // the advance, because `started` is a settled state and
                    // the entry leaves the pile as its row arrives.
                    let started_row = (state == "started")
                        .then(|| self.domain.lock().queued_prompt(command_uuid).cloned())
                        .flatten()
                        .filter(|prompt| prompt.source == PromptSource::You);
                    let known = { self.domain.lock().advance_queued_prompt(command_uuid, state) };
                    // **A judgment prompt the CLI settles without running
                    // ends the handoff**, for the same reason a reader's
                    // cancel does: no turn will ever finish it.
                    if judgment_settled_short {
                        self.abort_handoff(&format!(
                            "the handoff's brief was {state}; this session continues"
                        ));
                    }
                    // Only the states that IMPLY a row: a prompt's `completed`
                    // or `cancelled` follows the row's own removal at
                    // `started`, so logging those would be one false alarm per
                    // prompt, and an alarm nobody can act on is noise.
                    if !known && matches!(state.as_str(), "queued" | "started") {
                        tracing::debug!(
                            target: "forge_workspace::session_task",
                            slot = %self.key.display(),
                            uuid = %command_uuid,
                            state = %state,
                            "lifecycle frame for a prompt this session never recorded",
                        );
                    }
                    // **Before the lifecycle frame**, so a view holds the row
                    // and drains it when the state lands rather than drawing
                    // the announcement's bare words first.
                    if let Some(prompt) = started_row {
                        self.emit_prompt_row(
                            &prompt.text,
                            &prompt.attachments,
                            &prompt.uuid,
                            prompt.source,
                        );
                    }
                    // **A queued prompt the CLI starts is a turn start like
                    // any other.** `route` writes `in_turn` only when its
                    // prompt commits a turn; one queued behind a running turn
                    // does not, so this frame is the first moment the row can
                    // learn that turn is running. Without it a crash in a
                    // queued turn leaves `idle`, and the next boot sends no
                    // note.
                    if state == "started"
                        && let Some(workspace) = self.workspace.upgrade()
                    {
                        workspace.record_seat_state(
                            &self.key,
                            crate::store::sessions::SeatState::InTurn,
                        );
                    }
                    self.emit(SessionUpdate::PromptLifecycle {
                        key: self.key.clone(),
                        uuid: command_uuid.clone(),
                        state: state.clone(),
                    });
                } else {
                    // **A compaction boundary is a frame like any other.** It
                    // stays in the conversation the transport holds; the count
                    // is the scalar the handoff policy reads.
                    if matches!(&msg, forge_primitives::Message::CompactBoundary { .. }) {
                        self.compaction_count = self.compaction_count.saturating_add(1);
                    }
                    let msg = self.attribute_dispatch(msg);
                    // `None` either way: a frame off the wire is the CLI's
                    // own, and carries no sender.
                    self.emit(SessionUpdate::ChatAppended {
                        key: self.key.clone(),
                        msg,
                        source: None,
                    });
                }
            }
            AgentEvent::HookObservation {
                tool_use_id,
                permission_mode,
                effort,
                agent_id,
                agent_type,
                ..
            } => {
                self.emit(SessionUpdate::HookObservation {
                    key: self.key.clone(),
                    tool_use_id,
                    permission_mode,
                    effort,
                    agent_id,
                    agent_type,
                });
            }
        }
        // Last, so the failure's own frames are emitted before the words
        // that answer them draw below them: the continuation goes out here
        // rather than from a sweep, the seat's next turn starting while
        // the failure is still the newest thing a reader has seen.
        if nudge_armed && let Some(workspace) = self.workspace.upgrade() {
            workspace.fire_auto_continue(&self.key);
        }
        true
    }

    /// Record a prompt as waiting and announce it: the row's words and sender
    /// ride [`SessionUpdate::PromptQueued`], where the lifecycle frames carry
    /// only the id and the state.
    ///
    /// Returns `false` for a session whose CLI has said it does not carry
    /// those frames: a row nothing can settle is worse than no row, and the
    /// caller draws the prompt at dispatch instead, the way it did before the
    /// pile existed.
    fn record_queued(
        &self,
        uuid: &str,
        source: PromptSource,
        text: &str,
        attachments: &[forge_primitives::ImageAttachment],
    ) -> bool {
        {
            let mut guard = self.domain.lock();
            if guard.lifecycle_frames == Some(false) {
                return false;
            }
            guard.record_queued_prompt(uuid, source, text, attachments.to_vec());
        }
        self.emit(SessionUpdate::PromptQueued {
            key: self.key.clone(),
            uuid: uuid.to_owned(),
            source,
            text: text.to_owned(),
        });
        true
    }

    /// The row a person's prompt draws.
    ///
    /// **Emitted at `started` wherever the CLI can follow a queue** (#2816):
    /// the CLI takes a prompt sent while a turn runs at its own start - at
    /// that turn's end, or absorbed into the running turn - and emits
    /// `command_lifecycle: started` then, so a row forged at dispatch drew
    /// above the answer still being written. The held copy needs it here for
    /// the other half: the CLI never echoes a stdin prompt on the wire, so
    /// this frame is the page's only carrier of the reader's own words.
    ///
    /// **Two fallbacks draw at dispatch**, because no `started` is coming: a
    /// CLI that cannot follow a queue, and a dispatch that fails after the
    /// prompt was recorded. An occupant that dies or is replaced draws the
    /// queued rows on the connect or the failure frame instead.
    fn emit_prompt_row(
        &self,
        text: &str,
        attachments: &[forge_primitives::ImageAttachment],
        uuid: &str,
        source: PromptSource,
    ) {
        let images = forge_primitives::display_blocks(attachments);
        let mut framed = forge_primitives::Message::display_only_user_with_blocks(
            text.to_owned(),
            images,
            uuid.to_owned(),
        );
        framed.stamp_if_absent(&crate::install::rfc3339_now());
        self.emit(SessionUpdate::ChatAppended {
            key: self.key.clone(),
            msg: framed,
            source: Some(source),
        });
    }

    /// Settle the prompts still in the queue when the occupant went.
    ///
    /// **No row is forged for one that never started.** A live row would have
    /// no read carrier: the transcript keeps only the enqueue attachment and
    /// no start, so a reload would drop it and the two paths would disagree.
    /// The pile's ending line carries the words instead, the same carrier a
    /// refused or discarded prompt uses, and the card settles with it.
    fn settle_lost_queued(&self, prompts: Vec<crate::protocol::QueuedPrompt>) {
        for prompt in prompts {
            // **The words are re-announced so the ending line can carry them.**
            // A replacement may already have reset the page's queue to an
            // empty read; the announcement restores the row the discarded
            // state then turns into the one line. A page that still holds the
            // row ignores it by uuid.
            self.emit(SessionUpdate::PromptQueued {
                key: self.key.clone(),
                uuid: prompt.uuid.clone(),
                source: prompt.source,
                text: prompt.text,
            });
            self.emit(SessionUpdate::PromptLifecycle {
                key: self.key.clone(),
                uuid: prompt.uuid,
                state: "discarded".to_owned(),
            });
        }
    }

    fn execute_command(&mut self, cmd: Command) {
        // **The judgment prompt is the one the swap's gate lets through.**
        // Recognised by the id the handoff recorded for it, so nothing else
        // can pass on its word.
        let judgment_prompt = matches!(
            &cmd,
            Command::PromptUnder { uuid, .. }
                if self.domain.lock().handoff.judgment_uuid.as_deref() == Some(uuid.as_str())
        );
        // A person's prompt arriving while the seat swaps its occupant waits
        // for the successor, exactly as a peer or cron delivery does. It is
        // held before its queued row is recorded, because no session is
        // going to run it here.
        if !judgment_prompt && held_while_swapping(&cmd, &self.key, &self.workspace) {
            return;
        }
        // A prompt's queued row is recorded here, where its id is minted (or
        // is already the caller's) and its source is known: the lifecycle
        // frames that follow name only the id and the state, so this is the
        // one moment that can say what is waiting and who sent it.
        let cmd = match cmd {
            Command::Prompt { key, text, attachments } => {
                let uuid = forge_sdk::request_id::next_prompt_id();
                if !self.record_queued(&uuid, PromptSource::You, &text, &attachments) {
                    self.emit_prompt_row(&text, &attachments, &uuid, PromptSource::You);
                }
                Command::PromptUnder {
                    key,
                    text,
                    attachments,
                    uuid,
                    source: PromptSource::You,
                    dispatch_id: None,
                }
            }
            Command::PromptUnder { key, text, attachments, uuid, source, dispatch_id } => {
                // The continuation speaks for the occupant that failed. A
                // `/new` or `/resume` the queue drains ahead of it leaves a
                // replacement under the words, which point at a history the
                // replacement does not carry - so the prompt is dropped
                // rather than handed to it.
                if self.continuation_lost_its_occupant(&uuid) {
                    // The seat's own work, not forge's health: the drop is
                    // the intended outcome, so the record stays behind
                    // RUST_LOG rather than claiming a problem.
                    tracing::debug!(
                        target: "forge_workspace::session_task",
                        event_name = "auto_continue_dropped_occupant_replaced",
                        slot = %self.key.display(),
                        uuid = %uuid,
                        "a continuation's occupant was replaced before it ran; the prompt is dropped",
                    );
                    return;
                }
                let recorded = self.record_queued(&uuid, source, &text, &attachments);
                // **A CLI that cannot follow a queue draws its row here.**
                // Only a person's prompt: a delivery's own envelope row and
                // the machinery's forged row are already its carrier.
                if !recorded && source == PromptSource::You {
                    self.emit_prompt_row(&text, &attachments, &uuid, source);
                }
                Command::PromptUnder { key, text, attachments, uuid, source, dispatch_id }
            }
            other => other,
        };
        match cmd {
            Command::RespondPermission { key: _, tool_id, outcome } => {
                // Peek the slot kind first; only remove on a kind
                // match so a mismatched response leaves the real
                // waiter intact.
                let mut guard = self.domain.lock();
                let kind_matches = matches!(
                    guard.pending_interactions.get(&tool_id),
                    Some(PendingInteractionSlot::Permission { .. }),
                );
                if kind_matches
                    && let Some(PendingInteractionSlot::Permission { tx, .. }) =
                        guard.pending_interactions.remove(&tool_id)
                {
                    drop(guard);
                    let answered_with = permission_words(&outcome);
                    if tx.send(outcome).is_err() {
                        tracing::warn!(
                            target: "forge_workspace::session_task",
                            slot = %self.key.display(),
                            tool_id = %tool_id,
                            "permission oneshot receiver dropped before response could be sent"
                        );
                    }
                    self.emit(SessionUpdate::PendingInteractionResolved {
                        key: self.key.clone(),
                        tool_id,
                        question_index: None,
                        answered_with,
                    });
                } else if let Some(other) = guard.pending_interactions.get(&tool_id) {
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        tool_id = %tool_id,
                        slot = ?other,
                        "RespondPermission expected Permission slot; got different kind. Outcome dropped, slot preserved."
                    );
                } else {
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        tool_id = %tool_id,
                        "RespondPermission found no pending interaction (already responded or expired)"
                    );
                }
            }
            Command::RespondQuestion { key: _, tool_id, outcome } => {
                // Peek-before-remove - mirror of RespondPermission.
                let mut guard = self.domain.lock();
                let kind_matches = matches!(
                    guard.pending_interactions.get(&tool_id),
                    Some(PendingInteractionSlot::Question { .. }),
                );
                if kind_matches
                    && let Some(PendingInteractionSlot::Question { tx, request, .. }) =
                        guard.pending_interactions.remove(&tool_id)
                {
                    drop(guard);
                    let answered_with = question_words(&outcome);
                    if tx.send(outcome).is_err() {
                        tracing::warn!(
                            target: "forge_workspace::session_task",
                            slot = %self.key.display(),
                            tool_id = %tool_id,
                            "question oneshot receiver dropped"
                        );
                    }
                    self.emit(SessionUpdate::PendingInteractionResolved {
                        key: self.key.clone(),
                        tool_id,
                        question_index: Some(request.question_index),
                        answered_with,
                    });
                } else if let Some(other) = guard.pending_interactions.get(&tool_id) {
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        tool_id = %tool_id,
                        slot = ?other,
                        "RespondQuestion got non-Question slot. Outcome dropped, slot preserved."
                    );
                } else {
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        tool_id = %tool_id,
                        "RespondQuestion found no pending interaction"
                    );
                }
            }
            // Answered by this task's own state machine: a handoff asks for
            // its brief in a turn of its own and only swaps at a turn end.
            // **The entry opens the handoff; the exit completes it.** A call
            // with no note is where a handoff starts; a call carrying the
            // note is the skill's last act, accepted only while this seat is
            // already handing over.
            Command::Handoff { key: _, brief: Some(note) } => self.complete_handoff(note),
            Command::Handoff { key: _, brief: None } => {
                self.request_handoff(forge_primitives::HandoffReason::Manual, None);
            }
            other => {
                let sid = self.session_id_string();
                // `/new` starts under an id minted here, so the row this
                // session belongs to names the new session from the moment
                // it starts rather than the one it replaces.
                // A handoff supplies the id it wrote into its row; `/new`
                // mints one here.
                let fresh = match &other {
                    Command::NewSession { session_id, .. } => {
                        session_id.clone().or_else(|| self.fresh_session_id())
                    }
                    _ => None,
                };
                // The id the respawned child runs under: the one minted
                // above for `/new`, the transcript's own for `/resume`.
                // Its gateway segment is stamped from it below, so the
                // binding names the occupant the CLI actually runs as.
                let respawn_id = match &other {
                    Command::NewSession { .. } => fresh.clone(),
                    Command::ResumeSession { session_id, .. } => Some(session_id.clone()),
                    _ => None,
                };
                // **An occupant swap leaves the seat open with no turn in
                // flight.** The successor starts parked; whichever prompt
                // it is sent next is the turn that flips the row.
                if respawn_id.is_some()
                    && let Some(workspace) = self.workspace.upgrade()
                {
                    workspace.record_seat_state(&self.key, crate::store::sessions::SeatState::Idle);
                }
                // A worker's mission lives in its conversation, so a
                // `/new` that emptied it would leave the worker running
                // with no idea what it is for. The launch settings for a
                // `/new` are built without it, so re-deliver the charter
                // the store holds for this slot.
                //
                // Workers only here: a lead has no stored row to read one
                // from, and `stamp_respawn_overrides` below rebuilds its
                // charter and its `LEAD_DELEGATION_PREAMBLE` instead.
                let mut other = other;
                if let Command::NewSession { launch_settings, .. } = &mut other
                    && let Some(charter) =
                        self.workspace.upgrade().and_then(|ws| ws.stored_charter_for(&self.key))
                {
                    launch_settings.charter = Some(charter);
                }
                if let Some(respawn_id) = respawn_id.as_deref()
                    && let Some(workspace) = self.workspace.upgrade()
                    && let Command::NewSession { launch_settings, .. }
                    | Command::ResumeSession { launch_settings, .. } = &mut other
                {
                    workspace.stamp_respawn_overrides(&self.key, respawn_id, launch_settings);
                }
                // A person's send is one of the successor's ten, counted
                // where the prompt actually reaches the agent.
                let counts_for_successor =
                    matches!(&other, Command::PromptUnder { source: PromptSource::You, .. });
                // **A prompt that never reaches the CLI leaves the queue.**
                // Its card would otherwise wait on a frame no CLI will send,
                // and its words would have no row. Kept before the move.
                let failed = match &other {
                    Command::PromptUnder {
                        text,
                        attachments,
                        uuid,
                        source: PromptSource::You,
                        ..
                    } => Some((text.clone(), attachments.clone(), uuid.clone())),
                    _ => None,
                };
                if let Err(err) = execute_command_via_handle(
                    &self.handle,
                    &self.key,
                    sid.as_deref(),
                    fresh,
                    other,
                ) {
                    if let Some((text, attachments, uuid)) = failed {
                        let held = {
                            let mut guard = self.domain.lock();
                            let held = guard.queued_prompt(&uuid).is_some();
                            guard.drop_queued_prompt(&uuid);
                            held
                        };
                        if held {
                            self.emit_prompt_row(&text, &attachments, &uuid, PromptSource::You);
                            self.emit(SessionUpdate::PromptLifecycle {
                                key: self.key.clone(),
                                uuid,
                                state: "started".to_owned(),
                            });
                        }
                    }
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        slot = %self.key.display(),
                        error = %err,
                        "agent command dispatch failed; bridge channel closed?"
                    );
                    // Surface it - a view may already have committed
                    // optimistic state (Thinking, a flipped chip) that
                    // unwinds only when the failure is visible.
                    self.emit(SessionUpdate::TurnError {
                        key: self.key.clone(),
                        message: err.to_string(),
                        class: None,
                        terminal_reason: None,
                    });
                } else if counts_for_successor {
                    self.count_successor_prompt();
                }
            }
        }
    }

    /// Whether `uuid` is the continuation forge sent for this seat and the
    /// occupant it was sent for is no longer the one here. Taken either way:
    /// the prompt is running now, so the matching is spent.
    fn continuation_lost_its_occupant(&self, uuid: &str) -> bool {
        let mut guard = self.domain.lock();
        let Some((sent, armed_for)) = guard.auto_continue_queued.as_ref() else {
            return false;
        };
        if sent != uuid {
            return false;
        }
        let armed_for = armed_for.clone();
        guard.auto_continue_queued = None;
        armed_for != guard.session_id
    }

    /// Snapshot the session id stamped on `DomainSession`, formatted
    /// as a `String`. Most agent commands need the wire session_id;
    /// returns `None` when the bridge hasn't emitted its first
    /// `Connected` yet.
    fn session_id_string(&self) -> Option<String> {
        self.domain.lock().session_id.as_ref().map(std::string::ToString::to_string)
    }

    /// Send `update` to the workspace fan-out; log when no subscriber
    /// took it, so a regression there leaves a trail.
    // TODO(ved): gate emits on a per-task session epoch so a superseded
    // task (its slot re-spawned by a resume or an account switch) can't
    // emit a stale update onto its successor during the brief
    // post-supersession drain. Slot keying neither creates nor widens
    // that window - the successor holds the same slot either way - and
    // the switch stays idle-gated, so it is low-risk today.
    fn emit(&self, update: SessionUpdate) {
        if !self.update_tx.send(update) {
            tracing::warn!(
                target: "forge_workspace::session_task",
                slot = %self.key.display(),
                "no SessionUpdate subscriber took the event"
            );
        }
    }

    /// Flush `caller`'s buffered review activity into its batched
    /// notices. Every path a turn can end on calls this, so it has to be
    /// idempotent: `drain_review_activity` removes the buffer, and a
    /// caller with nothing buffered yields no notices. A turn that ended
    /// normally therefore leaves the teardown drains with nothing to do.
    ///
    /// `caller` is explicit because the replacement path drains a key
    /// that `DomainSession.key` is about to move off, and the buffer
    /// entry becomes unreachable once it has.
    fn drain_review_activity_for(&self, caller: &SessionSlot) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        for update in workspace.drain_review_activity(caller) {
            self.emit(update);
        }
    }

    /// The id a `/new` starts under: a fresh one, recorded against the row
    /// this session belongs to, so a restart re-enters the new session
    /// rather than the one `/new` replaced. `None` when the session has no
    /// row to record against, which leaves the CLI to pick its own id.
    fn fresh_session_id(&self) -> Option<String> {
        Some(self.workspace.upgrade()?.fresh_session_id_for(&self.key))
    }

    /// Give a successor the brief its swap wrote, as its first turn. The
    /// brief forges its own row, which the client draws as the handoff
    /// procedure.
    fn deliver_pending_brief(&mut self, key: &SessionSlot, occupant: &str) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        let Some(pending) = workspace.take_pending_brief(key) else { return };
        if pending.to != occupant {
            tracing::debug!(
                target: "forge_workspace::session_task",
                event_name = "handoff_brief_occupant_mismatch",
                slot = %key.display(),
                written_for = %pending.to,
                occupant = %occupant,
                "the handoff brief was written for another occupant; it is not given",
            );
            return;
        }
        let uuid = forge_sdk::request_id::next_forged_prompt_id();
        // The brief's own first line names the pair that handed over; kept
        // before the text moves into the dispatch.
        let first = pending.text.lines().next().unwrap_or_default().to_owned();
        if let Err(error) = workspace.dispatch_handoff_brief(key, pending.text, uuid) {
            tracing::warn!(
                target: "forge_workspace::session_task",
                event_name = "handoff_brief_delivery_failed",
                slot = %key.display(),
                %error,
                "the handoff brief could not be delivered to its successor",
            );
            // **The successor is told.** A seat that connected and got no
            // brief looks like a session that started empty; the brief's first
            // line names the session that handed over, and `/resume` is the
            // recovery.
            self.emit(SessionUpdate::Notice {
                key: key.clone(),
                severity: NoticeSeverity::Error,
                text: format!(
                    "the handoff brief could not be delivered to this session ({first}); \
                     resume the session that handed over with /resume"
                ),
            });
        }
    }

    /// The skill's last act: the note the successor's brief carries.
    ///
    /// **Only while this seat is already handing over.** The entry is
    /// `/handoff` or the automatic trigger; a call with no handoff in flight has no
    /// turn to belong to and is stated as refused, never turned into a start.
    fn complete_handoff(&mut self, note: String) {
        let mut domain = self.domain.lock();
        // **`parked` alone is not a running handoff.** A request parked for a
        // busy turn has no procedure turn yet, so an exit call cannot belong
        // to it; the facade's gate refuses that call before it arrives.
        if !domain.handoff.awaiting {
            drop(domain);
            self.emit(SessionUpdate::Notice {
                key: self.key.clone(),
                severity: NoticeSeverity::Error,
                text: "agents__handoff completes a running handoff; a handoff starts at /handoff \
                       or at the automatic trigger (fill or compaction)"
                    .to_owned(),
            });
            return;
        }
        domain.handoff.supplied = Some(note);
    }

    /// A handoff was asked for. The seat must be otherwise idle - no turn,
    /// no queued prompt, nothing parked on an answer - or the request waits
    /// for the next turn end: a handoff is never injected into a turn, and
    /// its prompt must run as a turn of its own.
    fn request_handoff(
        &mut self,
        reason: forge_primitives::HandoffReason,
        fill: Option<handoff::FillReading>,
    ) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        if workspace.swap_in_progress(&self.key) {
            tracing::debug!(
                target: "forge_workspace::session_task",
                event_name = "handoff_requested_during_swap",
                slot = %self.key.display(),
                "a swap is already building on this seat; this request is dropped",
            );
            return;
        }
        {
            let mut domain = self.domain.lock();
            if domain.handoff.in_progress() {
                tracing::debug!(
                    target: "forge_workspace::session_task",
                    event_name = "handoff_already_running",
                    slot = %self.key.display(),
                    "a handoff is already running; this request is dropped",
                );
                return;
            }
            if !domain.is_idle_for_handoff() {
                domain.handoff.reason = Some(reason);
                domain.handoff.fill = fill;
                domain.handoff.parked = true;
                return;
            }
            // The reason rides to the row even on the immediate path.
            domain.handoff.reason = Some(reason);
            domain.handoff.fill = fill;
        }
        self.begin_handoff();
    }

    /// Start the handoff's own turn.
    ///
    /// **The swap's gate opens HERE**, at the decision, not when the brief is
    /// built: everything the seat is sent from this point waits for the
    /// successor, and only the judgment prompt is let through.
    fn begin_handoff(&mut self) {
        if self.session_id_string().is_none() {
            self.emit(SessionUpdate::Notice {
                key: self.key.clone(),
                severity: NoticeSeverity::Error,
                text: "a handoff needs a connected session; this seat has none yet".to_owned(),
            });
            return;
        }
        let Some(workspace) = self.workspace.upgrade() else { return };
        // **One handoff at a time on a seat.** A swap already building is a
        // state in which this task's own request state reads as idle, so
        // the gate is the authority, not the domain.
        if workspace.swap_in_progress(&self.key) {
            tracing::debug!(
                target: "forge_workspace::session_task",
                event_name = "handoff_begin_during_swap",
                slot = %self.key.display(),
                "a swap is already building on this seat; this handoff is dropped",
            );
            return;
        }
        // **The seat is re-checked here, not only where the request was
        // parked.** A prompt can be committed between that park and this
        // boundary; beginning on top of it is what folds the judgment prompt
        // into someone else's turn.
        {
            let mut domain = self.domain.lock();
            if !domain.is_idle_for_handoff() {
                domain.handoff.parked = true;
                return;
            }
        }
        let token = workspace.begin_swap(&self.key);
        self.domain.lock().handoff.swap_token = Some(token);
        // **The procedure's own marker.** The judgment prompt is the handoff
        // turn's opener, so a view draws it as the procedure rather than as an
        // ordinary machinery nudge; the longer prefix is that marker and still
        // reads as the machinery's to every existing check.
        let uuid = forge_sdk::request_id::next_handoff_prompt_id();
        {
            let mut domain = self.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some(uuid.clone());
            domain.handoff.judgment_started = false;
        }
        // **The seat stands down before its own prompt lands.** A page already
        // open learns the handoff here; the record carries the same fact for a
        // page that attaches after this frame.
        self.emit(SessionUpdate::MachineTurn {
            key: self.key.clone(),
            machine: Some(forge_primitives::runtime::MachineTurn::Handoff),
        });
        let text = handoff::judgment_prompt();
        let deadline_uuid = uuid.clone();
        if let Err(error) = workspace.dispatch_handoff_prompt(&self.key, text, uuid) {
            self.domain.lock().handoff = crate::domain_session::HandoffState::default();
            self.emit(SessionUpdate::MachineTurn { key: self.key.clone(), machine: None });
            // Nothing is coming to hand over to, so the gate must not keep
            // holding prompts for it.
            let held = workspace.end_swap(&self.key);
            if !held.is_empty() {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    event_name = "handoff_prompts_dropped",
                    slot = %self.key.display(),
                    held = held.len(),
                    "the handoff could not ask for its brief; prompts held for it were dropped",
                );
            }
            for prompt in held {
                // The press never ran, so its composer mark settles here.
                self.emit(SessionUpdate::PromptLifecycle {
                    key: self.key.clone(),
                    uuid: prompt.uuid.clone(),
                    state: "cancelled".to_owned(),
                });
                if let Some(sender) = &prompt.sender {
                    workspace.notice_undelivered_message(
                        sender,
                        &self.key,
                        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                    );
                } else {
                    let first = prompt.text.lines().next().unwrap_or_default();
                    self.emit(SessionUpdate::Notice {
                        key: self.key.clone(),
                        severity: NoticeSeverity::Error,
                        text: format!("a prompt held for the failed handoff did not run: {first}"),
                    });
                }
            }
            self.emit(SessionUpdate::TurnError {
                key: self.key.clone(),
                message: format!("the handoff could not ask for its brief: {error}"),
                class: None,
                terminal_reason: None,
            });
            return;
        }
        // **The last backstop.** A prompt that never starts produces no turn
        // whose Result would finish the handoff, and the CLI may advertise no
        // lifecycle frames at all - so a judgment that has not started by the
        // deadline ends the handoff rather than holding the gate for the life
        // of the seat.
        let workspace = Arc::clone(&workspace);
        let domain = Arc::clone(&self.domain);
        let update_tx = self.update_tx.clone();
        let key = self.key.clone();
        tokio::spawn(async move {
            tokio::time::sleep(handoff::JUDGMENT_DEADLINE).await;
            let wedged = {
                let domain = domain.lock();
                domain.handoff.awaiting
                    && !domain.handoff.judgment_started
                    && domain.handoff.judgment_uuid.as_deref() == Some(deadline_uuid.as_str())
            };
            if wedged {
                Self::abort_handoff_state(
                    &workspace,
                    &domain,
                    &update_tx,
                    &key,
                    "the handoff's brief never started; this session continues",
                );
            }
        });
    }

    /// The same frame, naming the dispatch that owns it.
    ///
    /// A sub-agent's frames carry the dispatch their parent fired, and only
    /// the outermost dispatch is a card, so a deeper frame names no expansion;
    /// a `permission_denied` frame names the agent and no dispatch at all.
    /// Both walk the tracker's parent links to the owning card, and a frame
    /// whose chain reaches none is left alone.
    fn attribute_dispatch(&self, msg: forge_primitives::Message) -> forge_primitives::Message {
        let (held, owner) = {
            let domain = self.domain.lock();
            let tracker = &domain.card_tracker;
            match &msg {
                forge_primitives::Message::Assistant { parent_tool_use_id, .. }
                | forge_primitives::Message::User { parent_tool_use_id, .. }
                | forge_primitives::Message::StopHookSummary { parent_tool_use_id, .. } => {
                    let held = parent_tool_use_id.as_deref().filter(|id| !id.trim().is_empty());
                    (
                        held.map(str::to_owned),
                        held.and_then(|id| tracker.owning_dispatch(id)).map(str::to_owned),
                    )
                }
                // A refusal the CLI sent names the agent and no dispatch; an
                // already-stamped one names the dispatch. The agent is the
                // task id the roster opened a dispatch's call with.
                forge_primitives::Message::PermissionDenied { extras, .. } => {
                    let parent = extras
                        .get("parent_tool_use_id")
                        .and_then(serde_json::Value::as_str)
                        .filter(|id| !id.trim().is_empty());
                    let owner = match parent {
                        Some(parent) => tracker.owning_dispatch(parent),
                        None => extras
                            .get("agent_id")
                            .and_then(serde_json::Value::as_str)
                            .and_then(|agent| tracker.dispatch_of(agent)),
                    };
                    (parent.map(str::to_owned), owner.map(str::to_owned))
                }
                _ => return msg,
            }
        };
        let Some(owner) = owner else {
            // The frame keeps the parent the wire gave it; a nested id draws
            // nowhere, so the tracker's own record is the only trace.
            if let Some(held) = held.as_deref() {
                tracing::debug!(
                    target: "forge_workspace::subagent_cards",
                    event_name = "subagent_frame_without_a_card",
                    parent = %held,
                    "a parented frame resolves to no card; it keeps the parent the wire gave it",
                );
            }
            return msg;
        };
        if held.as_deref() == Some(owner.as_str()) {
            return msg;
        }
        let mut msg = msg;
        match &mut msg {
            forge_primitives::Message::Assistant { parent_tool_use_id, .. }
            | forge_primitives::Message::User { parent_tool_use_id, .. }
            | forge_primitives::Message::StopHookSummary { parent_tool_use_id, .. } => {
                *parent_tool_use_id = Some(owner);
            }
            forge_primitives::Message::PermissionDenied { extras, .. } => {
                extras.insert("parent_tool_use_id".to_owned(), serde_json::Value::String(owner));
            }
            _ => {}
        }
        msg
    }

    /// Hold the assistant text of a running judgment turn.
    fn capture_judgment(&self, message: &forge_primitives::Message) {
        let forge_primitives::Message::Assistant { message: envelope, parent_tool_use_id, .. } =
            message
        else {
            return;
        };
        // **A sub-agent's text is not the turn's note.** An agentic judgment
        // turn spawns Task work, and its frames arrive in the same stream;
        // letting one overwrite the note would hand the successor a worker's
        // line as the brief.
        if forge_primitives::names_a_dispatch(parent_tool_use_id.as_deref()) {
            return;
        }
        let mut domain = self.domain.lock();
        if !domain.handoff.awaiting {
            return;
        }
        if let Some(text) = handoff::assistant_text(&envelope.content) {
            domain.handoff.judgment = Some(text);
        }
    }

    /// Act on a turn that ended normally: finish a running handoff, or start
    /// one that arrived while the turn was running.
    fn after_turn_ended(&mut self) {
        // **The boundary's own turn is over, and its markers clear later in
        // the same event.** The idle gate must not read the turn that just
        // ended as still running, or every trigger parks and waits for a
        // turn that is never coming - which is exactly what the scratch
        // stack found. The `Result` is the freshest word on liveness, so
        // this is also where a stale Running mirror goes.
        {
            let mut domain = self.domain.lock();
            domain.serve_turn();
            // **Only the ended turn's stamps go.** A prompt committed before
            // this Result landed is the NEXT turn; its liveness must stand,
            // or a running seat reads idle here and the trigger fires into
            // it.
            if !domain.turns_outstanding() {
                domain.turn_open = false;
                if matches!(
                    domain.runtime_state,
                    Some(
                        forge_primitives::RuntimeSessionState::Running
                            | forge_primitives::RuntimeSessionState::RequiresAction
                    )
                ) {
                    domain.runtime_state = None;
                }
            }
        }
        self.measure_successor_at_boundary();
        let (awaiting, started, lifecycle_correlates, parked, reason) = {
            let mut domain = self.domain.lock();
            let awaiting = domain.handoff.awaiting;
            let started = domain.handoff.judgment_started;
            // A CLI that never advertised the lifecycle frames cannot say
            // which prompt a turn belongs to; the idle gate is then the
            // whole of the correlation.
            let correlates = domain.lifecycle_frames == Some(true);
            let parked = if awaiting { false } else { std::mem::take(&mut domain.handoff.parked) };
            (awaiting, started, correlates, parked, domain.handoff.reason.unwrap_or_default())
        };
        if awaiting {
            if lifecycle_correlates && !started {
                // Some other turn ended - the continuation a failed turn
                // fired, or a prompt sent before the handoff. It is not the
                // judgment turn, so its prose is not the brief.
                tracing::debug!(
                    target: "forge_workspace::session_task",
                    event_name = "handoff_judgment_turn_not_ours",
                    slot = %self.key.display(),
                    "a turn ended without the judgment prompt starting; the handoff waits",
                );
                return;
            }
            let judgment = {
                let mut domain = self.domain.lock();
                // **A note is whatever the turn ended on.** forge prescribes
                // no shape for it, so any non-empty note is the brief; the
                // exit call's note wins when both sources have one.
                let supplied = domain.handoff.supplied.take();
                let captured = domain.handoff.judgment.take();
                // **Whether the exit call carried a note at all**, which is not
                // the same as whether its note carried content: a shell like
                // `## Next` parses to nothing but is not an absent call.
                let from_tool_call = supplied.is_some();
                let from_turn_text = captured.is_some();
                domain.handoff.judgment_started = false;
                // **The exit call is the deliberate act; a turn that simply
                // ended is not.** Both are accepted for their text, but a note
                // taken from the closing text is marked so the successor can
                // tell it from one its predecessor chose to pass.
                if let Some(text) = supplied.filter(|text| handoff::parses_as_note(text)) {
                    handoff::parse_judgment(&text)
                } else if let Some(text) = captured.filter(|text| handoff::parses_as_note(text)) {
                    let why = if from_tool_call {
                        "the exit call's note carried no content; this is the session's closing \
                         text"
                    } else {
                        "the exit call carried no note; this is the session's closing text"
                    };
                    tracing::info!(
                        target: "forge_workspace::session_task",
                        event_name = "handoff_note_from_turn_text",
                        slot = %self.key.display(),
                        from_tool_call,
                        chars = text.chars().count(),
                        "the turn's closing text is the judgment half; the exit call's own note \
                         was absent or carried no content",
                    );
                    let mut sections = handoff::parse_judgment(&text);
                    sections.insert(
                        0,
                        forge_primitives::HandoffSection {
                            label: "source".to_owned(),
                            lines: vec![why.to_owned()],
                        },
                    );
                    sections
                } else {
                    // **The successor is told the note is missing; this is the
                    // trail that says so.** Either source can be a shell with
                    // no content - a headings-only reply parses to nothing -
                    // so the two fields name what forge had in hand.
                    tracing::warn!(
                        target: "forge_workspace::session_task",
                        event_name = "handoff_note_rejected",
                        slot = %self.key.display(),
                        from_tool_call,
                        from_turn_text,
                        "the handoff turn produced no note; the successor is told the note did \
                         not arrive",
                    );
                    handoff::missing_note()
                }
            };
            self.swap(reason, judgment);
            return;
        }
        if parked {
            self.begin_handoff();
            return;
        }
        self.maybe_trigger_handoff();
    }

    /// A cancelled judgment turn ends the handoff rather than finishing it:
    /// the reader stopped the prompt the brief was coming from, so the seat
    /// keeps its session and what waited during the swap goes back to it.
    fn abort_cancelled_handoff(&mut self) {
        let (awaiting, started, correlates) = {
            let domain = self.domain.lock();
            (
                domain.handoff.awaiting,
                domain.handoff.judgment_started,
                domain.lifecycle_frames == Some(true),
            )
        };
        if !awaiting || (correlates && !started) {
            return;
        }
        self.abort_handoff("the handoff's brief was cancelled; this session continues");
    }

    /// End a handoff that will not finish: clear its state, close its gate,
    /// hand back what the gate held, and tell the seat why.
    ///
    /// **Every way the judgment prompt can settle without running lands
    /// here.** A prompt the reader cancels, or the CLI refuses or discards,
    /// never produces the turn whose Result would finish the handoff - and
    /// left alone it would hold the gate open and drop every later handoff
    /// for the life of the seat.
    fn abort_handoff(&mut self, why: &str) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        Self::abort_handoff_state(&workspace, &self.domain, &self.update_tx, &self.key, why);
    }

    /// End a running handoff from wherever can reach the seat's state: the
    /// task itself for a cancel or a settlement, and the deadline task when
    /// the judgment prompt never starts.
    fn abort_handoff_state(
        workspace: &Arc<crate::Workspace>,
        domain: &Arc<parking_lot::Mutex<crate::domain_session::DomainSession>>,
        update_tx: &crate::update_fanout::UpdateFanout,
        key: &SessionSlot,
        why: &str,
    ) {
        {
            let mut guard = domain.lock();
            guard.handoff = crate::domain_session::HandoffState::default();
            // **The judgment prompt's committed turn settles here.** The
            // prompt was routed at `begin_handoff`, so its commit is open;
            // these paths end the handoff without the Result that would
            // serve it, and a seat left with an outstanding turn bails out
            // of every later trigger at the idle gate.
            guard.serve_turn();
        }
        // **The settle the domain just did is the row's too.** These paths
        // produce no Result, so no turn end reaches the row; left `in_turn`,
        // a restart would hand the seat a note for a turn nothing
        // interrupted. Written before the held prompts are re-delivered:
        // their `route` commits new turns and must have the last word.
        workspace.record_seat_state(key, crate::store::sessions::SeatState::Idle);
        // **The seat takes input again.** Every abort lands here - a
        // cancelled judgment prompt, one the CLI refused or discarded, and the
        // deadline - and a composer left standing down for a handoff that
        // ended is a seat nobody can type into.
        let _ = update_tx.send(SessionUpdate::MachineTurn { key: key.clone(), machine: None });
        let held = workspace.end_swap(key);
        if !update_tx.send(SessionUpdate::Notice {
            key: key.clone(),
            severity: NoticeSeverity::Info,
            text: why.to_owned(),
        }) {
            tracing::warn!(
                target: "forge_workspace::session_task",
                slot = %key.display(),
                "no SessionUpdate subscriber took the handoff-abort notice"
            );
        }
        for prompt in held {
            let sender = prompt.sender.clone();
            let first = prompt.text.lines().next().unwrap_or_default().to_owned();
            let uuid = forge_sdk::request_id::next_forged_prompt_id();
            // `route`, not `dispatch`: this is a re-delivery of words already
            // recorded, not a new press, so it takes no dispatch entry's
            // command handling.
            if let Err(error) = workspace.route(Command::PromptUnder {
                key: key.clone(),
                text: prompt.text,
                attachments: prompt.attachments,
                uuid,
                source: prompt.source,
                dispatch_id: None,
            }) {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    event_name = "handoff_held_prompt_redelivery_failed",
                    slot = %key.display(),
                    %error,
                    "a prompt held during an aborted handoff could not be handed back",
                );
                // The hand-back failed, so the original press never runs and
                // its composer mark settles here.
                let _ = update_tx.send(SessionUpdate::PromptLifecycle {
                    key: key.clone(),
                    uuid: prompt.uuid.clone(),
                    state: "cancelled".to_owned(),
                });
                if let Some(sender) = sender {
                    workspace.notice_undelivered_message(
                        &sender,
                        key,
                        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                    );
                } else {
                    let _ = update_tx.send(SessionUpdate::Notice {
                        key: key.clone(),
                        severity: NoticeSeverity::Error,
                        text: format!(
                            "a prompt held during the aborted handoff could not be handed back: {first}"
                        ),
                    });
                }
            }
        }
    }

    /// Count the successor's prompts, and mark the tenth for measurement.
    ///
    /// **Prompts, not turn boundaries.** `successor_counts` reads the
    /// transcript's user prompts, so counting boundaries here would compare
    /// ten endings against ten prompts that included forge's own brief turn.
    /// The brief and every other forge delivery carry `PromptSource::Forge`,
    /// so only a person's send counts.
    fn count_successor_prompt(&mut self) {
        let Some(watch) = self.successor.as_mut() else { return };
        watch.turns += 1;
        if watch.turns >= handoff::SUCCESSOR_TURNS {
            watch.measure_at_boundary = true;
        }
    }

    /// Measure the successor once its tenth prompt's turn has ended, when
    /// the transcript holds all ten. A successor that leaves before then
    /// goes unmeasured rather than writing half a comparison.
    fn measure_successor_at_boundary(&mut self) {
        let due = self.successor.as_ref().is_some_and(|watch| watch.measure_at_boundary);
        if !due {
            return;
        }
        let Some(watch) = self.successor.take() else { return };
        let Some(workspace) = self.workspace.upgrade() else { return };
        let cwd = workspace.cwd_for_session(&self.key).unwrap_or_default();
        workspace.measure_successor(self.key.clone(), watch.to, cwd, watch.predecessor_reads);
    }

    /// The automatic trigger: at a turn boundary with no handoff running,
    /// ask the CLI for this seat's own fill reading.
    ///
    /// **Asked at every boundary, page or no page.** A view refreshes the
    /// reading, but an unattended worker has no view, so a trigger that read
    /// only what a page had asked for would never fire on exactly the
    /// sessions that run longest. A failed ask skips this boundary and says
    /// so at debug; the denominator is never guessed.
    fn maybe_trigger_handoff(&mut self) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        if !workspace.handoff_policy_for(&self.key).enabled {
            return;
        }
        // A swap already building on this seat is the one this boundary
        // must not race: `swap` clears the request state, so an in-flight
        // build reads as idle here and would fire a second handoff.
        if workspace.swap_in_progress(&self.key) {
            return;
        }
        {
            let mut domain = self.domain.lock();
            if domain.handoff.in_progress() || !domain.is_idle_for_handoff() {
                return;
            }
            // Re-armed rather than skipped when a probe is already out: a
            // reading that never came (the bridge's own timeout swallows it)
            // would otherwise leave the trigger stuck off for the life of
            // the session.
            domain.handoff.probing = true;
        }
        let Some(session_id) = self.session_id_string() else {
            self.domain.lock().handoff.probing = false;
            return;
        };
        if let Err(error) = self.handle.get_context_usage(session_id) {
            self.domain.lock().handoff.probing = false;
            tracing::debug!(
                target: "forge_workspace::session_task",
                event_name = "handoff_reading_ask_failed",
                slot = %self.key.display(),
                %error,
                "the fill reading could not be asked for; no handoff trigger this turn",
            );
        }
    }

    /// Judge a reading the trigger asked for: a fill at or over the
    /// configured share, or a compaction the fill trigger did not stop.
    fn evaluate_handoff_trigger(
        &mut self,
        reading_for: &str,
        reported: Option<u8>,
        total_tokens: Option<u64>,
        effective_max_tokens: Option<u64>,
    ) {
        // **A reading for another occupant is the previous session's.** The
        // probe is asynchronous, so a swap can land while one is out; that
        // answer says nothing about the session here and must not judge it
        // (nor spend the boundary's probe).
        if self.session_id_string().as_deref() != Some(reading_for) {
            tracing::debug!(
                target: "forge_workspace::session_task",
                event_name = "handoff_reading_stale_occupant",
                slot = %self.key.display(),
                reading_for = %reading_for,
                "a fill reading arrived for a session this seat no longer runs; ignored",
            );
            return;
        }
        {
            let mut domain = self.domain.lock();
            if !std::mem::take(&mut domain.handoff.probing) {
                return;
            }
        }
        let Some(workspace) = self.workspace.upgrade() else { return };
        let policy = workspace.handoff_policy_for(&self.key);
        if !policy.enabled {
            return;
        }
        let fill = fill_of(reported, total_tokens, effective_max_tokens);
        let compaction_count = self.compaction_count;
        let reason = if compaction_count >= policy.after_compactions {
            // The backstop: a huge turn crossed the window and the CLI
            // compacted before a boundary could carry the handoff.
            Some(forge_primitives::HandoffReason::Compaction)
        } else if fill.is_some_and(|fill| fill.fires(policy.at_percent)) {
            Some(forge_primitives::HandoffReason::Fill)
        } else {
            None
        };
        let Some(reason) = reason else { return };
        // **Through the request, not straight into `begin_handoff`.** The
        // probe is asynchronous: a turn may have opened while it was out,
        // and this path is where that turn parks the handoff instead of
        // having the judgment prompt folded into it. The reading rides with
        // the request so a dropped one cannot overwrite a running handoff's.
        self.request_handoff(reason, fill);
    }

    /// Replace this seat's occupant with a new session that continues from
    /// the brief, on the same order `/new` uses.
    fn swap(
        &mut self,
        reason: forge_primitives::HandoffReason,
        judgment: Vec<forge_primitives::HandoffSection>,
    ) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        let (from, fill, token) = {
            let mut domain = self.domain.lock();
            let from = domain.session_id.as_ref().map(std::string::ToString::to_string);
            let fill = domain.handoff.fill;
            let token = domain.handoff.swap_token;
            domain.handoff = crate::domain_session::HandoffState::default();
            (from, fill, token)
        };
        let Some(from) = from else {
            // Nothing to hand over: close the gate this beginning opened and
            // answer what it was holding, or the seat holds prompts for a
            // successor nothing is bringing. **The seat keeps its session**, so
            // the machine turn ends here as well - no successor arrives whose
            // record would clear it.
            self.emit(SessionUpdate::MachineTurn { key: self.key.clone(), machine: None });
            let held = workspace.end_swap(&self.key);
            for prompt in held {
                // The press never ran, so its composer mark settles here.
                self.emit(SessionUpdate::PromptLifecycle {
                    key: self.key.clone(),
                    uuid: prompt.uuid.clone(),
                    state: "cancelled".to_owned(),
                });
                if let Some(sender) = &prompt.sender {
                    workspace.notice_undelivered_message(
                        sender,
                        &self.key,
                        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                    );
                } else {
                    let first = prompt.text.lines().next().unwrap_or_default();
                    self.emit(SessionUpdate::Notice {
                        key: self.key.clone(),
                        severity: NoticeSeverity::Error,
                        text: format!(
                            "the handoff did not run; this prompt waits no longer: {first}"
                        ),
                    });
                }
            }
            self.emit(SessionUpdate::Notice {
                key: self.key.clone(),
                severity: NoticeSeverity::Error,
                text: "a handoff needs a connected session; this seat has none yet".to_owned(),
            });
            return;
        };
        // **A successful swap emits no machine-turn frame on purpose.** The
        // successor's `SessionReplaced` makes every client re-read the record,
        // and the record answers `machine: null` because the handoff state was
        // cleared above - so the seat stays down until its new occupant's own
        // record lands, drawn under the spawn blocker rather than a stale line.
        let policy = workspace.handoff_policy_for(&self.key);
        let cwd = workspace.cwd_for_session(&self.key).unwrap_or_default();
        // Minted, not recorded: the id reaches the slot's row on Connected.
        // A recorded id whose spawn failed is one the next boot resumes into
        // an empty session, which a handoff record would then claim to have
        // joined.
        let to = handoff::mint_session_id();
        // The base settings alone: the NewSession arm re-delivers the
        // charter, rebuilds the lead's blocks and stamps the new occupant's
        // gateway binding, exactly as it does for `/new`.
        let launch_settings = workspace.launch_settings_for(&self.key, &cwd);
        let charter = workspace.stored_charter_for(&self.key);
        let role = if self.key.is_lead() {
            handoff::Role::Lead
        } else {
            handoff::Role::Worker {
                charter_opening: charter
                    .as_deref()
                    .and_then(|charter| charter.lines().next())
                    .map(|line| line.chars().take(200).collect()),
            }
        };
        let request = handoff::SwapRequest {
            slot: self.key.clone(),
            from,
            to,
            token,
            reason,
            fill,
            at_percent: policy.at_percent,
            role,
            judgment,
            cwd,
            launch_settings,
        };
        workspace.start_handoff(request);
    }

    /// Drain everything parked for this session's slot on its first
    /// `Connected`, in arrival order. The take is the session's own
    /// `(org, project, label)` bucket, so a payload parked for a team
    /// worker never lands on the project's lead.
    fn drain_parked(&self) {
        let Some(workspace) = self.workspace.upgrade() else { return };
        let parked = workspace.take_parked_for_slot(&self.key);
        self.deliver_parked_peers(&workspace, parked.peer);
        self.deliver_parked_crons(&workspace, parked.cron);
        self.deliver_parked_gotify(&workspace, parked.gotify);
        self.deliver_parked_slack(&workspace, parked.slack);
    }

    /// Deliver the peer prompts parked for this session's slot. Each is
    /// re-dispatched as a normal `Command::Prompt` against `self.key`.
    /// The existing prompt-delivery path handles it identically to a
    /// user-typed prompt - the only difference is the prose body
    /// carries the `[Message id=m-…]` wrapper
    /// that `forge_server::envelope::detect_inbound` matches, which
    /// the chat renders as a styled peer block.
    fn deliver_parked_peers(
        &self,
        workspace: &Arc<crate::Workspace>,
        pending: Vec<crate::parked::ParkedPeer>,
    ) {
        if pending.is_empty() {
            return;
        }
        // Same typed peer-envelope echo the running-target dispatch path
        // does. Fire BEFORE the LLM-side dispatch so the user-turn
        // ordering is natural. The sender is not used here: it rides the
        // parked entry for the expiry path alone.
        for entry in pending {
            let crate::parked::ParkedPeer { wrapped, .. } = entry;
            let uuid = forge_sdk::request_id::next_prompt_id();
            crate::spawn::push_peer_user_turn_into_chat(workspace, &self.key, &wrapped, &uuid);
            let text = wrapped.to_prose();
            if let Err(err) =
                workspace.dispatch_workspace_prompt_under(&self.key, text, PromptSource::Peer, uuid)
            {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    slot = %self.key.display(),
                    error = ?err,
                    "deliver_parked_peers: dispatch failed; prompt dropped"
                );
                crate::spawn::send_dispatch_turn_error(workspace, self.key.clone(), &err);
            }
        }
    }

    /// Deliver the cron prompts parked for this session's slot - the
    /// bucket a due cron filled while the slot was asleep. Each is
    /// echoed as a cron block (missed-marked when overdue) and
    /// re-dispatched as a plain `Command::Prompt`.
    fn deliver_parked_crons(
        &self,
        workspace: &Arc<crate::Workspace>,
        pending: Vec<crate::crons::PendingCron>,
    ) {
        if pending.is_empty() {
            return;
        }
        for cron in pending {
            let text = crate::spawn::missed_cron_text(&cron.text, cron.missed);
            let uuid = forge_sdk::request_id::next_prompt_id();
            crate::spawn::push_cron_prompt_into_chat(
                workspace,
                &self.key,
                &text,
                &uuid,
                &cron.cron_id,
                cron.description.as_deref(),
            );
            if let Err(err) =
                workspace.dispatch_workspace_prompt_under(&self.key, text, PromptSource::Cron, uuid)
            {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    slot = %self.key.display(),
                    error = ?err,
                    "deliver_parked_crons: dispatch failed; prompt dropped",
                );
                crate::spawn::send_dispatch_turn_error(workspace, self.key.clone(), &err);
            }
        }
    }

    /// Deliver the Gotify notifications parked for this session's slot.
    /// Each is echoed into chat as a notification block and re-dispatched
    /// as a plain `Command::Prompt`, landing as an ordinary user turn.
    /// Mirrors [`Self::deliver_parked_crons`], which echoes its own
    /// block before dispatching.
    fn deliver_parked_gotify(
        &self,
        workspace: &Arc<crate::Workspace>,
        pending: Vec<crate::mcp::gotify::types::GotifyNotification>,
    ) {
        if pending.is_empty() {
            return;
        }
        for notification in pending {
            // Echo the notification block, then re-dispatch its prose as a
            // plain user turn (mirrors the running-target path in
            // spawn::deliver_gotify_message).
            let uuid = forge_sdk::request_id::next_prompt_id();
            crate::spawn::push_gotify_notification_into_chat(
                workspace,
                &self.key,
                &notification,
                &uuid,
            );
            if let Err(err) = workspace.dispatch_workspace_prompt_under(
                &self.key,
                notification.to_prose(),
                PromptSource::Gotify,
                uuid,
            ) {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    slot = %self.key.display(),
                    error = ?err,
                    "deliver_parked_gotify: dispatch failed; prompt dropped"
                );
                crate::spawn::send_dispatch_turn_error(workspace, self.key.clone(), &err);
            }
        }
    }

    /// Deliver the Slack messages parked for this session's slot. Each
    /// conversation's is echoed into chat as one notification block and
    /// re-dispatched as a plain `Command::Prompt`, landing as an ordinary
    /// user turn. Mirrors [`Self::deliver_parked_gotify`].
    fn deliver_parked_slack(
        &self,
        workspace: &Arc<crate::Workspace>,
        pending: Vec<forge_primitives::slack::SlackMessage>,
    ) {
        if pending.is_empty() {
            return;
        }
        // The parked bucket is flat, so regroup it into the per-conversation
        // block each batch was read as.
        let mut by_conversation: std::collections::BTreeMap<String, Vec<_>> =
            std::collections::BTreeMap::new();
        for message in pending {
            by_conversation.entry(message.conversation.clone()).or_default().push(message);
        }
        for messages in by_conversation.into_values() {
            let Some(first) = messages.first() else { continue };
            let prose = crate::spawn::slack_bundle_to_prose(
                &messages,
                workspace.slack_stale_after(&first.workspace),
                std::time::SystemTime::now(),
            );
            let uuid = forge_sdk::request_id::next_prompt_id();
            crate::spawn::push_slack_message_into_chat(workspace, &self.key, &prose, &uuid);
            if let Err(err) = workspace.dispatch_workspace_prompt_under(
                &self.key,
                prose,
                PromptSource::Slack,
                uuid,
            ) {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    slot = %self.key.display(),
                    error = ?err,
                    "deliver_parked_slack: dispatch failed; prompt dropped"
                );
                crate::spawn::send_dispatch_turn_error(workspace, self.key.clone(), &err);
            }
        }
    }
}

/// Drop hook: on SessionTask exit (any reason - graceful close,
/// crash, panic), drop whatever is parked for this session's slot - a
/// message waiting on a session that no longer exists is acknowledged
/// back to its sender rather than delivered to nobody.
///
/// Uses the stored `Weak<Workspace>` reference so a Workspace drop
/// before the task drops doesn't double-fire or panic.
impl Drop for SessionTask {
    fn drop(&mut self) {
        // Teardown backstop for the routes out of `run` that produce no
        // terminal envelope: the command channel closing on a release or
        // despawn, and the runtime dropping the task. Child death needs
        // no backstop - `reader_loop` emits ConnectionFailed on both of
        // its exit arms (stream error and stream close), and that arm
        // drains review activity before terminating the task.
        //
        // The teardown signal fires here rather than at `run`'s tail so
        // every exit resolves it - a waiter (the despawn's worktree
        // removal) must not hang on a task that ended some other way.
        if let Some(done) = self.teardown_done.take() {
            let _ = done.send_replace(true);
        }
        let caller = self.domain.lock().key.clone();
        self.drain_review_activity_for(&caller);
        if let Some(workspace) = self.workspace.upgrade() {
            workspace.expire_parked_for_slot(
                &self.key,
                crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
            );
            // A task that ends mid-swap leaves its gate open; closing it
            // here is what keeps a later prompt from being held for a
            // successor nothing is bringing.
            let held = workspace.end_swap(&self.key);
            if !held.is_empty() {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    event_name = "handoff_prompts_dropped_on_teardown",
                    slot = %self.key.display(),
                    held = held.len(),
                    "the session task ended during a handoff; prompts held for its successor were dropped",
                );
            }
            for prompt in &held {
                // The press never ran, so its composer mark settles here.
                let _ = self.update_tx.send(SessionUpdate::PromptLifecycle {
                    key: self.key.clone(),
                    uuid: prompt.uuid.clone(),
                    state: "cancelled".to_owned(),
                });
                if let Some(sender) = &prompt.sender {
                    workspace.notice_undelivered_message(
                        sender,
                        &self.key,
                        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
                    );
                } else {
                    let first = prompt.text.lines().next().unwrap_or_default();
                    let _ = self.update_tx.send(SessionUpdate::Notice {
                        key: self.key.clone(),
                        severity: NoticeSeverity::Error,
                        text: format!(
                            "a prompt held for the handoff did not run; the session ended: {first}"
                        ),
                    });
                }
            }
            // **Every exit releases the pool, not only `run`'s tail.** A
            // task that ends by panic, a dropped runtime or an early return
            // never reaches that tail, and its pooled handle outlived it:
            // every later spawn fast-pathed a seat with nothing behind it
            // (#2683). The identity check keeps a superseded task from
            // taking its successor's entry.
            workspace.release_session_if_current(&self.key, &self.handle);
        }
    }
}

/// Shared worker Connected hook: when the session that connected is a
/// project's lead and no live workers exist for the project yet,
/// (re-)spawn its workers - one `SpawnWorker` per persisted worker row.
/// Called from `SessionTask::translate_event` (production) and
/// `on_connected_for_test` (tests). Idempotent; safe to call multiple
/// times for the same session - the `live_workers.is_empty()` gate
/// guards against double-spawn on `/new` reconnects or transient
/// retries, and `respawn_workers_for_lead` no-ops when the project has
/// no worker rows.
///
/// The slot's label carries the role: only a lead (`None`) owns a team.
fn maybe_respawn_workers_on_connected(
    workspace: &Arc<crate::Workspace>,
    slot: &crate::SessionSlot,
    force_new: bool,
) {
    if !slot.is_lead() {
        return;
    }
    // **A closed lead does not bring its workers back.** The boot wave
    // never spawns a closed lead, so this hook should not fire for one;
    // the check keeps the guarantee local rather than resting on that.
    if matches!(workspace.stored_seat_state(slot), Some(crate::store::sessions::SeatState::Closed))
    {
        return;
    }
    if workspace.find_project_view_by_name(slot.project()).is_none() {
        return;
    }
    let Some(project_key) = workspace.project_key_for_name(slot.project()) else {
        return;
    };
    if !workspace.list_live_workers(&project_key).is_empty() {
        return;
    }
    // Re-spawn the project's persisted workers on a lead reconnect, so
    // each resumes the id the store holds for its label instead of
    // starting fresh. Workspace claims a per-project in-flight guard
    // synchronously so a fast double-Connected can't slip a second
    // worker-spawn through; the guard is released after the SpawnWorker
    // commands are dispatched.
    workspace.respawn_workers_for_lead(slot, project_key, force_new);
}

/// Shared worker-kick hook: when the session that connected is a worker,
/// dispatch a `Command::Prompt` carrying the live worker's stored kick
/// to it. Claude sessions don't act until a
/// user-turn arrives, so without this kick a worker would sit idle
/// indefinitely after spawn (its charter would shape behaviour IF
/// prompted, but nothing prompts it).
///
/// A worker spawned without a kick gets none - it stays caller-driven
/// until its lead sends it something. The re-spawn path decides what a
/// resuming worker is kicked with, so there is nothing to decide here.
///
/// Called from `SessionTask::translate_event` (production) and
/// `on_connected_for_test` (tests). The dispatch goes through the
/// Workspace command bus to the worker's own SessionTask queue,
/// which processes the prompt on its next loop iteration once
/// translate_event returns.
fn maybe_kick_worker_on_connected(workspace: &Arc<crate::Workspace>, slot: &crate::SessionSlot) {
    // The label is the worker's; a lead has none and gets no kick.
    if slot.is_lead() {
        return;
    }
    let label = slot.label();
    let Some(project_key) = workspace.project_key_for_name(slot.project()) else {
        return;
    };
    // `handle_spawn_worker` inserts the entry as Spawning before the agent
    // spawn so this hook always finds it, which makes a miss an invariant
    // violation rather than a kick-less worker. Kept apart from `None`
    // kick, which is the ordinary silent case.
    let Some(entry) =
        workspace.list_live_workers(&project_key).into_iter().rev().find(|w| w.label == label)
    else {
        tracing::warn!(
            target: "forge_workspace::workers",
            label = %label,
            slot = %slot.display(),
            "no live worker entry for this label; the worker connects unkicked and idles",
        );
        return;
    };
    let Some(kick) = entry.kick else {
        return;
    };
    // #259: kicks route through the workspace-level dispatcher so
    // multi-worker boots don't fire N simultaneous Prompts at
    // Anthropic's per-IP burst limit. The drainer fires one per
    // `KICK_DISPATCH_INTERVAL`; the first kick of an empty queue
    // has zero added latency.
    workspace.enqueue_kick(crate::workspace::KickRequest { slot: slot.clone(), prompt_body: kick });
}

/// A lead's first turn after a boot spawn handed it a stored session id
/// to resume: the restart note the spawn stamped on the domain when the
/// boot read the seat as mid-turn. The hook takes the note, so a reconnect
/// repeats nothing, and a parked seat, a first boot or `--new` never
/// stamped one.
fn maybe_kick_lead_on_connected(
    workspace: &Arc<crate::Workspace>,
    slot: &crate::SessionSlot,
    domain: &Mutex<DomainSession>,
) {
    if !slot.is_lead() {
        return;
    }
    let Some(note) = domain.lock().pending_lead_resume_note.take() else { return };
    workspace.enqueue_kick(crate::workspace::KickRequest { slot: slot.clone(), prompt_body: note });
}

/// Test-only entry point for the Connected hooks.
/// Drives `maybe_respawn_workers_on_connected` (lead path) and
/// `maybe_kick_worker_on_connected` (worker path) directly without
/// constructing a `SessionTask` or pumping through the actor - the
/// `connected_hook_tests` module uses this to assert the trigger logic.
/// The slot's label selects: a lead drives the respawn, a worker its
/// kick. The lead restart-note hook is exercised by its own test, which
/// needs the session's domain.
#[cfg(test)]
fn on_connected_for_test(
    workspace: &Arc<crate::Workspace>,
    slot: &crate::SessionSlot,
    _real_session_id: &str,
) {
    // Normal (non-`--new`) Connected simulation; the force-new cascade
    // is exercised directly against respawn_workers_for_lead.
    maybe_respawn_workers_on_connected(workspace, slot, false);
    maybe_kick_worker_on_connected(workspace, slot);
}

/// Forward a `Command` straight to `handle`. Pure transport - no
/// pending-interaction bookkeeping; the only commands that consult
/// `PendingInteractionSlot` (RespondPermission / RespondQuestion)
/// must be handled by the caller before delegation here.
///
/// Used by both `SessionTask::execute_command` (production: actor
/// path) and `Workspace::dispatch`'s synchronous test fallback when
/// no `SessionTask` is running for `key`.
///
/// Returns `Ok(())` on successful enqueue; `Err(...)` on AgentHandle
/// send failure (dispatcher channel closed) or on a command dropped
/// for having no `session_id` yet (pre-Connect).
pub(crate) fn execute_command_via_handle(
    handle: &Arc<AgentHandle>,
    key: &SessionSlot,
    session_id: Option<&str>,
    new_session_id: Option<String>,
    cmd: Command,
) -> Result<(), forge_agent::AgentError> {
    match cmd {
        // A handoff runs the task's own state machine, before it reaches here;
        // a vault answer is workspace state, handled before the agent path.
        Command::Handoff { .. } | Command::RespondVaultAsk { .. } => Ok(()),
        Command::Prompt { key: _, text, attachments } => {
            let Some(sid) = session_id else {
                return Err(warn_no_session(key, "Prompt"));
            };
            // The live path rewrites `Prompt` into `PromptUnder` before it gets
            // here, so this arm is the test fallback's alone: it mints without
            // recording, because the fallback holds no session state to record
            // into.
            let uuid = forge_sdk::request_id::next_prompt_id();
            handle.prompt_with_images(sid.to_owned(), text, attachments, uuid)
        }
        Command::PromptUnder { key: _, text, attachments, uuid, source: _, dispatch_id: _ } => {
            let Some(sid) = session_id else {
                return Err(warn_no_session(key, "PromptUnder"));
            };
            handle.prompt_with_images(sid.to_owned(), text, attachments, uuid)
        }
        Command::Cancel { key: _ } => {
            let Some(sid) = session_id else {
                return Err(warn_no_session(key, "Cancel"));
            };
            handle.cancel(sid.to_owned())
        }
        Command::CancelQueuedPrompt { key: _, uuid } => {
            let Some(sid) = session_id else {
                return Err(warn_no_session(key, "CancelQueuedPrompt"));
            };
            handle.cancel_queued(sid.to_owned(), uuid)
        }
        Command::SetMode { key: _, mode } => {
            let Some(sid) = session_id else {
                return Err(warn_no_session(key, "SetMode"));
            };
            handle.set_mode(sid.to_owned(), mode)
        }
        Command::SetModel { key: _, model } => {
            let Some(sid) = session_id else {
                return Err(warn_no_session(key, "SetModel"));
            };
            handle.set_model(sid.to_owned(), model)
        }
        Command::NewSession { key: _, cwd, launch_settings, .. } => {
            handle.new_session(new_session_id, cwd, launch_settings)
        }
        Command::ResumeSession { key: _, session_id, cwd, launch_settings } => {
            handle.resume_session(session_id, cwd, launch_settings)
        }
        Command::RespondPermission { .. } | Command::RespondQuestion { .. } => {
            tracing::error!(
                target: "forge_workspace::session_task",
                slot = %key.display(),
                command = ?cmd,
                "Respond* commands must be handled by SessionTask::execute_command before delegation"
            );
            Ok(())
        }
        // No per-session route: app-level commands are caught in
        // `Workspace::dispatch`'s own branches, and `ReadCallOutput` is
        // answered by the transport from its held conversation before any
        // dispatch. A command of either kind arriving here is a wiring bug.
        misrouted @ (Command::ReadCallOutput { .. }
        | Command::SetDictateOverride { .. }
        | Command::ResetDictateOverrides { .. }
        | Command::DictateStream { .. }
        | Command::DictateStop { .. }
        | Command::SpawnProject { .. }
        | Command::DeliverPeerPrompt { .. }
        | Command::SpawnWorker { .. }
        | Command::CloseWorker { .. }
        | Command::DespawnWorker { .. }
        | Command::DeliverWorkerPrompt { .. }
        | Command::DeliverWorkerPromptToLead { .. }
        | Command::DeliverGotifyMessage { .. }
        | Command::RespondSlackPost { .. }
        | Command::RespondBrowserHandOff { .. }
        | Command::RespondTerminalHandOff { .. }
        | Command::AnswerDocumentHandOff { .. }
        | Command::DictateCatalogueCheck
        | Command::DictateInstall { .. }
        | Command::DictateActivate { .. }
        | Command::DictateDeactivate { .. }
        | Command::DictateBench { .. }
        | Command::DictateBenchStop
        | Command::VoiceBenchStart
        | Command::VoiceBenchStop
        | Command::DictateReadAloudStart { .. }
        | Command::DictateReadAloudStop { .. }
        | Command::DictateReadAloudDelete { .. }
        | Command::DictateBenchDelete { .. }
        | Command::DictateUninstall { .. }
        | Command::SetReviewThreadStatus { .. }
        | Command::CloseSession { .. }
        | Command::UpsertReviewThread { .. }
        | Command::DeleteReviewThread { .. }
        | Command::SubmitReview { .. }
        | Command::TaskVerdict { .. }
        | Command::TaskAnswer { .. }
        | Command::TaskRank { .. }
        | Command::TaskAssign { .. }
        | Command::TaskCreate { .. }
        | Command::TaskMove { .. }
        | Command::TaskReopen { .. }
        | Command::TaskReserve { .. }
        | Command::PluginInstall { .. }
        | Command::PluginUpdate { .. }
        | Command::PluginUpdateAll
        | Command::PluginCheckUpdates
        | Command::MarketplaceAdd { .. }
        | Command::MarketplaceRepair { .. }
        | Command::RespondSettingsWrite { .. }
        | Command::VoiceMode { .. }
        | Command::VoicePreview { .. }
        | Command::BiometricEnrol { .. }
        | Command::BiometricRewrite { .. }
        | Command::BiometricRelease { .. }
        | Command::BiometricRevoke { .. }
        | Command::VaultLock
        | Command::VaultEnrolmentMaterial { .. }) => {
            tracing::warn!(
                target: "forge_workspace::session_task",
                slot = %key.display(),
                command = ?misrouted,
                "command has no per-session route"
            );
            Ok(())
        }
    }
}

/// The words a permission answer carried, where it carried any: the box's own
/// notes, the one field a dictation into the ask lands in (#1360).
/// Hold a prompt aimed at a seat that is swapping its occupant, answering
/// whether it went into the hold.
///
/// The machinery's own deliveries are gated in
/// `Workspace::dispatch_workspace_prompt_under`; a person's prompt reaches
/// the task directly, so this is the door it comes through.
fn held_while_swapping(
    cmd: &Command,
    key: &SessionSlot,
    workspace: &std::sync::Weak<crate::Workspace>,
) -> bool {
    let prompt = match cmd {
        Command::Prompt { key: _, text, attachments } => crate::handoff::HeldPrompt {
            text: text.clone(),
            attachments: attachments.clone(),
            source: PromptSource::You,
            // A plain prompt carries no id yet; this is the one it keeps
            // through the hold and the drain, so the transcript row the
            // successor writes carries it.
            uuid: forge_sdk::request_id::next_prompt_id(),
            sender: None,
        },
        Command::PromptUnder { key: _, text, attachments, source, uuid, .. } => {
            crate::handoff::HeldPrompt {
                text: text.clone(),
                attachments: attachments.clone(),
                source: *source,
                uuid: uuid.clone(),
                sender: None,
            }
        }
        _ => return false,
    };
    let Some(workspace) = workspace.upgrade() else { return false };
    workspace.hold_prompt(key, prompt)
}

/// The fill a reading states, against the CLI's own effective window.
///
/// **Counted from the two numbers rather than taken from the reported
/// share** when both are there: the denominator has to be the effective
/// window after any lowered auto-compact window, so a reading that names
/// only its share is the fallback rather than the truth. `None` when
/// neither says anything, so nothing fires on a guess.
fn fill_of(
    reported: Option<u8>,
    total_tokens: Option<u64>,
    effective_max_tokens: Option<u64>,
) -> Option<crate::handoff::FillReading> {
    if let (Some(total), Some(max)) = (total_tokens, effective_max_tokens)
        && max > 0
    {
        let percent = total.saturating_mul(100).saturating_add(max / 2) / max;
        return Some(crate::handoff::FillReading {
            percent: u8::try_from(percent).unwrap_or(u8::MAX),
            total_tokens: total,
            max_tokens: max,
        });
    }
    reported.map(|percent| crate::handoff::FillReading { percent, total_tokens: 0, max_tokens: 0 })
}

fn permission_words(outcome: &forge_primitives::PermissionOutcome) -> Option<String> {
    match outcome {
        forge_primitives::PermissionOutcome::Selected { notes_text, .. } => notes_text.clone(),
        forge_primitives::PermissionOutcome::Cancelled => None,
    }
}

/// The words a question answer carried, where it carried any: its own note,
/// for the same reason as [`permission_words`].
fn question_words(outcome: &forge_primitives::QuestionOutcome) -> Option<String> {
    match outcome {
        forge_primitives::QuestionOutcome::Answered { annotation, .. } => {
            annotation.as_ref().and_then(|held| held.notes.clone())
        }
        forge_primitives::QuestionOutcome::Cancelled => None,
    }
}

fn warn_no_session(key: &SessionSlot, command: &'static str) -> forge_agent::AgentError {
    tracing::warn!(
        target: "forge_workspace::session_task",
        slot = %key.display(),
        command,
        "command dropped: no session_id stamped on DomainSession yet",
    );
    forge_agent::AgentError::NoSession { command }
}

/// The wire subtype of the retry frame, where the CLI names an
/// authentication failure on the retry path. A view matches the same
/// literal.
const API_RETRY_SUBTYPE: &str = "api_retry";

/// What the failure is called in the nudge: the CLI's own errors when the
/// result frame reported any, else its subtype, else a plain fallback.
pub(crate) fn failure_reason(errors: Option<&[String]>, subtype: &str) -> String {
    if let Some(errors) = errors.filter(|errors| !errors.is_empty()) {
        return errors.join("; ");
    }
    if !subtype.is_empty() && subtype != "success" {
        return subtype.to_owned();
    }
    "an error".to_owned()
}

/// What one event MOVED in the domain's whole sets.
///
/// **A set that did not change is not news.** Each moves whole and on discrete
/// frames, and every frame of a busy seat reaches this fold - so a viewer
/// redrawing on each one would pay for nothing, and the answer is taken by
/// comparing the sets the fold was handed with the ones it left.
///
/// The walk joins them on the death only: nothing else in this fold writes it
/// (the seat's own loop does), so the flag is the one
/// transition this fold makes - a snapshot that was held and is now gone.
pub(crate) struct Moved {
    pub monitors: bool,
    pub background_tasks: bool,
    pub processes: bool,
    pub commands: bool,
    pub agents: bool,
    pub cards: bool,
    /// The prompts still queued when the occupant went. They died with its
    /// process, so the caller draws the row each one will never get.
    pub lost_prompts: Vec<crate::protocol::QueuedPrompt>,
    /// A failed turn armed the continuation, which the caller fires the
    /// moment this fold returns.
    pub nudge: bool,
    /// The CLI reported a repository mutation. `Some(false)` re-reads the
    /// tree, `Some(true)` also re-runs the PR lookup because the held block
    /// was looked up before the change existed.
    pub repo_nudge: Option<bool>,
    /// The seat's turn ended in this event, as the caller announces it.
    /// `None` while no turn ended here.
    pub turn_ended: Option<MovedTurnEnd>,
}

/// What a turn's end was, for the caller to announce.
pub(crate) enum MovedTurnEnd {
    /// The turn finished (or failed) on its own; the CLI's terminal reason
    /// rides where it gave one.
    Complete { terminal_reason: Option<forge_primitives::runtime::TerminalReason> },
    /// The reader's own interrupt: the CLI reports it as a failed `Result`
    /// too, so the cancel flag is what tells the two apart.
    Cancelled,
}

/// Apply an [`AgentEvent`] to a [`DomainSession`]. Pure mutation; no
/// I/O, no async, no sends. Called from inside
/// [`SessionTask::translate_event`] under the domain's lock.
///
/// Workspace owns the routing metadata every dispatch needs
/// (`session_id`) plus the facts a view reads through the view
/// surface. Operational state a view renders from the update stream
/// itself (lifecycle, cwd, account info) stays on the view.
///
/// The answer is what the caller announces, so it is the sets as they stand
/// AFTER the fold rather than an opinion about the event.
pub(crate) fn apply_event_to_domain(domain: &mut DomainSession, event: &AgentEvent) -> Moved {
    let held_monitors = domain.monitors.clone();
    let held_tasks = domain.background_tasks.clone();
    let held_live_tasks = domain.live_tasks.clone();
    let held_walk = domain.process_snapshot.is_some();
    let held_commands = domain.available_commands.clone();
    let held_agents = domain.available_agents.clone();
    let held_cards = domain.cards_snapshot.clone();
    let mut nudge = false;
    let mut turn_ended = None;
    let mut lost_prompts = Vec::new();
    // **The CLI's own report of a repository mutation is the one signal the
    // file watch cannot produce**: a commit or a stage touches only `.git`,
    // which the watch filters out, so the tree is re-read on the frame rather
    // than at the next staleness window. A published change is the same wake
    // plus a PR lookup, because the block the seat holds was looked up before
    // the PR existed.
    let repo_nudge = match event {
        AgentEvent::SdkMessage {
            msg: forge_primitives::Message::VcsStateChanged { .. }, ..
        } => Some(false),
        AgentEvent::SdkMessage {
            msg: forge_primitives::Message::CodeChangePublished { .. },
            ..
        } => Some(true),
        _ => None,
    };
    hold_view_facts(domain, event);
    if let AgentEvent::ConnectionFailed { .. } = event {
        // The subprocess is gone - drop the runtime/turn mirrors so the
        // in-flight guards don't read a stale turn. The failure mark goes
        // with them: the row reads its failure from the lifecycle.
        domain.runtime_state = None;
        domain.reset_turns();
        domain.turn_open = false;
        domain.pending_cancel = false;
        domain.failed_turn_at = None;
        domain.auto_continue = None;
        domain.auto_continue_spent = false;
        // No terminal `background_tasks_changed` follows a dead session,
        // so the last snapshot would stand forever - and the registry with
        // it, spinning rows over tasks a dead process never finished.
        lost_prompts = domain.drop_background_tasks();
        // The walk describes the subprocess's tree, so it goes with the
        // process: left standing it draws rows for processes that are not
        // there, and nothing follows a dead session that would replace it.
        domain.process_snapshot = None;
    }
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::Result { is_error, subtype, errors, terminal_reason, .. },
        ..
    } = event
    {
        // The stamp is spent on every outcome: a cancel that raced a turn
        // the CLI had already finished must not exempt the next failure.
        let cancelled = std::mem::take(&mut domain.pending_cancel);
        // The turn's end is announced (#1486): the frames carry the
        // Result, but a page's live row reads its liveness from the record
        // and only this frame asks it to re-read. **Every Result announces**,
        // including one covering no turn at all (a `/compact` on an idle
        // seat): the frame states the CLI's terminator, and a page whose
        // record says nothing is in flight no-ops on it. The cancel flag is
        // the one the failure mark already spends, so an interrupt racing a
        // finished turn is announced as cancelled and a cancel spent by an
        // earlier result reads as a completion - the page settles either
        // way, and only its record-consult differs.
        turn_ended = Some(if cancelled {
            MovedTurnEnd::Cancelled
        } else {
            MovedTurnEnd::Complete { terminal_reason: *terminal_reason }
        });
        // A foreground call cannot outlive the turn that ran it, and its own
        // ending frame does not always come: the `TaskStop` tool path sends
        // none, and a cancelled turn can bury the one it would have sent. A
        // backgrounded call outlives its turn and stays in the registry.
        domain.settle_foreground_holds();
        // An errored `Result` marks the slot for the rail, unless the
        // reader asked for the interruption - a cancel ends with the same
        // failed result a genuine error does.
        if *is_error && !cancelled {
            let at = std::time::SystemTime::now();
            domain.failed_turn_at = Some(at);
            // Every non-cancelled failed turn is this nudge's to answer,
            // whatever its class: the caller fires the continuation the
            // moment this fold returns, so a seat nobody is watching
            // resumes without the person having to type again (#2146).
            if !domain.auto_continue_spent {
                domain.auto_continue = Some(PendingAutoContinue {
                    reason: failure_reason(errors.as_deref(), subtype),
                });
                nudge = true;
            }
        } else if !*is_error {
            // A turn that finished ends the episode: a later failure is a
            // new one and gets its own nudge.
            domain.auto_continue = None;
            domain.auto_continue_spent = false;
        }
    }
    if let AgentEvent::SdkMessage { msg: forge_primitives::Message::Error { .. }, .. } = event {
        // A transport death ends the turn too; nothing marks for it, but
        // the stamp must not outlive the turn it was armed for.
        domain.pending_cancel = false;
    }
    // The snapshot carries the whole set, so mirroring it is an
    // assignment and an empty one clears.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::BackgroundTasksChanged { tasks, .. },
        ..
    } = event
    {
        domain.background_work = !tasks.is_empty();
        let parsed: Vec<crate::BackgroundTask> = tasks
            .iter()
            .filter_map(|task| {
                let entry = task.as_object()?;
                Some(crate::BackgroundTask {
                    task_id: entry.get("task_id")?.as_str()?.to_owned(),
                    // The registry names the background set by definition,
                    // and its entries carry no flag of their own.
                    is_backgrounded: true,
                    task_type: entry.get("task_type")?.as_str()?.to_owned(),
                    description: entry.get("description")?.as_str()?.to_owned(),
                    command: None,
                    tool_use_id: None,
                })
            })
            .collect();
        if parsed.len() != tasks.len() {
            tracing::debug!(
                target: "forge_workspace::session_task",
                event_name = "background_tasks_parse_dropped",
                dropped = tasks.len() - parsed.len(),
                entry_count = tasks.len(),
                "background_tasks_changed dropped unparseable entries; possible wire drift",
            );
        }
        domain.replace_background_tasks(parsed);
    }
    // The command a card carried, which is what the OS scan adopts a detached
    // process by and what tells a view that a rostered task has a row to draw.
    //
    // ANY card that carries a command, not only one whose input asked to run
    // in the background: the CLI backgrounds a bash three ways, and two of
    // them (`backgroundedByUser`, `assistantAutoBackgrounded`) cannot show on
    // the card. The `task_started` link is what scopes it - a command no
    // live task names is never read.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::Assistant { message, .. },
        ..
    } = event
    {
        for block in &message.content {
            let forge_primitives::ContentBlock::ToolUse { id, input, .. } = block else {
                continue;
            };
            if let Some(command) = input.get("command").and_then(serde_json::Value::as_str) {
                domain.hold_background_command(id.clone(), command.to_owned());
            }
        }
    }
    // `task_started` is what links a task to the card that began it, and so
    // to the command. **A `local_bash` task it announces is a call this seat
    // is running**, backgrounded or not: the registry names only the
    // backgrounded ones, so a long foreground call is held here until the
    // `task_notification` that ends it.
    if let AgentEvent::SdkMessage {
        msg:
            forge_primitives::Message::TaskStarted {
                task_id,
                description,
                tool_use_id,
                task_type,
                extras,
                ..
            },
        ..
    } = event
    {
        if let Some(tool_use_id) = tool_use_id {
            domain.hold_task_tool_use(task_id.clone(), tool_use_id.clone());
        }
        // Two flags ride the frame's unmodelled fields: the dispatch marker
        // (a sub-agent's call is not this seat's row) and the CLI's own
        // backgrounding, which a consumer reads off the hold. A frame that
        // states neither is a session call the CLI did not background.
        let dispatched = extras.get("parent_tool_use_id").and_then(serde_json::Value::as_str);
        let backgrounded =
            extras.get("is_backgrounded").and_then(serde_json::Value::as_bool).unwrap_or(false);
        if task_type.as_deref() == Some("local_bash")
            && !forge_primitives::names_a_dispatch(dispatched)
        {
            domain.note_live_task(crate::BackgroundTask {
                task_id: task_id.clone(),
                is_backgrounded: backgrounded,
                task_type: "local_bash".to_owned(),
                description: description.clone(),
                command: None,
                tool_use_id: tool_use_id.clone(),
            });
        }
    }
    // A task's own ending withdraws it from the live set. The notification is
    // the ending frame - it rides beside a terminal `task_updated` and names
    // the output file - and a terminal patch is the same answer a frame
    // earlier.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::TaskNotification { task_id, tool_use_id, .. },
        ..
    } = event
    {
        domain.settle_live_task(task_id, tool_use_id.as_deref());
    }
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::TaskUpdated { task_id, patch, .. },
        ..
    } = event
        && patch.status.as_deref().is_some_and(task_status_is_terminal)
    {
        // The patch names only the task, so the id is the only match here.
        domain.settle_live_task(task_id, None);
    }
    if let AgentEvent::Connected { session_id, .. } = event {
        domain.session_id = Some(SessionId::new(session_id.clone()));
        domain.runtime_state = None;
        domain.reset_turns();
        domain.turn_open = false;
        // The failure mark named the last occupant's turn, and so did any
        // interrupt it was holding.
        domain.pending_cancel = false;
        domain.failed_turn_at = None;
        domain.auto_continue = None;
        domain.auto_continue_spent = false;
        // A second Connected is a new occupant in the same slot, and the
        // CLI re-sends the whole background set only when it changes: a
        // registry left standing would spin a row over a task that went
        // with the identity it belonged to.
        lost_prompts = domain.drop_background_tasks();
        // A new occupant has advertised nothing yet: the CLI sends
        // `system/init` at the head of a turn only, so the last one's
        // catalogues would stand until this one's first message - and
        // after a login swap they came from another account's config dir.
        domain.available_commands.clear();
        domain.available_agents.clear();
        // The agent catalogue is read from the first init of a turn, and
        // a swap that ends no turn - a mid-turn `/new`, a reconnect after
        // a login - never sees the Result that re-arms it. Left armed it
        // would drop the new occupant's own init and keep the list empty
        // for a whole turn, which is the state clearing the two above is
        // meant to end.
        domain.agents_emitted_this_turn = false;
        // It connected, so it is not waiting to be let in.
        domain.awaiting_login = false;
    }
    // The login wait, from the two signals the CLI actually sends: it
    // attributes the failure to the assistant message, or names it on the
    // retry frame. `AssistantMessageError` is typed, so nothing here keys
    // on prose.
    if let AgentEvent::SdkMessage { msg, .. } = event {
        match msg {
            forge_primitives::Message::Assistant {
                error: Some(forge_primitives::AssistantMessageError::AuthenticationFailed),
                ..
            } => domain.awaiting_login = true,
            forge_primitives::Message::System { subtype, data, .. }
                if subtype == API_RETRY_SUBTYPE =>
            {
                if let Some(update) = data
                    .as_object()
                    .and_then(forge_agent::translate::state_parsing::build_api_retry_update)
                    && update.error == forge_primitives::ApiRetryError::AuthenticationFailed
                {
                    domain.awaiting_login = true;
                }
            }
            _ => {}
        }
    }
    // A `TurnError` the classifier reads as auth-required holds the session
    // on `/login`. The class is derived where the event is built, so it is
    // read here rather than searched out of the message again, and a class
    // the producer could not name stays unclassified rather than being
    // guessed at.
    if let AgentEvent::TurnError { class, .. } = event
        && *class == forge_primitives::TurnErrorClass::AuthRequired
    {
        domain.awaiting_login = true;
    }
    // A turn that finished proves the credential works, so the wait is
    // over before any reconnect. Success only: a turn that died on the
    // missing credential ends with its own failed `Result`, and clearing
    // on that would undo the mark the frames above just set. The same
    // two-line test exists on the view surface, and folding the two into
    // one is its own piece.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::Result { is_error, subtype, .. },
        ..
    } = event
        && !*is_error
        && subtype == "success"
    {
        domain.awaiting_login = false;
    }
    // Mirror runtime liveness from `session_state_changed` so the
    // workspace's in-flight guards see a turn authoritatively,
    // independent of a view's gate. Reuse the canonical decoder parser
    // rather than re-inlining it.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::System { subtype, data, .. },
        ..
    } = event
        && subtype == "session_state_changed"
        && let Some(state) =
            forge_agent::translate::state_parsing::parse_runtime_session_state(data.get("state"))
    {
        domain.runtime_state = Some(state);
    }
    // Mirror the frames' own claim about the turn, which is the one signal
    // that covers a turn's OPENING: `turn_pending` is spent by the previous
    // Result and `session_state_changed` no longer arrives, so thinking and
    // prose alone left the header reading idle while the model worked
    // (`DomainSession::turn_open` carries the measured window).
    if let AgentEvent::SdkMessage { msg, .. } = event
        && let Some(said) = crate::domain_session::liveness_of(msg)
    {
        domain.note_liveness(said);
    }
    // The two catalogues the composer's autocomplete reads, as the CLI
    // last advertised them. Held on the session so a view arriving after
    // the turn started reads one answer rather than waiting for the next
    // init frame, which is a whole turn away.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::System { subtype, data, .. },
        ..
    } = event
        && subtype == "init"
        && let Some(record) = data.as_object()
    {
        if let Some(entries) = record.get("slash_commands").and_then(serde_json::Value::as_array) {
            let commands =
                forge_agent::translate::commands::map_available_commands_from_json(entries);
            // An init frame that advertises none carries nothing about
            // them, and the CLI re-fires one every turn.
            if !commands.is_empty() {
                domain.available_commands = commands;
            }
        }
        if !domain.agents_emitted_this_turn
            && let Some(agents) = record.get("agents")
        {
            domain.available_agents =
                forge_agent::translate::agents::map_available_agents_from_names(Some(agents));
            domain.agents_emitted_this_turn = true;
        }
    }
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::CommandsChanged { commands, .. },
        ..
    } = event
    {
        let parsed = forge_agent::translate::commands::map_available_commands_from_json(commands);
        // A payload carrying entries that parse to none means the CLI's
        // entry shape changed under us, and storing it would wipe the
        // list; a legitimately empty one clears it.
        let drift = parsed.is_empty() && !commands.is_empty();
        if drift {
            // A view reading the surface alone would otherwise lose the
            // signal this guard logs.
            tracing::warn!(
                target: "forge_workspace::session_task",
                slot = %domain.key.display(),
                event_name = "commands_changed_parse_empty",
                message = "commands_changed carried entries but none parsed; likely wire drift, keeping prior list",
                outcome = "skipped",
                entry_count = commands.len(),
            );
        } else {
            domain.available_commands = parsed;
        }
    }
    // The turn boundary re-arms the agent read.
    if let AgentEvent::SdkMessage {
        msg: forge_primitives::Message::Result { .. } | forge_primitives::Message::Error { .. },
        ..
    } = event
    {
        domain.agents_emitted_this_turn = false;
    }
    // The instance list folds frame by frame, in this same walk: the frames
    // that open and settle a card are matched here either way, so the join
    // costs a lookup rather than a second pass over the conversation. The
    // push is change-gated on the list itself - a frame that moved nothing
    // announces nothing.
    if let AgentEvent::SdkMessage { msg, .. } = event {
        domain.card_tracker.apply(msg);
        let cards = domain.card_tracker.cards();
        if cards != domain.cards_snapshot {
            domain.cards_snapshot = cards;
        }
    }
    Moved {
        monitors: domain.monitors != held_monitors,
        background_tasks: domain.background_tasks != held_tasks
            || domain.live_tasks != held_live_tasks,
        processes: held_walk && domain.process_snapshot.is_none(),
        commands: domain.available_commands != held_commands,
        agents: domain.available_agents != held_agents,
        // Live news only: a connect seeds the list from the history it
        // carries and the read on that event answers it.
        cards: domain.cards_snapshot != held_cards
            && matches!(event, AgentEvent::SdkMessage { .. }),
        nudge,
        repo_nudge,
        turn_ended,
        lost_prompts,
    }
}

/// Drop every fact that describes one run of a session: the hook's mode
/// and effort, the model it resolved, the two bridge snapshots that
/// describe a subprocess tree, and the monitor set that run started.
///
/// This mirrors the view's own reset on the same events, so what it holds
/// is what a view draws. Two facts are deliberately not here, because the
/// view's reset does not touch them either: the sub-agent attribution
/// outlives the run it came from, and the process walk is cleared on the
/// death alone - where the tree it describes goes with the subprocess -
/// rather than on every identity this clears.
fn clear_runtime_identity(domain: &mut DomainSession) {
    domain.observed_permission_mode = None;
    domain.observed_effort = None;
    domain.current_model = None;
    domain.mcp_servers = None;
    domain.context_usage = None;
    // A handoff belongs to the occupant that was running it: its reply, its
    // parked request and its judgment describe a conversation the new one
    // does not carry.
    domain.handoff = crate::domain_session::HandoffState::default();
    domain.monitors.clear();
}

/// The facts this event carries that a view reads through the view
/// surface: the hook observation's mode and effort, the two bridge
/// snapshots, the resolved model, and the monitor set.
///
/// One source, two readers: each fact is folded from the same event the
/// `SessionUpdate` for it is built from, so the held copy cannot drift
/// from the streamed one.
fn hold_view_facts(domain: &mut DomainSession, event: &AgentEvent) {
    if let AgentEvent::Connected { current_model, available_models, history_updates, .. } = event {
        // A replacement occupant inherits nothing the last one held:
        // its hook mirrors describe a session that is gone, and its
        // bridge snapshots describe subprocesses that went with it.
        clear_runtime_identity(domain);
        domain.current_model = Some(current_model.clone());
        domain.available_models.clone_from(available_models);
        // The instance fold is seeded from the history the connect carries,
        // so a resumed seat answers the card list its history holds.
        domain.card_tracker = crate::subagent_cards::CardTracker::default();
        if let Some(history) = history_updates.as_ref() {
            for message in history {
                domain.card_tracker.apply(message);
            }
        }
        domain.cards_snapshot = domain.card_tracker.cards();
        // A monitor started before this process did is in the transcript
        // the connect carries, so the same fold runs over it: a view
        // opening the session sees the monitor rather than nothing. A
        // sub-agent's Monitor call is the instance's, not the session's.
        if let Some(history) = history_updates {
            for msg in history {
                if forge_primitives::messages::ran_under_a_dispatch(msg) {
                    continue;
                }
                fold_monitor(domain, msg, MonitorOrigin::Transcript);
            }
            // A transcript's monitors are all settled, so the seed drains in
            // the one call: a resumed session shows no section rather than a
            // row per monitor it ever ran.
            drain_settled_monitors(domain);
        }
    }
    // A connection that died leaves the session with no runtime identity.
    // The core blanks what a view reads through it - a mode or a model left
    // standing describes a run that is gone.
    if matches!(event, AgentEvent::ConnectionFailed { .. }) {
        clear_runtime_identity(domain);
    }
    if let AgentEvent::HookObservation { permission_mode, effort, .. } = event {
        if let Some(mode) =
            permission_mode.as_deref().and_then(forge_primitives::PermissionMode::from_wire)
        {
            domain.observed_permission_mode = Some(mode);
        }
        // An unreadable level is a level forge cannot name, not a reason
        // to forget the one already held.
        if let Some(level) = effort.as_deref().and_then(forge_primitives::EffortLevel::from_stored)
        {
            domain.observed_effort = Some(level);
        }
    }
    if let AgentEvent::McpSnapshot { servers, error, .. } = event {
        domain.mcp_servers = Some(crate::domain_session::McpServers {
            servers: servers.clone(),
            error: error.clone(),
        });
    }
    if let AgentEvent::ContextUsage { percentage, max_tokens, .. } = event {
        domain.context_usage = Some(crate::domain_session::ContextUsage {
            percent: *percentage,
            max_tokens: *max_tokens,
        });
    }
    if let AgentEvent::SdkMessage { msg, .. } = event {
        fold_monitor(domain, msg, MonitorOrigin::Wire);
        if let forge_primitives::Message::System { subtype, data, .. } = msg
            && subtype == "init"
        {
            reconcile_model_from_init(domain, data);
        }
    }
}

/// Take the model a turn's `system/init` names, which is how a switch
/// reaches a reader: `/model` re-fires the frame with the model the turn
/// runs under, and the frame arrives at the head of every turn besides.
///
/// A frame naming the model the session is already on changes nothing, so
/// a session that did not switch keeps the name its connect resolved
/// rather than being renamed to the CLI's own spelling of the same model.
fn reconcile_model_from_init(domain: &mut DomainSession, data: &serde_json::Value) {
    let Some(model_id) = data.get("model").and_then(serde_json::Value::as_str).map(str::trim)
    else {
        return;
    };
    if model_id.is_empty()
        || domain.current_model.as_ref().is_some_and(|held| held.resolved_id == model_id)
    {
        return;
    }
    // No requested id: the pin forge stamped described the model the
    // session connected on, and the CLI has just named a different one, so
    // the CLI's own answer is what names this model.
    domain.current_model = Some(forge_agent::session_lifecycle::resolve_current_model_from_inputs(
        model_id,
        None,
        None,
        &domain.available_models,
    ));
}

/// Whether a `task_updated` patch names a status that ends the task.
fn task_status_is_terminal(status: &str) -> bool {
    monitor_status_from_wire(status).is_some()
}

/// The status a terminal `task_updated` names, in the vocabulary the
/// renderers use. `None` for a status that is not terminal, and for one
/// forge does not know: a patch that only stamps an end time carries no
/// status at all.
fn monitor_status_from_wire(status: &str) -> Option<forge_primitives::MonitorStatus> {
    match status {
        "completed" => Some(forge_primitives::MonitorStatus::Completed),
        "failed" | "killed" | "stopped" => Some(forge_primitives::MonitorStatus::Stopped),
        _ => None,
    }
}

/// Which side of the session a monitor was folded from, which decides the
/// state it starts in.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MonitorOrigin {
    /// The live wire, where a `Monitor` tool call means the monitor runs
    /// until a command frame settles it.
    Wire,
    /// The transcript a connect carries. It holds no lifecycle frame - the
    /// replay synthesizer emits user and assistant messages only - so a
    /// monitor found here is one whose task is over as far as this process
    /// can tell, and nothing that follows can settle it, because every
    /// settlement is keyed on the task id a transcript cannot carry.
    Transcript,
}

/// Fold one wire message into the session's monitor set: the `Monitor`
/// tool call that starts one, the task id the CLI assigns it, and the
/// lifecycle message that settles it.
///
/// The CLI's task ids are what the terminal transitions are keyed by,
/// so a record's `task_id` is what lets a later `task_updated` find it
/// at all.
fn fold_monitor(
    domain: &mut DomainSession,
    msg: &forge_primitives::Message,
    origin: MonitorOrigin,
) {
    match msg {
        forge_primitives::Message::Assistant { message, .. } => {
            for block in &message.content {
                let forge_primitives::ContentBlock::ToolUse { id, name, input, .. } = block else {
                    continue;
                };
                if name != "Monitor" {
                    continue;
                }
                let Some(parsed) = forge_agent::user_interaction::parse_monitor_input(input) else {
                    continue;
                };
                if domain.monitors.iter().any(|held| &held.tool_use_id == id) {
                    continue;
                }
                let status = match origin {
                    MonitorOrigin::Wire => forge_primitives::MonitorStatus::Running,
                    MonitorOrigin::Transcript => forge_primitives::MonitorStatus::Completed,
                };
                domain.monitors.push(forge_primitives::MonitorRecord {
                    tool_use_id: id.clone(),
                    task_id: None,
                    description: parsed.description,
                    command: parsed.command,
                    persistent: parsed.persistent,
                    timeout_ms: parsed.timeout_ms,
                    status,
                    output_file: None,
                    ended_at: None,
                });
            }
        }
        forge_primitives::Message::TaskStarted { task_id, tool_use_id: Some(id), .. } => {
            let Some(record) = domain.monitors.iter_mut().find(|held| &held.tool_use_id == id)
            else {
                return;
            };
            record.task_id.get_or_insert_with(|| task_id.clone());
        }
        forge_primitives::Message::TaskUpdated { task_id, patch, .. } => {
            // A status forge does not classify is one it cannot act on,
            // so only the instant is stamped then: it is a fact the frame
            // states whether or not this build can name how it ended.
            settle_monitor(
                domain,
                task_id,
                patch.status.as_deref().and_then(monitor_status_from_wire),
                None,
                patch.end_time,
            );
        }
        forge_primitives::Message::TaskNotification { task_id, status, output_file, .. } => {
            let settled = match status {
                forge_primitives::TaskNotificationStatus::Completed => {
                    Some(forge_primitives::MonitorStatus::Completed)
                }
                forge_primitives::TaskNotificationStatus::Failed
                | forge_primitives::TaskNotificationStatus::Stopped => {
                    Some(forge_primitives::MonitorStatus::Stopped)
                }
                // A status forge cannot name settles nothing, but it is
                // still a notification and the drain below is unconditional.
                forge_primitives::TaskNotificationStatus::Unknown => None,
            };
            if let Some(status) = settled {
                settle_monitor(domain, task_id, Some(status), Some(output_file.clone()), None);
            }
            // The notification is the last frame a monitor sends, so it is
            // where the set drains once nothing in it is running: a session
            // that ran a monitor an hour ago draws no section in any view.
            drain_settled_monitors(domain);
        }
        _ => {}
    }
}

/// Drop the monitor set once every entry in it is terminal.
fn drain_settled_monitors(domain: &mut DomainSession) {
    if !domain.monitors.is_empty()
        && domain.monitors.iter().all(|monitor| monitor.status.is_terminal())
    {
        domain.monitors.clear();
    }
}

fn settle_monitor(
    domain: &mut DomainSession,
    task_id: &str,
    status: Option<forge_primitives::MonitorStatus>,
    output_file: Option<String>,
    end_time_ms: Option<u64>,
) {
    let Some(record) =
        domain.monitors.iter_mut().find(|held| held.task_id.as_deref() == Some(task_id))
    else {
        return;
    };
    if let Some(status) = status {
        record.status = status;
    }
    if let Some(path) = output_file {
        record.output_file = Some(path);
    }
    if let Some(end_ms) = end_time_ms {
        record.ended_at =
            Some(std::time::SystemTime::UNIX_EPOCH + std::time::Duration::from_millis(end_ms));
    }
}

/// Forward an awaited permission outcome to the agent so the bridge
/// can complete the round-trip with the CLI subprocess.
fn spawn_permission_response_forwarder(
    agent: Arc<AgentHandle>,
    response_rx: tokio::sync::oneshot::Receiver<forge_primitives::PermissionOutcome>,
    session_id: String,
    tool_call_id: String,
) {
    let span = tracing::info_span!(
        "permission_response_forwarder",
        session_id = %session_id,
        tool_call_id = %tool_call_id,
    );
    tokio::task::spawn(
        async move {
            let Ok(outcome) = response_rx.await else {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    session_id = %session_id,
                    tool_call_id = %tool_call_id,
                    "permission response channel closed before forwarding"
                );
                return;
            };
            let selected_option = match &outcome {
                forge_primitives::PermissionOutcome::Selected { option_id, .. } => {
                    option_id.clone()
                }
                forge_primitives::PermissionOutcome::Cancelled => "cancelled".to_owned(),
            };
            let session_id_for_log = session_id.clone();
            let tool_call_id_for_log = tool_call_id.clone();
            match agent.permission_response(session_id, tool_call_id, outcome) {
                Ok(()) => {
                    tracing::info!(
                        target: "forge_workspace::session_task",
                        session_id = %session_id_for_log,
                        tool_call_id = %tool_call_id_for_log,
                        selected_option = %selected_option,
                        "permission response forwarded to bridge"
                    );
                }
                Err(err) => {
                    tracing::error!(
                        target: "forge_workspace::session_task",
                        session_id = %session_id_for_log,
                        tool_call_id = %tool_call_id_for_log,
                        selected_option = %selected_option,
                        error = %err,
                        "failed to forward permission response to bridge"
                    );
                }
            }
        }
        .instrument(span),
    );
}

/// Forward an awaited question outcome to the agent so the bridge
/// can complete the round-trip with the CLI subprocess.
fn spawn_question_response_forwarder(
    agent: Arc<AgentHandle>,
    response_rx: tokio::sync::oneshot::Receiver<forge_primitives::QuestionOutcome>,
    session_id: String,
    tool_call_id: String,
) {
    let span = tracing::info_span!(
        "question_response_forwarder",
        session_id = %session_id,
        tool_call_id = %tool_call_id,
    );
    tokio::task::spawn(
        async move {
            let Ok(outcome) = response_rx.await else {
                tracing::warn!(
                    target: "forge_workspace::session_task",
                    session_id = %session_id,
                    tool_call_id = %tool_call_id,
                    "question response channel closed before forwarding"
                );
                return;
            };
            let selected_option_count = match &outcome {
                forge_primitives::QuestionOutcome::Answered { selected_option_ids, .. } => {
                    selected_option_ids.len()
                }
                forge_primitives::QuestionOutcome::Cancelled => 0,
            };
            let session_id_for_log = session_id.clone();
            let tool_call_id_for_log = tool_call_id.clone();
            match agent.question_response(session_id, tool_call_id, outcome) {
                Ok(()) => {
                    tracing::info!(
                        target: "forge_workspace::session_task",
                        session_id = %session_id_for_log,
                        tool_call_id = %tool_call_id_for_log,
                        selected_option_count,
                        "question response forwarded to bridge"
                    );
                }
                Err(err) => {
                    tracing::error!(
                        target: "forge_workspace::session_task",
                        session_id = %session_id_for_log,
                        tool_call_id = %tool_call_id_for_log,
                        selected_option_count,
                        error = %err,
                        "failed to forward question response to bridge"
                    );
                }
            }
        }
        .instrument(span),
    );
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used)]
mod tests {
    use super::*;
    use crate::update_fanout::{SeatUpdate, SubscriberRole};
    use forge_agent::Agent;
    use forge_agent::client::SpawnFailureKind;
    use forge_primitives::{ContentBlock, Message};

    fn empty_domain() -> DomainSession {
        let (handle, _rx) = Agent::testing_stub();
        DomainSession::new(SessionSlot::from_str_for_test("test"), Some(Arc::new(handle)))
    }

    /// The slot a test task carries. Drains resolve the parked bucket
    /// against it, so a test that parks must park under the same triple.
    fn test_slot() -> crate::SessionSlot {
        crate::SessionSlot::lead("TestOrg", "forge")
    }

    /// Drive a worker's Connected through `translate_event` with a session
    /// id the tag write cannot use, so the write fails non-NotFound and the
    /// rollback arm runs, and return the row it left behind.
    ///
    /// `connected_once` is the shape under test: false is a spawn's first
    /// Connected, true is the `/new` re-tag of a worker that is already
    /// established. The domain carries the spawn's provenance either way,
    /// since a `/new` reuses it.
    async fn tag_rollback_leftover_row(connected_once: bool) -> Option<serde_json::Value> {
        let cfg_dir = tempfile::tempdir().expect("cfg tempdir");
        std::fs::create_dir_all(cfg_dir.path().join("forge")).expect("forge dir");
        std::fs::write(
            cfg_dir.path().join("forge").join("forge.toml"),
            "[[orgs]]\nname = \"Default\"\naccounts = [\"Acct\"]\n\n\
             [[orgs.projects]]\nname = \"forge\"\npath = \"/tmp/tag-rollback-row\"\n\n\
             [[accounts]]\ndisplay_name = \"Acct\"\ntoken = \"t\"\nmodels = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
        )
        .expect("write forge.toml");
        let config = crate::config::load_from_dir(cfg_dir.path()).expect("load config");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config(cfg_dir.path().to_owned(), config)
                .expect("stub over the fixture config");
        let db_dir = tempfile::tempdir().expect("db tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        let project_key = workspace.project_key_for_name("forge").expect("the fixture project");
        let worker_slot = crate::SessionSlot::worker("Default", "forge", "steward");
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "steward".to_owned(),
                charter: "c".to_owned(),
                slot: worker_slot.clone(),
                session_id: Some(forge_primitives::SessionId::new("steward-id")),
                status: forge_primitives::WorkerLiveness::Spawning,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: crate::SessionSlot::from_str_for_test("lead-uuid"),
                // Its tag never landed, so the rollback's second fact holds.
                needs_tag: true,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );
        workspace
            .record_worker_row(
                &project_key,
                "steward",
                "steward-id",
                "charter",
                Some("kick"),
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the row the rollback judges");

        let (handle, _agent_cmds) = Agent::testing_stub();
        let arc = Arc::new(handle);
        let domain = workspace.register_domain_session(worker_slot.clone(), Some(Arc::clone(&arc)));
        // The spawn that wrote the row is the one this task runs.
        domain.lock().spawn_wrote_row = true;
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: worker_slot.clone(),
            handle: arc,
            command_rx,
            domain,
            update_tx: workspace.update_sender(),
            connected_once,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::Connected {
            session_id: "not-a-uuid".to_owned(),
            cwd: "/tmp/tag-rollback-row".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        });

        // The rollback runs in a detached task, so wait for the Removed
        // event that says it ran rather than for a wall clock.
        tokio::time::timeout(std::time::Duration::from_secs(5), async {
            while let Some(frame) = update_rx.recv().await {
                if let crate::protocol::SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && action == crate::protocol::WorkerStatusAction::Removed
                {
                    return;
                }
            }
        })
        .await
        .expect("the rollback emits a Removed event");

        let db = workspace.db.lock();
        crate::store::sessions::get(db.as_ref().expect("db"), "Default", "forge", "steward")
            .expect("read the row the rollback left")
            .map(|row| serde_json::json!({ "charter": row.charter, "kick": row.kick }))
    }

    /// A spawn's first Connected owns the row it minted: the rollback
    /// discards the spawn, and a row left behind re-spawns a worker the
    /// caller was told had failed.
    #[tokio::test]
    async fn a_first_connected_rolls_back_the_row_its_spawn_minted() {
        assert!(
            tag_rollback_leftover_row(false).await.is_none(),
            "the first Connected of a minting spawn takes the row with the rollback",
        );
    }

    /// A `/new` re-tag runs the same arm over a row that predates the
    /// connection, and the spawn's provenance is still stamped on the
    /// domain the `/new` reuses. The first-connect count is the only thing
    /// separating the two, so dropping it deletes a live worker's row.
    #[tokio::test]
    async fn a_new_session_retag_keeps_the_workers_row() {
        assert!(
            tag_rollback_leftover_row(true).await.is_some(),
            "a `/new` re-tag must not take the row of a worker that is already established",
        );
    }

    fn workspace_with_account_config_dir(
        _config_dir: &str,
    ) -> (tempfile::TempDir, Arc<crate::Workspace>) {
        let dir = tempfile::tempdir().expect("tempdir");
        let forge = dir.path().join("forge");
        std::fs::create_dir_all(&forge).expect("forge dir");
        std::fs::write(
            forge.join("forge.toml"),
            "[[orgs]]\nname = \"Default\"\naccounts = [\"Acct\"]\n\n\
             [[orgs.projects]]\nname = \"forge\"\npath = \"~/Projects/forge\"\n\n\
             [[accounts]]\ndisplay_name = \"Acct\"\ntoken = \"t\"\nmodels = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
        )
        .expect("write forge.toml");
        let workspace =
            Arc::new(crate::Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        (dir, workspace)
    }

    /// A workspace holding one submitted review plus one un-drained
    /// reply from `worker`, i.e. a turn that has touched a review and
    /// not yet ended. Returns the tempdir (kept alive for the db), the
    /// workspace, the review's submit origin, and the replying session.
    fn workspace_with_pending_review_activity()
    -> (tempfile::TempDir, Arc<crate::Workspace>, SessionSlot, SessionSlot) {
        use forge_primitives::review::{
            ReviewAnchor, ReviewAuthor, ReviewComment, ReviewSide, ReviewStatus, ReviewThread,
        };
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        workspace.upsert_review_thread(
            "forge",
            "feat",
            ReviewThread {
                id: "a".to_owned(),
                anchor: ReviewAnchor {
                    path: "src/x.rs".to_owned(),
                    side: ReviewSide::New,
                    line: 1,
                    content_hash: 1,
                    context: vec!["ctx".to_owned()],
                    base_ref: "main".to_owned(),
                },
                comments: vec![ReviewComment {
                    author: ReviewAuthor::User,
                    text: "look".to_owned(),
                    at: "t".to_owned(),
                    review_id: None,
                }],
                status: ReviewStatus::Open,
                created_at: "t".to_owned(),
                updated_at: "t".to_owned(),
                commit: None,
            },
        );
        let reviewer = SessionSlot::from_str_for_test("reviewer");
        let worker = SessionSlot::from_str_for_test("worker");
        workspace.submit_review("forge", "feat", None, &["a".to_owned()], reviewer.clone());
        workspace
            .review_reply(&worker, "forge", "feat", "a", "implementer", "fixed", "t")
            .expect("reply recorded as this turn's activity");
        (dir, workspace, reviewer, worker)
    }

    /// A `SessionTask` bound to `key`, plus the receiver for what it emits.
    fn review_task_for(
        workspace: &Arc<crate::Workspace>,
        key: &SessionSlot,
    ) -> (SessionTask, mpsc::UnboundedReceiver<SeatUpdate>) {
        let (handle, _cmds) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let domain = Arc::new(Mutex::new(DomainSession::new(key.clone(), Some(handle.clone()))));
        let task = SessionTask {
            key: key.clone(),
            handle,
            command_rx,
            domain,
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        (task, update_rx)
    }

    /// A `SessionTask` bound to `key`, plus the receiver for the agent
    /// commands it forwards. `review_task_for` drops that receiver;
    /// this keeps it for a test that asserts what the task dispatched.
    fn command_task_for(
        workspace: &Arc<crate::Workspace>,
        key: &SessionSlot,
    ) -> (SessionTask, mpsc::UnboundedReceiver<forge_primitives::AgentCommand>) {
        let (handle, cmds) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let _update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let domain = Arc::new(Mutex::new(DomainSession::new(key.clone(), Some(handle.clone()))));
        let task = SessionTask {
            key: key.clone(),
            handle,
            command_rx,
            domain,
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        (task, cmds)
    }

    /// A task that ends any way but `run`'s own tail - a panic, or a
    /// dropped runtime - takes its pool entry with it. The tail alone left
    /// a handle pooled with nothing behind it, and every later spawn
    /// fast-pathed the dead seat (#2683).
    #[tokio::test]
    async fn dropping_a_session_task_releases_its_pooled_handle() {
        let (workspace, _updates) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("drop-task-key");
        let (task, _update_rx) = review_task_for(&workspace, &key);
        let handle = Arc::clone(&task.handle);
        workspace.pool.lock().insert(
            key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&handle),
                account: forge_gateway::AccountKey("acct-a".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "drop-task".to_owned(),
            },
        );
        let (cmd_tx, _cmd_rx) = mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(key.clone(), cmd_tx);
        workspace.register_domain_session(key.clone(), Some(Arc::clone(&handle)));

        drop(task);

        assert!(!workspace.pool.lock().contains_key(&key), "the pool entry goes with its task");
        assert!(
            !workspace.command_senders.lock().contains_key(&key),
            "and the command sender the seat was addressed by",
        );
        assert!(
            !workspace.domain_handles.lock().contains_key(&key),
            "and the domain handle that pointed at it",
        );
    }

    /// A handoff swaps under the id its row names, leaves the brief where
    /// the successor takes it, and dispatches a spawn under that same id -
    /// the pair on the row and the occupant that runs are one.
    #[tokio::test]
    async fn a_handoff_swaps_under_the_id_its_row_names() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        // **A live task must reach PART 1.** The build reads the seat's own
        // domain, so the domain is registered and a background task seeded;
        // deleting `sections.extend(live)` fails this.
        workspace.domain_handles.lock().insert(slot.clone(), Arc::clone(&task.domain));
        task.domain.lock().background_tasks.push(forge_primitives::background::BackgroundTask {
            task_id: "b1".to_owned(),
            is_backgrounded: true,
            task_type: "local_bash".to_owned(),
            description: "cargo watch".to_owned(),
            command: Some("cargo watch".to_owned()),
            tool_use_id: None,
        });

        task.execute_command(Command::Handoff { key: slot.clone(), brief: None });
        task.domain.lock().handoff.judgment = Some("Now: the cut is half in.".to_owned());
        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");

        assert_eq!(record.from, "old-session-id", "the row names the session that handed over");
        assert_eq!(
            record.reason,
            forge_primitives::HandoffReason::Manual,
            "a manual handoff is a handoff asked for",
        );
        assert!(
            record.brief.ground_truth.iter().any(|section| section.label == "record"),
            "the ground truth is built at the swap: {:?}",
            record.brief.ground_truth,
        );
        let live = record
            .brief
            .ground_truth
            .iter()
            .find(|section| section.label == "background")
            .expect("the live background task reaches PART 1");
        assert!(
            live.lines.iter().any(|line| line.contains("local_bash: cargo watch [b1]")),
            "with what it is and its id: {:?}",
            live.lines,
        );
        assert!(
            record.brief.judgment.iter().any(|section| section.label == "Now"),
            "the caller's brief is the judgment half: {:?}",
            record.brief.judgment,
        );

        let dispatched = workspace.drain_test_dispatch_buffer();
        let spawn = dispatched.iter().find_map(|command| match command {
            Command::NewSession { session_id, .. } => Some(session_id.clone()),
            _ => None,
        });
        assert_eq!(
            spawn,
            Some(Some(record.to.clone())),
            "the spawn runs under the id the row names",
        );

        let pending =
            workspace.take_pending_brief(&slot).expect("the brief waits for its successor");
        assert_eq!(pending.to, record.to, "and it names the same occupant");
        assert!(pending.text.starts_with("HANDOFF - "), "the successor is given the brief");
        assert!(
            workspace.handoff_for_successor(&slot, &record.to).is_some(),
            "and the record is written, so the successor is measurable",
        );
    }

    /// A prompt that arrives while the seat swaps its occupant waits for the
    /// successor: the session on its way out is never handed a turn the new
    /// one would not carry, and what waited follows the brief.
    #[tokio::test]
    async fn a_prompt_sent_mid_swap_waits_for_the_successor() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, mut agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        task.connected_once = true;
        workspace.begin_swap(&slot);

        task.execute_command(Command::Prompt {
            key: slot.clone(),
            text: "sent mid swap".to_owned(),
            attachments: Vec::new(),
        });
        assert!(
            agent_rx.try_recv().is_err(),
            "the session on its way out is not handed the prompt",
        );

        task.translate_event(connected_event("new-session-id", "/tmp/forge"));

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == "sent mid swap"
            )),
            "the successor is handed it once it is here: {dispatched:?}",
        );
        assert!(!workspace.swap_in_progress(&slot), "and the gate is closed");
    }

    /// A replacement that is not the successor a brief names does not take
    /// it: a login or logout can land mid-swap, and the brief belongs to the
    /// session it was written for.
    #[tokio::test]
    async fn a_non_matching_replacement_leaves_the_brief_for_its_successor() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.connected_once = true;
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        workspace.set_pending_brief(
            &slot,
            crate::handoff::PendingBrief {
                to: "new-session-id".to_owned(),
                text: "HANDOFF - old -> new".to_owned(),
            },
        );

        task.translate_event(connected_event("a-login-session", "/tmp/forge"));

        assert!(
            workspace.pending_brief_for(&slot).is_some(),
            "another replacement leaves the brief for the successor it names",
        );
        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "and it is given to nobody else",
        );

        task.translate_event(connected_event("new-session-id", "/tmp/forge"));
        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text.starts_with("HANDOFF - old -> new")
            )),
            "the named successor is the one given it: {dispatched:?}",
        );
    }

    /// A handoff mints its successor without recording it: the id reaches the
    /// slot's row on Connected. A recorded id whose spawn failed is one the
    /// next boot resumes into an empty session, which the handoff record
    /// would then claim to have joined.
    #[tokio::test]
    async fn a_handoff_does_not_persist_its_successor_before_it_connects() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        workspace.note_running_session_id(&slot, "old-session-id");

        task.execute_command(Command::Handoff { key: slot.clone(), brief: None });
        task.domain.lock().handoff.judgment = Some("Now: the cut is half in.".to_owned());
        task.after_turn_ended();
        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");

        assert_eq!(
            task.domain.lock().session_id.as_ref().map(forge_primitives::SessionId::as_str),
            Some("old-session-id")
        );
        let stored = {
            let guard = workspace.db.lock();
            let db = guard.as_ref().expect("a db");
            crate::store::sessions::get(db, slot.org(), slot.project(), slot.label())
                .expect("read")
                .and_then(|row| row.session_id)
        };
        assert_eq!(
            stored.as_deref(),
            Some("old-session-id"),
            "the successor id is not on the slot's row before it has run: {record:?}",
        );
    }

    /// A swap that finds no session on the seat closes the gate its beginning
    /// opened: a hold left open would keep every later prompt for a successor
    /// nothing is bringing.
    #[tokio::test]
    async fn a_handoff_that_loses_its_session_closes_the_gate() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let key = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, mut update_rx, _agent_rx) = nudge_task_for(&workspace, &key);
        workspace.begin_swap(&key);
        workspace.hold_prompt(
            &key,
            crate::handoff::HeldPrompt {
                text: "held".to_owned(),
                attachments: Vec::new(),
                source: crate::protocol::PromptSource::You,
                uuid: "held-1".to_owned(),
                sender: None,
            },
        );

        task.swap(forge_primitives::HandoffReason::Manual, Vec::new());

        assert!(!workspace.swap_in_progress(&key), "the gate is closed with the swap");
        let mut said = Vec::new();
        let mut turns = Vec::new();
        let mut settled = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { text, .. } => said.push(text),
                SessionUpdate::MachineTurn { machine, .. } => turns.push(machine),
                SessionUpdate::PromptLifecycle { uuid, state, .. } => settled.push((uuid, state)),
                _ => {}
            }
        }
        assert!(
            said.iter().any(|text| text.contains("needs a connected session")),
            "the seat is told why: {said:?}",
        );
        assert!(
            said.iter().any(|text| text.contains("this prompt waits no longer")),
            "and the held prompt is accounted for: {said:?}",
        );
        assert!(
            settled.iter().any(|(uuid, state)| uuid == "held-1" && state == "cancelled"),
            "and the press's composer mark settles: {settled:?}",
        );
        // **The seat keeps its session, so it keeps its composer.** No
        // successor arrives whose record read would clear the machine turn.
        assert_eq!(turns, vec![None], "the machine turn ends with the handoff");
    }

    /// One handoff at a time: a swap already building takes the seat, so a
    /// handoff asked for then is dropped rather than racing it.
    #[tokio::test]
    async fn a_second_handoff_is_dropped_while_one_builds() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        workspace.begin_swap(&task.key);

        task.begin_handoff();

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "no judgment prompt is sent by a handoff that cannot own the seat",
        );
        assert!(!task.domain.lock().handoff.awaiting, "and nothing is left waiting");
    }

    /// A peer message held by the swap answers ITS SENDER when the handoff
    /// never reaches a successor, the way the parked bucket does.
    #[tokio::test]
    async fn a_failed_handoff_answers_a_held_peers_sender() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        let sender = SessionSlot::from_str_for_test("sender-proj");
        workspace.begin_swap(&task.key);
        workspace.hold_prompt(
            &task.key,
            crate::handoff::HeldPrompt {
                text: "[Message id=m-1] are you up?".to_owned(),
                attachments: Vec::new(),
                source: crate::protocol::PromptSource::Peer,
                uuid: "peer-1".to_owned(),
                sender: Some(sender.clone()),
            },
        );

        task.translate_event(AgentEvent::ConnectionFailed {
            message: "the child exited".to_owned(),
            kind: forge_agent::client::SpawnFailureKind::Unclassified,
        });

        let mut told = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && wrapped.kind == crate::mcp::peers::types::WrappedKind::DeliveryFailureNotice
            {
                told = Some((key, wrapped));
            }
        }
        let (key, notice) = told.expect("the sender is told its message never landed");
        assert_eq!(key, sender, "on the sender's own seat");
        assert_eq!(
            notice.sender_name, "forge/handoff-cut",
            "and the notice names the seat that never took it",
        );
    }

    /// **Every Result settles the seat, not only a clean one.** A success, a
    /// failure and the reader's cancel all end the turn the row names; a
    /// settle narrowed to the success arm would leave a failed seat looking
    /// mid-turn until the next boot kicked it.
    #[tokio::test]
    async fn every_result_settles_the_seat_to_idle() {
        use crate::store::sessions::SeatState;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let key = SessionSlot::worker("TestOrg", "forge", "settling");
        workspace.record_session_id("TestOrg", "forge", "settling", "id-1");
        let (mut task, _agent_rx) = command_task_for(&workspace, &key);

        for (label, subtype, cancelled, is_error) in [
            ("a success", "success", false, false),
            ("a failure", "error_during_execution", false, true),
            ("a cancel", "error_during_execution", true, true),
        ] {
            workspace.record_seat_state(&key, SeatState::InTurn);
            {
                let mut domain = task.domain.lock();
                domain.reset_turns();
                domain.commit_turn();
                // The cancel stamp is armed while the turn runs; the
                // commit's own cleanup would spend it first.
                domain.pending_cancel = cancelled;
            }

            task.translate_event(AgentEvent::SdkMessage {
                session_id: "id-1".to_owned(),
                msg: result_message(subtype, is_error),
            });

            assert_eq!(
                workspace.stored_seat_state(&key),
                Some(SeatState::Idle),
                "{label} settles the turn, so the seat is open with nothing in flight",
            );
        }
    }

    /// **A settle must not erase the turn the boundary itself starts.** A
    /// parked handoff begins its judgment turn from `after_turn_ended`; that
    /// prompt routes through the workspace and writes `in_turn`, so the
    /// settle's own `idle` has to land first. Written after the hooks, a
    /// handoff running for minutes would leave the row reading idle, and a
    /// restart in that window would park the lead with no restart note.
    #[tokio::test]
    async fn a_settle_does_not_erase_the_handoff_turn_it_starts() {
        use crate::store::sessions::SeatState;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let key = SessionSlot::lead("TestOrg", "forge");
        workspace.record_session_id("TestOrg", "forge", "lead", "id-1");
        workspace.record_seat_state(&key, SeatState::InTurn);
        let (mut task, _agent_rx) = command_task_for(&workspace, &key);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("id-1".to_owned()));
        // The handoff was asked for while the turn ran; this boundary is the
        // idle one it waited for.
        task.domain.lock().handoff.parked = true;
        task.domain.lock().commit_turn();
        // The judgment prompt routes through the workspace, so the seat has
        // to be one the workspace can route to, and the task has to hold its
        // own domain there for the commit to be seen.
        workspace.domain_handles.lock().insert(key.clone(), Arc::clone(&task.domain));
        let (command_tx, _command_rx) = tokio::sync::mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(key.clone(), command_tx);
        let _updates = workspace.subscribe_mirror();

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "id-1".to_owned(),
            msg: result_message("success", false),
        });

        assert!(task.domain.lock().handoff.awaiting, "the boundary starts the handoff");
        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::InTurn),
            "the judgment turn the boundary started is the state the row holds",
        );
    }

    /// **A turn a transport death cut off stays on the row.** The death is
    /// forge's to heal, and the state it interrupted is what the next boot
    /// reads to decide whether the seat was mid-work; a death write here
    /// would turn a stuck turn into a parked seat.
    #[tokio::test]
    async fn a_transport_death_leaves_an_interrupted_turn_in_turn() {
        use crate::store::sessions::SeatState;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let key = SessionSlot::worker("TestOrg", "forge", "dying");
        workspace.record_session_id("TestOrg", "forge", "dying", "id-1");
        workspace.record_seat_state(&key, SeatState::InTurn);
        let (mut task, _agent_rx) = command_task_for(&workspace, &key);
        task.domain.lock().commit_turn();

        task.translate_event(AgentEvent::ConnectionFailed {
            message: "the child exited".to_owned(),
            kind: forge_agent::client::SpawnFailureKind::Unclassified,
        });

        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::InTurn),
            "the interrupted turn stays on the row for the next boot",
        );
    }

    /// **A `/resume` swap leaves the seat open with nothing in flight.**
    /// The successor starts parked on the id it names, whatever the seat
    /// it replaced was doing; the next prompt is the turn that flips it.
    #[tokio::test]
    async fn a_resume_swap_leaves_the_seat_idle() {
        use crate::store::sessions::SeatState;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let key = SessionSlot::lead("TestOrg", "forge");
        workspace.record_session_id("TestOrg", "forge", "lead", "old-id");
        workspace.record_seat_state(&key, SeatState::InTurn);
        let (mut task, _agent_rx) = command_task_for(&workspace, &key);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-id".to_owned()));

        task.execute_command(Command::ResumeSession {
            key: key.clone(),
            session_id: "successor-id".to_owned(),
            cwd: "/tmp".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
        });

        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::Idle),
            "the successor starts parked",
        );
    }

    /// **A queued prompt's start is a turn start too.** `route` writes
    /// `in_turn` only for a prompt that commits a turn; one queued behind a
    /// running turn gets its own Result, so the CLI's `started` frame is the
    /// first moment the row can learn a turn is running. A crash in that
    /// turn must not leave the row reading parked.
    #[tokio::test]
    async fn a_queued_prompt_start_marks_the_seat_in_turn() {
        use crate::store::sessions::SeatState;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let key = SessionSlot::worker("TestOrg", "forge", "queued-start");
        workspace.record_session_id(key.org(), key.project(), key.label(), "id-1");
        workspace.record_seat_state(&key, SeatState::Idle);
        let (mut task, _agent_rx) = command_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "id-1".to_owned(),
            msg: forge_primitives::Message::CommandLifecycle {
                command_uuid: "queued-id".to_owned(),
                state: "started".to_owned(),
                uuid: "lifecycle-1".to_owned(),
                session_id: "id-1".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            },
        });

        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::InTurn),
            "the CLI starting a queued prompt is a turn start",
        );
    }

    /// A cancelled judgment turn ends the handoff rather than finishing it,
    /// and what the swap's gate held goes back to the session that stays.
    #[tokio::test]
    async fn a_cancelled_judgment_turn_ends_the_handoff_and_returns_its_prompts() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.judgment_started = true;
            domain.pending_cancel = true;
        }
        workspace.begin_swap(&task.key);
        workspace.hold_prompt(
            &task.key,
            crate::handoff::HeldPrompt {
                text: "sent during the swap".to_owned(),
                attachments: Vec::new(),
                source: crate::protocol::PromptSource::You,
                uuid: "held-swap".to_owned(),
                sender: None,
            },
        );

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: result_message("error_during_execution", true),
        });

        assert!(!workspace.swap_in_progress(&task.key), "the handoff is over");
        assert!(
            !task.domain.lock().handoff.awaiting,
            "and nothing is left waiting on a judgment turn",
        );
        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == "sent during the swap"
            )),
            "the held prompt goes back to the session that continues, under the id it was held \
             with: {dispatched:?}",
        );
    }

    /// The machine-turn frames this run emitted, in order.
    fn drain_machine_turns(
        rx: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Option<forge_primitives::runtime::MachineTurn>> {
        let mut out = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::MachineTurn { machine, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                out.push(machine);
            }
        }
        out
    }

    /// **A handoff announces its machine turn both ways.** The record carries
    /// the same fact for a page that attaches mid-turn, but a read is not
    /// pushed - so a page already open hears the begin and the end here, and
    /// without them the composer stays live through the handoff and locked
    /// after an abort.
    #[tokio::test]
    async fn a_handoff_announces_its_machine_turn_both_ways() {
        use forge_primitives::runtime::MachineTurn;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _workspace_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        // The fixture's task carries a fanout of its own, so this is the
        // subscriber the run's frames reach.
        let mut rx = task.update_tx.subscribe(SubscriberRole::Answering);

        task.begin_handoff();
        assert_eq!(
            drain_machine_turns(&mut rx),
            vec![Some(MachineTurn::Handoff)],
            "the seat stands down as the judgment prompt goes out",
        );

        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.judgment_started = true;
            domain.pending_cancel = true;
        }
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: result_message("error_during_execution", true),
        });
        assert_eq!(
            drain_machine_turns(&mut rx),
            vec![None],
            "the cancelled handoff hands the seat back",
        );
    }

    /// **A judgment prompt the core refuses hands the seat straight back.**
    /// The begin announced the handoff, so without the failure's own clear a
    /// composer would stay down for a handoff that never ran.
    #[tokio::test]
    async fn a_refused_judgment_prompt_clears_the_machine_turn() {
        use forge_primitives::runtime::MachineTurn;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _workspace_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        // No dispatch intercept and no seat route: the prompt cannot be sent.
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        let mut rx = task.update_tx.subscribe(SubscriberRole::Answering);

        task.begin_handoff();

        assert_eq!(
            drain_machine_turns(&mut rx),
            vec![Some(MachineTurn::Handoff), None],
            "the begin announces the turn and the refused prompt undoes it",
        );
    }

    /// A judgment prompt cancelled before it ever started is the same end
    /// as a cancelled turn: no Result will come, so the handoff must close
    /// and hand back what it was holding.
    #[tokio::test]
    async fn a_judgment_prompt_cancelled_before_it_starts_ends_the_handoff() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.judgment_started = false;
        }
        workspace.begin_swap(&task.key);
        workspace.hold_prompt(
            &task.key,
            crate::handoff::HeldPrompt {
                text: "sent during the swap".to_owned(),
                attachments: Vec::new(),
                source: crate::protocol::PromptSource::You,
                uuid: "held-swap".to_owned(),
                sender: None,
            },
        );

        task.translate_event(AgentEvent::PromptCancelResolved {
            uuid: "judgment-id".to_owned(),
            cancelled: true,
        });

        assert!(!workspace.swap_in_progress(&task.key), "the handoff is over");
        assert!(
            !task.domain.lock().handoff.awaiting,
            "and nothing waits on a brief that will never be written",
        );
        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == "sent during the swap"
            )),
            "the held prompt goes back to the session that continues, under the id it was held \
             with: {dispatched:?}",
        );
    }

    /// **The judgment prompt's committed turn settles on the abort.** The
    /// real sender path commits it, so a test that arms the handoff state by
    /// hand cannot see the leak; this one routes the prompt through a
    /// registered sender and cancels it before it starts.
    #[tokio::test]
    async fn a_cancelled_judgment_short_settles_the_committed_turn() {
        use crate::store::sessions::SeatState;

        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        workspace.domain_handles.lock().insert(slot.clone(), Arc::clone(&task.domain));
        workspace.record_session_id(slot.org(), slot.project(), slot.label(), "old-session-id");
        let (commands, mut routed) = mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(slot.clone(), commands);

        task.begin_handoff();
        assert_eq!(
            workspace.stored_seat_state(&slot),
            Some(SeatState::InTurn),
            "routing the judgment prompt commits its turn on the row",
        );

        assert!(
            matches!(
                routed.try_recv(),
                Ok(Command::PromptUnder { text, .. }) if text == crate::handoff::judgment_prompt()
            ),
            "the judgment prompt reached the seat's sender",
        );
        assert!(task.domain.lock().turn_pending, "and its turn is committed");
        let judgment_uuid = task
            .domain
            .lock()
            .handoff
            .judgment_uuid
            .clone()
            .expect("the handoff recorded its prompt id");

        task.translate_event(AgentEvent::PromptCancelResolved {
            uuid: judgment_uuid,
            cancelled: true,
        });

        let domain = task.domain.lock();
        assert!(!domain.turn_pending, "the abort settles the judgment prompt's turn");
        assert!(domain.is_idle_for_handoff(), "so the seat is idle again");
        assert!(!domain.handoff.awaiting, "and the handoff is over");
        drop(domain);
        assert_eq!(
            workspace.stored_seat_state(&slot),
            Some(SeatState::Idle),
            "and the row settles with it, so no boot kicks a turn nothing interrupted",
        );
    }

    /// A judgment prompt the CLI refuses or discards without running is the
    /// same dead end, whichever state names it.
    #[tokio::test]
    async fn a_refused_judgment_prompt_ends_the_handoff() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
        }
        workspace.begin_swap(&task.key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: forge_primitives::Message::CommandLifecycle {
                command_uuid: "judgment-id".to_owned(),
                state: "refused".to_owned(),
                uuid: "lifecycle-1".to_owned(),
                session_id: "old-session-id".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            },
        });

        assert!(!workspace.swap_in_progress(&task.key), "the handoff is over");
        assert!(
            !task.domain.lock().handoff.awaiting,
            "and the seat is free to continue on its own",
        );
        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "nothing is swapped for a brief that was refused",
        );
    }

    /// A `completed` with no `started` before it is a prompt the CLI settled
    /// without running; no Result will finish that handoff.
    #[tokio::test]
    async fn a_completed_judgment_with_no_start_ends_the_handoff() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.judgment_started = false;
        }
        workspace.begin_swap(&task.key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: forge_primitives::Message::CommandLifecycle {
                command_uuid: "judgment-id".to_owned(),
                state: "completed".to_owned(),
                uuid: "lifecycle-1".to_owned(),
                session_id: "old-session-id".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            },
        });

        assert!(!workspace.swap_in_progress(&task.key), "the handoff is over");
        assert!(!task.domain.lock().handoff.awaiting, "nothing waits on a turn that never started");
    }

    /// **A replacement in the judgment window leaves the handoff ownerless.**
    /// The old occupant's judgment turn can never produce a Result here, so
    /// the new occupant must not be swapped by it or have its trigger held
    /// off by it.
    #[tokio::test]
    async fn a_replacement_during_the_judgment_window_ends_the_handoff() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.connected_once = true;
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.judgment_started = true;
        }
        workspace.begin_swap(&task.key);
        workspace.hold_prompt(
            &task.key,
            crate::handoff::HeldPrompt {
                text: "sent during the swap".to_owned(),
                attachments: Vec::new(),
                source: crate::protocol::PromptSource::You,
                uuid: "held-swap".to_owned(),
                sender: None,
            },
        );

        task.translate_event(connected_event("replacement-id", "/tmp/forge"));

        assert!(!workspace.swap_in_progress(&task.key), "the gate is closed");
        assert!(
            !task.domain.lock().handoff.awaiting,
            "nothing waits on the previous occupant's judgment",
        );
        let dispatched = workspace.drain_test_dispatch_buffer();
        let held = dispatched
            .iter()
            .find_map(|command| match command {
                Command::PromptUnder { text, uuid, .. } if text == "sent during the swap" => {
                    Some(uuid.clone())
                }
                _ => None,
            })
            .expect("what the swap held goes to the occupant that is here");
        assert_eq!(
            held, "held-swap",
            "the drain keeps the id the hold carried, and draws no second turn: a fresh id \
             would orphan a cron row's schedule pairing (#1815)",
        );
    }

    /// The last backstop: a judgment prompt that never starts is abandoned at
    /// the deadline rather than holding the seat's gate forever.
    #[tokio::test(start_paused = true)]
    async fn a_judgment_prompt_that_never_starts_is_abandoned_at_the_deadline() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);

        task.begin_handoff();
        assert!(workspace.swap_in_progress(&task.key), "precondition: the gate is open");
        // The spawned deadline sleeps from the clock it was first polled at,
        // so it has to register before the clock moves.
        tokio::task::yield_now().await;

        tokio::time::advance(crate::handoff::JUDGMENT_DEADLINE + std::time::Duration::from_secs(1))
            .await;
        // The woken deadline task runs on the scheduler, not inside advance.
        for _ in 0..4 {
            tokio::task::yield_now().await;
        }

        assert!(!workspace.swap_in_progress(&task.key), "the deadline ends the handoff");
        assert!(
            !task.domain.lock().handoff.awaiting,
            "and the seat is free to continue on its own",
        );
    }

    /// A handoff's successor lands as a REPLACEMENT connect, and that is
    /// where its measurement must be armed; arming only on a first connect
    /// left every live handoff unmeasured.
    #[tokio::test]
    async fn a_replacement_connect_arms_the_successor_measurement() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.connected_once = true;
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        workspace.record_handoff(
            &forge_primitives::HandoffRecord {
                slot: slot.clone(),
                from: "old-session-id".to_owned(),
                to: "new-session-id".to_owned(),
                reason: forge_primitives::HandoffReason::Fill,
                fill_percent: Some(85),
                total_tokens: Some(850_000),
                max_tokens: Some(1_000_000),
                at_percent: 85,
                brief: forge_primitives::HandoffBrief::default(),
                transcript_path: "/tmp/old.jsonl".to_owned(),
                at: "2026-10-24T08:00:00Z".to_owned(),
                cycle: forge_primitives::HandoffCycle::default(),
                successor: None,
            },
            &[],
        );

        task.translate_event(connected_event("new-session-id", "/tmp/forge"));

        let watch = task.successor.as_ref().expect("the replacement connect arms it");
        assert_eq!(watch.to, "new-session-id", "for the occupant the handoff named");
        assert_eq!(watch.turns, 0, "and no prompt is counted before one runs");
        assert!(!watch.measure_at_boundary, "nor is anything measured yet");

        // The brief's own turn ending is not one of the successor's ten: the
        // brief is forge's own prompt, and the count is of a person's sends.
        task.after_turn_ended();
        assert_eq!(
            task.successor.as_ref().map(|watch| watch.turns),
            Some(0),
            "a turn boundary alone counts nothing",
        );
        assert!(
            task.successor.as_ref().is_some_and(|watch| !watch.measure_at_boundary),
            "and no measurement is armed by it",
        );
    }

    /// A reconnect of the same successor keeps its watch: the ten prompts are
    /// still that occupant's, and restarting would measure a later set
    /// against the brief.
    #[tokio::test]
    async fn a_reconnect_of_the_same_successor_keeps_its_count() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.connected_once = true;
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        workspace.record_handoff(
            &forge_primitives::HandoffRecord {
                slot: slot.clone(),
                from: "old-session-id".to_owned(),
                to: "new-session-id".to_owned(),
                reason: forge_primitives::HandoffReason::Fill,
                fill_percent: Some(85),
                total_tokens: Some(850_000),
                max_tokens: Some(1_000_000),
                at_percent: 85,
                brief: forge_primitives::HandoffBrief::default(),
                transcript_path: "/tmp/old.jsonl".to_owned(),
                at: "2026-10-24T08:00:00Z".to_owned(),
                cycle: forge_primitives::HandoffCycle::default(),
                successor: None,
            },
            &[],
        );
        task.translate_event(connected_event("new-session-id", "/tmp/forge"));
        task.count_successor_prompt();
        task.count_successor_prompt();

        task.translate_event(connected_event("new-session-id", "/tmp/forge"));

        assert_eq!(
            task.successor.as_ref().map(|watch| watch.turns),
            Some(2),
            "a reconnect of the same occupant does not restart the ten",
        );
    }

    /// The successor's window closes at its tenth turn: a row that kept
    /// counting would measure the seat's later work against a brief that
    /// had nothing to do with it.
    #[tokio::test]
    async fn the_successor_is_measured_at_its_tenth_turn() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        task.successor = Some(crate::handoff::SuccessorWatch {
            to: "old-session-id".to_owned(),
            turns: 0,
            predecessor_reads: Vec::new(),
            measure_at_boundary: false,
        });

        for _ in 0..(crate::handoff::SUCCESSOR_TURNS - 1) {
            task.count_successor_prompt();
        }
        assert_eq!(
            task.successor.as_ref().map(|watch| watch.turns),
            Some(crate::handoff::SUCCESSOR_TURNS - 1),
            "nine prompts are counted and the watch is still open",
        );
        assert!(
            task.successor.as_ref().is_some_and(|watch| !watch.measure_at_boundary),
            "nine prompts do not measure anything",
        );

        task.count_successor_prompt();
        assert!(
            task.successor.as_ref().is_some_and(|watch| watch.measure_at_boundary),
            "the tenth prompt arms the measurement",
        );
        assert!(task.successor.is_some(), "but it waits for that prompt's turn to end");
        task.after_turn_ended();
        assert!(task.successor.is_none(), "the tenth turn closes the measurement");
    }

    /// The successor's count is of a person's prompts, the same thing the
    /// transcript fold counts. A forge delivery - the brief, a kick, an
    /// auto-continue - is not one of the ten.
    #[tokio::test]
    async fn only_a_persons_prompt_counts_toward_the_successor() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("new-session-id"));
        task.successor = Some(crate::handoff::SuccessorWatch {
            to: "new-session-id".to_owned(),
            turns: 0,
            predecessor_reads: Vec::new(),
            measure_at_boundary: false,
        });

        task.execute_command(Command::Prompt {
            key: slot.clone(),
            text: "do the thing".to_owned(),
            attachments: Vec::new(),
        });
        assert_eq!(
            task.successor.as_ref().map(|watch| watch.turns),
            Some(1),
            "a person's prompt is one of the ten",
        );

        task.execute_command(Command::PromptUnder {
            key: slot.clone(),
            text: "HANDOFF - old -> new".to_owned(),
            attachments: Vec::new(),
            uuid: forge_sdk::request_id::next_forged_prompt_id(),
            source: crate::protocol::PromptSource::Forge,
            dispatch_id: None,
        });
        assert_eq!(
            task.successor.as_ref().map(|watch| watch.turns),
            Some(1),
            "forge's own delivery is not one of them",
        );
    }

    /// **A prompt held by a swap draws no row while it waits.** Its row lands
    /// when the successor's CLI starts it; the frame this used to forge before
    /// the hold drew words the successor had not taken yet (#2816).
    #[tokio::test]
    async fn a_prompt_held_by_a_swap_draws_no_row_while_it_waits() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "held-frame");
        let (mut task, mut update_rx, mut agent_rx) = nudge_task_for(&workspace, &slot);
        workspace.begin_swap(&slot);
        assert!(workspace.swap_in_progress(&slot), "premise: the swap gate holds prompts");

        task.execute_command(Command::PromptUnder {
            key: slot.clone(),
            text: "held words".to_owned(),
            attachments: Vec::new(),
            uuid: "held-frame-uuid".to_owned(),
            source: crate::protocol::PromptSource::You,
            dispatch_id: None,
        });

        let mut drawn = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::ChatAppended { msg, .. } = &*frame.update {
                drawn.push(msg.clone());
            }
        }
        assert!(drawn.is_empty(), "the held prompt draws no row: {drawn:?}");
        assert!(
            agent_rx.try_recv().is_err(),
            "and nothing was handed to the agent: the swap is holding it",
        );
        let held = workspace.end_swap(&slot);
        assert_eq!(held.len(), 1, "the prompt waits for the successor");
        assert_eq!(held[0].uuid, "held-frame-uuid", "under the id its row will carry");
    }

    /// **A dispatched prompt draws no row of its own** (#2816).
    ///
    /// The queue's announcement carries the words, and the row lands when the
    /// CLI starts the prompt. The frame this used to forge here was stamped at
    /// dispatch, so a prompt sent while a turn ran drew above the assistant
    /// text the running turn wrote after the press.
    #[tokio::test]
    async fn a_dispatched_prompt_emits_no_row_before_the_cli_starts_it() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "send-row");
        let (mut task, mut update_rx, _agent_rx) = nudge_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("send-row-session"));

        task.execute_command(Command::PromptUnder {
            key: slot.clone(),
            text: "sent mid turn".to_owned(),
            // Two the sender drops before the model sees them: the live row
            // must draw only what a reload would carry.
            attachments: vec![
                forge_primitives::ImageAttachment {
                    data: "iVBORw0KGgo=".to_owned(),
                    mime_type: "image/png".to_owned(),
                },
                forge_primitives::ImageAttachment {
                    data: "iVBORw0KGgo=".to_owned(),
                    mime_type: "text/plain".to_owned(),
                },
                forge_primitives::ImageAttachment {
                    data: "not base64!".to_owned(),
                    mime_type: "image/png".to_owned(),
                },
            ],
            uuid: "send-row-uuid".to_owned(),
            source: crate::protocol::PromptSource::You,
            dispatch_id: None,
        });

        let mut queued = false;
        while let Ok(frame) = update_rx.try_recv() {
            match &*frame.update {
                SessionUpdate::ChatAppended { msg, .. } => {
                    panic!("a prompt that has not started draws no row: {msg:?}");
                }
                SessionUpdate::PromptQueued { uuid, text, .. } if uuid == "send-row-uuid" => {
                    assert_eq!(text, "sent mid turn", "the queue carries the words meanwhile");
                    queued = true;
                }
                _ => {}
            }
        }
        assert!(queued, "the queue announces the prompt until the CLI takes it");

        // The CLI takes it: the row lands now, with the words the queue
        // carried and the attachment the dispatch held.
        let before = time::OffsetDateTime::now_utc();
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "send-row-session".to_owned(),
            msg: forge_primitives::Message::CommandLifecycle {
                command_uuid: "send-row-uuid".to_owned(),
                state: "started".to_owned(),
                uuid: "lifecycle-1".to_owned(),
                session_id: "send-row-session".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            },
        });
        let after = time::OffsetDateTime::now_utc();

        let announced: Vec<SessionUpdate> = std::iter::from_fn(|| update_rx.try_recv().ok())
            .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
            .collect();
        let drawn: Vec<(&forge_primitives::Message, Option<crate::protocol::PromptSource>)> =
            announced
                .iter()
                .filter_map(|update| match update {
                    SessionUpdate::ChatAppended { msg, source, .. } => Some((msg, *source)),
                    _ => None,
                })
                .collect();
        let [(msg, source)] = drawn.as_slice() else {
            panic!("the start draws one row: {drawn:?}");
        };
        // **The row lands before the state that drains it.** A view holds the
        // row on the frame and draws it when the state arrives; the other
        // order draws the announcement's bare words and loses the attachment.
        let row_at = announced
            .iter()
            .position(|update| matches!(update, SessionUpdate::ChatAppended { .. }))
            .expect("the row is announced");
        let lifecycle_at = announced
            .iter()
            .position(|update| {
                matches!(
                    update,
                    SessionUpdate::PromptLifecycle { state, .. } if state == "started"
                )
            })
            .expect("the state is announced");
        assert!(
            row_at < lifecycle_at,
            "the row is emitted before the lifecycle frame that drains it: {announced:?}",
        );
        assert_eq!(*source, Some(crate::protocol::PromptSource::You), "the reader's own send");
        let forge_primitives::Message::User { message, uuid, .. } = msg else {
            panic!("the row is the user turn it draws: {msg:?}");
        };
        assert_eq!(uuid.as_deref(), Some("send-row-uuid"), "under the prompt's own id");
        assert!(
            message.content.iter().any(|block| matches!(
                block,
                forge_primitives::ContentBlock::Text { text, .. } if text == "sent mid turn"
            )),
            "carrying the words the queue announced: {message:?}",
        );
        let Some(forge_primitives::ContentBlock::Image { source, extras }) = message
            .content
            .iter()
            .find(|block| matches!(block, forge_primitives::ContentBlock::Image { .. }))
        else {
            panic!("and the attachment the dispatch held: {message:?}");
        };
        assert_eq!(
            source.get("media_type").and_then(serde_json::Value::as_str),
            Some("image/png"),
            "the row names the mime",
        );
        assert_eq!(
            extras.get("forge_bytes").and_then(serde_json::Value::as_u64),
            Some(8),
            "and the eight bytes the payload weighed, never the payload",
        );
        assert_eq!(
            message.content.len(),
            2,
            "only the attachment the sender kept draws, beside the words: {message:?}",
        );
        // **The row carries the clock a mid-turn page reads.** Stamped where
        // the CLI's start is handled, not at dispatch.
        let stamp =
            serde_json::to_value(msg).expect("encode")["timestamp"].as_str().map(str::to_owned);
        let stamp = stamp.expect("the row carries a stamp");
        let at =
            time::OffsetDateTime::parse(&stamp, &time::format_description::well_known::Rfc3339)
                .unwrap_or_else(|error| panic!("a client cannot read the stamp {stamp}: {error}"));
        assert!(
            at >= before - time::Duration::seconds(5) && at <= after + time::Duration::seconds(5),
            "the row carries the task's own clock, not a constant: {stamp} sits outside \
             {before}..{after}",
        );
    }

    /// A judgment turn that ends swaps the seat, and the row's judgment is
    /// the reply that turn wrote.
    #[tokio::test]
    async fn the_judgment_turn_swaps_when_it_ends() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.judgment = Some("Next: the client row.".to_owned());
            domain.handoff.swap_token = Some(token);
        }

        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        assert!(
            record.brief.judgment.iter().any(|section| section.label == "Next"),
            "the judgment is the reply, parsed by its heading: {:?}",
            record.brief.judgment,
        );
    }

    /// **The note is the turn's last text, not its bookkeeping.** The turn
    /// now records memory with tool calls before it writes the note, so the
    /// capture must keep the newest assistant text: keeping the first would
    /// hand the successor a progress line instead of the brief.
    #[tokio::test]
    async fn an_agentic_judgment_turn_captures_its_last_text() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        task.domain.lock().handoff.awaiting = true;

        for frame in [
            serde_json::json!({
                "type": "assistant",
                "session_id": "old-session-id",
                "message": {
                    "id": "m1",
                    "role": "assistant",
                    "model": "a-model",
                    "content": [{"type": "text", "text": "recording what this session learned"}],
                },
            }),
            serde_json::json!({
                "type": "assistant",
                "session_id": "old-session-id",
                "message": {
                    "id": "m2",
                    "role": "assistant",
                    "model": "a-model",
                    "content": [{
                        "type": "tool_use",
                        "id": "t1",
                        "name": "Write",
                        "input": {"file_path": "memory.md", "content": "the lesson"},
                    }],
                },
            }),
            serde_json::json!({
                "type": "assistant",
                "session_id": "old-session-id",
                "message": {
                    "id": "m3",
                    "role": "assistant",
                    "model": "a-model",
                    "content": [{"type": "text", "text": "Now: the cut is in."}],
                },
            }),
            // A sub-agent's frame arrives in the same stream and after the
            // note; it must not become the brief.
            serde_json::json!({
                "type": "assistant",
                "session_id": "old-session-id",
                "parent_tool_use_id": "task-1",
                "message": {
                    "id": "m4",
                    "role": "assistant",
                    "model": "a-model",
                    "content": [{"type": "text", "text": "a sub-agent line that must not win"}],
                },
            }),
        ] {
            task.translate_event(AgentEvent::SdkMessage {
                session_id: "old-session-id".to_owned(),
                msg: serde_json::from_value(frame).expect("an assistant frame"),
            });
        }

        assert_eq!(
            task.domain.lock().handoff.judgment.as_deref(),
            Some("Now: the cut is in."),
            "the note the turn ended on, not the bookkeeping before it",
        );
    }

    /// **The exit call's note is the brief's judgment half.** The skill ends
    /// by calling `agents__handoff` with the note; that note, not the turn's
    /// other prose, is what the successor is given.
    #[tokio::test]
    async fn the_exit_calls_note_is_the_judgment_half() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.swap_token = Some(token);
            // The turn's closing text, which the exit call's note outranks.
            domain.handoff.judgment = Some("I am still working".to_owned());
        }

        task.execute_command(Command::Handoff {
            key: slot.clone(),
            brief: Some("Now: the cut is in.".to_owned()),
        });
        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        assert_eq!(
            record.brief.judgment.first().map(|section| section.label.as_str()),
            Some("Now"),
            "the exit call's note is PART 2: {:?}",
            record.brief.judgment,
        );
        assert!(
            record.brief.judgment[0].lines.iter().any(|line| line.contains("the cut is in.")),
            "and its text, not the captured prose",
        );
        assert!(
            record.brief.judgment.iter().all(|section| section.label != "source"),
            "an exit-call note carries no source row: {:?}",
            record.brief.judgment,
        );

        // **The successor's own text carries PART 2.** A record that holds
        // the judgment while the delivered brief drops it is the regression
        // this pins.
        let delivered =
            workspace.pending_brief_for(&slot).expect("the brief waits for the successor");
        assert!(
            delivered.text.contains("PART 2: JUDGMENT"),
            "the delivered brief carries PART 2: {}",
            delivered.text,
        );
        assert!(
            delivered.text.contains("Now: the cut is in."),
            "and the note's first heading: {}",
            delivered.text,
        );
    }

    /// **No note means no note.** A turn that ends on nothing hands the
    /// successor an explicit "the note did not arrive" section, never filler
    /// dressed as the brief.
    #[tokio::test]
    async fn a_handoff_without_a_note_states_it() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.swap_token = Some(token);
            domain.handoff.judgment = Some("   \n".to_owned());
        }

        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        let section = record.brief.judgment.first().expect("a stated section");
        assert_eq!(section.label, "note", "the missing note is its own section");
        assert!(
            section.lines[0].contains("the handoff note did not arrive"),
            "and says so: {:?}",
            section.lines,
        );
        assert_eq!(
            record.brief.judgment.len(),
            1,
            "an empty turn states the note once: {:?}",
            record.brief.judgment,
        );
    }

    /// **A note taken from the turn's closing text says so.** Nothing in a
    /// capture distinguishes prose the predecessor chose to pass from a turn
    /// that simply ended, so the judgment carries a `source` row when the exit
    /// call had no note.
    #[tokio::test]
    async fn a_note_taken_from_the_turn_text_is_marked() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.swap_token = Some(token);
            domain.handoff.judgment =
                Some("Memory is updated and the monitor is stopped.".to_owned());
        }

        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        assert_eq!(
            record.brief.judgment.iter().map(|section| section.label.as_str()).collect::<Vec<_>>(),
            ["source", "note"],
            "the capture is marked, then drawn as the note it is: {:?}",
            record.brief.judgment,
        );
        assert!(
            record.brief.judgment[0]
                .lines
                .iter()
                .any(|line| line.contains("the exit call carried no note")),
            "the source row says where it came from: {:?}",
            record.brief.judgment[0].lines,
        );
        assert!(
            record.brief.judgment[1].lines.iter().any(|line| line.contains("Memory is updated")),
            "and the turn's text is the note: {:?}",
            record.brief.judgment[1].lines,
        );
    }

    /// **A note that carried no content is not an absent call.** An exit call
    /// whose brief was a shell like `## Next` was made; the source row must
    /// say the note had no content rather than that no call arrived.
    #[tokio::test]
    async fn a_content_free_exit_note_is_named_as_such() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.swap_token = Some(token);
            domain.handoff.judgment =
                Some("Memory is updated and the monitor is stopped.".to_owned());
        }

        task.execute_command(Command::Handoff {
            key: slot.clone(),
            brief: Some("## Next".to_owned()),
        });
        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        assert_eq!(
            record.brief.judgment.iter().map(|section| section.label.as_str()).collect::<Vec<_>>(),
            ["source", "note"],
            "the capture is marked: {:?}",
            record.brief.judgment,
        );
        assert!(
            record.brief.judgment[0]
                .lines
                .iter()
                .any(|line| line.contains("the exit call's note carried no content")),
            "the row names the call that was made: {:?}",
            record.brief.judgment[0].lines,
        );
    }

    /// The task's own refusal: an exit with no handoff turn running states
    /// where a handoff starts and stores nothing.
    #[tokio::test]
    async fn an_exit_with_no_handoff_turn_is_stated() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(crate::update_fanout::SubscriberRole::Answering);

        task.execute_command(Command::Handoff {
            key: slot.clone(),
            brief: Some("Now: x".to_owned()),
        });

        assert!(task.domain.lock().handoff.supplied.is_none(), "no note is stored");
        let mut stated = false;
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::Notice { text, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && text.contains("/handoff")
                && text.contains("automatic trigger")
            {
                stated = true;
            }
        }
        assert!(stated, "the seat is told where a handoff starts");
    }

    /// **An empty exit does not discard a valid captured note.** The exit
    /// call's note is tried first; when it carries nothing, the capture is.
    #[tokio::test]
    async fn an_empty_exit_falls_back_to_the_captured_note() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.swap_token = Some(token);
            domain.handoff.judgment = Some("Now: the captured note.".to_owned());
        }

        task.execute_command(Command::Handoff { key: slot.clone(), brief: Some("   ".to_owned()) });
        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        assert_eq!(
            record.brief.judgment.iter().map(|section| section.label.as_str()).collect::<Vec<_>>(),
            ["source", "Now"],
            "the captured note is PART 2, marked as a capture: {:?}",
            record.brief.judgment,
        );
        assert!(
            record.brief.judgment[1].lines.iter().any(|line| line.contains("the captured note")),
            "and its text, not the empty exit",
        );
    }

    /// A handoff asked for while a turn runs sends nothing into that turn:
    /// it waits, and the judgment prompt goes out as its own turn after.
    #[tokio::test]
    async fn a_handoff_asked_mid_turn_waits_for_the_turn_to_end() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        task.domain.lock().turn_pending = true;

        task.execute_command(Command::Handoff { key: slot.clone(), brief: None });

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "a running turn is never handed a prompt in the middle",
        );
        assert!(task.domain.lock().handoff.parked, "the request waits for the boundary instead");

        task.domain.lock().turn_pending = false;
        task.after_turn_ended();

        let dispatched = workspace.drain_test_dispatch_buffer();
        let Some(Command::PromptUnder { text, source, .. }) = dispatched.first() else {
            panic!("the judgment prompt was never sent: {dispatched:?}");
        };
        assert_eq!(
            text,
            &crate::handoff::judgment_prompt(),
            "forge's own text, which names no skill"
        );
        assert_eq!(*source, PromptSource::Forge, "and it is forge's turn, not the user's");
        assert!(task.domain.lock().handoff.awaiting, "the reply is waited for");
    }

    /// A turn boundary in a fresh task with a session id, a compaction count
    /// and the stub workspace: the shape the trigger reads.
    fn trigger_task(
        workspace: &Arc<crate::Workspace>,
        compaction_count: u32,
    ) -> (SessionTask, mpsc::UnboundedReceiver<forge_primitives::AgentCommand>) {
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, agent_rx) = command_task_for(workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-session-id"));
        task.compaction_count = compaction_count;
        (task, agent_rx)
    }

    fn reading(reported: Option<u8>, total: Option<u64>, effective: Option<u64>) -> AgentEvent {
        reading_for("old-session-id", reported, total, effective)
    }

    fn reading_for(
        session_id: &str,
        reported: Option<u8>,
        total: Option<u64>,
        effective: Option<u64>,
    ) -> AgentEvent {
        AgentEvent::ContextUsage {
            session_id: session_id.to_owned(),
            percentage: reported,
            max_tokens: Some(1_000_000),
            total_tokens: total,
            effective_max_tokens: effective,
        }
    }

    /// **The trigger must fire at a REAL turn boundary.** The turn's
    /// `turn_pending` marker is cleared later in the same event than
    /// `after_turn_ended` runs, so a gate that read it would park every
    /// handoff and wait for a turn that never comes; this drives a `Result`
    /// through the actor and then its reading.
    #[tokio::test]
    async fn the_trigger_measures_at_a_real_turn_boundary() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 0);
        // The state the actor is in when a `Result` lands.
        task.domain.lock().turn_pending = true;

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: result_message("success", false),
        });

        assert!(
            matches!(
                agent_rx.try_recv(),
                Ok(forge_primitives::AgentCommand::GetContextUsage { .. })
            ),
            "the boundary asks for the reading",
        );
        assert!(
            !task.domain.lock().handoff.parked,
            "and does not park on the turn that just ended",
        );

        task.translate_event(reading(Some(90), Some(180_000), Some(200_000)));

        assert!(
            workspace.drain_test_dispatch_buffer().iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == &crate::handoff::judgment_prompt()
            )),
            "the handoff begins at the boundary",
        );
        assert!(workspace.swap_in_progress(&task.key), "with its gate open");
    }

    /// **A handoff parked by a prompt queued inside a running turn begins at
    /// the shared Result.** One turn ended, so the seat is idle and the
    /// judgment prompt goes out as its own turn rather than the handoff
    /// sitting parked forever.
    #[tokio::test]
    async fn a_handoff_parked_by_a_queued_prompt_begins_at_the_shared_result() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.commit_turn();
            domain.commit_turn();
            domain.handoff.reason = Some(forge_primitives::HandoffReason::Manual);
            domain.handoff.parked = true;
        }

        task.after_turn_ended();

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == &crate::handoff::judgment_prompt()
            )),
            "the judgment prompt goes out once the shared turn ends: {dispatched:?}",
        );
        assert!(workspace.swap_in_progress(&task.key), "and the swap gate opens with it");
    }

    /// A prompt queued behind the boundary is not a second turn, and the
    /// seat stays busy while it waits: no handoff fires into it, and the
    /// reading is asked only once the queue is clear.
    #[tokio::test]
    async fn a_prompt_queued_behind_the_boundary_keeps_the_seat_busy() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.commit_turn();
            // The prompt the CLI queued inside that turn, before its Result.
            domain.commit_turn();
            domain.record_queued_prompt(
                "queued-2",
                crate::protocol::PromptSource::You,
                "the next ask",
                Vec::new(),
            );
        }

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: result_message("success", false),
        });

        assert!(!task.domain.lock().turn_in_flight(), "the shared Result ended the turn");
        assert!(
            !task.domain.lock().is_idle_for_handoff(),
            "but the queued prompt still holds the seat",
        );
        assert!(agent_rx.try_recv().is_err(), "so no reading is asked for at this boundary");

        // The CLI ran it; its lifecycle settles and its own Result serves the
        // boundary.
        task.domain.lock().advance_queued_prompt("queued-2", "completed");
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: result_message("success", false),
        });
        assert!(
            matches!(
                agent_rx.try_recv(),
                Ok(forge_primitives::AgentCommand::GetContextUsage { .. })
            ),
            "the clear boundary is the one that asks",
        );
    }

    /// The probe is asynchronous: a turn can open while it is out (the
    /// continuation a failed turn fires is the near case). The reading then
    /// parks the handoff instead of writing its prompt into that turn.
    #[tokio::test]
    async fn the_trigger_parks_when_a_turn_started_while_the_probe_was_out() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 0);

        task.maybe_trigger_handoff();
        assert!(
            matches!(
                agent_rx.try_recv(),
                Ok(forge_primitives::AgentCommand::GetContextUsage { .. })
            ),
            "precondition: the reading was asked for",
        );
        // The failed turn's continuation opens a turn before the answer lands.
        task.domain.lock().turn_pending = true;

        task.translate_event(reading(Some(90), Some(900_000), Some(1_000_000)));

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "no judgment prompt is written into a running turn",
        );
        let parked = task.domain.lock().handoff.parked;
        assert!(parked, "the handoff waits for the boundary instead");
        assert_eq!(
            task.domain.lock().handoff.reason,
            Some(forge_primitives::HandoffReason::Fill),
            "and the reason it will fire for is kept",
        );

        // That turn ends: the handoff now begins, and its gate opens with it.
        task.domain.lock().turn_pending = false;
        task.after_turn_ended();
        assert!(
            workspace.drain_test_dispatch_buffer().iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == &crate::handoff::judgment_prompt()
            )),
            "the judgment prompt goes out as its own turn once the seat is idle",
        );
        assert!(workspace.swap_in_progress(&task.key), "and the swap gate is open");
    }

    /// A parked handoff re-checks the seat before it begins: a prompt
    /// committed after the park is a turn the judgment prompt must not be
    /// folded into.
    #[tokio::test]
    async fn a_parked_handoff_rechecks_the_seat_before_it_begins() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.handoff.reason = Some(forge_primitives::HandoffReason::Fill);
            domain.handoff.parked = true;
            domain.commit_turn();
        }

        task.begin_handoff();

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "the judgment prompt is not written into a running turn",
        );
        assert!(task.domain.lock().handoff.parked, "the handoff stays parked for its own boundary");
        assert!(!workspace.swap_in_progress(&task.key), "and its gate never opened");
    }

    /// An unanswered judgment turn waits for ITS turn: a boundary from any
    /// other turn is not the reply the brief is built from.
    #[tokio::test]
    async fn a_turn_that_is_not_the_judgment_turn_does_not_swap() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.judgment_started = false;
            domain.handoff.judgment = Some("Next: not the judgment turn".to_owned());
        }

        task.after_turn_ended();

        assert!(
            task.domain.lock().handoff.awaiting,
            "the handoff is still waiting for its own prompt's turn",
        );
        assert!(
            update_rx.try_recv().is_err(),
            "and no handoff row was emitted for another turn's prose",
        );
    }

    /// The CLI's lifecycle frame is what names the judgment turn, and its
    /// end is what swaps.
    #[tokio::test]
    async fn the_lifecycle_frame_names_the_judgment_turn() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, mut update_rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        let token = workspace.begin_swap(&task.key);
        {
            let mut domain = task.domain.lock();
            domain.lifecycle_frames = Some(true);
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.swap_token = Some(token);
        }
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "old-session-id".to_owned(),
            msg: forge_primitives::Message::CommandLifecycle {
                command_uuid: "judgment-id".to_owned(),
                state: "started".to_owned(),
                uuid: "lifecycle-1".to_owned(),
                session_id: "old-session-id".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            },
        });
        assert!(task.domain.lock().handoff.judgment_started, "the frame names the turn");
        task.domain.lock().handoff.judgment = Some("Next: the client row.".to_owned());

        task.after_turn_ended();

        let record = tokio::time::timeout(std::time::Duration::from_secs(10), async {
            while let Some(frame) = update_rx.recv().await {
                if let SessionUpdate::Handoff { handoff, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                {
                    return handoff;
                }
            }
            panic!("the handoff row was never emitted");
        })
        .await
        .expect("the handoff lands");
        assert!(
            record.brief.judgment.iter().any(|section| section.label == "Next"),
            "the judgment is that turn's reply: {:?}",
            record.brief.judgment,
        );
    }

    /// A late reading for the previous occupant cannot judge this one, and it
    /// does not spend the boundary's probe.
    #[tokio::test]
    async fn a_reading_for_another_occupant_does_not_judge_this_one() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        task.maybe_trigger_handoff();

        task.translate_event(reading_for(
            "an-older-session",
            Some(99),
            Some(990_000),
            Some(1_000_000),
        ));

        assert!(
            task.domain.lock().handoff.probing,
            "the boundary's probe is still owed to this occupant's reading",
        );
        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "and the previous session's fill asks for nothing here",
        );
    }

    /// A boundary during a swap's build does not fire a second handoff: the
    /// state it would read as idle is the swap's own.
    #[tokio::test]
    async fn no_second_handoff_fires_while_a_swap_builds() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 0);
        workspace.begin_swap(&task.key);

        task.maybe_trigger_handoff();

        assert!(agent_rx.try_recv().is_err(), "no reading is even asked for while the swap builds");
        assert!(!task.domain.lock().handoff.probing, "and nothing is armed");
    }

    /// At the configured share the trigger asks for the judgment half in a
    /// turn of its own, and the row later says why it fired.
    #[tokio::test]
    async fn the_trigger_fires_at_the_configured_share() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 0);

        task.maybe_trigger_handoff();
        assert!(
            matches!(
                agent_rx.try_recv(),
                Ok(forge_primitives::AgentCommand::GetContextUsage { .. })
            ),
            "the reading is asked of the CLI at the boundary",
        );

        task.translate_event(reading(Some(85), Some(850_000), Some(1_000_000)));

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == &crate::handoff::judgment_prompt()
            )),
            "at 85% the judgment half is asked for: {dispatched:?}",
        );
        assert_eq!(
            task.domain.lock().handoff.reason,
            Some(forge_primitives::HandoffReason::Fill),
            "and the reason rides to the row",
        );
        let fill = task.domain.lock().handoff.fill.expect("the reading that fired");
        assert_eq!(fill.percent, 85);
        assert_eq!((fill.total_tokens, fill.max_tokens), (850_000, 1_000_000));
    }

    /// A reading that was already out when a handoff began belongs to no
    /// handoff: the running one keeps the reading it fired on, which is what
    /// the row will carry.
    #[tokio::test]
    async fn a_late_reading_does_not_overwrite_a_running_handoffs_fill() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);
        {
            let mut domain = task.domain.lock();
            domain.handoff.awaiting = true;
            domain.handoff.judgment_uuid = Some("judgment-id".to_owned());
            domain.handoff.fill = Some(crate::handoff::FillReading {
                percent: 86,
                total_tokens: 860_000,
                max_tokens: 1_000_000,
            });
            // The probe was asked before the handoff began.
            domain.handoff.probing = true;
        }

        task.translate_event(reading(Some(99), Some(990_000), Some(1_000_000)));

        let fill = task.domain.lock().handoff.fill.expect("the running handoff keeps its reading");
        assert_eq!(
            fill.percent, 86,
            "the late reading is dropped, not written over the running handoff's",
        );
    }

    /// One point under the share is not a handoff: the trigger fires at the
    /// line, not near it.
    #[tokio::test]
    async fn a_reading_under_the_share_does_not_fire() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);

        task.maybe_trigger_handoff();
        task.translate_event(reading(Some(84), Some(840_000), Some(1_000_000)));

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "84% is under the default share and asks for nothing",
        );
        assert!(!task.domain.lock().handoff.probing, "and the boundary is spent");
    }

    /// The denominator is the CLI's effective window, not the share it
    /// reports: a window lowered for auto-compact fires earlier, which is
    /// the whole reason the trigger is a percentage rather than a count.
    #[tokio::test]
    async fn the_effective_window_is_the_denominator() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);

        task.maybe_trigger_handoff();
        // 900k of an effective 1M is 90%, though the CLI's share of the raw
        // 2M window reads 45%.
        task.translate_event(reading(Some(45), Some(900_000), Some(1_000_000)));

        assert!(
            workspace.drain_test_dispatch_buffer().iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == &crate::handoff::judgment_prompt()
            )),
            "the effective window's 90% fires even though the reported share does not",
        );
    }

    /// A compaction the fill trigger did not stop arms the backstop: the
    /// session hands over at the next boundary whatever its fill reads.
    #[tokio::test]
    async fn the_count_backstop_fires_when_a_compaction_came_first() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 1);

        task.maybe_trigger_handoff();
        assert!(
            matches!(
                agent_rx.try_recv(),
                Ok(forge_primitives::AgentCommand::GetContextUsage { .. })
            ),
            "the boundary asks for the reading",
        );
        task.translate_event(reading(Some(10), Some(100_000), Some(1_000_000)));

        assert!(
            workspace.drain_test_dispatch_buffer().iter().any(|command| matches!(
                command,
                Command::PromptUnder { text, .. } if text == &crate::handoff::judgment_prompt()
            )),
            "a session that compacted hands over even at a low fill",
        );
        assert_eq!(
            task.domain.lock().handoff.reason,
            Some(forge_primitives::HandoffReason::Compaction),
            "and the row says a compaction came first",
        );
        assert!(workspace.swap_in_progress(&task.key), "with its gate open");
    }

    /// `enabled = false` is the one off switch: not even a reading is asked
    /// for, so a project that must not be interrupted pays nothing.
    #[tokio::test]
    async fn the_trigger_is_off_when_the_table_says_so() {
        let dir = tempfile::tempdir().expect("tempdir");
        let mut config = crate::config::LoadedConfig::empty_for_test();
        config.handoff = crate::config::HandoffSettings {
            enabled: Some(false),
            ..crate::config::HandoffSettings::default()
        };
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config(dir.path().to_path_buf(), config)
                .expect("the stub builds");
        workspace.enable_test_dispatch_intercept();
        let (mut task, mut agent_rx) = trigger_task(&workspace, 3);

        task.maybe_trigger_handoff();
        assert!(
            agent_rx.try_recv().is_err(),
            "a disabled trigger does not even ask for the reading",
        );
        assert!(!task.domain.lock().handoff.probing, "and nothing is left half-armed");
    }

    /// A reading that says nothing fires nothing: the trigger never guesses
    /// a denominator.
    #[tokio::test]
    async fn a_reading_with_no_numbers_does_not_fire() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.enable_test_dispatch_intercept();
        let (mut task, _agent_rx) = trigger_task(&workspace, 0);

        task.maybe_trigger_handoff();
        task.translate_event(reading(None, None, None));

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "an empty reading is not a full one",
        );
    }

    /// The brief is given only to the occupant it was written for: a connect
    /// under any other id is a different session, and the brief describes a
    /// history it does not carry.
    #[test]
    fn the_brief_goes_to_the_occupant_it_was_written_for() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        let slot = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);

        let brief = || crate::handoff::PendingBrief {
            to: "new-id".to_owned(),
            text: "HANDOFF - 9cfe315c -> 4b21e0a7".to_owned(),
        };
        workspace.set_pending_brief(&slot, brief());
        task.deliver_pending_brief(&slot, "someone-else");
        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "another occupant is not given a brief written for this one",
        );

        workspace.set_pending_brief(&slot, brief());
        task.deliver_pending_brief(&slot, "new-id");
        let dispatched = workspace.drain_test_dispatch_buffer();
        let Some(Command::PromptUnder { text, source, .. }) = dispatched.first() else {
            panic!("the brief was never delivered: {dispatched:?}");
        };
        assert!(text.starts_with("HANDOFF - "), "the successor is given the brief itself");
        assert_eq!(*source, PromptSource::Forge, "as forge's own first turn");
    }

    /// A worker's mission lives in its conversation, so `/new` has to
    /// re-deliver the charter the store holds for its slot. A view
    /// builds the launch settings for a `/new` and knows nothing of the
    /// charter, so without the re-delivery a worker that ran `/new`
    /// comes back as a session that is still its slot but no longer its
    /// worker - alive-looking and doing nothing.
    #[test]
    fn a_worker_that_runs_new_is_re_delivered_its_charter() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let slot = SessionSlot::worker("TestOrg", "forge", "reviewer");
        workspace.seed_test_session_charter(&slot, "mind the queues", false);
        let (mut task, mut agent_rx) = command_task_for(&workspace, &slot);

        task.execute_command(Command::NewSession {
            key: slot.clone(),
            cwd: "/tmp/forge".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
            session_id: None,
        });

        let Some(forge_primitives::AgentCommand::NewSession { launch_settings, .. }) =
            agent_rx.try_recv().ok()
        else {
            panic!("the task forwards the new-session command to the handle");
        };
        assert_eq!(
            launch_settings.get("charter").and_then(serde_json::Value::as_str),
            Some("mind the queues"),
            "the worker comes back with the charter its row holds",
        );
    }

    /// A respawn moves the id the child runs under, so its gateway
    /// binding moves with it. `/new` stamps the id it mints and
    /// `/resume` the transcript it re-enters, the segment the session
    /// left behind keeps no binding, and `bound_account_for` - what the
    /// projects pane reads - follows the child that is actually running
    /// rather than the one it replaced.
    #[test]
    fn a_respawn_moves_the_gateway_binding_to_the_id_the_child_runs_under() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let slot = SessionSlot::worker("Busytools", "forge", "reviewer");
        let account = forge_gateway::AccountKey("OpenRouter".to_owned());
        let (handle, _cmds) = Agent::testing_stub();
        workspace.pool.lock().insert(
            slot.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::new(handle),
                account: account.clone(),
                permission_mode: None,
                registration: Some(forge_gateway::binding::Registration {
                    org: "Busytools".to_owned(),
                    project: "forge".to_owned(),
                    session: "spawn-id".to_owned(),
                    account: account.clone(),
                    provider: forge_primitives::account::Provider::Anthropic,
                }),
                session_id: "spawn-id".to_owned(),
            },
        );
        workspace.gateway.bindings.bind("Busytools", "forge", "spawn-id", account.clone());
        let (mut task, mut agent_rx) = command_task_for(&workspace, &slot);

        let stamped_base_url = |launch_settings: &serde_json::Value| -> Option<String> {
            launch_settings
                .get("env_overrides")
                .and_then(|overrides| overrides.get("ANTHROPIC_BASE_URL"))
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned)
        };
        let listener_base = format!("http://127.0.0.1:{}", workspace.gateway_port());
        // A respawn's settings are built by a view, which knows nothing of
        // the spawn-time flags, so the tools forge has replaced have to be
        // re-denied here or the new occupant gets them back.
        let denied = |launch_settings: &serde_json::Value| -> String {
            launch_settings
                .get("extra_args")
                .and_then(serde_json::Value::as_array)
                .and_then(|pairs| {
                    pairs.iter().find(|pair| {
                        pair.get(0).and_then(serde_json::Value::as_str) == Some("disallowedTools")
                    })
                })
                .and_then(|pair| pair.get(1).and_then(serde_json::Value::as_str))
                .unwrap_or_default()
                .to_owned()
        };

        task.execute_command(Command::NewSession {
            key: slot.clone(),
            cwd: "/tmp/forge".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
            session_id: None,
        });

        let Some(forge_primitives::AgentCommand::NewSession {
            session_id, launch_settings, ..
        }) = agent_rx.try_recv().ok()
        else {
            panic!("the task forwards the new-session command to the handle");
        };
        let minted = session_id.expect("`/new` starts under a minted id");
        assert_eq!(
            stamped_base_url(&launch_settings).as_deref(),
            Some(format!("{listener_base}/Busytools/forge/{minted}").as_str()),
            "`/new` stamps the base URL with the id it mints for the child",
        );
        assert_eq!(
            workspace.bound_account_for(&slot),
            Some(account.clone()),
            "the account read for the slot follows the child that is running",
        );
        for tool in [
            "CronCreate",
            "CronDelete",
            "CronList",
            "TaskCreate",
            "TaskGet",
            "TaskList",
            "TaskUpdate",
            "SendMessage",
            "ListAgents",
            "Workflow",
            "RemoteTrigger",
        ] {
            assert!(
                denied(&launch_settings).split(',').any(|name| name == tool),
                "{tool} must reach a respawned session's launch; got {:?}",
                denied(&launch_settings),
            );
        }
        assert_eq!(
            workspace.gateway.bindings.binding_for("Busytools", "forge", "spawn-id"),
            None,
            "the id the session left behind keeps no binding",
        );

        // The same stamp on the routed `/resume`, whose id comes from the
        // command rather than a mint.
        task.execute_command(Command::ResumeSession {
            key: slot.clone(),
            session_id: "resumed-id".to_owned(),
            cwd: "/tmp/forge".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
        });

        let Some(forge_primitives::AgentCommand::ResumeSession { launch_settings, .. }) =
            agent_rx.try_recv().ok()
        else {
            panic!("the task forwards the resume command to the handle");
        };
        assert_eq!(
            stamped_base_url(&launch_settings).as_deref(),
            Some(format!("{listener_base}/Busytools/forge/resumed-id").as_str()),
            "`/resume` stamps the base URL with the transcript it re-enters",
        );
        assert_eq!(
            workspace.bound_account_for(&slot),
            Some(account),
            "the binding follows the resumed occupant",
        );
        assert_eq!(
            workspace.gateway.bindings.binding_for("Busytools", "forge", &minted),
            None,
            "and the segment the new session left behind is dropped",
        );
    }

    /// A respawn rebuilds the launch from view-built settings, so every denial
    /// a worker's own spawn wrote has to come back from the row that holds
    /// its flags. `AskUserQuestion` is the one the respawn stamp used to
    /// omit: a non-interactive worker that regained it would put a question
    /// in a row nobody is watching, and block there unseen.
    #[test]
    fn a_respawned_worker_keeps_its_own_denials() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let slot = SessionSlot::worker("TestOrg", "forge", "reviewer");
        workspace.seed_test_session_charter(&slot, "review the diff", false);
        let (mut task, mut agent_rx) = command_task_for(&workspace, &slot);

        task.execute_command(Command::NewSession {
            key: slot.clone(),
            cwd: "/tmp/forge".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
            session_id: None,
        });

        let Some(forge_primitives::AgentCommand::NewSession { launch_settings, .. }) =
            agent_rx.try_recv().ok()
        else {
            panic!("the task forwards the new-session command to the handle");
        };
        let denied = respawn_denials(&launch_settings);
        let names: Vec<&str> = denied.split(',').collect();
        for tool in ["AskUserQuestion", "EnterWorktree", "ExitWorktree"] {
            assert!(
                names.contains(&tool),
                "{tool} must come back on a non-interactive worker's respawn; got {denied:?}",
            );
        }
    }

    /// The question denial belongs to the spawn, not to the kind: a worker
    /// the user asked to talk to directly keeps `AskUserQuestion` across a
    /// respawn, and still keeps the worktree pins that make it a worker.
    #[test]
    fn a_respawned_interactive_worker_keeps_the_question() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let slot = SessionSlot::worker("TestOrg", "forge", "reviewer");
        workspace.seed_test_session_charter(&slot, "review the diff", true);
        let (mut task, mut agent_rx) = command_task_for(&workspace, &slot);

        task.execute_command(Command::NewSession {
            key: slot.clone(),
            cwd: "/tmp/forge".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
            session_id: None,
        });

        let Some(forge_primitives::AgentCommand::NewSession { launch_settings, .. }) =
            agent_rx.try_recv().ok()
        else {
            panic!("the task forwards the new-session command to the handle");
        };
        let denied = respawn_denials(&launch_settings);
        let names: Vec<&str> = denied.split(',').collect();
        assert!(
            !names.contains(&"AskUserQuestion"),
            "an interactive worker asks its own row's user; got {denied:?}",
        );
        assert!(
            names.contains(&"EnterWorktree"),
            "and it is still a worker, pinned to its spawn location; got {denied:?}",
        );
    }

    /// The kind half of the same stamp: a lead respawns without the
    /// worktree pins because a lead still hops worktrees, and keeps the
    /// question because a lead's row is where the user is.
    #[test]
    fn a_respawned_lead_keeps_its_own_surface() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, mut agent_rx) = command_task_for(&workspace, &slot);

        task.execute_command(Command::NewSession {
            key: slot.clone(),
            cwd: "/tmp/forge".to_owned(),
            launch_settings: forge_agent::client::SessionLaunchSettings::default(),
            session_id: None,
        });

        let Some(forge_primitives::AgentCommand::NewSession { launch_settings, .. }) =
            agent_rx.try_recv().ok()
        else {
            panic!("the task forwards the new-session command to the handle");
        };
        let denied = respawn_denials(&launch_settings);
        let names: Vec<&str> = denied.split(',').collect();
        for tool in ["EnterWorktree", "ExitWorktree", "AskUserQuestion"] {
            assert!(!names.contains(&tool), "a lead keeps {tool} across a respawn; got {denied:?}");
        }
        assert!(
            names.contains(&"Workflow"),
            "the replaced set still reaches a lead's respawn; got {denied:?}",
        );
    }

    /// The `--disallowedTools` value a respawn's launch carries.
    fn respawn_denials(launch_settings: &serde_json::Value) -> String {
        launch_settings
            .get("extra_args")
            .and_then(serde_json::Value::as_array)
            .and_then(|pairs| {
                pairs.iter().find(|pair| {
                    pair.get(0).and_then(serde_json::Value::as_str) == Some("disallowedTools")
                })
            })
            .and_then(|pair| pair.get(1).and_then(serde_json::Value::as_str))
            .unwrap_or_default()
            .to_owned()
    }

    /// First-Connected drains the session's buffered Slack messages: each
    /// dispatches a plain `Command::Prompt` AND echoes a
    /// `SlackMessageAppended` so a message that arrived while the project was
    /// asleep shows its block once the session connects. Driven through
    /// Connected rather than the private drain so the ordering is pinned -
    /// the drain runs after the Connected emit, and both carry the task's
    /// own slot, which is the bucket the message was parked under.
    #[test]
    fn first_connected_drains_parked_slack_and_echoes_block() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        workspace.seed_test_project("slack-drain", "/tmp/slack-drain");

        // The slot production derives for the project this fixture seeds,
        // and the bucket a delivery for that project's lead parks on.
        let session_key = SessionSlot::lead("TestOrg", "slack-drain");
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        workspace.park_slack(
            &session_key,
            vec![forge_primitives::slack::SlackMessage {
                workspace: "acme".to_owned(),
                conversation: "D1".to_owned(),
                conversation_label: "U9".to_owned(),
                ts: "100.000001".to_owned(),
                thread_ts: None,
                user: Some("U9".to_owned()),
                author: None,
                text: "the buffered text".to_owned(),
                parent_user_id: None,
                latest_reply: None,
                edited: None,
                files: Vec::new(),
            }],
        );

        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        workspace.enable_test_dispatch_intercept();
        task.translate_event(connected_event(&session_key.display(), "/tmp/slack-drain"));

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|c| matches!(
                c, crate::protocol::Command::Prompt { key, text, .. }
                    | crate::protocol::Command::PromptUnder { key, text, .. }
                    if *key == session_key && text.contains("the buffered text")
            )),
            "the buffered message arrives as the session's own prompt: {dispatched:?}",
        );

        let mut echoed = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::SlackMessageAppended { key, prose, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && key == session_key
                && prose.contains("the buffered text")
            {
                echoed = Some(prose);
            }
        }
        let prose = echoed
            .expect("an asleep-buffered Slack message echoes a SlackMessageAppended on drain");
        assert!(
            prose.contains("d old"),
            "the drain reads the workspace's stale threshold: {prose}",
        );

        assert!(
            workspace.take_parked_for_slot(&session_key).slack.is_empty(),
            "the buffer drains once flushed",
        );
    }

    /// The drain runs after the Connected emit, so the session's own
    /// `Connected` update lands before the drained Slack echo - a drain
    /// hoisted above the emit paints the block before the session the block
    /// belongs to. Driven through Connected rather than the private drain so
    /// the ordering is observable on the update channel.
    #[test]
    fn first_connected_emits_connected_before_draining_slack() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        workspace.seed_test_project("slack-rekey", "/tmp/slack-rekey");
        let slot = SessionSlot::lead("TestOrg", "slack-rekey");
        let domain = Arc::new(parking_lot::Mutex::new(DomainSession::new(slot.clone(), None)));
        workspace.park_slack(&slot, vec![buffered_slack("buffered while asleep")]);

        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: slot.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        workspace.enable_test_dispatch_intercept();
        task.translate_event(connected_event(&slot.display(), "/tmp/slack-rekey"));

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|c| matches!(
                c, crate::protocol::Command::Prompt { key, text, .. }
                    | crate::protocol::Command::PromptUnder { key, text, .. }
                    if *key == slot && text.contains("buffered while asleep")
            )),
            "the drained prompt rides the task's own slot: {dispatched:?}",
        );

        let mut connected = false;
        let mut echo_after_connected = false;
        while let Ok(frame) = update_rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Connected { .. } => connected = true,
                SessionUpdate::SlackMessageAppended { key, .. } if key == slot => {
                    assert!(
                        connected,
                        "the session's Connected lands before its drained Slack echo",
                    );
                    echo_after_connected = true;
                }
                _ => {}
            }
        }
        assert!(echo_after_connected, "the drained message still echoes a block");
    }

    /// The review-activity notice a task emitted, if any.
    fn drained_notice(
        update_rx: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Option<(SessionSlot, String, usize, String)> {
        let mut notice = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::ReviewActivityNotice { key, branch, waiting, message } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                notice = Some((key, branch, waiting, message));
            }
        }
        notice
    }

    fn result_message(subtype: &str, is_error: bool) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "result",
            "subtype": subtype,
            "duration_ms": 1,
            "duration_api_ms": 1,
            "is_error": is_error,
            "num_turns": 1,
            "session_id": "worker"
        }))
        .expect("parse result message")
    }

    /// The same frame with the CLI's terminal reason aboard.
    fn result_message_with_reason(reason: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "result",
            "subtype": "success",
            "duration_ms": 1,
            "duration_api_ms": 1,
            "is_error": false,
            "num_turns": 1,
            "session_id": "worker",
            "terminal_reason": reason,
        }))
        .expect("parse result message")
    }

    /// A `Result` covering no turn, as a local command (`/compact` on an
    /// idle seat) emits: the capture's seventh result of a six-turn run.
    fn result_message_for_a_local_command() -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "result",
            "subtype": "success",
            "duration_ms": 1,
            "duration_api_ms": 0,
            "is_error": false,
            "num_turns": 0,
            "session_id": "worker",
        }))
        .expect("parse result message")
    }

    /// An errored `Result` carrying the CLI's own error strings, which are
    /// what the nudge's reason is composed from.
    fn result_message_with_errors(errors: &[&str]) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "result",
            "subtype": "error_during_execution",
            "duration_ms": 1,
            "duration_api_ms": 1,
            "is_error": true,
            "num_turns": 1,
            "session_id": "worker",
            "errors": errors,
        }))
        .expect("parse result message")
    }

    /// A wire `api_retry` frame, where the CLI names a failure on the
    /// retry path.
    fn api_retry_message(error: &str, status: Option<u16>) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "api_retry",
            "session_id": "worker",
            "attempt": 1,
            "max_retries": 4,
            "retry_delay_ms": 500,
            "error_status": status,
            "error": error,
        }))
        .expect("parse api_retry message")
    }

    /// Turn-end wiring: a `Message::Result` on a worker session drains its
    /// accumulated review activity into one `ReviewActivityNotice` routed to
    /// the submit origin. Guards the seam - a wrong `Message::Result` arm
    /// kills the whole notification with every unit test still green.
    #[tokio::test]
    async fn turn_end_result_drains_review_activity_to_a_notice() {
        let (_dir, workspace, reviewer, worker) = workspace_with_pending_review_activity();
        let (mut task, mut update_rx) = review_task_for(&workspace, &worker);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: result_message("success", false),
        });

        let (key, branch, waiting, message) = drained_notice(&mut update_rx)
            .expect("a ReviewActivityNotice emits on the turn's Result");
        assert_eq!(key, reviewer, "the notice routes to the submit origin, not the worker");
        assert_eq!(branch, "feat", "the notice names the branch it is about");
        assert_eq!(waiting, 1, "the replied-to thread now awaits the reviewer");
        assert!(message.contains("review #1"), "the notice names the review: {message}");
        assert!(message.contains("1 replied"), "the tally counts the reply: {message}");
    }

    /// **A turn's end is announced** (#1486): the frames carry a `Result`
    /// when a turn ends, but a page's live row reads its liveness from the
    /// record - and only this frame asks the page to re-read it. Never
    /// sent, every frame-built turn stayed live for the rest of the
    /// session.
    #[tokio::test]
    async fn a_results_end_announces_the_turn_complete() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("turn-ends");
        let (mut task, mut update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "turn-ends".to_owned(),
            msg: result_message("success", false),
        });

        let mut said = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::TurnComplete { key, terminal_reason } => {
                    said.push(("complete", key, terminal_reason));
                }
                SessionUpdate::TurnCancelled { key } => said.push(("cancelled", key, None)),
                _ => {}
            }
        }
        assert_eq!(said.len(), 1, "exactly one end frame, saw {said:?}");
        assert_eq!(said[0].0, "complete", "an ordinary end, not the cancel's frame");
        assert_eq!(said[0].1, key, "announced on the seat its turn ended");
        assert_eq!(said[0].2, None, "the test's Result carries no terminal reason");
    }

    /// The CLI's terminal reason rides the frame when the result carried
    /// one, and a local command's result - covering no turn - still
    /// announces: the frame states the CLI's terminator, and the page's
    /// handlers no-op when nothing is in flight.
    #[tokio::test]
    async fn a_results_terminal_reason_rides_the_frame() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("turn-reason");
        let (mut task, mut update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "turn-reason".to_owned(),
            msg: result_message_with_reason("completed"),
        });
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "turn-reason".to_owned(),
            msg: result_message_for_a_local_command(),
        });

        let mut said = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::TurnComplete { terminal_reason, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                said.push(terminal_reason);
            }
        }
        assert_eq!(
            said,
            [Some(forge_primitives::runtime::TerminalReason::Completed), None],
            "the reason rides the frame, and a turn-less result announces without one",
        );
    }

    /// A transport `Error` announces no end of its own: it ends the turn
    /// too (`liveness_of` says so), but the page learns that from the
    /// lifecycle, and the frame is the `Result`'s.
    #[tokio::test]
    async fn a_transport_error_announces_no_end() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("turn-error");
        let (mut task, mut update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "turn-error".to_owned(),
            msg: forge_primitives::Message::Error {
                error: "stream closed".to_owned(),
                extras: serde_json::Map::new(),
            },
        });

        let mut said = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::TurnComplete { .. } => said.push("complete"),
                SessionUpdate::TurnCancelled { .. } => said.push("cancelled"),
                _ => {}
            }
        }
        assert!(said.is_empty(), "a transport error is not the Result's frame: {said:?}");
    }

    /// The reader's own interrupt is the other end: the CLI reports it as a
    /// failed `Result` too, so the cancel flag the arm already spends is
    /// what tells the two apart.
    #[tokio::test]
    async fn a_cancelled_results_end_announces_the_turn_cancelled() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("turn-cancelled");
        let (mut task, mut update_rx) = review_task_for(&workspace, &key);

        task.domain.lock().pending_cancel = true;
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "turn-cancelled".to_owned(),
            msg: result_message("error_during_execution", true),
        });

        let mut said = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::TurnComplete { .. } => said.push("complete"),
                SessionUpdate::TurnCancelled { .. } => said.push("cancelled"),
                _ => {}
            }
        }
        assert_eq!(said, ["cancelled"], "the reader's cancel is its own frame");
    }

    /// A cancelled turn reaches the same `Message::Result` arm - the CLI
    /// reports the interrupt as `error_during_execution`, not as a
    /// separate terminal envelope.
    #[tokio::test]
    async fn cancelled_turn_result_drains_review_activity() {
        let (_dir, workspace, reviewer, worker) = workspace_with_pending_review_activity();
        let (mut task, mut update_rx) = review_task_for(&workspace, &worker);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: result_message("error_during_execution", true),
        });

        let (key, ..) = drained_notice(&mut update_rx).expect("a cancelled turn still notifies");
        assert_eq!(key, reviewer);
    }

    /// A turn that ends in error marks the slot - the fact the rail's
    /// failure mark reads - and a result the reader asked to interrupt
    /// does not: a cancel ends with the same failed `Result`.
    #[test]
    fn an_errored_result_marks_the_slot_unless_the_reader_cancelled() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("failed-rail");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "failed-rail".to_owned(),
            msg: result_message("error_during_execution", true),
        });
        assert!(
            task.domain.lock().failed_turn_at.is_some(),
            "a genuine error marks the slot for the rail",
        );

        // The reader cancels the next turn: armed at Cancel routing when
        // the turn is in flight, spent at the result, which must not mark.
        task.domain.lock().failed_turn_at = None;
        task.domain.lock().pending_cancel = true;
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "failed-rail".to_owned(),
            msg: result_message("error_during_execution", true),
        });
        assert!(
            task.domain.lock().failed_turn_at.is_none(),
            "a cancelled turn is the reader's own act, not a failure to flag",
        );
        assert!(!task.domain.lock().pending_cancel, "the stamp is spent at the result");

        // And spent when unused: a cancel that raced a turn the CLI had
        // already finished must not exempt the next genuine failure.
        task.domain.lock().pending_cancel = true;
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "failed-rail".to_owned(),
            msg: result_message("success", false),
        });
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "failed-rail".to_owned(),
            msg: result_message("error_during_execution", true),
        });
        assert!(
            task.domain.lock().failed_turn_at.is_some(),
            "a success spends the stamp, so the next real failure marks",
        );
    }

    /// A plain failure's reason is the CLI's own error strings, in the order
    /// it reported them, carried into the words the model receives.
    #[test]
    fn a_plain_failure_is_continued_with_the_cli_errors_as_its_reason() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("nudge-rail");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "nudge-rail".to_owned(),
            msg: result_message_with_errors(&["API Error: 400 ...", "request too large"]),
        });

        let prompts = captured_prompts(&workspace);
        assert_eq!(prompts.len(), 1, "the failure's continuation goes out: {prompts:?}");
        assert!(
            prompts[0].contains("API Error: 400 ...; request too large"),
            "the CLI's own errors are the reason, in the order it reported them: {prompts:?}",
        );
        assert!(task.domain.lock().failed_turn_at.is_some(), "the rail's mark is set with it");
    }

    /// A turn the reader cancelled ends with the same failed `Result` a
    /// genuine error does, and arms nothing - there is no failure to pick
    /// back up, only the interruption the reader asked for.
    #[test]
    fn a_cancelled_turn_arms_no_continuation() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("cancelled-rail");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        task.domain.lock().pending_cancel = true;

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "cancelled-rail".to_owned(),
            msg: result_message_with_errors(&["aborted_streaming"]),
        });

        let domain = task.domain.lock();
        assert!(domain.failed_turn_at.is_none(), "a cancelled turn is not a failure to mark");
        assert!(domain.auto_continue.is_none(), "and nothing is armed to pick up");
    }

    /// A result the CLI sent no errors for is named by its subtype in the
    /// continuation's words, and an empty list names nothing either.
    #[test]
    fn a_result_without_errors_is_named_by_its_subtype_in_the_nudge() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("subtype-rail");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "subtype-rail".to_owned(),
            msg: result_message("error_max_turns", true),
        });
        let reason = task.domain.lock().auto_continue.clone().expect("armed").reason;
        assert_eq!(reason, "error_max_turns", "no errors reported, so the subtype names it");

        task.domain.lock().auto_continue = None;
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "subtype-rail".to_owned(),
            msg: result_message_with_errors(&[]),
        });
        let reason = task.domain.lock().auto_continue.clone().expect("armed").reason;
        assert_eq!(reason, "error_during_execution", "an empty list names nothing either");
    }

    /// The words of the reason, branch by branch: the CLI's errors win when
    /// it reported any, then the result's subtype, and a plain wording when
    /// neither names anything.
    #[test]
    fn the_failures_reason_prefers_the_cli_errors_then_the_subtype() {
        assert_eq!(
            super::failure_reason(Some(&["API Error: 400 ...".to_owned()]), "error_max_turns"),
            "API Error: 400 ...",
            "the CLI's own errors are the reason",
        );
        assert_eq!(
            super::failure_reason(None, "error_max_turns"),
            "error_max_turns",
            "a result with no errors is named by its subtype",
        );
        assert_eq!(
            super::failure_reason(None, "success"),
            "an error",
            "a subtype that names nothing falls back to plain wording",
        );
        assert_eq!(super::failure_reason(None, ""), "an error", "and so does an empty subtype");
    }

    /// A turn that finished ends the episode: the spend is dropped, so a later
    /// unrelated failure is continued on its own terms.
    #[test]
    fn a_completed_turn_clears_the_spend_for_the_next_failure() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("spent-rail");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        task.domain.lock().auto_continue_spent = true;

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "spent-rail".to_owned(),
            msg: result_message("success", false),
        });

        let domain = task.domain.lock();
        assert!(!domain.auto_continue_spent, "a completed turn ends the episode");
    }

    /// A task whose domain IS the workspace's own for the slot - the
    /// sharing production does - so the fold is what the workspace's fire
    /// reads, and a captured dispatch is what the seat's prompt path
    /// produced.
    fn nudge_task_for(
        workspace: &Arc<crate::Workspace>,
        key: &SessionSlot,
    ) -> (
        SessionTask,
        mpsc::UnboundedReceiver<SeatUpdate>,
        mpsc::UnboundedReceiver<forge_primitives::AgentCommand>,
    ) {
        workspace.enable_test_dispatch_intercept();
        let (handle, to_agent) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let domain = workspace.register_domain_session(key.clone(), Some(Arc::clone(&handle)));
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let task = SessionTask {
            key: key.clone(),
            handle,
            command_rx,
            domain,
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        (task, update_rx, to_agent)
    }

    /// The prompts `workspace` captured, in order.
    fn captured_prompts(workspace: &Arc<crate::Workspace>) -> Vec<String> {
        workspace
            .drain_test_dispatch_buffer()
            .into_iter()
            .filter_map(|cmd| match cmd {
                crate::protocol::Command::PromptUnder { text, .. } => Some(text),
                _ => None,
            })
            .collect()
    }

    /// The `PromptUnder` commands `workspace` captured, in order.
    fn captured_prompt_commands(
        workspace: &Arc<crate::Workspace>,
    ) -> Vec<crate::protocol::Command> {
        workspace
            .drain_test_dispatch_buffer()
            .into_iter()
            .filter(|cmd| matches!(cmd, crate::protocol::Command::PromptUnder { .. }))
            .collect()
    }

    /// Run a failed turn and then execute the continuation it dispatched,
    /// with a replacement's `Connected` landing in between when `replace`.
    /// The answer is whether the prompt reached the CLI.
    fn continuation_reaches_the_cli(label: &str, replace: bool) -> bool {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test(label);
        let (mut task, _update_rx, mut to_agent) = nudge_task_for(&workspace, &key);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-occupant"));

        task.translate_event(AgentEvent::SdkMessage {
            session_id: label.to_owned(),
            msg: result_message("error_during_execution", true),
        });
        let captured = captured_prompt_commands(&workspace);
        let [crate::protocol::Command::PromptUnder { text, uuid, .. }] = captured.as_slice() else {
            panic!("the failure's continuation is dispatched: {captured:?}");
        };
        let (text, uuid) = (text.clone(), uuid.clone());

        if replace {
            // What a `/new` or `/resume` drained first leaves behind: a new
            // occupant under the queued prompt.
            task.translate_event(AgentEvent::Connected {
                session_id: "new-occupant".to_owned(),
                cwd: "/tmp/continuation-occupant".to_owned(),
                current_model: forge_primitives::CurrentModel {
                    resolved_id: "claude".to_owned(),
                    display_name_short: "claude".to_owned(),
                    display_name_long: "claude".to_owned(),
                    requested_id: None,
                    catalog_id: None,
                    supports_effort: false,
                    supported_effort_levels: Vec::new(),
                    supports_auto_mode: None,
                    supports_adaptive_thinking: None,
                    is_authoritative: true,
                },
                available_models: Vec::new(),
                mode: None,
                history_updates: None,
                compaction_count: 0,
            });
        }

        task.execute_command(crate::protocol::Command::PromptUnder {
            key: key.clone(),
            text,
            attachments: Vec::new(),
            uuid: uuid.clone(),
            source: crate::protocol::PromptSource::Forge,
            dispatch_id: None,
        });
        // **The continuation is the command under test, not whatever arrives
        // next.** The turn boundary also asks the CLI for a fill reading, so
        // "something was sent" would answer a different question - and a
        // dropped continuation would read as delivered on the strength of a
        // probe.
        loop {
            match to_agent.try_recv() {
                Ok(forge_primitives::AgentCommand::PromptWithImages { uuid: sent, .. })
                    if sent == uuid =>
                {
                    return true;
                }
                Ok(_) => {}
                Err(_) => return false,
            }
        }
    }

    /// The continuation speaks for the occupant that failed. A `/new` or
    /// `/resume` the queue drains first leaves a replacement under it, and
    /// the replacement carries none of the history the words point at - so
    /// the prompt is dropped where it would have run, and still lands when
    /// the occupant did not move.
    #[test]
    fn a_continuation_is_dropped_when_the_occupant_changed_under_it() {
        assert!(
            continuation_reaches_the_cli("kept-rail", false),
            "control: with the occupant unchanged the continuation reaches the CLI",
        );
        assert!(
            !continuation_reaches_the_cli("replaced-rail", true),
            "the replacement is not handed words about a history it does not have",
        );
    }

    /// Everything `updates` holds right now.
    fn drain_updates(rx: &mut mpsc::UnboundedReceiver<SeatUpdate>) -> Vec<SessionUpdate> {
        let mut seen = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            seen.push(std::sync::Arc::unwrap_or_clone(frame.update));
        }
        seen
    }

    /// A turn that dies on a retried 5xx is the nudge's like any other
    /// failure: forge's continuation goes out the moment the result lands -
    /// no delay, nothing left for a sweep - and it draws as the turn the
    /// model received. The terminal's dead-turn path used to own this class
    /// and no longer exists, so leaving it alone would leave the seat dead
    /// until the person typed again (#2146).
    #[test]
    fn a_server_error_failure_is_nudged_at_once() {
        let (workspace, mut updates) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("server-rail");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "server-rail".to_owned(),
            msg: api_retry_message("server_error", Some(529)),
        });
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "server-rail".to_owned(),
            msg: result_message("error_during_execution", true),
        });

        let prompts = captured_prompts(&workspace);
        assert_eq!(
            prompts.len(),
            1,
            "the failed result fires the continuation itself: {prompts:?}"
        );
        assert!(
            prompts[0].contains("error_during_execution"),
            "the prompt names the failure it answers: {prompts:?}",
        );
        let domain = task.domain.lock();
        assert!(domain.auto_continue.is_none(), "the fire took the armed continuation");
        assert!(domain.auto_continue_spent, "the episode is spent: one nudge per failure");

        let drawn = drain_updates(&mut updates);
        assert!(
            drawn.iter().any(|update| matches!(
                update,
                SessionUpdate::ChatAppended { msg: forge_primitives::Message::User { .. }, .. }
            )),
            "the continuation's words draw in every view: {drawn:?}",
        );
    }

    /// **A live frame crosses the task stamped.**
    ///
    /// The kinds a turn OPENS with are exactly the ones the CLI does not
    /// stamp - the prompt frame carries no timestamp at all, and neither do
    /// the counter or result frames - so a page opening mid-turn had no row
    /// to anchor its clock on: 0.0s until the first assistant frame, whose
    /// stamp is the moment it was written rather than the turn's start. The
    /// receipt is forge's own record of when the row crossed; a frame the
    /// CLI did stamp keeps its own.
    #[test]
    fn a_live_frame_crosses_stamped_and_keeps_the_stamp_it_came_with() {
        let (workspace, _updates) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("stamp-crossing");
        let (mut task, mut updates, _to_agent) = nudge_task_for(&workspace, &key);

        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage {
                session_id: "stamp-crossing".to_owned(),
                msg,
            });
        };

        // The prompt frame as the CLI sends it: no stamp of its own.
        let prompt: forge_primitives::Message = serde_json::from_value(serde_json::json!({
            "type": "user",
            "message": {"role": "user", "content": [{"type": "text", "text": "hi"}]},
            "session_id": "stamp-crossing",
        }))
        .expect("a prompt frame");
        send(&mut task, prompt);

        // And one the CLI stamped itself.
        let spoke: forge_primitives::Message = serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "uuid": "a1",
            "timestamp": "2026-10-15T05:18:15.544Z",
            "session_id": "stamp-crossing",
            "message": {
                "id": "m1",
                "role": "assistant",
                "model": "claude-opus-5",
                "content": [{"type": "text", "text": "working"}],
            },
        }))
        .expect("an assistant frame");
        send(&mut task, spoke);

        let drawn: Vec<forge_primitives::Message> = drain_updates(&mut updates)
            .into_iter()
            .filter_map(|update| match update {
                SessionUpdate::ChatAppended { msg, .. } => Some(msg),
                _ => None,
            })
            .collect();
        assert_eq!(drawn.len(), 2, "both frames are drawn: {drawn:?}");

        let prompt_stamp = serde_json::to_value(&drawn[0]).expect("encode")["timestamp"]
            .as_str()
            .map(str::to_owned)
            .expect("the prompt row carries a stamp for a clock to anchor on");
        assert!(
            time::OffsetDateTime::parse(
                &prompt_stamp,
                &time::format_description::well_known::Rfc3339,
            )
            .is_ok(),
            "and it is a time the client can read: {prompt_stamp}",
        );
        assert_eq!(
            serde_json::to_value(&drawn[1]).expect("encode")["timestamp"].as_str(),
            Some("2026-10-15T05:18:15.544Z"),
            "while the frame the CLI stamped keeps its own",
        );
    }

    /// A rate-limited turn gets the continuation too: the gateway answers
    /// an exhausted window by rotating the account, and whatever failure
    /// still reaches forge is the nudge's to answer (#2146).
    #[test]
    fn a_rate_limited_failure_is_nudged_at_once() {
        let (workspace, _updates) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("rate-limit-rail");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "rate-limit-rail".to_owned(),
            msg: api_retry_message("rate_limit", Some(429)),
        });
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "rate-limit-rail".to_owned(),
            msg: result_message("error_during_execution", true),
        });

        let prompts = captured_prompts(&workspace);
        assert_eq!(prompts.len(), 1, "a 429 failure is nudged like any other: {prompts:?}");
    }

    /// The gateway edge: a rate_limit_event whose status is not
    /// `allowed` reports the gateway, which drops the account binding the
    /// session's requests were stamped with. The binding is keyed by the id
    /// the CLI reported, so the fixture stamps one on the domain. An
    /// `allowed` frame reports nothing.
    #[test]
    fn a_rate_limit_event_not_allowed_reports_the_gateway_for_the_session_key() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let session_id = "w-uuid";
        let key = SessionSlot::from_str_for_test(session_id);
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new(session_id));

        workspace.gateway.bindings.bind(
            key.org(),
            key.project(),
            session_id,
            forge_gateway::AccountKey("A".to_owned()),
        );

        let rejected = forge_primitives::Message::RateLimitEvent {
            rate_limit_info: forge_primitives::RateLimitInfo {
                status: forge_primitives::RateLimitStatus::Rejected,
                resets_at: Some(1_800_000_000),
                rate_limit_type: None,
                utilization: None,
                overage_status: None,
                overage_resets_at: None,
                overage_disabled_reason: None,
                raw: serde_json::Map::new(),
            },
            uuid: "u1".to_owned(),
            session_id: session_id.to_owned(),
            extras: serde_json::Map::new(),
        };
        task.translate_event(AgentEvent::SdkMessage {
            session_id: session_id.to_owned(),
            msg: rejected,
        });

        assert!(
            workspace.gateway.bindings.binding_for(key.org(), key.project(), session_id).is_none(),
            "the report drops the session's own binding",
        );

        // The re-bound key must survive the allowed frame: allowed
        // frames arrive every turn, so a lost guard here would rotate
        // a live session's binding on each one. Re-binding the task's
        // OWN key is what makes this assert kill the guard regression.
        workspace.gateway.bindings.bind(
            key.org(),
            key.project(),
            session_id,
            forge_gateway::AccountKey("C".to_owned()),
        );
        task.translate_event(AgentEvent::SdkMessage {
            session_id: session_id.to_owned(),
            msg: forge_primitives::Message::RateLimitEvent {
                rate_limit_info: forge_primitives::RateLimitInfo {
                    status: forge_primitives::RateLimitStatus::Allowed,
                    resets_at: None,
                    rate_limit_type: None,
                    utilization: None,
                    overage_status: None,
                    overage_resets_at: None,
                    overage_disabled_reason: None,
                    raw: serde_json::Map::new(),
                },
                uuid: "u2".to_owned(),
                session_id: session_id.to_owned(),
                extras: serde_json::Map::new(),
            },
        });
        assert_eq!(
            workspace.gateway.bindings.binding_for(key.org(), key.project(), session_id),
            Some(forge_gateway::AccountKey("C".to_owned())),
            "an allowed frame rotates nothing",
        );
    }

    /// `Message::Error` is the CLI's last-gasp transport failure; no
    /// Result follows it, so it has to drain on its own.
    #[tokio::test]
    async fn transport_error_drains_review_activity() {
        let (_dir, workspace, reviewer, worker) = workspace_with_pending_review_activity();
        let (mut task, mut update_rx) = review_task_for(&workspace, &worker);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: forge_primitives::Message::Error {
                error: "stream closed".to_owned(),
                extras: serde_json::Map::new(),
            },
        });

        let (key, ..) =
            drained_notice(&mut update_rx).expect("a transport error still notifies the reviewer");
        assert_eq!(key, reviewer);
    }

    /// The session being replaced mid-turn (`/new`, `/clear`, an account
    /// switch) never produces a Result, so the drain has to happen here or
    /// the activity this turn touched sits until the task exits.
    #[tokio::test]
    async fn session_replacement_drains_review_activity() {
        let (_dir, workspace, reviewer, worker) = workspace_with_pending_review_activity();
        let (mut task, mut update_rx) = review_task_for(&workspace, &worker);
        task.connected_once = true;

        task.translate_event(connected_event("worker-replacement", "/tmp/proj"));

        let (key, ..) = drained_notice(&mut update_rx)
            .expect("the replaced identity flushes what its turn touched");
        assert_eq!(key, reviewer);
        assert!(
            workspace.drain_review_activity(&worker).is_empty(),
            "nothing strands under the worker's own slot",
        );
    }

    /// Teardown backstop: the subprocess dying or a despawn closing the
    /// command channel drops the task without any terminal envelope.
    #[tokio::test]
    async fn task_teardown_drains_review_activity() {
        let (_dir, workspace, reviewer, worker) = workspace_with_pending_review_activity();
        let (task, mut update_rx) = review_task_for(&workspace, &worker);

        drop(task);

        let (key, ..) =
            drained_notice(&mut update_rx).expect("teardown flushes the stranded activity");
        assert_eq!(key, reviewer);
    }

    /// `run` exiting its select loop reaches the drain, rather than only
    /// a hand-dropped task doing so.
    ///
    /// This does NOT model subprocess death. `Agent::testing_stub`
    /// substitutes an event channel whose sender is already dropped,
    /// which production never does - `SessionTask.handle` keeps an `Arc`
    /// chain to `BridgeInner.event_tx` alive for the task's whole life,
    /// so the event arm's `break` is unreachable there. The fixture also
    /// closes the command channel, so this test cannot say which arm
    /// broke; what it establishes is that leaving `run` drains.
    #[tokio::test]
    async fn run_exiting_on_a_closed_channel_drains_review_activity() {
        let (_dir, workspace, reviewer, worker) = workspace_with_pending_review_activity();
        let (task, mut update_rx) = review_task_for(&workspace, &worker);

        task.run().await;

        let (key, ..) =
            drained_notice(&mut update_rx).expect("the run loop's exit flushes the activity");
        assert_eq!(key, reviewer);
    }

    /// A `ConnectionFailed` event is terminal for the task: the dead
    /// spawn's pool entry and command sender are released so the next
    /// retry (projects-pane click, cron fire) re-spawns instead of
    /// dispatching into the dead handle, a view still receives the
    /// user-visible `SessionUpdate::ConnectionFailed`, and
    /// `translate_event` signals the run loop to exit so `Drop`'s
    /// expiry backstop fires.
    #[tokio::test]
    async fn connection_failed_releases_registrations_and_terminates() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let key = SessionSlot::from_str_for_test("dead-spawn");
        let (handle, _cmds) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let (cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let mut update_rx = update_tx.subscribe(SubscriberRole::Answering);
        workspace.pool.lock().insert(
            key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&handle),
                account: forge_gateway::AccountKey("Acct".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        workspace.command_senders.lock().insert(key.clone(), cmd_tx);
        workspace.register_domain_session(key.clone(), Some(Arc::clone(&handle)));
        let mut task = SessionTask {
            key: key.clone(),
            handle,
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(key.clone(), None))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        let continues = task.translate_event(AgentEvent::ConnectionFailed {
            message: "spawn failed".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });

        assert!(!continues, "ConnectionFailed must terminate the task");
        assert!(
            !workspace.pool.lock().contains_key(&key),
            "pool entry released so a retry spawns fresh"
        );
        assert!(!workspace.command_senders.lock().contains_key(&key), "command sender released");
        let update = update_rx.try_recv().expect("an update emits");
        assert!(
            matches!(
                &*update.update,
                SessionUpdate::ConnectionFailed { key: emitted, .. } if *emitted == key
            ),
            "the ConnectionFailed envelope still goes out"
        );
        // **A died session leaves no machine turn.** A handoff whose successor
        // never came up and a compaction both end with the subprocess; the
        // stand-down follows the death so a client reads it second.
        assert!(
            matches!(
                update_rx.try_recv().map(|frame| std::sync::Arc::unwrap_or_clone(frame.update)),
                Ok(SessionUpdate::MachineTurn { machine: None, .. })
            ),
            "the machine turn ends with the session",
        );
    }

    /// A `ConnectionFailed` releases the task's registrations, so a
    /// later click or delivery does not find a dead handle still
    /// registered under the key.
    #[tokio::test]
    async fn connection_failed_releases_the_session_registrations() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let key = SessionSlot::from_str_for_test("real-key");
        let (handle, _cmds) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let (cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let _update_rx = update_tx.subscribe(SubscriberRole::Answering);
        workspace.pool.lock().insert(
            key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&handle),
                account: forge_gateway::AccountKey("Acct".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        workspace.command_senders.lock().insert(key.clone(), cmd_tx);
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(key.clone(), None))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        let continues = task.translate_event(AgentEvent::ConnectionFailed {
            message: "spawn failed".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });

        assert!(!continues);
        assert!(
            !workspace.pool.lock().contains_key(&key),
            "pool entry under the real key released"
        );
        assert!(
            !workspace.command_senders.lock().contains_key(&key),
            "command sender under the real key released"
        );
    }

    /// A spawn that never connected strands whatever was parked for it, and
    /// the expiry reaches it by slot rather than by key: one bucket holds
    /// it, and the release below drops the domain it was once buffered on.
    /// For Slack the delivery was already committed, so nothing re-delivers
    /// it.
    #[tokio::test]
    async fn connection_failed_expires_the_buffers_parked_for_its_slot() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let key = test_slot();
        let (handle, _cmds) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let (cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let _update_rx = update_tx.subscribe(SubscriberRole::Answering);
        workspace.pool.lock().insert(
            key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&handle),
                account: forge_gateway::AccountKey("Acct".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        workspace.command_senders.lock().insert(key.clone(), cmd_tx);
        workspace.register_domain_session(key.clone(), Some(Arc::clone(&handle)));
        workspace.park_slack(&test_slot(), vec![buffered_slack("parked while spawning")]);

        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(key.clone(), None))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        let continues = task.translate_event(AgentEvent::ConnectionFailed {
            message: "spawn failed".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });

        assert!(!continues);
        assert!(
            workspace.take_parked_for_slot(&test_slot()).slack.is_empty(),
            "the message parked for this slot is expired, not left for a later session",
        );
    }

    /// Everything `updates` holds that is a `Notice`, as its text.
    fn notices_of(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<(NoticeSeverity, String)> {
        drain_updates(updates)
            .into_iter()
            .filter_map(|update| match update {
                SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                _ => None,
            })
            .collect()
    }

    /// Record a death on `key`'s seat the way the arm above does, so a test
    /// drives the record rather than hand-rolling it.
    fn record_death_via_arm(task: &mut SessionTask, occupant: &str, message: &str) {
        task.connected_once = true;
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new(occupant));
        task.translate_event(AgentEvent::ConnectionFailed {
            message: message.to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });
    }

    /// A session that died is not silently swapped: the recovery that comes
    /// up on the slot announces the death and what forge did about it - the
    /// same occupant resumed, or a new one under a new id - exactly once,
    /// and a connect with no death behind it stays quiet.
    ///
    /// The verb is "ended" rather than "died" on purpose: the same arm
    /// catches a `/new` or `/resume` that failed to respawn, where the
    /// occupant was swapped out rather than crashing, and "ended" is true
    /// of both.
    #[test]
    fn a_recovery_after_a_death_announces_what_forge_did() {
        let message = "the claude subprocess closed its output stream";

        // The death: an occupant that had been up, whose subprocess ended.
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("died-and-restarted");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);
        record_death_via_arm(&mut task, "dead-occupant", message);

        // The recovery lands as its own task on the same slot, under a new id.
        let (mut revived, mut updates, _to_agent) = nudge_task_for(&workspace, &key);
        revived.translate_event(connected_event("fresh-occupant", "/tmp/recovery-announced"));
        let notices = notices_of(&mut updates);
        assert_eq!(notices.len(), 1, "one line, and only one: {notices:?}");
        let (severity, text) = &notices[0];
        assert_eq!(
            *severity,
            NoticeSeverity::Error,
            "a death reads at failure level: the client leads the row with the severity word",
        );
        assert_eq!(
            text,
            "The agent's session ended; forge restarted it under a new id (dead-occupant -> fresh-occupant).",
            "the restart names both ids, in pinned words",
        );

        // A second connect on the slot stays quiet: the death is announced
        // once, not on every connect that follows it.
        revived.translate_event(connected_event("second-occupant", "/tmp/recovery-announced"));
        assert!(
            notices_of(&mut updates).is_empty(),
            "a later connect does not re-announce the death",
        );

        // **The lifecycle tells the truth about now**: the recovering connect
        // clears the failure as it always did, so the row reads what the seat
        // is - and the death rides on as its own record.
        assert_eq!(
            workspace.spawn_failure(&key),
            None,
            "a recovered seat that still read Failed would be the same lie, mirrored",
        );
        assert!(
            workspace.death_stands(&key),
            "the death nobody was shown rides until a reader sees it",
        );
        assert_eq!(
            workspace.death_reason(&key).as_deref(),
            Some(message),
            "and it carries the reason the seat died with",
        );
        assert!(
            workspace.spend_death(&key),
            "showing the seat takes the death, and answers that it did",
        );
        assert!(!workspace.death_stands(&key), "the record goes with the spend");
        assert_eq!(workspace.death_reason(&key), None, "and the reason with it");

        // And the same id back: the session resumed.
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("died-and-resumed");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);
        record_death_via_arm(&mut task, "kept-occupant", message);
        let (mut revived, mut updates, _to_agent) = nudge_task_for(&workspace, &key);
        revived.translate_event(connected_event("kept-occupant", "/tmp/recovery-announced"));
        let notices = notices_of(&mut updates);
        assert_eq!(
            notices.first().map(|(_, text)| text.as_str()),
            Some("The agent's session ended; forge resumed it (kept-occupant)."),
            "the same occupant coming back reads as a resume: {notices:?}",
        );

        // Control: a connect with no death behind it draws no line.
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("connected-quiet");
        let (mut task, mut updates, _to_agent) = nudge_task_for(&workspace, &key);
        task.translate_event(connected_event("first-occupant", "/tmp/plain-connect"));
        assert!(notices_of(&mut updates).is_empty(), "a plain connect announces nothing");
    }

    /// **The spend does not eat the announcement.** A reader who opens a
    /// crashed seat's page spends the row's trace and then wakes the seat,
    /// so the connect that answers their own click is the first one to see
    /// the death - and it still owes them the sentence.
    #[test]
    fn a_spent_death_still_announces_on_the_recovery_that_answers_the_click() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("spent-then-recovered");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);
        record_death_via_arm(
            &mut task,
            "dead-occupant",
            "the claude subprocess closed its output stream",
        );

        // The page opened: the seat was shown, the trace spent, and the
        // recovery has not happened yet.
        assert!(workspace.spend_death(&key), "the show took the trace");
        assert!(!workspace.death_stands(&key), "and the row's mark is gone");

        // The wake's spawn lands, under a new id.
        let (mut revived, mut updates, _to_agent) = nudge_task_for(&workspace, &key);
        revived.translate_event(connected_event("fresh-occupant", "/tmp/recovery-announced"));
        let notices = notices_of(&mut updates);
        assert_eq!(
            notices.first().map(|(_, text)| text.as_str()),
            Some(
                "The agent's session ended; forge restarted it under a new id (dead-occupant -> fresh-occupant)."
            ),
            "the click's own recovery is still announced: {notices:?}",
        );
        assert!(
            !workspace.death_stands(&key),
            "spent and announced leaves no standing death behind",
        );
    }

    /// One logged event: its level and every field formatted into a string.
    /// `record_str` forwards here, so a `%`-formatted field arrives through
    /// this arm however the macro wrote it.
    #[derive(Default, Clone)]
    struct LoggedEvent(std::sync::Arc<std::sync::Mutex<Vec<(tracing::Level, String)>>>);

    struct AllFields<'a>(&'a mut String);

    impl tracing::field::Visit for AllFields<'_> {
        fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
            use std::fmt::Write as _;
            let _ = write!(self.0, " {}={value:?}", field.name());
        }
    }

    impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for LoggedEvent {
        fn on_event(
            &self,
            event: &tracing::Event<'_>,
            _ctx: tracing_subscriber::layer::Context<'_, S>,
        ) {
            let mut fields = String::new();
            event.record(&mut AllFields(&mut fields));
            self.0.lock().expect("capture").push((*event.metadata().level(), fields));
        }
    }

    /// **The one line that says a seat's session ended.** It is a WARN, and
    /// it carries the seat and the occupant: a reader triaging it has to
    /// know which seat died, and the agent-side line alone names neither.
    #[test]
    fn a_death_warns_at_warn_with_the_seat_and_the_occupant() {
        use tracing_subscriber::layer::SubscriberExt;

        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("death-warns");
        let (mut task, _update_rx, _to_agent) = nudge_task_for(&workspace, &key);

        let capture = LoggedEvent::default();
        let subscriber = tracing_subscriber::registry().with(capture.clone());
        tracing::subscriber::with_default(subscriber, || {
            record_death_via_arm(
                &mut task,
                "dead-occupant",
                "the claude subprocess closed its output stream",
            );
        });

        let events = capture.0.lock().expect("capture");
        let (level, fields) = events
            .iter()
            .find(|(_, fields)| fields.contains("event_name=\"session_ended\""))
            .unwrap_or_else(|| panic!("no session_ended event; saw {events:?}"));
        assert_eq!(*level, tracing::Level::WARN, "a session's end reads at WARN: {fields}");
        for needle in [
            "slot=TestOrg/test-project/death-warns",
            "session_id=dead-occupant",
            "error=the claude subprocess closed its output stream",
        ] {
            assert!(fields.contains(needle), "the line carries `{needle}`: {fields}");
        }
    }

    /// A `PermissionRequest` registers a pending slot; `RespondPermission`
    /// consumes it and the outcome reaches the agent round-trip. The
    /// happy path of the can_use_tool parking lot.
    #[tokio::test]
    async fn respond_permission_round_trips_to_the_agent() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (handle, mut agent_rx) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let key = SessionSlot::from_str_for_test("perm");
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let _update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(
                key.clone(),
                Some(Arc::clone(&handle)),
            ))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::PermissionRequest {
            session_id: key.display(),
            request: permission_request_fixture("tu-1"),
        });
        assert!(
            task.domain.lock().pending_interactions.contains_key("tu-1"),
            "the request parks a pending permission slot"
        );
        assert_eq!(
            workspace.pending_request_seq(&key),
            1,
            "the permission has its own identity on the wire",
        );

        task.execute_command(Command::RespondPermission {
            key: key.clone(),
            tool_id: "tu-1".to_owned(),
            outcome: forge_primitives::PermissionOutcome::Cancelled,
        });

        let cmd = tokio::time::timeout(std::time::Duration::from_secs(2), agent_rx.recv())
            .await
            .expect("the forwarded outcome reaches the agent promptly")
            .expect("command channel open");
        assert!(
            matches!(
                cmd,
                forge_primitives::AgentCommand::PermissionResponse { tool_call_id, .. }
                    if tool_call_id == "tu-1"
            ),
            "the outcome forwards to the bridge with the right tool id"
        );
        assert!(
            !task.domain.lock().pending_interactions.contains_key("tu-1"),
            "the slot is consumed"
        );
    }

    /// A subscriber that only reads must not keep a permission request
    /// parked. With no subscriber that can answer it, the guard resolves
    /// the slot `Cancelled` rather than leaving the turn waiting on a
    /// reply nobody will send. Catches the guard keying on "somebody
    /// took the update" instead of "somebody can answer it", which the
    /// observer's arrival would otherwise turn into a hang.
    #[tokio::test]
    async fn a_permission_request_with_only_an_observer_fails_closed() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (handle, mut agent_rx) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let key = SessionSlot::from_str_for_test("perm-observer");
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let mut observer = update_tx.subscribe(SubscriberRole::Observing);
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(
                key.clone(),
                Some(Arc::clone(&handle)),
            ))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::PermissionRequest {
            session_id: key.display(),
            request: permission_request_fixture("tu-obs"),
        });

        assert!(
            !task.domain.lock().pending_interactions.contains_key("tu-obs"),
            "the slot is resolved rather than parked, so the turn cannot hang",
        );
        assert!(
            matches!(
                observer.try_recv(),
                Ok(SeatUpdate { update, .. })
                    if matches!(&*update, SessionUpdate::PermissionRequest { tool_id, .. } if tool_id == "tu-obs")
            ),
            "the observer is still delivered the request it cannot answer",
        );
        let cmd = tokio::time::timeout(std::time::Duration::from_secs(2), agent_rx.recv())
            .await
            .expect("the cancelled outcome reaches the agent")
            .expect("command channel open");
        assert!(
            matches!(
                &cmd,
                forge_primitives::AgentCommand::PermissionResponse {
                    tool_call_id,
                    outcome: forge_primitives::PermissionOutcome::Cancelled,
                    ..
                } if tool_call_id == "tu-obs"
            ),
            "the orphaned permission answers the bridge Cancelled, got {cmd:?}",
        );
        assert!(
            tokio::time::timeout(std::time::Duration::from_millis(200), agent_rx.recv())
                .await
                .is_err(),
            "a second permission response is the duplicate this catches",
        );
    }

    /// The question guard keys on an answering subscriber the same way
    /// the permission one does. Catches pointing this site back at
    /// `send`: the permission test drives a different event, so an
    /// observer's arrival here would park the question on a reply nobody
    /// will send and no other test would notice.
    #[tokio::test]
    async fn a_question_request_with_only_an_observer_fails_closed() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (handle, mut agent_rx) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let key = SessionSlot::from_str_for_test("question-observer");
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let mut observer = update_tx.subscribe(SubscriberRole::Observing);
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(
                key.clone(),
                Some(Arc::clone(&handle)),
            ))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::QuestionRequest {
            session_id: key.display(),
            request: question_request_fixture("tu-q-obs"),
        });

        assert!(
            !task.domain.lock().pending_interactions.contains_key("tu-q-obs"),
            "the question slot is resolved rather than parked, so the turn cannot hang",
        );
        assert!(
            matches!(
                observer.try_recv(),
                Ok(frame)
                    if matches!(&*frame.update, SessionUpdate::QuestionRequest { tool_id, .. } if tool_id == "tu-q-obs")
            ),
            "the observer is still delivered the question it cannot answer",
        );
        let cmd = tokio::time::timeout(std::time::Duration::from_secs(2), agent_rx.recv())
            .await
            .expect("the cancelled outcome reaches the agent")
            .expect("command channel open");
        assert!(
            matches!(
                &cmd,
                forge_primitives::AgentCommand::QuestionResponse {
                    tool_call_id,
                    outcome: forge_primitives::QuestionOutcome::Cancelled,
                    ..
                } if tool_call_id == "tu-q-obs"
            ),
            "the orphaned question answers the bridge Cancelled, got {cmd:?}",
        );
        assert!(
            tokio::time::timeout(std::time::Duration::from_millis(200), agent_rx.recv())
                .await
                .is_err(),
            "a second question response is the duplicate this catches",
        );
    }

    /// The cross-kind guard: `AskUserQuestion` reuses the can_use_tool
    /// wire, so a `RespondPermission` can arrive with a tool id whose
    /// slot is a Question. The mismatched outcome must be dropped and
    /// the REAL waiter (the question's oneshot) preserved.
    #[tokio::test]
    async fn respond_permission_against_a_question_slot_is_dropped() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (handle, mut agent_rx) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let key = SessionSlot::from_str_for_test("xkind");
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let _update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(
                key.clone(),
                Some(Arc::clone(&handle)),
            ))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::QuestionRequest {
            session_id: key.display(),
            request: question_request_fixture("tu-q1"),
        });
        assert_eq!(
            workspace.pending_request_seq(&key),
            1,
            "the question has its own identity on the wire",
        );

        task.execute_command(Command::RespondPermission {
            key: key.clone(),
            tool_id: "tu-q1".to_owned(),
            outcome: forge_primitives::PermissionOutcome::Cancelled,
        });

        assert!(
            task.domain.lock().pending_interactions.contains_key("tu-q1"),
            "the question slot survives the mismatched permission response"
        );
        assert!(agent_rx.try_recv().is_err(), "nothing forwards to the agent on a kind mismatch");
    }

    /// The round rides the resolution: a batch reuses one tool id and
    /// advances the question index, and a view's clear needs the pair to
    /// dequeue a batch's rounds one at a time (the loss itself is the
    /// record's single ask slot - #1717's queue, its own piece).
    ///
    /// **This pins the ANSWER path** - one of the sites that emits the
    /// frame; the identity drain and the orphan arms carry the same field,
    /// and the compiler holds every site to naming it.
    #[tokio::test]
    async fn an_answered_questions_resolution_names_its_round() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (handle, _agent_rx) = Agent::testing_stub();
        let handle = Arc::new(handle);
        let key = SessionSlot::from_str_for_test("ask-round");
        let (_cmd_tx, command_rx) = mpsc::unbounded_channel();
        let update_tx = UpdateFanout::default();
        let mut observer = update_tx.subscribe(SubscriberRole::Answering);
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::clone(&handle),
            command_rx,
            domain: Arc::new(Mutex::new(DomainSession::new(
                key.clone(),
                Some(Arc::clone(&handle)),
            ))),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        let mut request = question_request_fixture("tu-round");
        request.question_index = 3;
        task.translate_event(AgentEvent::QuestionRequest { session_id: key.display(), request });

        task.execute_command(Command::RespondQuestion {
            key: key.clone(),
            tool_id: "tu-round".to_owned(),
            outcome: forge_primitives::QuestionOutcome::Cancelled,
        });

        let mut resolved = None;
        while let Ok(frame) = observer.try_recv() {
            if let SessionUpdate::PendingInteractionResolved { question_index, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                resolved = Some(question_index);
            }
        }
        assert_eq!(resolved, Some(Some(3)), "the resolution names the round it ends");
    }

    fn permission_request_fixture(tool_id: &str) -> forge_primitives::PermissionRequest {
        forge_primitives::PermissionRequest {
            tool_call: forge_primitives::ToolCall {
                tool_call_id: tool_id.to_owned(),
                title: "Read".to_owned(),
                kind: forge_primitives::ToolKind::Read,
                status: forge_primitives::ToolCallStatus::Pending,
                content: Vec::new(),
                raw_input: None,
                raw_output: None,
                output_metadata: None,
                task_metadata: None,
                locations: Vec::new(),
                meta: None,
            },
            options: Vec::new(),
            display: None,
        }
    }

    fn question_request_fixture(tool_id: &str) -> forge_primitives::QuestionRequest {
        forge_primitives::QuestionRequest {
            tool_call: forge_primitives::ToolCall {
                tool_call_id: tool_id.to_owned(),
                title: "AskUserQuestion".to_owned(),
                kind: forge_primitives::ToolKind::Other,
                status: forge_primitives::ToolCallStatus::Pending,
                content: Vec::new(),
                raw_input: None,
                raw_output: None,
                output_metadata: None,
                task_metadata: None,
                locations: Vec::new(),
                meta: None,
            },
            prompt: forge_primitives::QuestionPrompt {
                question: "Which?".to_owned(),
                header: "Pick".to_owned(),
                multi_select: false,
                options: Vec::new(),
            },
            question_index: 0,
            total_questions: 1,
        }
    }

    /// The typed dispatch-failure events map onto their session-keyed
    /// envelopes: `SetModelFailed` (the /model rollback trigger) and
    /// `TurnError` (the committed-turn unwind).
    #[tokio::test]
    async fn set_model_failed_and_turn_error_map_to_keyed_updates() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (mut task, mut update_rx) =
            review_task_for(&workspace, &SessionSlot::from_str_for_test("m"));

        task.translate_event(AgentEvent::SetModelFailed {
            session_id: "m".to_owned(),
            model: "claude-attempted".to_owned(),
            message: "not available".to_owned(),
        });
        assert!(
            matches!(
                update_rx.try_recv(),
                Ok(frame)
                    if matches!(&*frame.update, SessionUpdate::SetModelFailed { model, message, .. } if model == "claude-attempted" && message == "not available")
            ),
            "SetModelFailed keeps model + message for the rollback reducer"
        );

        task.translate_event(AgentEvent::TurnError {
            session_id: "m".to_owned(),
            message: "stdin write failed".to_owned(),
            class: forge_primitives::TurnErrorClass::Other,
        });
        assert!(
            matches!(
                update_rx.try_recv(),
                Ok(frame)
                    if matches!(&*frame.update, SessionUpdate::TurnError { message, .. } if message == "stdin write failed")
            ),
            "TurnError carries the failure text so the spinner unwinds"
        );
    }

    /// The class an event was built with rides the update stream, so a
    /// view that reads only `SessionUpdate` can tell an auth failure from
    /// any other error instead of searching the message itself.
    #[tokio::test]
    async fn turn_error_carries_its_class_onto_the_update_stream() {
        let (_dir, workspace) = workspace_with_account_config_dir("/tmp/forge-testing-stub");
        let (mut task, mut update_rx) =
            review_task_for(&workspace, &SessionSlot::from_str_for_test("m"));

        for class in [
            forge_primitives::TurnErrorClass::AuthRequired,
            forge_primitives::TurnErrorClass::Other,
        ] {
            task.translate_event(AgentEvent::TurnError {
                session_id: "m".to_owned(),
                message: "interrupt not acknowledged by the CLI".to_owned(),
                class,
            });
            assert!(
                matches!(
                    update_rx.try_recv(),
                    Ok(frame)
                        if matches!(&*frame.update, SessionUpdate::TurnError { class: Some(on_wire), .. } if *on_wire == class)
                ),
                "the class has to reach the stream as {class:?}, not as None a reader must guess past",
            );
        }
    }

    /// The teardown drain must not double-notify a turn that already
    /// ended cleanly - every site shares one idempotent drain.
    #[tokio::test]
    async fn teardown_after_a_normal_turn_end_emits_nothing_further() {
        let (_dir, workspace, _reviewer, worker) = workspace_with_pending_review_activity();
        let (mut task, mut update_rx) = review_task_for(&workspace, &worker);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: result_message("success", false),
        });
        assert!(drained_notice(&mut update_rx).is_some(), "the turn's own notice fired");

        drop(task);

        assert!(drained_notice(&mut update_rx).is_none(), "teardown adds no second notice");
    }

    /// The store follows the id the CLI reports when it connects. A
    /// `/resume`, a `/clear`, a login or a logout move a session's id
    /// without forge choosing it, and a boot resolves a session from this
    /// row - so the row has to move with every Connected, not only the
    /// first.
    #[test]
    fn connected_records_the_id_the_cli_adopted() {
        let dir = tempfile::tempdir().expect("tempdir");
        let root = dir.path().join("solo");
        std::fs::create_dir_all(&root).expect("root");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "{root}"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                root = root.display()
            ),
        )
        .expect("write forge.toml");
        let workspace =
            Arc::new(crate::Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        let key = SessionSlot::lead("TestOrg", "forge");
        workspace.seed_test_bound_session(&key, "Stargate");
        {
            let db = workspace.db.lock();
            let db = db.as_ref().expect("db");
            crate::store::sessions::put(
                db,
                &crate::store::sessions::SessionRecord {
                    org: "TestOrg".to_owned(),
                    project: "forge".to_owned(),
                    label: "lead".to_owned(),
                    session_id: None,
                    charter: None,
                    kick: None,
                    resume_kick: None,
                    interactive: None,
                    seat_state: None,
                    is_git_repo: None,
                    mcp_families: None,
                    cwd: None,
                },
            )
            .expect("seed the row");
        }

        let stored = || {
            let db = workspace.db.lock();
            let db = db.as_ref().expect("db");
            crate::store::sessions::get(db, "TestOrg", "forge", "lead")
                .expect("read")
                .and_then(|row| row.session_id)
        };

        let (mut task, _updates) = review_task_for(&workspace, &key);
        task.translate_event(connected_event("first-id", "/proj"));
        assert_eq!(
            stored().as_deref(),
            Some("first-id"),
            "the first Connected records the id the CLI adopted",
        );

        // `/resume`, `/clear`, `/login` and `/logout` all arrive as a
        // second Connected on this same task, which is the arm that used
        // to leave the row naming the session the user left.
        task.translate_event(connected_event("second-id", "/proj"));
        assert_eq!(
            stored().as_deref(),
            Some("second-id"),
            "so does a replacement, which is the id the next boot has to resume",
        );
    }

    /// `apply_event_to_domain` on `AgentEvent::Connected` stamps (or
    /// overwrites) `session_id` so subsequent `AgentHandle` calls
    /// route to the live identity. See
    /// `translate_second_connected_overwrites_session_id` for the
    /// `/new`-flow overwrite case.
    #[test]
    fn translate_connected_stamps_session_id() {
        let mut domain = empty_domain();
        assert!(domain.session_id.is_none());

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::Connected {
                session_id: "real-uuid-1".to_owned(),
                cwd: "/proj".to_owned(),
                current_model: forge_primitives::CurrentModel {
                    resolved_id: "claude".to_owned(),
                    display_name_short: "claude".to_owned(),
                    display_name_long: "claude".to_owned(),
                    requested_id: None,
                    catalog_id: None,
                    supports_effort: false,
                    supported_effort_levels: Vec::new(),
                    supports_auto_mode: None,
                    supports_adaptive_thinking: None,
                    is_authoritative: true,
                },
                available_models: Vec::new(),
                mode: None,
                history_updates: None,
                compaction_count: 0,
            },
        );

        assert_eq!(
            domain.session_id.as_ref().map(std::string::ToString::to_string),
            Some("real-uuid-1".to_owned())
        );
    }

    /// **The whole chain, not just its two ends.**
    ///
    /// `liveness_of` and `note_liveness` are each pinned, but nothing pinned the
    /// FOLD that joins them - so an edit that called `liveness_of` and dropped
    /// its answer would leave every test green while the header went back to
    /// reading idle through a turn's opening, which is the 41-second window the
    /// mirror exists to close. This drives a real frame through the real fold.
    #[test]
    fn a_thinking_frame_on_the_wire_opens_the_turn() {
        let mut domain = empty_domain();
        assert!(!domain.turn_in_flight(), "precondition: nothing is running");

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::SdkMessage {
                session_id: "s".to_owned(),
                msg: forge_primitives::Message::ThinkingTokens {
                    estimated_tokens: 40,
                    estimated_tokens_delta: 40,
                    uuid: "tokens-1".to_owned(),
                    session_id: "s".to_owned(),
                    extras: serde_json::Map::new(),
                },
            },
        );

        assert!(
            domain.turn_in_flight(),
            "the frame did not reach the liveness mirror, so the header reads idle",
        );
    }

    /// `apply_event_to_domain` on `AgentEvent::ConnectionFailed`
    /// clears the runtime/turn mirrors: the subprocess is gone, so the
    /// in-flight guards must not read a stale "turn in flight".
    #[test]
    fn connection_failed_clears_domain_turn_state() {
        let mut domain = empty_domain();
        domain.runtime_state = Some(forge_primitives::RuntimeSessionState::Running);
        domain.turn_pending = true;

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::ConnectionFailed {
                message: "reader died".to_owned(),
                kind: SpawnFailureKind::Unclassified,
            },
        );

        assert_eq!(domain.runtime_state, None, "runtime_state cleared on ConnectionFailed");
        assert!(!domain.turn_pending, "turn_pending cleared on ConnectionFailed");
    }

    /// The monitor sets these updates announced, in the order they went out.
    fn announced_monitors(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Vec<forge_primitives::MonitorRecord>> {
        let mut announced = Vec::new();
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::MonitorsChanged { monitors, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                announced.push(monitors);
            }
        }
        announced
    }

    /// The task sets these updates announced, in the order they went out.
    fn announced_tasks(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Vec<forge_workspace::BackgroundTask>> {
        let mut announced = Vec::new();
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::BackgroundTasksChanged { tasks, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                announced.push(tasks);
            }
        }
        announced
    }

    /// An assistant frame carrying one tool call, under `parent_tool_use_id`.
    fn assistant_tool_use(
        tool: &str,
        parent_tool_use_id: Option<&str>,
    ) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {
                "id": "msg-dispatch",
                "role": "assistant",
                "model": "claude-sonnet-5",
                "content": [{
                    "type": "tool_use",
                    "id": "tu-dispatch",
                    "name": tool,
                    "input": {"description": "investigate"},
                }],
            },
            "session_id": "s",
            "parent_tool_use_id": parent_tool_use_id,
        }))
        .expect("parse an assistant tool_use")
    }

    /// An assistant frame carrying a `Task` call, which is a dispatch.
    fn dispatch_frame(parent_tool_use_id: Option<&str>) -> forge_primitives::Message {
        assistant_tool_use("Task", parent_tool_use_id)
    }

    /// The card lists a task announced, in order.
    fn announced_cards(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Vec<forge_primitives::runtime::SubagentCard>> {
        let mut announced = Vec::new();
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::SubagentCardsChanged { cards, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                announced.push(cards);
            }
        }
        announced
    }

    /// **The instance list is pushed as it moves.** The card fold rides the
    /// same frame walk that raises the dispatch flag, and the push is
    /// change-gated on the list: the dispatch announces a running card, a
    /// roster frame that moves nothing announces nothing, and the terminal
    /// row announces the settled list.
    #[test]
    fn a_dispatch_announces_a_card_and_the_roster_settles_it() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        task.translate_event(sdk_message(dispatch_frame(None)));
        let announced = announced_cards(&mut updates);
        assert_eq!(announced.len(), 1, "the dispatch announces the list once");
        assert_eq!(announced[0].len(), 1, "with one instance");
        assert!(announced[0][0].running, "running, because nothing has said it ended");
        assert_eq!(announced[0][0].name, "investigate", "named by the dispatch's description");

        // The roster opening the task moves no fact the card draws - it was
        // already running - so the list is equal and nothing is announced.
        task.translate_event(sdk_message(forge_primitives::Message::TaskStarted {
            task_id: "t-a".to_owned(),
            description: "investigate".to_owned(),
            uuid: "u-start".to_owned(),
            session_id: "s".to_owned(),
            tool_use_id: Some("tu-dispatch".to_owned()),
            task_type: Some("local_agent".to_owned()),
            extras: serde_json::Map::new(),
        }));
        assert!(
            announced_cards(&mut updates).is_empty(),
            "a frame that moves no fact on the list announces nothing",
        );

        // The terminal row settles the card, and that IS news.
        task.translate_event(sdk_message(forge_primitives::Message::TaskUpdated {
            task_id: "t-a".to_owned(),
            patch: forge_primitives::messages::TaskUpdatePatch {
                status: Some("completed".to_owned()),
                end_time: Some(1_700_000_000_123),
                extras: serde_json::Map::new(),
            },
            uuid: "u-upd".to_owned(),
            session_id: "s".to_owned(),
            extras: serde_json::Map::new(),
        }));
        let announced = announced_cards(&mut updates);
        assert_eq!(announced.len(), 1, "the ending announces the list once");
        assert!(!announced[0][0].running, "and the card is settled");
        assert_eq!(announced[0][0].ended_at_ms, Some(1_700_000_000_123));
    }

    /// **A sub-agent's refusal names the dispatch it belongs under.**
    ///
    /// The CLI's `permission_denied` frame is session-scoped: it names the
    /// refused call and the sub-agent that made it (`agent_id`, which is the
    /// `task_id` the roster opened the dispatch with) and carries no
    /// `parent_tool_use_id` at all - so the chat drew a sub-agent's refusal as
    /// a row the session itself had made. The transcript keeps no such row, so
    /// a resume draws the refusal from the sub-agent's own sidecar instead,
    /// where it survives as the call's errored result.
    #[test]
    fn a_subagents_refusal_names_the_dispatch_it_belongs_under() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        task.translate_event(sdk_message(agent_call("call-dispatch", None)));
        task.translate_event(sdk_message(forge_primitives::Message::TaskStarted {
            task_id: "agent-1".to_owned(),
            description: "review the fold".to_owned(),
            uuid: "u-start".to_owned(),
            session_id: "s".to_owned(),
            tool_use_id: Some("call-dispatch".to_owned()),
            task_type: Some("local_agent".to_owned()),
            extras: serde_json::Map::new(),
        }));
        task.translate_event(sdk_message(refusal(Some("agent-1"))));

        let drawn = drawn_refusals(&mut updates);
        assert_eq!(drawn.len(), 1, "the refusal is drawn: {drawn:?}");
        assert_eq!(
            drawn[0].get("parent_tool_use_id").and_then(serde_json::Value::as_str),
            Some("call-dispatch"),
            "under the Task call whose instance it refused",
        );

        // **A nested dispatch has no card of its own.** Its `Task` call is a
        // child line of the instance that fired it, so a refusal the nested
        // instance made belongs on that outer row: stamped with the child id
        // it would draw nowhere (measured shape: `spawn_depth: 2`, an `Agent`
        // call under the outer dispatch).
        task.translate_event(sdk_message(agent_call("call-inner", Some("call-dispatch"))));
        task.translate_event(sdk_message(forge_primitives::Message::TaskStarted {
            task_id: "agent-2".to_owned(),
            description: "inner".to_owned(),
            uuid: "u-start-2".to_owned(),
            session_id: "s".to_owned(),
            tool_use_id: Some("call-inner".to_owned()),
            task_type: Some("local_agent".to_owned()),
            extras: {
                let mut extras = serde_json::Map::new();
                extras.insert("spawn_depth".to_owned(), serde_json::Value::from(2));
                extras
            },
        }));
        task.translate_event(sdk_message(refusal(Some("agent-2"))));

        let drawn = drawn_refusals(&mut updates);
        assert_eq!(drawn.len(), 1, "the nested refusal is drawn: {drawn:?}");
        assert_eq!(
            drawn[0].get("parent_tool_use_id").and_then(serde_json::Value::as_str),
            Some("call-dispatch"),
            "on the owning instance's row, not the cardless dispatch it ran under",
        );

        // A task the roster never linked leaves the refusal where it was:
        // over the session, which is a row rather than the silence a stamp
        // naming no card would give it (rule 25).
        task.translate_event(sdk_message(refusal(Some("agent-unknown"))));
        let drawn = drawn_refusals(&mut updates);
        assert_eq!(drawn.len(), 1, "an unplaceable refusal is drawn too");
        assert_eq!(
            drawn[0].get("parent_tool_use_id"),
            None,
            "and an unlinked task's refusal stays the session's own row",
        );

        // A task linked to a call that opened no row at either level is
        // unplaceable too: a stamp naming that call would draw it nowhere.
        task.translate_event(sdk_message(forge_primitives::Message::TaskStarted {
            task_id: "agent-orphan".to_owned(),
            description: "orphan".to_owned(),
            uuid: "u-start-orphan".to_owned(),
            session_id: "s".to_owned(),
            tool_use_id: Some("call-orphan".to_owned()),
            task_type: Some("local_agent".to_owned()),
            extras: serde_json::Map::new(),
        }));
        task.translate_event(sdk_message(refusal(Some("agent-orphan"))));
        let drawn = drawn_refusals(&mut updates);
        assert_eq!(drawn.len(), 1, "an orphaned task's refusal is drawn too");
        assert_eq!(
            drawn[0].get("parent_tool_use_id"),
            None,
            "and it stays the session's own row: no row owns that call",
        );

        task.translate_event(sdk_message(refusal(None)));
        let drawn = drawn_refusals(&mut updates);
        assert_eq!(drawn.len(), 1, "a session's own refusal is drawn too");
        assert_eq!(
            drawn[0].get("parent_tool_use_id"),
            None,
            "and the session's own refusal names no dispatch",
        );
    }

    /// **A frame from an agent three levels down names the card that owns
    /// it.** The wire parents such a frame to the `Agent` call its own parent
    /// fired; that call is a child line one level below the card, and a level
    /// further the frame names that child line rather than a card - so the
    /// frame drew nowhere and the refusal drew at the session's level. The
    /// tracker's parent links walk the chain back to the top-level dispatch on
    /// every frame, which is the expansion that draws it.
    #[test]
    fn a_third_level_agents_frames_name_the_card_that_owns_them() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        // The session's dispatch, the dispatch the first-level agent made
        // under it, and the one the second-level agent made under that.
        task.translate_event(sdk_message(agent_call("call-dispatch", None)));
        task.translate_event(sdk_message(task_started("agent-1", Some("call-dispatch"))));
        task.translate_event(sdk_message(agent_call("call-inner", Some("call-dispatch"))));
        task.translate_event(sdk_message(task_started("agent-2", Some("call-inner"))));
        task.translate_event(sdk_message(agent_call("call-deeper", Some("call-inner"))));
        task.translate_event(sdk_message(task_started("agent-3", Some("call-deeper"))));
        let _ = drain_updates(&mut updates);

        task.translate_event(sdk_message(agent_said(Some("call-deeper"))));
        assert_eq!(
            drawn_frame_parents(&mut updates),
            [Some("call-dispatch".to_owned())],
            "the third-level agent's frame names the card that owns its dispatch",
        );

        task.translate_event(sdk_message(user_result(Some("call-deeper"))));
        task.translate_event(sdk_message(hook_summary(Some("call-deeper"))));
        assert_eq!(
            drawn_frame_parents(&mut updates),
            [Some("call-dispatch".to_owned()), Some("call-dispatch".to_owned())],
            "its tool result and hook summary name the same card",
        );

        task.translate_event(sdk_message(refusal(Some("agent-3"))));
        let drawn = drawn_refusals(&mut updates);
        assert_eq!(drawn.len(), 1, "the third-level refusal is drawn: {drawn:?}");
        assert_eq!(
            drawn[0].get("parent_tool_use_id").and_then(serde_json::Value::as_str),
            Some("call-dispatch"),
            "and it names the card, not the dispatch two levels down",
        );
    }

    /// An assistant frame the agent named by `parent` produced.
    fn agent_said(parent: Option<&str>) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {
                "id": "msg-said",
                "role": "assistant",
                "model": "claude-sonnet-5",
                "content": [{"type": "text", "text": "working"}],
            },
            "session_id": "s",
            "parent_tool_use_id": parent,
        }))
        .expect("an assistant frame")
    }

    /// A tool result the agent named by `parent` produced.
    fn user_result(parent: Option<&str>) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "user",
            "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call", "content": "done"}]},
            "session_id": "s",
            "parent_tool_use_id": parent,
        }))
        .expect("a user frame")
    }

    /// A hook summary the agent named by `parent` fired.
    fn hook_summary(parent: Option<&str>) -> forge_primitives::Message {
        forge_primitives::Message::StopHookSummary {
            actions: 1,
            hook_infos: Vec::new(),
            hook_errors: Vec::new(),
            has_output: false,
            level: "suggestion".to_owned(),
            prevented_continuation: false,
            stop_reason: String::new(),
            tool_use_id: String::new(),
            parent_tool_use_id: parent.map(str::to_owned),
            session_id: "s".to_owned(),
            uuid: "u-hook".to_owned(),
            extras: serde_json::Map::new(),
        }
    }

    /// The parent each frame the task drew carries.
    fn drawn_frame_parents(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Option<String>> {
        drain_updates(updates)
            .into_iter()
            .filter_map(|update| match update {
                SessionUpdate::ChatAppended {
                    msg:
                        forge_primitives::Message::Assistant { parent_tool_use_id, .. }
                        | forge_primitives::Message::User { parent_tool_use_id, .. }
                        | forge_primitives::Message::StopHookSummary { parent_tool_use_id, .. },
                    ..
                } => Some(parent_tool_use_id),
                _ => None,
            })
            .collect()
    }

    /// An `Agent` call: a top-level dispatch opens a card, and one under
    /// `parent` is a child line of the instance that fired it.
    fn agent_call(call: &str, parent: Option<&str>) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {
                "id": "msg-call",
                "role": "assistant",
                "model": "claude-sonnet-5",
                "content": [{
                    "type": "tool_use",
                    "id": call,
                    "name": "Agent",
                    "input": {"description": "dispatch"},
                }],
            },
            "session_id": "s",
            "parent_tool_use_id": parent,
        }))
        .expect("an agent call")
    }

    /// A `permission_denied` frame as the CLI sends it: the refused call, the
    /// agent that made it when a sub-agent did, and never a dispatch.
    fn refusal(agent: Option<&str>) -> forge_primitives::Message {
        let mut frame = serde_json::json!({
            "type": "system",
            "subtype": "permission_denied",
            "tool_name": "Bash",
            "tool_use_id": "call-refused",
            "decision_reason_type": "subcommandResults",
            "message": "Permission to use Bash with command rm -rf /tmp/x has been denied.",
            "uuid": "u-denied",
            "session_id": "s",
        });
        if let Some(agent) = agent {
            frame["agent_id"] = serde_json::Value::String(agent.to_owned());
        }
        serde_json::from_value(frame).expect("a permission_denied frame")
    }

    /// The refusals the task drew, as the wire spells them.
    fn drawn_refusals(updates: &mut mpsc::UnboundedReceiver<SeatUpdate>) -> Vec<serde_json::Value> {
        drain_updates(updates)
            .into_iter()
            .filter_map(|update| match update {
                SessionUpdate::ChatAppended { msg, .. } => Some(msg),
                _ => None,
            })
            .filter(|msg| matches!(msg, forge_primitives::Message::PermissionDenied { .. }))
            .map(|msg| serde_json::to_value(&msg).expect("encode a refusal"))
            .collect()
    }

    /// **A connect seeds the list from its history and announces nothing**,
    /// the same rule the dispatch flag follows: the read on that event
    /// answers it, and a fresh `/new` carries none.
    #[test]
    fn a_connect_seeds_the_cards_without_announcing() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        task.translate_event(AgentEvent::Connected {
            session_id: "resumed-uuid".to_owned(),
            cwd: "/proj".to_owned(),
            current_model: forge_primitives::CurrentModel::new("claude-opus-5", "Opus", "Claude"),
            available_models: Vec::new(),
            mode: None,
            history_updates: Some(vec![dispatch_frame(None)]),
            compaction_count: 0,
        });

        assert_eq!(
            task.domain.lock().cards_snapshot.len(),
            1,
            "a history that dispatched seeds one card",
        );
        assert!(
            announced_cards(&mut updates).is_empty(),
            "and the seed is not announced: the read on this event answers it",
        );

        task.translate_event(AgentEvent::Connected {
            session_id: "new-uuid".to_owned(),
            cwd: "/proj".to_owned(),
            current_model: forge_primitives::CurrentModel::new("claude-opus-5", "Opus", "Claude"),
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        });

        assert!(task.domain.lock().cards_snapshot.is_empty(), "a fresh /new leaves none");
        assert!(announced_cards(&mut updates).is_empty(), "and the clear is not announced");
    }

    /// The command catalogues these updates announced, in the order they went out.
    fn announced_commands(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Vec<forge_primitives::runtime::AvailableCommand>> {
        let mut announced = Vec::new();
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::SlashCommandsChanged { commands, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                announced.push(commands);
            }
        }
        announced
    }

    /// The agent catalogues these updates announced, in the order they went out.
    fn announced_agents(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<Vec<forge_primitives::runtime::AvailableAgent>> {
        let mut announced = Vec::new();
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::SubagentsChanged { subagents, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                announced.push(subagents);
            }
        }
        announced
    }

    /// The `/` menu's catalogue moves on the frames that can move it - a turn's
    /// init and a plugin reload's `commands_changed` - and a frame that leaves
    /// it as it was says nothing.
    ///
    /// **The no-move half is what a turn's init makes necessary.** The CLI
    /// re-fires init every turn, so the case the composer would pay for most
    /// often is the same list again.
    #[test]
    fn a_command_catalogue_that_moved_is_announced() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        task.translate_event(sdk_message(init_frame(&["/help"], &[])));
        let announced = announced_commands(&mut updates);
        assert_eq!(announced.len(), 1, "the init that fills the catalogue announces it");
        assert_eq!(
            announced[0],
            task.domain.lock().available_commands,
            "and what it announces is what the core holds",
        );

        task.translate_event(sdk_message(result_message("success", false)));
        task.translate_event(sdk_message(init_frame(&["/help"], &[])));
        assert_eq!(
            announced_commands(&mut updates).len(),
            0,
            "a turn's init repeating the same list is not a move, so nothing is announced",
        );

        task.translate_event(sdk_message(forge_primitives::Message::CommandsChanged {
            commands: vec![serde_json::json!({"name": "/reload", "description": "Reloaded"})],
            uuid: "cmd-uuid".to_owned(),
            session_id: "s".to_owned(),
            extras: serde_json::Map::new(),
        }));
        let reloaded = announced_commands(&mut updates);
        assert_eq!(reloaded.len(), 1, "the reload's list is a move");
        assert_eq!(reloaded[0], task.domain.lock().available_commands);
    }

    /// The agent catalogue moves on the one frame that carries it, and an init
    /// that advertises what the last turn did says nothing.
    #[test]
    fn an_agent_catalogue_that_moved_is_announced() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        task.translate_event(sdk_message(init_frame(&[], &["reviewer"])));
        let announced = announced_agents(&mut updates);
        assert_eq!(announced.len(), 1, "the init that fills the catalogue announces it");
        assert_eq!(
            announced[0],
            task.domain.lock().available_agents,
            "and what it announces is what the core holds",
        );

        task.translate_event(sdk_message(result_message("success", false)));
        task.translate_event(sdk_message(init_frame(&[], &["reviewer"])));
        assert_eq!(
            announced_agents(&mut updates).len(),
            0,
            "an init repeating the same catalogue is not a move, so nothing is announced",
        );

        task.translate_event(sdk_message(result_message("success", false)));
        task.translate_event(sdk_message(init_frame(&[], &["reviewer", "researcher"])));
        let grown = announced_agents(&mut updates);
        assert_eq!(grown.len(), 1, "an agent the CLI started advertising is a move");
        assert_eq!(grown[0], task.domain.lock().available_agents);
    }

    /// The monitor set moves on discrete task frames, so the frame that moved
    /// it announces the whole set and a frame that moved nothing says nothing.
    ///
    /// **The no-move half is the one worth having.** Every frame here reaches
    /// the fold, and a stamp that repeats an id already stamped must not
    /// redraw every viewer of the seat.
    #[test]
    fn a_monitor_set_that_moved_is_announced() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        // The call that starts a watch enters the set.
        task.translate_event(sdk_message(monitor_tool_use("tu-mon", "ci-watch")));
        let announced = announced_monitors(&mut updates);
        assert_eq!(announced.len(), 1, "the call that starts a watch announces the set");
        assert_eq!(
            announced[0],
            task.domain.lock().monitors,
            "and what it announces is what the core holds",
        );

        // The task id the CLI stamps is a move; the same stamp again is not.
        task.translate_event(sdk_message(task_started("t-mon", Some("tu-mon"))));
        assert_eq!(
            announced_monitors(&mut updates).len(),
            1,
            "stamping the task id moves the set, so it is announced",
        );
        task.translate_event(sdk_message(task_started("t-mon", Some("tu-mon"))));
        assert_eq!(
            announced_monitors(&mut updates).len(),
            0,
            "and a frame that moves nothing says nothing",
        );

        // A STATUS-ONLY change is a move too, and it is the one the shared
        // comparison has to catch on its own: the record's id is untouched,
        // so nothing but the status separates a settle from a repeat.
        task.translate_event(sdk_message(task_updated("t-mon", "completed")));
        let settled = announced_monitors(&mut updates);
        assert_eq!(settled.len(), 1, "settling a monitor announces the settled set");
        assert_eq!(
            settled[0][0].status,
            forge_primitives::MonitorStatus::Completed,
            "with the status the frame gave it",
        );
        task.translate_event(sdk_message(task_updated("t-mon", "completed")));
        assert_eq!(
            announced_monitors(&mut updates).len(),
            0,
            "and the same settle again, on a record already settled, says nothing",
        );

        // The notification is the last frame a monitor sends, and the drain
        // that empties the set is a move like any other.
        task.translate_event(sdk_message(task_notification("t-mon")));
        let drained = announced_monitors(&mut updates);
        assert_eq!(drained.len(), 1, "the drain announces");
        assert!(drained[0].is_empty(), "with the empty set, which is what the core now holds");
    }

    /// The background registry is the CLI's whole set on every change, so a
    /// frame that moved it announces it and one that did not says nothing.
    #[test]
    fn a_background_registry_that_moved_is_announced() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        task.translate_event(sdk_message(background_tasks(one_live_task())));
        let announced = announced_tasks(&mut updates);
        assert_eq!(announced.len(), 1, "the frame that fills the registry announces it");
        assert_eq!(
            announced[0],
            task.domain.lock().task_rows(),
            "and what it announces is what the core holds",
        );

        task.translate_event(sdk_message(background_tasks(one_live_task())));
        assert_eq!(
            announced_tasks(&mut updates).len(),
            0,
            "the same set again is not a move, so nothing is announced",
        );

        // A connection that died leaves nothing standing: a registry that
        // outlived its process spins rows over tasks nobody is running.
        task.translate_event(AgentEvent::ConnectionFailed {
            message: "reader died".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });
        let cleared = announced_tasks(&mut updates);
        assert_eq!(cleared.len(), 1, "and the clear is announced");
        assert!(cleared[0].is_empty(), "with the empty set the core now holds");
    }

    /// The walks these updates announced, in the order they went out.
    fn announced_walks(
        updates: &mut mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<forge_agent::env::processes::ProcessSnapshot> {
        let mut announced = Vec::new();
        while let Ok(frame) = updates.try_recv() {
            if let SessionUpdate::ProcessesChanged { snapshot, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                announced.push(snapshot);
            }
        }
        announced
    }

    /// **A walk that outlives its process draws a tree that is not there.** The
    /// walk describes the subprocess's descendants, and nothing follows a dead
    /// session that would replace it - so the clear is announced on the death
    /// frame like the registry's, rather than left for the next reader to
    /// notice and the next session to overwrite.
    #[test]
    fn a_dead_sessions_walk_is_cleared_and_announced() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::lead("TestOrg", "forge");
        let (mut task, _agent_rx) = command_task_for(&workspace, &slot);
        let mut updates = task.update_tx.subscribe(SubscriberRole::Answering);

        let walk = || forge_agent::env::processes::ProcessSnapshot {
            processes: vec![forge_agent::env::processes::ProcessEntry {
                pid: 4242,
                parent_pid: 1,
                name: "claude".to_owned(),
                command: "claude".to_owned(),
                memory_bytes: 1,
            }],
            scanned_at: std::time::SystemTime::now(),
        };
        task.domain.lock().process_snapshot = Some(walk());

        // A frame that does not end the run leaves the walk exactly where the
        // seat's own loop put it.
        task.translate_event(sdk_message(background_tasks(one_live_task())));
        assert!(
            announced_walks(&mut updates).is_empty(),
            "a frame that did not end the run announces no walk",
        );
        assert!(task.domain.lock().process_snapshot.is_some(), "and clears none");

        task.translate_event(AgentEvent::ConnectionFailed {
            message: "reader died".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });

        let cleared = announced_walks(&mut updates);
        assert_eq!(cleared.len(), 1, "the death announces the walk's clear");
        assert!(cleared[0].processes.is_empty(), "with the empty walk the core now holds");
        assert!(
            task.domain.lock().process_snapshot.is_none(),
            "and the store is cleared, so a read answers null rather than a dead tree",
        );
    }

    /// **The fold is the only place a repository frame becomes a nudge.** The
    /// work tests drive `note_repository_activity` and
    /// `note_code_change_published` directly, so a missing arm, a swapped
    /// flag, or a deleted block would leave them green while the wiring did
    /// nothing.
    #[test]
    fn repository_frames_ask_for_the_nudge_they_need() {
        let mut domain = empty_domain();

        let vcs = apply_event_to_domain(
            &mut domain,
            &sdk_message(forge_primitives::Message::VcsStateChanged {
                kind: "commit".to_owned(),
                branch: Some("main".to_owned()),
                cwd: "/tmp/repo".to_owned(),
                uuid: "u1".to_owned(),
                session_id: "s".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            }),
        );
        assert_eq!(vcs.repo_nudge, Some(false), "a mutation re-reads the tree only");

        let published = apply_event_to_domain(
            &mut domain,
            &sdk_message(forge_primitives::Message::CodeChangePublished {
                provider: "github".to_owned(),
                url: "https://example.test/pull/1".to_owned(),
                repo: "a/b".to_owned(),
                identifier: "1".to_owned(),
                action: Some("created".to_owned()),
                branch: Some("main".to_owned()),
                uuid: "u2".to_owned(),
                session_id: "s".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            }),
        );
        assert_eq!(published.repo_nudge, Some(true), "a published change also looks the PR up");

        let other = apply_event_to_domain(
            &mut domain,
            &sdk_message(forge_primitives::Message::System {
                subtype: "init".to_owned(),
                session_id: Some("s".to_owned()),
                data: serde_json::json!({}),
            }),
        );
        assert_eq!(other.repo_nudge, None, "every other event asks for neither");
    }

    /// **The flag is only half the wiring.** The fallback above proves the fold
    /// answers *what*; this pins the call that acts on the answer, because
    /// deleting the block that reads it leaves every other test green. A
    /// published frame clears the attempt stamp on the seat's stored snapshot
    /// through the task's own workspace handle.
    #[test]
    fn a_published_frame_clears_the_stored_pr_attempt_through_the_task() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let slot = SessionSlot::from_str_for_test("test");
        let (handle, _agent_cmds) = Agent::testing_stub();
        let arc = Arc::new(handle);
        let domain = workspace.register_domain_session(slot.clone(), Some(Arc::clone(&arc)));
        domain.lock().work_snapshot = Some(crate::work::WorkSnapshot {
            diff: forge_primitives::git_diff::GitDiffSnapshot {
                branch: forge_primitives::git::GitBranch::Detached,
                pushed_sha: None,
                pr_fetched_at: Some(std::time::SystemTime::now()),
                default_branch: None,
                repo_gate: forge_primitives::git_diff::RepoGate::InRepo,
                worktree: forge_primitives::git_diff::LayerState::Clean,
                branch_ahead: forge_primitives::git_diff::LayerState::Clean,
                pr: None,
                closes: Vec::new(),
            },
            cwd: std::path::PathBuf::from("/tmp/repo"),
            read_at: std::time::Instant::now(),
            base: None,
            base_at: None,
            base_error: None,
        });

        let (_cmd_tx, command_rx) = tokio::sync::mpsc::unbounded_channel();
        let mut task = SessionTask {
            key: slot.clone(),
            handle: arc,
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: std::sync::Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(sdk_message(forge_primitives::Message::CodeChangePublished {
            provider: "github".to_owned(),
            url: "https://example.test/pull/1".to_owned(),
            repo: "a/b".to_owned(),
            identifier: "1".to_owned(),
            action: Some("created".to_owned()),
            branch: Some("main".to_owned()),
            uuid: "u2".to_owned(),
            session_id: "s".to_owned(),
            extras: forge_primitives::messages::Extras::new(),
        }));

        assert!(
            domain
                .lock()
                .work_snapshot
                .as_ref()
                .is_some_and(|held| held.diff.pr_fetched_at.is_none()),
            "the frame's nudge reached the workspace that clears the attempt",
        );
    }

    /// A monitor still running when the connection dies can never be settled,
    /// and the session page reads this set directly through the view surface,
    /// so a dead one draws as live on both surfaces until the next connect
    /// replaces it.
    #[test]
    fn connection_failed_drops_the_domain_monitor_set() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-mon", "ci-watch")));
        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-mon", Some("tu-mon"))));
        assert_eq!(domain.monitors.len(), 1, "the monitor is seeded before the failure");
        assert_eq!(
            domain.monitors[0].status,
            forge_primitives::MonitorStatus::Running,
            "and it is still running, which is what makes it unsettleable",
        );

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::ConnectionFailed {
                message: "reader died".to_owned(),
                kind: SpawnFailureKind::Unclassified,
            },
        );

        assert!(
            domain.monitors.is_empty(),
            "the run's monitor set does not outlive the run that held it",
        );
    }

    /// A second `Connected` is a new occupant in the same slot, and it
    /// inherits nothing the previous one held: `background_tasks_changed`
    /// is not re-sent for a session that has not started one, so a
    /// registry left standing would have a row spin over a task nobody is
    /// running until a real snapshot arrives.
    #[test]
    fn a_second_connected_drops_background_work() {
        let mut domain = empty_domain();
        domain.background_work = true;

        apply_event_to_domain(&mut domain, &connected_event("new-uuid", "/proj"));

        assert!(
            !domain.background_work,
            "a replaced occupant's background work must not survive it",
        );
    }

    /// A second `Connected` (`/new`, `/login`, `/logout`) overwrites
    /// the session_id mirror so subsequent user commands route to the
    /// new identity.
    #[test]
    fn translate_second_connected_overwrites_session_id() {
        let mut domain = empty_domain();
        domain.session_id = Some(SessionId::new("old-uuid"));

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::Connected {
                session_id: "new-uuid".to_owned(),
                cwd: "/proj".to_owned(),
                current_model: forge_primitives::CurrentModel {
                    resolved_id: "claude".to_owned(),
                    display_name_short: "claude".to_owned(),
                    display_name_long: "claude".to_owned(),
                    requested_id: None,
                    catalog_id: None,
                    supports_effort: false,
                    supported_effort_levels: Vec::new(),
                    supports_auto_mode: None,
                    supports_adaptive_thinking: None,
                    is_authoritative: true,
                },
                available_models: Vec::new(),
                mode: None,
                history_updates: None,
                compaction_count: 0,
            },
        );

        assert_eq!(
            domain.session_id.as_ref().map(std::string::ToString::to_string),
            Some("new-uuid".to_owned()),
            "second Connected must overwrite session_id mirror",
        );
    }

    /// `SessionTask::translate_event` on a second `Connected`
    /// (`connected_once = true`) drains `pending_interactions` so
    /// forwarder tasks parked on the previous identity's
    /// tool_call_ids exit instead of waiting forever.
    #[test]
    fn translate_second_connected_drains_pending_interactions() {
        use tokio::sync::oneshot;

        let (handle, _commands_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = UpdateFanout::default();
        let mut update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let domain = Arc::new(parking_lot::Mutex::new(empty_domain()));
        let (response_tx, mut response_rx) =
            oneshot::channel::<forge_primitives::PermissionOutcome>();
        domain.lock().pending_interactions.insert(
            "stale_tool_id".to_owned(),
            crate::workspace::testing::test_permission(response_tx),
        );
        let mut task = SessionTask {
            key: SessionSlot::from_str_for_test("old-uuid"),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: true,
            workspace: std::sync::Weak::new(),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::Connected {
            session_id: "new-uuid".to_owned(),
            cwd: "/proj".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        });

        assert!(
            domain.lock().pending_interactions.is_empty(),
            "second Connected must clear stale pending_interactions",
        );
        assert!(
            matches!(
                response_rx.try_recv(),
                Err(tokio::sync::oneshot::error::TryRecvError::Closed)
            ),
            "forwarder receiver must observe Closed after the sender was dropped"
        );
        // The drop is announced, or a view drawing a dock from the request
        // it folded keeps offering a prompt the core has let go, and every
        // click on it reaches nothing.
        let announced: Vec<String> = std::iter::from_fn(|| update_rx.try_recv().ok())
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::PendingInteractionResolved { key, tool_id, .. } => {
                    assert_eq!(key, SessionSlot::from_str_for_test("old-uuid"));
                    Some(tool_id)
                }
                _ => None,
            })
            .collect();
        assert_eq!(
            announced,
            vec!["stale_tool_id".to_owned()],
            "a dropped prompt is announced with its own tool id",
        );
    }

    /// First-Connected drains the slot's parked peer prompts in FIFO
    /// order, dispatching one `Command::Prompt` per parked entry, then
    /// leaves the bucket empty. Pinned via the workspace's
    /// command-intercept buffer so the full first-Connected branch of
    /// `translate_event` runs end-to-end (no poking the private drain
    /// method directly).
    #[tokio::test]
    async fn first_connected_drains_parked_peer_prompts_in_fifo_order() {
        use crate::mcp::peers::types::{MessageId, WrappedKind, WrappedPrompt};

        let (workspace, _update_rx) = crate::Workspace::testing_stub();
        let sender = SessionSlot::from_str_for_test("sender-proj");

        // Park three Messages for the task's slot in known order.
        let session_key = test_slot();
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let bodies = ["first", "second", "third"];
        for body in bodies {
            workspace.park_peer_prompt(
                &session_key,
                &sender,
                WrappedPrompt {
                    id: MessageId::mint(),
                    kind: WrappedKind::Message,
                    sender_name: "forge".to_owned(),
                    sender_org: "Default".to_owned(),
                    body: body.to_owned(),
                },
            );
        }

        // connected_once=false → first-Connected arm that drains the
        // parked buckets. The drain resolves against the task's own slot,
        // so the test doesn't have to register against the workspace pool.
        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        workspace.enable_test_dispatch_intercept();
        task.translate_event(AgentEvent::Connected {
            session_id: session_key.display(),
            cwd: "/tmp/drain".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        });

        // Drain dispatches Command::Prompt for each buffered entry,
        // in insertion order. Filter out anything else in case
        // translate_event grows side-effects later.
        let buffered = workspace.drain_test_dispatch_buffer();
        let drained_bodies: Vec<String> = buffered
            .into_iter()
            .filter_map(|cmd| match cmd {
                crate::protocol::Command::Prompt { text, .. }
                | crate::protocol::Command::PromptUnder { text, .. } => Some(text),
                _ => None,
            })
            .collect();
        assert_eq!(
            drained_bodies.len(),
            bodies.len(),
            "one Command::Prompt per buffered wrapped prompt"
        );
        for (i, expected_body) in bodies.iter().enumerate() {
            assert!(
                drained_bodies[i].contains(expected_body),
                "drain position {i}: expected body '{expected_body}' in dispatched text '{}'",
                drained_bodies[i],
            );
        }
        assert!(
            workspace.take_parked_for_slot(&session_key).peer.is_empty(),
            "the parked peer prompts are drained after first-Connected"
        );
    }

    /// One Slack message, shaped as a delivery buffers it.
    fn buffered_slack(text: &str) -> forge_primitives::slack::SlackMessage {
        forge_primitives::slack::SlackMessage {
            workspace: "acme".to_owned(),
            conversation: "D1".to_owned(),
            conversation_label: "U9".to_owned(),
            ts: "100.000001".to_owned(),
            thread_ts: None,
            user: Some("U9".to_owned()),
            author: None,
            text: text.to_owned(),
            parent_user_id: None,
            latest_reply: None,
            edited: None,
            files: Vec::new(),
        }
    }

    fn connected_event(session_id: &str, cwd: &str) -> AgentEvent {
        AgentEvent::Connected {
            session_id: session_id.to_owned(),
            cwd: cwd.to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        }
    }

    fn cron_worker_entry(
        label: &str,
        slot: crate::SessionSlot,
    ) -> crate::mcp::workers::types::WorkerEntry {
        crate::mcp::workers::types::WorkerEntry {
            label: label.to_owned(),
            charter: "c".to_owned(),
            spawned_by: crate::SessionSlot::lead(slot.org(), slot.project()),
            slot,
            session_id: None,
            status: forge_primitives::WorkerLiveness::Running,
            spawned_at: std::time::SystemTime::UNIX_EPOCH,
            needs_tag: false,
            is_git_repo_at_spawn: false,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    /// A cron entry carrying what a park reads: the id, the prompt and a
    /// description.
    fn test_cron(id: &str, prompt: &str) -> forge_primitives::cron::CronEntry {
        use forge_primitives::cron::{CronEntry, CronId, CronKind};
        CronEntry {
            id: CronId::from(id),
            project_name: "cron-drain".to_owned(),
            kind: CronKind::Recurring("0 9 * * *".to_owned()),
            prompt: prompt.to_owned(),
            created_at: std::time::SystemTime::UNIX_EPOCH,
            description: Some(format!("{id} summary")),
            last_fire: None,
            next_fire: std::time::SystemTime::UNIX_EPOCH,
            team_role: None,
            wake: true,
        }
    }

    /// First-Connected drains the session slot's buffered cron prompts:
    /// each dispatches a plain `Command::Prompt` AND echoes a
    /// `CronPromptAppended` so an asleep-fired cron shows its block once the
    /// session connects (mirrors the gotify drain echo). Reproduce-first:
    /// the echo is absent until the drain calls `push_cron_prompt_into_chat`.
    #[tokio::test]
    async fn first_connected_drains_pending_cron_prompts_and_echoes_block() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        workspace.seed_test_project("cron-drain", "/tmp/cron-drain");
        // The slot production derives for the seeded project, and the
        // bucket the drain reads.
        let session_key = SessionSlot::lead("TestOrg", "cron-drain");
        workspace.park_cron(&session_key, &test_cron("c1", "morning reminder"), false);

        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));

        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        workspace.enable_test_dispatch_intercept();
        task.translate_event(connected_event(&session_key.display(), "/tmp/cron-drain"));

        // The buffered cron prompt is dispatched as a plain user turn.
        let buffered = workspace.drain_test_dispatch_buffer();
        assert!(
            buffered.iter().any(|c| matches!(
                c, crate::protocol::Command::Prompt { text, .. }
                    | crate::protocol::Command::PromptUnder { text, .. }
                    if text == "morning reminder"
            )),
            "the buffered cron prompt is dispatched on first-Connected",
        );

        // AND an echo lands so the drained prompt shows a cron block, naming
        // the entry the parked fire came from - the bucket is the only place
        // that identity survives an asleep fire.
        let mut echoed = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::CronPromptAppended { key, text, cron_id, description, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && key == session_key
                && text == "morning reminder"
            {
                echoed = Some((cron_id, description));
            }
        }
        let (cron_id, description) =
            echoed.expect("an asleep-fired cron echoes a CronPromptAppended on drain");
        assert_eq!(cron_id, "c1", "the drained echo names the entry that fired");
        assert_eq!(description.as_deref(), Some("c1 summary"), "and its description");

        assert!(
            workspace.take_parked_for_slot(&session_key).cron.is_empty(),
            "the slot's cron bucket is drained after first-Connected",
        );
    }

    /// A worker session drains only its OWN `(project, label)` cron bucket
    /// on first Connect - the lead's bucket stays buffered - and a missed
    /// entry's `[missed cron] ` marker survives the buffer -> drain into the
    /// dispatched prompt (the asleep/drain missed path, distinct from the
    /// live-fire path).
    #[tokio::test]
    async fn worker_first_connected_drains_its_own_bucket_with_missed_marker() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        workspace.seed_test_project("wdp", "/tmp/wdp");
        let key =
            workspace.list_projects().into_iter().find(|v| v.name == "wdp").expect("view").key;

        // A missed cron for the worker + an on-time lead cron for the project.
        let worker_slot = crate::SessionSlot::worker("TestOrg", "wdp", "reviewer");
        let lead_slot = crate::SessionSlot::lead("TestOrg", "wdp");
        workspace.insert_live_worker(&key, cron_worker_entry("reviewer", worker_slot.clone()));
        workspace.park_cron(&worker_slot, &test_cron("c-worker", "worker work"), true);
        workspace.park_cron(&lead_slot, &test_cron("c-lead", "lead work"), false);

        let session_key = worker_slot.clone();
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        workspace.enable_test_dispatch_intercept();
        task.translate_event(connected_event(&worker_slot.display(), "/tmp/wdp"));

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|c| matches!(
                c, crate::protocol::Command::Prompt { key, text, .. }
                    | crate::protocol::Command::PromptUnder { key, text, .. }
                    if *key == session_key && text == "[missed cron] worker work"
            )),
            "the worker drains its own missed cron with the marker applied",
        );
        // The lead's bucket is untouched by the worker's drain.
        let lead_bucket = workspace.take_parked_for_slot(&lead_slot).cron;
        assert_eq!(lead_bucket.len(), 1, "the lead's cron stays buffered");
        assert_eq!(lead_bucket[0].text, "lead work");
    }

    /// Every echo in a multi-fire bucket names its OWN entry: the bucket
    /// holds one entry per due cron, so an identity read once for the
    /// bucket - the shape the loop's surrounding arguments invite - would
    /// print the first schedule on every row. Sorted rather than
    /// positional, so this does not pin drain order.
    #[tokio::test]
    async fn a_drain_names_each_entry_in_a_multi_fire_bucket() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        workspace.seed_test_project("cron-drain", "/tmp/cron-drain");
        let session_key = SessionSlot::lead("TestOrg", "cron-drain");
        workspace.park_cron(&session_key, &test_cron("c1", "morning reminder"), false);
        workspace.park_cron(&session_key, &test_cron("c2", "worker digest"), true);
        // A once-off registered without a description: the reply's own
        // contract says the key is null then, and the row falls back to the
        // prompt's first line.
        let mut bare = test_cron("c3", "check the queue");
        bare.description = None;
        workspace.park_cron(&session_key, &bare, false);

        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        workspace.enable_test_dispatch_intercept();
        task.translate_event(connected_event(&session_key.display(), "/tmp/cron-drain"));

        let mut heard: Vec<(String, String, Option<String>)> = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::CronPromptAppended { key, text, cron_id, description, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && key == session_key
            {
                heard.push((text, cron_id, description));
            }
        }
        heard.sort();
        assert_eq!(
            heard,
            vec![
                (
                    "[missed cron] worker digest".to_owned(),
                    "c2".to_owned(),
                    Some("c2 summary".to_owned())
                ),
                ("check the queue".to_owned(), "c3".to_owned(), None),
                ("morning reminder".to_owned(), "c1".to_owned(), Some("c1 summary".to_owned())),
            ],
            "each echo carries its own entry's identity, and a missing description stays null",
        );
    }

    /// **A resumed connect hands the WINDOW on, not the read.**
    ///
    /// `history_updates` is a resume's whole transcript - 51,274 rows and
    /// 2.5GiB on the seat #2150 was filed from - and the connect used to pass
    /// it on whole. The update is what the transport's copy is seeded from and
    /// what every subscriber takes a clone of, so the read was paid again per
    /// subscriber to hand over what each of them cuts to a window anyway. The
    /// update carries the cut window on both routes a resumed identity takes
    /// in.
    #[tokio::test]
    async fn a_resumed_connect_hands_the_window_not_the_whole_read() {
        let cap = crate::conversation_window::CONVERSATION_CAP;
        let slack = crate::conversation_window::CONVERSATION_SLACK;
        let read = cap + slack + 1;

        // Both routes a connect takes: the first one, and the replacement a
        // `/new` or a `/resume` takes on a task that has connected once.
        for connected_once in [false, true] {
            let (workspace, mut update_rx) = crate::Workspace::testing_stub();
            let session_key = SessionSlot::from_str_for_test("handover-window-uuid");
            let domain =
                Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
            let (handle, _agent_cmd_rx) = Agent::testing_stub();
            let (_cmd_tx, command_rx) =
                tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
            let mut task = SessionTask {
                key: session_key.clone(),
                handle: Arc::new(handle),
                command_rx,
                domain,
                update_tx: workspace.update_sender(),
                connected_once,
                workspace: Arc::downgrade(&workspace),
                compaction_count: 0,
                successor: None,
                teardown_done: None,
            };
            let frame = |at: usize| {
                serde_json::from_value::<forge_primitives::Message>(serde_json::json!({
                    "type": "user",
                    "message": {"role": "user", "content": format!("frame {at}")},
                    "session_id": session_key.display(),
                }))
                .expect("a user frame")
            };
            let mut event = connected_event(&session_key.display(), "/tmp/handed-over");
            if let AgentEvent::Connected { history_updates, .. } = &mut event {
                *history_updates = Some((0..read).map(frame).collect());
            }
            task.translate_event(event);

            let mut handed = None;
            while let Ok(frame) = update_rx.try_recv() {
                match std::sync::Arc::unwrap_or_clone(frame.update) {
                    SessionUpdate::Connected { history, dropped, .. }
                    | SessionUpdate::SessionReplaced { history, dropped, .. } => {
                        handed = Some((history, dropped));
                    }
                    _ => {}
                }
            }
            let (handed, cut) = handed.expect("a connect crosses as Connected or SessionReplaced");
            assert!(
                (cap..=cap + slack).contains(&handed.len()),
                "the update hands over the window the task keeps, not the read: {} messages of \
                 the {read} the connect carried (connected_once: {connected_once})",
                handed.len(),
            );
            assert_eq!(
                cut,
                read - handed.len(),
                "and the cut the window left behind rides with it: a consumer holding the window \
                 alone reads its front as the conversation's, so a walk below it would stop \
                 there instead of crossing into the transcript (connected_once: {connected_once})",
            );
            assert!(
                handed.last().is_some_and(|message| {
                    matches!(message, forge_primitives::Message::User { message, .. }
                        if message.content.iter().any(|block| matches!(block,
                            forge_primitives::ContentBlock::Text { text, .. }
                                if text == &format!("frame {}", read - 1))))
                }),
                "and it is the NEWEST window rather than the oldest: the transcript's own tail",
            );
        }
    }

    /// **A handover's cut rides the frames as thinking debt.** A resume hands
    /// the window to the update stream with no page to fold into, so the first
    /// counter the newest turn carries absorbs what the cut took - else a
    /// thought-heavy turn resumes showing only the surviving suffix.
    #[tokio::test]
    async fn a_resumed_connect_folds_the_cut_thinking_into_the_window() {
        let read = 5_100;
        for connected_once in [false, true] {
            let (workspace, mut update_rx) = crate::Workspace::testing_stub();
            let session_key = SessionSlot::from_str_for_test("handover-thinking-uuid");
            let domain =
                Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
            let (handle, _agent_cmd_rx) = Agent::testing_stub();
            let (_cmd_tx, command_rx) =
                tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
            let mut task = SessionTask {
                key: session_key.clone(),
                handle: Arc::new(handle),
                command_rx,
                domain,
                update_tx: workspace.update_sender(),
                connected_once,
                workspace: Arc::downgrade(&workspace),
                compaction_count: 0,
                successor: None,
                teardown_done: None,
            };
            let counter = |at: usize| {
                serde_json::from_value::<forge_primitives::Message>(serde_json::json!({
                    "type": "system",
                    "subtype": "thinking_tokens",
                    "estimated_tokens": 1,
                    "estimated_tokens_delta": 1,
                    "uuid": format!("t-{at}"),
                    "session_id": session_key.display(),
                }))
                .expect("a counter frame")
            };
            let mut history = vec![
                serde_json::from_value::<forge_primitives::Message>(serde_json::json!({
                    "type": "user",
                    "message": {"role": "user", "content": "the thought-heavy turn"},
                    "session_id": session_key.display(),
                }))
                .expect("a user frame"),
            ];
            history.extend((0..read).map(counter));
            let mut event = connected_event(&session_key.display(), "/tmp/handed-over");
            if let AgentEvent::Connected { history_updates, .. } = &mut event {
                *history_updates = Some(history);
            }
            task.translate_event(event);

            let mut handed = None;
            while let Ok(frame) = update_rx.try_recv() {
                match std::sync::Arc::unwrap_or_clone(frame.update) {
                    SessionUpdate::Connected { history, .. }
                    | SessionUpdate::SessionReplaced { history, .. } => {
                        handed = Some(history);
                    }
                    _ => {}
                }
            }
            let handed = handed.expect("a connect crosses as Connected or SessionReplaced");
            let sum: i64 = handed
                .iter()
                .filter_map(|message| match message {
                    forge_primitives::Message::ThinkingTokens {
                        estimated_tokens_delta, ..
                    } => Some(*estimated_tokens_delta),
                    _ => None,
                })
                .sum();
            assert_eq!(
                sum,
                i64::try_from(read).expect("the test's count fits"),
                "the handover carries the whole turn, not the suffix (connected_once: \
                 {connected_once})",
            );
        }
    }

    /// The count has coverage at both ends - the scan produces it, the
    /// client reads it - and this is the layer in between. Both emitted
    /// arms are checked because a task that has connected before emits
    /// `SessionReplaced` instead of `Connected`, and forcing the field to
    /// zero on either one is invisible to every other test here.
    #[tokio::test]
    async fn translate_event_carries_a_non_zero_compaction_count_on_both_arms() {
        for (connected_once, arm) in [(false, "Connected"), (true, "SessionReplaced")] {
            let (workspace, mut update_rx) = crate::Workspace::testing_stub();
            let session_key = SessionSlot::from_str_for_test("count-through-uuid");
            let domain =
                Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
            let (handle, _agent_cmd_rx) = Agent::testing_stub();
            let (_cmd_tx, command_rx) =
                tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
            let mut task = SessionTask {
                key: session_key.clone(),
                handle: Arc::new(handle),
                command_rx,
                domain: Arc::clone(&domain),
                update_tx: workspace.update_sender(),
                connected_once,
                workspace: Arc::downgrade(&workspace),
                compaction_count: 0,
                successor: None,
                teardown_done: None,
            };

            let mut event = connected_event(&session_key.display(), "/tmp/count");
            if let AgentEvent::Connected { compaction_count, .. } = &mut event {
                *compaction_count = 7;
            }
            task.translate_event(event);

            let mut seen = None;
            while let Ok(frame) = update_rx.try_recv() {
                match std::sync::Arc::unwrap_or_clone(frame.update) {
                    SessionUpdate::Connected { compaction_count, .. }
                    | SessionUpdate::SessionReplaced { compaction_count, .. } => {
                        seen = Some(compaction_count);
                    }
                    _ => {}
                }
            }
            assert_eq!(seen, Some(7), "{arm} must carry the count through unchanged");
        }
    }

    /// A resumed conversation carries its sub-agent frames to the page: they
    /// are the dispatch row's expansion, and the card fold must open a card
    /// for an instance whose sidecar settled every call even though its only
    /// dispatch answer is the launch acknowledgement (#1763).
    #[tokio::test]
    async fn subagent_frames_ride_the_connected_history() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        let session_key = SessionSlot::from_str_for_test("sidecar-chat-uuid");
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        let dispatch = serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {"id": "msg_1", "type": "message", "role": "assistant",
                "model": "claude-sonnet-5", "content": [
                {"type": "tool_use", "id": "toolu_a", "name": "Agent",
                 "input": {"prompt": "explore"}}
            ]},
            "session_id": "sidecar-chat",
            "uuid": "a1",
        }))
        .expect("the dispatch decodes");
        let child = serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {"id": "msg_2", "type": "message", "role": "assistant",
                "model": "claude-sonnet-5", "content": [
                {"type": "tool_use", "id": "toolu_child", "name": "Bash",
                 "input": {"command": "ls"}}
            ]},
            "parent_tool_use_id": "toolu_a",
            "session_id": "sidecar-chat",
            "uuid": "c1",
        }))
        .expect("the sub-agent frame decodes");
        let dispatch_ack = serde_json::from_value(serde_json::json!({
            "type": "user",
            "message": {"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": "toolu_a",
                 "content": "Async agent launched successfully"}
            ]},
            "session_id": "sidecar-chat",
            "uuid": "u1",
        }))
        .expect("the dispatch ack decodes");
        let child_result = serde_json::from_value(serde_json::json!({
            "type": "user",
            "message": {"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": "toolu_child", "content": "total 0"}
            ]},
            "session_id": "sidecar-chat",
            "uuid": "u2",
        }))
        .expect("the child result decodes");
        let mut event = connected_event("sidecar-chat", "/tmp/sidecar");
        if let AgentEvent::Connected { history_updates, .. } = &mut event {
            *history_updates = Some(vec![dispatch, dispatch_ack, child, child_result]);
        }

        task.translate_event(event);

        let mut history_len = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::Connected { history, .. } = &*frame.update {
                history_len = Some(history.len());
            }
        }
        assert_eq!(history_len, Some(4), "the sub-agent frames ride the page as the row expansion");
        let cards = domain.lock().cards_snapshot.clone();
        assert_eq!(cards.len(), 1, "the folded instance gets its card");
        assert_eq!(cards[0].calls, 1, "and its call is the card's");
        assert!(
            !cards[0].running,
            "every sidecar call settled means the instance is settled, not hidden",
        );
    }

    /// **The worktree check runs before the first connect's side effects.**
    /// A git worker whose worktree is gone must not be announced live,
    /// kicked, or handed its parked prompts, because the failure then
    /// releases the session those prompts were dispatched into (#1593).
    ///
    /// **The path composes from the row's root, never the connect cwd.** A
    /// resumed worker connects with its worktree as cwd, so composing from
    /// that asked about `<worktree>/.claude/worktrees/<label>` and named the
    /// doubled path in the reason.
    #[tokio::test]
    async fn a_git_worker_without_a_worktree_is_failed_before_the_first_connect_effects() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        let session_key = SessionSlot::worker("TestOrg", "proj-x", "builder");
        let project_key = crate::ProjectKey::new("proj-x");
        let root = tempfile::tempdir().expect("root");
        let worktree = root.path().join(".claude/worktrees/builder");
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "builder".to_owned(),
                charter: "charter".to_owned(),
                slot: session_key.clone(),
                session_id: Some(forge_primitives::SessionId::new("builder-session")),
                status: forge_primitives::WorkerLiveness::Spawning,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::lead("TestOrg", "proj-x"),
                needs_tag: true,
                is_git_repo_at_spawn: true,
                cwd: Some(root.path().to_path_buf()),
                diagnostic: None,
                kick: None,
            },
        );
        let (handle, _commands) = Agent::testing_stub();
        let handle = Arc::new(handle);
        workspace.pool.lock().insert(
            session_key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&handle),
                account: forge_gateway::AccountKey("acct-a".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "builder-session".to_owned(),
            },
        );
        let (commands, mut routed) = tokio::sync::mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(session_key.clone(), commands);
        let (_task_tx, task_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let mut task = SessionTask {
            key: session_key.clone(),
            handle,
            command_rx: task_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        // A resumed worker's connect cwd is already its worktree.
        let alive =
            task.translate_event(connected_event("builder-session", &worktree.to_string_lossy()));

        assert!(!alive, "the task stops rather than continue on a failed worker");
        let mut connected = false;
        while let Ok(frame) = update_rx.try_recv() {
            if matches!(&*frame.update, SessionUpdate::Connected { .. }) {
                connected = true;
            }
        }
        assert!(!connected, "the dead worker is never announced live");
        assert!(routed.try_recv().is_err(), "and nothing is dispatched into its session");
        let entry = workspace
            .list_live_workers(&project_key)
            .into_iter()
            .find(|entry| entry.label == "builder")
            .expect("the row stays as the visible failure");
        assert_eq!(entry.status, forge_primitives::WorkerLiveness::Failed);
        let reason = entry.diagnostic.expect("the row names the missing worktree");
        let worktree = worktree.display().to_string();
        assert!(reason.contains(&worktree), "the row names the worktree: {reason}");
        assert!(
            !reason.contains("builder/.claude/worktrees/builder"),
            "the reason is not the connect cwd composed a second time: {reason}",
        );
        assert!(
            !workspace.session_is_pooled(&session_key),
            "and the session is released with the failure",
        );
    }

    /// A compaction boundary moves the task's count, which is the handoff
    /// policy's `after_compactions` backstop.
    ///
    /// **The count has two sources and both must land on one scalar**: the
    /// connect seeds it from the transcript it resumed, and a boundary frame
    /// the session emits after it moves it. A store that kept only the
    /// connect's number would report the count from before every compaction
    /// since.
    #[tokio::test]
    async fn a_compaction_boundary_moves_the_tasks_count() {
        let (workspace, _update_rx) = crate::Workspace::testing_stub();
        let session_key = SessionSlot::from_str_for_test("compaction-count-uuid");
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain,
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        let mut event = connected_event(&session_key.display(), "/tmp/count");
        if let AgentEvent::Connected { compaction_count, .. } = &mut event {
            *compaction_count = 4;
        }
        task.translate_event(event);
        assert_eq!(task.compaction_count, 4, "a resumed connect seeds the count it carries");

        task.translate_event(AgentEvent::SdkMessage {
            session_id: session_key.display(),
            msg: forge_primitives::Message::CompactBoundary {
                trigger: "auto".to_owned(),
                pre_tokens: 1,
                post_tokens: 1,
                uuid: "c1".to_owned(),
                session_id: session_key.display(),
                metadata_extras: serde_json::Map::new(),
                extras: serde_json::Map::new(),
            },
        });
        assert_eq!(task.compaction_count, 5, "and the boundary the session emits moves it");
    }

    /// A re-spawn that replaces the session seeds `connected_once =
    /// true`, so the new task's first Connected emits `SessionReplaced`
    /// (not a fresh Connected) carrying the resumed history. A view's
    /// reducer resets the chat then re-seeds it from that history, so
    /// the same conversation stays visible across the replacement.
    #[tokio::test]
    async fn connected_once_seed_emits_session_replaced_with_resumed_history() {
        use forge_primitives::Message;

        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        let session_key = SessionSlot::from_str_for_test("replacement-visible-uuid");
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));

        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx,
            // The seed a session-replacing re-spawn installs.
            connected_once: true,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        // A one-message resumed history (the --resume backfill).
        let history = vec![Message::System {
            subtype: "info".to_owned(),
            session_id: Some(session_key.display()),
            data: serde_json::json!({ "body": "earlier turn" }),
        }];

        task.translate_event(AgentEvent::Connected {
            session_id: session_key.display(),
            cwd: "/tmp/respawn".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: Some(history),
            compaction_count: 0,
        });

        let mut replaced_history_len = None;
        let mut saw_plain_connected = false;
        while let Ok(frame) = update_rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::SessionReplaced { key, history, .. } => {
                    assert_eq!(key, session_key, "SessionReplaced targets the re-spawned session");
                    replaced_history_len = Some(history.len());
                }
                SessionUpdate::Connected { .. } => saw_plain_connected = true,
                _ => {}
            }
        }
        assert_eq!(
            replaced_history_len,
            Some(1),
            "connected_once=true emits SessionReplaced carrying the resumed conversation",
        );
        assert!(
            !saw_plain_connected,
            "a session-replacing re-spawn must not emit a fresh Connected"
        );
    }

    /// A replacement under a listening seat tells the successor it is heard:
    /// `/new` and `/resume` leave the listener set alone, so the note has to
    /// fire on the occupant change rather than on a listener transition.
    #[tokio::test]
    async fn a_replaced_seat_tells_the_successor_it_is_heard() {
        struct Silent;
        impl forge_tts::Engine for Silent {
            fn speak(
                &self,
                _request: forge_tts::SpeakRequest,
            ) -> tokio::sync::mpsc::Receiver<Result<forge_tts::Chunk, forge_tts::Error>>
            {
                let (sender, receiver) = tokio::sync::mpsc::channel(1);
                drop(sender);
                receiver
            }
        }

        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        workspace.install_voice_engine_for_test(Arc::new(Silent));
        let session_key = SessionSlot::from_str_for_test("voice-respawn-uuid");
        workspace.voice_service().set_listening(&session_key, 1, true, false);
        // The seat has no command sender yet, so this note cannot be delivered:
        // it must forge no row, or the page would draw a note the agent never got.
        while let Ok(frame) = update_rx.try_recv() {
            assert!(
                !matches!(&*frame.update, SessionUpdate::ChatAppended { .. }),
                "a note that was not delivered draws no row",
            );
        }
        let (command_tx, mut command_rx) = tokio::sync::mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(session_key.clone(), command_tx);

        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx_task) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let update_tx = workspace.update_sender();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx: command_rx_task,
            domain,
            update_tx,
            connected_once: true,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::Connected {
            session_id: session_key.display(),
            cwd: "/tmp/respawn".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: Some(Vec::new()),
            compaction_count: 0,
        });

        let mut note = None;
        let mut note_uuid = None;
        while let Ok(command) = command_rx.try_recv() {
            if let crate::protocol::Command::PromptUnder { text, uuid, .. } = command {
                note = Some(text);
                note_uuid = Some(uuid);
            }
        }
        assert!(
            note.as_deref().is_some_and(|text| text.contains("The user is listening")),
            "the successor is told it is heard, got: {note:?}",
        );

        let mut row = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::ChatAppended { key, msg, source, .. } = &*frame.update
                && key == &session_key
            {
                row = Some(((*msg).clone(), *source));
            }
        }
        let (row, source) = row.expect("the delivered note forges the row a page draws");
        assert_eq!(source, Some(PromptSource::Forge), "the row is forge's own delivery");
        let Message::User { message, uuid, timestamp, .. } = &row else {
            panic!("a voice note draws as an information row, not the reader's turn: {row:?}");
        };
        assert_eq!(uuid, &note_uuid, "the row and the prompt share one id");
        assert!(timestamp.is_some(), "the row carries forge's clock");
        let text = message
            .content
            .iter()
            .find_map(|block| match block {
                ContentBlock::Text { text, .. } => Some(text.as_str()),
                _ => None,
            })
            .expect("the row carries the note's words");
        assert_eq!(Some(text), note.as_deref(), "the row carries exactly the prose the agent got");
        assert!(
            text.starts_with("[Voice]\n\n"),
            "the envelope is what makes the view draw it as information, got: {text:?}",
        );
    }

    /// The replaced identity's `/dictate` override axes die with it:
    /// a view mints a blank bucket for the new session, so an axis
    /// left on the domain would style a session that no longer exists.
    #[tokio::test]
    async fn a_replaced_identity_drops_its_overrides() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        let session_key = SessionSlot::from_str_for_test("dictate-rekey-uuid");
        let domain =
            Arc::new(parking_lot::Mutex::new(DomainSession::new(session_key.clone(), None)));
        domain.lock().dictate_overrides.styling = Some(forge_dictate::normalize::Styling::Formal);

        let (handle, _agent_cmd_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: session_key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: true,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::Connected {
            session_id: session_key.display(),
            cwd: "/tmp/respawn".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        });

        assert_eq!(domain.lock().dictate_overrides, crate::dictate::DictateOverrides::default());

        let mut replaced_seen = false;
        while let Ok(frame) = update_rx.try_recv() {
            replaced_seen |= matches!(&*frame.update, SessionUpdate::SessionReplaced { .. });
        }
        assert!(
            replaced_seen,
            "the scenario must still be a replacement, or the test proves nothing"
        );
    }

    /// The login wait comes from the typed signals the CLI sends, and a
    /// turn that finished clears it.
    ///
    /// The `TurnError` envelope's text is a fallback rather than the
    /// signal: its producers are forge's own failed prompt write and
    /// failed cancel, so no CLI output reaches it, and a classifier over
    /// its text can fire on ordinary error words.
    #[test]
    fn a_login_wait_comes_from_the_typed_signals() {
        let held = |event: &AgentEvent| {
            let mut domain = empty_domain();
            apply_event_to_domain(&mut domain, event);
            domain.awaiting_login
        };

        assert!(
            held(&sdk_message(assistant_with("authentication_failed"))),
            "the CLI attributes the failure to the assistant message, and that is typed",
        );
        assert!(
            held(&sdk_message(api_retry("authentication_failed"))),
            "and names it on the retry frame as well",
        );
        assert!(
            !held(&sdk_message(assistant_with("server_error"))),
            "another class is not a login wait",
        );

        // A finished turn proves the credential works. A failed one does
        // not, and clearing on it would undo the mark the frames above
        // just set.
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(assistant_with("authentication_failed")));
        assert!(domain.awaiting_login, "precondition: held");
        apply_event_to_domain(
            &mut domain,
            &sdk_message(result_message("error_during_execution", true)),
        );
        assert!(
            domain.awaiting_login,
            "a turn that died on the missing credential does not clear the wait",
        );
        apply_event_to_domain(&mut domain, &sdk_message(result_message("success", false)));
        assert!(!domain.awaiting_login, "a turn that finished does");
    }

    fn sdk_message(msg: forge_primitives::Message) -> AgentEvent {
        AgentEvent::SdkMessage { session_id: "s".to_owned(), msg }
    }

    fn hook_observation(
        permission_mode: Option<&str>,
        effort: Option<&str>,
        tool_use_id: Option<&str>,
        agent_type: Option<&str>,
    ) -> AgentEvent {
        AgentEvent::HookObservation {
            session_id: "s".to_owned(),
            tool_use_id: tool_use_id.map(str::to_owned),
            permission_mode: permission_mode.map(str::to_owned),
            effort: effort.map(str::to_owned),
            agent_id: tool_use_id.map(|_| "agent-1".to_owned()),
            agent_type: agent_type.map(str::to_owned),
        }
    }

    fn init_frame_naming_the_model(model: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "init",
            "session_id": "s",
            "model": model,
        }))
        .expect("parse an init frame naming a model")
    }

    fn mcp_server(name: &str) -> forge_primitives::McpServerStatus {
        serde_json::from_value(serde_json::json!({ "name": name, "status": "connected" }))
            .expect("parse an MCP server status")
    }

    fn monitor_tool_use(tool_use_id: &str, description: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {
                "id": "msg-mon",
                "role": "assistant",
                "model": "claude-sonnet-5",
                "content": [{
                    "type": "tool_use",
                    "id": tool_use_id,
                    "name": "Monitor",
                    "input": {
                        "description": description,
                        "command": "gh run watch 1",
                        "persistent": true,
                    },
                }],
            },
            "session_id": "s",
        }))
        .expect("parse a Monitor tool_use")
    }

    fn task_started(task_id: &str, tool_use_id: Option<&str>) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_started",
            "task_id": task_id,
            "description": "watch CI",
            "uuid": "u-task",
            "session_id": "s",
            "tool_use_id": tool_use_id,
        }))
        .expect("parse a task_started")
    }

    fn task_updated(task_id: &str, status: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_updated",
            "task_id": task_id,
            "patch": { "status": status },
            "uuid": "u-upd",
            "session_id": "s",
        }))
        .expect("parse a task_updated")
    }

    /// A terminal patch as the CLI sends one: the status and the instant
    /// it ended, in one frame.
    fn task_updated_at(task_id: &str, status: &str, end_ms: u64) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_updated",
            "task_id": task_id,
            "patch": { "status": status, "end_time": end_ms },
            "uuid": "u-upd",
            "session_id": "s",
        }))
        .expect("parse a task_updated carrying an end time")
    }

    fn task_notification(task_id: &str) -> forge_primitives::Message {
        task_notification_with_status(task_id, "completed")
    }

    fn task_notification_with_status(task_id: &str, status: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_notification",
            "task_id": task_id,
            "status": status,
            "output_file": "/tmp/forge-test-monitor.out",
            "summary": "Monitor stream ended",
            "uuid": "u-note",
            "session_id": "s",
        }))
        .expect("parse a task_notification")
    }

    /// A `commands_changed` payload carrying entries that parse to none
    /// means the CLI's entry shape changed under us. Storing it would
    /// wipe the list, and `/help` with it, for every view reading
    /// through this, so the prior one stands.
    #[test]
    fn an_unparseable_commands_changed_payload_keeps_the_retained_commands() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&["/help"], &[])));

        apply_event_to_domain(
            &mut domain,
            &sdk_message(forge_primitives::Message::CommandsChanged {
                commands: vec![serde_json::json!({"no_name": "x"}), serde_json::json!(7)],
                uuid: "cmd-uuid".to_owned(),
                session_id: "s".to_owned(),
                extras: serde_json::Map::new(),
            }),
        );

        let commands: Vec<&str> =
            domain.available_commands.iter().map(|c| c.name.as_str()).collect();
        assert_eq!(commands, vec!["/help"], "the prior list stands rather than being wiped");
    }

    /// An empty payload is a real answer - a plugin uninstall - and it
    /// clears.
    #[test]
    fn an_empty_commands_changed_payload_clears_the_retained_commands() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&["/help"], &[])));

        apply_event_to_domain(
            &mut domain,
            &sdk_message(forge_primitives::Message::CommandsChanged {
                commands: Vec::new(),
                uuid: "cmd-uuid".to_owned(),
                session_id: "s".to_owned(),
                extras: serde_json::Map::new(),
            }),
        );

        assert!(domain.available_commands.is_empty(), "an empty payload clears the list");
    }

    /// A `Connected` in the same seat is a NEW OCCUPANT, and it has
    /// advertised nothing yet: the CLI sends `system/init` at the head of
    /// a turn only, so the last one's catalogues would stand until the new
    /// occupant's first message. The core clears both on the same event,
    /// and after a login swap the stale list came from another account's
    /// config dir - another session's data, not a late one.
    ///
    /// The refill is half the property: a swap that ends no turn - a
    /// mid-turn `/new`, a reconnect after a login - never sees the
    /// `Result` that re-arms the agent read, so the new occupant's own
    /// init has to be the thing that fills the catalogue back in.
    #[test]
    fn a_new_occupant_advertises_no_catalogues_until_its_own_init() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&["/help"], &["reviewer"])));

        apply_event_to_domain(&mut domain, &connected_event("new-occupant", "/proj"));

        assert!(
            domain.available_commands.is_empty(),
            "the previous occupant's command list does not stand",
        );
        assert!(domain.available_agents.is_empty(), "nor the agent catalogue it advertised");

        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&["/newhelp"], &["newagent"])));

        let commands: Vec<&str> =
            domain.available_commands.iter().map(|c| c.name.as_str()).collect();
        let agents: Vec<&str> = domain.available_agents.iter().map(|a| a.name.as_str()).collect();
        assert_eq!(commands, vec!["/newhelp"], "the new occupant's own init refills the commands");
        assert_eq!(agents, vec!["newagent"], "and the catalogue, without waiting a turn");
    }

    /// A `system/init` frame, which is where the CLI advertises both
    /// catalogues: bare command names and bare agent names.
    fn init_frame(slash_commands: &[&str], agents: &[&str]) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "init",
            "session_id": "s",
            "slash_commands": slash_commands,
            "agents": agents,
        }))
        .expect("an init frame")
    }

    /// Both lists are facts about the session, so the core keeps them: a
    /// view that arrives after the turn started reads them rather than
    /// waiting for the next init frame, which may be a whole turn away.
    #[test]
    fn the_catalogues_the_cli_advertises_are_retained_on_the_domain() {
        let mut domain = empty_domain();

        apply_event_to_domain(
            &mut domain,
            &sdk_message(init_frame(&["/help", "memory"], &["reviewer"])),
        );

        let commands: Vec<&str> =
            domain.available_commands.iter().map(|c| c.name.as_str()).collect();
        assert_eq!(commands, vec!["/help", "memory"], "the command list is kept whole");
        let agents: Vec<&str> = domain.available_agents.iter().map(|a| a.name.as_str()).collect();
        assert_eq!(agents, vec!["reviewer"], "and so is the agent catalogue");
    }

    /// A plugin reload re-sends the command list mid-session, and the
    /// retained copy has to follow it or the dropdown goes stale.
    #[test]
    fn a_commands_changed_frame_refreshes_the_retained_commands() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&["/help"], &[])));

        let refreshed = forge_primitives::Message::CommandsChanged {
            commands: vec![serde_json::json!({"name": "/reload", "description": "Reloaded"})],
            uuid: "cmd-uuid".to_owned(),
            session_id: "s".to_owned(),
            extras: serde_json::Map::new(),
        };
        apply_event_to_domain(&mut domain, &sdk_message(refreshed));

        let commands: Vec<&str> =
            domain.available_commands.iter().map(|c| c.name.as_str()).collect();
        assert_eq!(commands, vec!["/reload"], "the reload's list replaces the init one");
    }

    /// The CLI re-fires `system/init` every turn. A frame that advertises
    /// no commands carries nothing about them, so it must not wipe what
    /// the previous turn established.
    #[test]
    fn an_init_frame_with_no_commands_keeps_the_retained_ones() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&["/help"], &["reviewer"])));

        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&[], &["reviewer"])));

        assert_eq!(domain.available_commands.len(), 1, "the earlier list stands");
        assert_eq!(domain.available_agents.len(), 1, "and the catalogue with it");
    }

    /// The agent catalogue is read once per turn, the rule this fold
    /// applies: a re-fire inside the same turn is the
    /// same list, and the turn boundary is what re-arms the read.
    #[test]
    fn the_agent_catalogue_is_read_once_per_turn() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&[], &["reviewer"])));

        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&[], &["someone-else"])));
        assert_eq!(
            domain.available_agents.first().map(|a| a.name.as_str()),
            Some("reviewer"),
            "a re-fire inside the turn does not replace the catalogue",
        );

        apply_event_to_domain(&mut domain, &sdk_message(result_message("success", false)));
        apply_event_to_domain(&mut domain, &sdk_message(init_frame(&[], &["someone-else"])));
        assert_eq!(
            domain.available_agents.first().map(|a| a.name.as_str()),
            Some("someone-else"),
            "and the next turn's frame does",
        );
    }

    /// The hook observation carries three facts a view renders: the
    /// permission mode, the effort level and
    /// the tool_use -> agent-type attribution. All three land on the
    /// session so a view reads them instead of folding the same event
    /// again.
    #[test]
    fn a_hook_observation_is_held_on_the_domain() {
        let mut domain = empty_domain();

        apply_event_to_domain(
            &mut domain,
            &hook_observation(Some("acceptEdits"), Some("xhigh"), Some("tu-1"), Some("Explore")),
        );

        assert_eq!(
            domain.observed_permission_mode,
            Some(forge_primitives::PermissionMode::AcceptEdits),
            "the hook's permission mode is kept",
        );
        assert_eq!(
            domain.observed_effort,
            Some(forge_primitives::EffortLevel::Xhigh),
            "and its effort level",
        );
    }

    /// A level the CLI spells differently is a level forge cannot name,
    /// not a reason to forget the one it already has.
    #[test]
    fn an_unreadable_hook_effort_keeps_the_level_already_held() {
        let mut domain = empty_domain();
        domain.observed_effort = Some(forge_primitives::EffortLevel::High);

        apply_event_to_domain(&mut domain, &hook_observation(None, Some("turbo"), None, None));

        assert_eq!(
            domain.observed_effort,
            Some(forge_primitives::EffortLevel::High),
            "an unreadable level leaves the held one standing",
        );
    }

    /// The MCP set is per session, and the core is the one that asks for
    /// it, so the answer is kept rather than only passed through.
    #[test]
    fn the_mcp_snapshot_the_bridge_returns_is_held() {
        let mut domain = empty_domain();

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::McpSnapshot {
                session_id: "s".to_owned(),
                servers: vec![mcp_server("ctx7")],
                error: None,
            },
        );

        let held = domain.mcp_servers.as_ref().expect("the snapshot is kept");
        assert_eq!(held.servers.len(), 1, "the server list is kept whole");
        assert_eq!(held.servers[0].name, "ctx7", "and names the server it carries");
        assert_eq!(held.error, None, "with no error standing beside it");
    }

    /// A later snapshot replaces the one before it, including when the
    /// bridge reports a failure: a stale `connected` row is worse than
    /// no row.
    #[test]
    fn a_failed_mcp_snapshot_replaces_the_one_before_it() {
        let mut domain = empty_domain();
        apply_event_to_domain(
            &mut domain,
            &AgentEvent::McpSnapshot {
                session_id: "s".to_owned(),
                servers: vec![mcp_server("ctx7")],
                error: None,
            },
        );

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::McpSnapshot {
                session_id: "s".to_owned(),
                servers: Vec::new(),
                error: Some("the CLI refused".to_owned()),
            },
        );

        let held = domain.mcp_servers.as_ref().expect("the snapshot is kept");
        assert!(held.servers.is_empty(), "the failed read's empty set replaces the old one");
        assert_eq!(held.error.as_deref(), Some("the CLI refused"), "and carries why");
    }

    /// Context usage is the header's `ctx` reading, and it survives its
    /// own refresh: the poll that fills it lands on the session rather
    /// than only on the view that asked.
    #[test]
    fn the_context_usage_the_bridge_reports_is_held() {
        let mut domain = empty_domain();

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::ContextUsage {
                session_id: "s".to_owned(),
                percentage: Some(62),
                max_tokens: Some(1_000_000),
                total_tokens: Some(620_000),
                effective_max_tokens: Some(1_000_000),
            },
        );

        let held = domain.context_usage.expect("the usage is kept");
        assert_eq!(held.percent, Some(62), "the percentage is kept");
        assert_eq!(held.max_tokens, Some(1_000_000), "and the window it is a share of");
    }

    /// The model a session runs is stated at connect, and a view reading
    /// later must get the session's own rather than nothing.
    #[test]
    fn a_connected_session_holds_the_model_it_reported() {
        let mut domain = empty_domain();

        apply_event_to_domain(&mut domain, &connected_event("uuid-1", "/proj"));

        assert_eq!(
            domain.current_model.as_ref().map(|m| m.resolved_id.as_str()),
            Some("claude"),
            "the model the connect reported is kept",
        );
    }

    /// The CLI names the model each turn runs under at the head of the
    /// turn, and that frame is how a mid-session switch reaches a reader:
    /// after `/model` a view's row moves, and a read that only
    /// listened at connect would go on naming the model the session left.
    #[test]
    fn the_model_follows_a_later_turns_init_frame() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &connected_event("uuid-1", "/proj"));
        apply_event_to_domain(
            &mut domain,
            &sdk_message(init_frame_naming_the_model("claude-opus-5-5")),
        );

        assert_eq!(
            domain.current_model.as_ref().map(|model| model.resolved_id.as_str()),
            Some("claude-opus-5-5"),
            "the model the turn runs under is the model the session is said to be on",
        );
    }

    /// The frame arrives at the head of every turn, including the turns
    /// that changed nothing, so a session that is not switching keeps the
    /// name it resolved at connect rather than being renamed to the CLI's
    /// own spelling of it.
    #[test]
    fn an_init_frame_naming_the_same_model_keeps_the_resolved_name() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &connected_event("uuid-1", "/proj"));
        domain.current_model = Some(forge_primitives::CurrentModel {
            requested_id: Some("Opus (1M context)".to_owned()),
            resolved_id: "claude".to_owned(),
            display_name_short: "Opus (1M context)".to_owned(),
            display_name_long: "Opus (1M context)".to_owned(),
            ..forge_primitives::CurrentModel::new("claude", "claude", "claude")
        });

        apply_event_to_domain(&mut domain, &sdk_message(init_frame_naming_the_model("claude")));

        assert_eq!(
            domain.current_model.as_ref().map(|model| model.display_name_long.as_str()),
            Some("Opus (1M context)"),
            "a turn that switched nothing does not rename the session",
        );
    }

    /// A replacement occupant inherits none of the last one's facts: the
    /// hook mirrors describe a session that is gone, and the process tree
    /// belonged to a subprocess that exited with it.
    #[test]
    fn a_replaced_occupant_clears_the_held_view_facts() {
        let mut domain = empty_domain();
        apply_event_to_domain(
            &mut domain,
            &hook_observation(Some("plan"), Some("max"), Some("tu-1"), Some("Explore")),
        );
        domain.mcp_servers = Some(crate::domain_session::McpServers::default());
        domain.context_usage =
            Some(crate::domain_session::ContextUsage { percent: Some(10), max_tokens: None });

        apply_event_to_domain(&mut domain, &connected_event("uuid-2", "/proj"));

        assert_eq!(domain.observed_permission_mode, None, "the dead run's mode does not stand");
        assert_eq!(domain.observed_effort, None, "nor its effort");
        assert_eq!(domain.mcp_servers, None, "nor the servers it had connected");
        assert_eq!(domain.context_usage, None, "nor the context it had filled");
    }

    /// A dead connection blanks the session's runtime identity, and a view
    /// renders that: what the core holds has to go with the run it
    /// described, or the read answers with a mode and a model the session no
    /// longer has.
    #[test]
    fn a_dead_connection_clears_the_held_view_facts() {
        let mut domain = seeded_view_facts();

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::ConnectionFailed {
                message: "reader died".to_owned(),
                kind: SpawnFailureKind::Unclassified,
            },
        );

        assert_view_facts_cleared(&domain, "the subprocess died");
    }

    fn seeded_view_facts() -> DomainSession {
        let mut domain = empty_domain();
        apply_event_to_domain(
            &mut domain,
            &hook_observation(Some("plan"), Some("max"), Some("tu-1"), Some("Explore")),
        );
        domain.current_model =
            Some(forge_primitives::CurrentModel::new("claude-opus-5", "Opus", "Claude Opus 5"));
        domain.mcp_servers = Some(crate::domain_session::McpServers::default());
        domain.context_usage =
            Some(crate::domain_session::ContextUsage { percent: Some(10), max_tokens: None });
        domain
    }

    fn assert_view_facts_cleared(domain: &DomainSession, why: &str) {
        assert_eq!(domain.observed_permission_mode, None, "{why} leaves no mode standing");
        assert_eq!(domain.observed_effort, None, "{why} leaves no effort standing");
        assert_eq!(domain.current_model, None, "{why} leaves no model standing");
        assert_eq!(domain.context_usage, None, "{why} leaves no context reading standing");
        assert_eq!(domain.mcp_servers, None, "{why} leaves no server snapshot standing");
    }

    /// The walk describes a subprocess tree, so it goes with the process: left
    /// standing it paints rows for programs that are not there, and nothing
    /// following a dead session would ever replace it. The clear reaches the
    /// stream as an empty walk, which is what the monitors and the background
    /// registry already do on the same event.
    ///
    /// **This reverses an earlier call** that kept the walk readable after a
    /// failure, on the view going on painting it - the ageing note said the
    /// tree was old, never that it was gone.
    #[test]
    fn a_dead_connection_clears_the_process_walk() {
        let mut domain = empty_domain();
        domain.process_snapshot = Some(forge_agent::env::processes::ProcessSnapshot {
            processes: Vec::new(),
            scanned_at: std::time::SystemTime::UNIX_EPOCH,
        });

        apply_event_to_domain(
            &mut domain,
            &AgentEvent::ConnectionFailed {
                message: "reader died".to_owned(),
                kind: SpawnFailureKind::Unclassified,
            },
        );

        assert!(
            domain.process_snapshot.is_none(),
            "the tree went with the subprocess, so the read has nothing to serve",
        );
    }

    /// A Monitor tool call is live work, and the core holds it so a view
    /// can draw it.
    #[test]
    fn a_monitor_tool_call_enters_the_held_set() {
        let mut domain = empty_domain();

        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-mon", "ci-watch")));

        assert_eq!(domain.monitors.len(), 1, "the call enters the set");
        let held = &domain.monitors[0];
        assert_eq!(held.tool_use_id, "tu-mon", "keyed by the tool_use that started it");
        assert_eq!(held.description, "ci-watch", "carrying its headline");
        assert_eq!(held.command, "gh run watch 1", "and the command it watches");
        assert_eq!(
            held.status,
            forge_primitives::MonitorStatus::Running,
            "and it starts running, which is the only state the tool call proves",
        );
        assert_eq!(held.task_id, None, "with no task id the wire has not named yet");
    }

    /// The monitor's terminal transition is keyed by the CLI's task id,
    /// so the `task_started` stamp is what lets a later `task_updated`
    /// find the record at all.
    #[test]
    fn a_monitors_task_transition_settles_its_held_record() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-mon", "ci-watch")));

        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-1", Some("tu-mon"))));
        assert_eq!(
            domain.monitors[0].task_id.as_deref(),
            Some("t-1"),
            "the task id the CLI assigned is stamped on the record",
        );

        apply_event_to_domain(&mut domain, &sdk_message(task_updated("t-1", "completed")));

        assert_eq!(
            domain.monitors[0].status,
            forge_primitives::MonitorStatus::Completed,
            "a clean exit settles the monitor",
        );
    }

    /// The instant a monitor ended rides the frame that settles it, and a
    /// view draws the age from it. Without it the record says how a
    /// monitor ended and not when, which is the whole difference between
    /// `completed` and `completed 12m`.
    #[test]
    fn a_monitors_terminal_transition_stamps_the_instant_it_ended() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-mon", "ci-watch")));
        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-1", Some("tu-mon"))));

        apply_event_to_domain(
            &mut domain,
            &sdk_message(task_updated_at("t-1", "completed", 1_700_000_000_123)),
        );

        assert_eq!(
            domain.monitors[0].ended_at,
            Some(
                std::time::SystemTime::UNIX_EPOCH
                    + std::time::Duration::from_millis(1_700_000_000_123)
            ),
            "the frame that ends the monitor is the frame that says when",
        );
    }

    /// A running monitor has no end instant, and a read that carried one
    /// would draw an age on work that is still going.
    #[test]
    fn a_running_monitor_carries_no_end_instant() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-mon", "ci-watch")));
        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-1", Some("tu-mon"))));
        apply_event_to_domain(&mut domain, &sdk_message(task_updated("t-1", "running")));

        assert_eq!(
            domain.monitors[0].ended_at, None,
            "a monitor still watching has not ended, so it has nothing to age",
        );
    }

    /// A monitor that was already running before this process started is
    /// in the transcript the connect carries, and the transcript carries
    /// no lifecycle frame at all: the replay synthesizer emits user and
    /// assistant messages and nothing else. So a seeded entry is settled
    /// on arrival - one seeded running could never be settled, because
    /// every settlement is keyed on the task id the transcript cannot
    /// carry.
    #[test]
    fn a_monitor_folded_from_a_transcript_is_seeded_settled() {
        let mut domain = empty_domain();

        fold_monitor(
            &mut domain,
            &monitor_tool_use("tu-mon", "ci-watch"),
            MonitorOrigin::Transcript,
        );

        assert_eq!(domain.monitors.len(), 1, "the transcript's monitor is seeded");
        assert_eq!(
            domain.monitors[0].status,
            forge_primitives::MonitorStatus::Completed,
            "settled rather than left falsely running forever",
        );
        assert_eq!(
            domain.monitors[0].task_id, None,
            "with no task id, which is why nothing could ever settle it",
        );
    }

    /// **A sub-agent's Monitor call is not the session's.** The connect-time
    /// fold that seeds monitors skips a parented frame, so a resumed
    /// conversation does not grow a monitor row from work an instance ran.
    #[test]
    fn a_subagents_monitor_call_is_not_seeded() {
        let mut domain = empty_domain();
        let mut framed = monitor_tool_use("tu-mon", "ci-watch");
        if let forge_primitives::Message::Assistant { parent_tool_use_id, .. } = &mut framed {
            *parent_tool_use_id = Some("toolu_dispatch".to_owned());
        }
        let mut event = connected_event("s-mon", "/tmp/mon");
        if let AgentEvent::Connected { history_updates, .. } = &mut event {
            *history_updates = Some(vec![framed]);
        }

        apply_event_to_domain(&mut domain, &event);

        assert!(domain.monitors.is_empty(), "the instance's monitor is not the session's");
    }

    /// A live tool call is not settled: its task is running and the
    /// command frames that settle it are still to come.
    #[test]
    fn a_monitor_folded_from_the_wire_is_seeded_running() {
        let mut domain = empty_domain();

        fold_monitor(&mut domain, &monitor_tool_use("tu-mon", "ci-watch"), MonitorOrigin::Wire);

        assert_eq!(
            domain.monitors[0].status,
            forge_primitives::MonitorStatus::Running,
            "a call on the live wire is running until the command says otherwise",
        );
    }

    /// The monitor set drains once every entry is terminal: a session that
    /// ran a monitor an hour ago shows no section, not a section with
    /// nothing to say.
    #[test]
    fn the_monitor_set_drains_once_every_entry_is_terminal() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-a", "ci-watch")));
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-b", "deploy-gate")));
        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-a", Some("tu-a"))));
        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-b", Some("tu-b"))));

        apply_event_to_domain(&mut domain, &sdk_message(task_updated("t-a", "completed")));
        assert_eq!(
            domain.monitors.len(),
            2,
            "one settled monitor keeps the section, holding its tail"
        );

        apply_event_to_domain(&mut domain, &sdk_message(task_notification("t-b")));

        assert!(
            domain.monitors.is_empty(),
            "every entry terminal drains the set rather than leaving an empty section",
        );
    }

    /// A notification whose status forge cannot name is still a
    /// notification, and it is the last frame a monitor sends: the
    /// set drains on every one of them, so a status the CLI adds
    /// later must not leave the core's set standing forever.
    #[test]
    fn an_unnameable_task_status_still_drains_the_set() {
        let mut domain = empty_domain();
        apply_event_to_domain(&mut domain, &sdk_message(monitor_tool_use("tu-a", "ci-watch")));
        apply_event_to_domain(&mut domain, &sdk_message(task_started("t-a", Some("tu-a"))));
        // Settled by the command frame, which deliberately does not drain:
        // the notification that follows is what carries the tail.
        apply_event_to_domain(&mut domain, &sdk_message(task_updated("t-a", "killed")));

        apply_event_to_domain(
            &mut domain,
            &sdk_message(task_notification_with_status("t-a", "reticulating")),
        );

        assert!(
            domain.monitors.is_empty(),
            "a notification drains the set whatever its status says",
        );
    }

    /// The same drain runs over a transcript's seed, so a resumed session
    /// whose monitors were all over shows none of them.
    #[test]
    fn a_resumed_sessions_history_leaves_no_live_monitor() {
        let mut domain = empty_domain();
        let mut connected = connected_event("uuid-1", "/proj");
        if let AgentEvent::Connected { history_updates, .. } = &mut connected {
            *history_updates = Some(vec![
                monitor_tool_use("tu-mon", "ci-watch"),
                monitor_tool_use("tu-other", "deploy-gate"),
            ]);
        }

        apply_event_to_domain(&mut domain, &connected);

        assert!(
            domain.monitors.is_empty(),
            "a transcript cannot say a monitor is still running, so none of them are drawn",
        );
    }

    fn assistant_with(error: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "message": {
                "id": "msg-1",
                "role": "assistant",
                "model": "claude-sonnet-5",
                "content": [],
            },
            "session_id": "s",
            "error": error,
        }))
        .expect("parse an assistant message")
    }

    fn api_retry(error: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "api_retry",
            "session_id": "s",
            "attempt": 1,
            "max_retries": 3,
            "retry_delay_ms": 100,
            "error": error,
        }))
        .expect("parse a retry frame")
    }

    /// A failed connection is recorded where a view can read it, and a
    /// `Connected` clears it.
    ///
    /// Both halves go through `translate_event`, the dispatcher the run
    /// loop uses, and that is what this test is for: the record is in the
    /// failure arm and the clear is in the `Connected` arm rather than in
    /// `register_domain_session`, which production never calls - the
    /// spawn entries hoist a domain straight into `domain_handles` and
    /// insert it themselves.
    ///
    /// Both `Connected` branches are driven, because narrowing the clear
    /// into the replacement branch is the plausible mistake and it leaves
    /// the common recovery reading failed for the life of the process: a
    /// fresh task's FIRST connect after a retry.
    #[tokio::test]
    async fn a_connection_failure_is_recorded_and_a_connected_clears_it() {
        let (workspace, _update_rx) = crate::Workspace::testing_stub();

        for (key, connected_once) in [
            (SessionSlot::from_str_for_test("record-failure-replaced"), true),
            (SessionSlot::from_str_for_test("record-failure-fresh"), false),
        ] {
            let (handle, _agent_cmds) = Agent::testing_stub();
            let arc = Arc::new(handle);
            let domain = workspace.register_domain_session(key.clone(), Some(Arc::clone(&arc)));
            let (_cmd_tx, command_rx) =
                tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
            let mut task = SessionTask {
                key: key.clone(),
                handle: arc,
                command_rx,
                domain,
                update_tx: workspace.update_sender(),
                connected_once,
                workspace: Arc::downgrade(&workspace),
                compaction_count: 0,
                successor: None,
                teardown_done: None,
            };

            task.translate_event(AgentEvent::ConnectionFailed {
                message: "the bucket died".to_owned(),
                kind: SpawnFailureKind::Unclassified,
            });
            assert_eq!(
                workspace.spawn_failure(&key).as_deref(),
                Some("the bucket died"),
                "a failed connection is recorded where a view can read it ({connected_once})",
            );

            task.translate_event(connected_event("fresh-uuid", "/proj"));

            assert_eq!(
                workspace.spawn_failure(&key),
                None,
                "and a session that comes up clears it rather than reading failed for the \
                 process ({connected_once})",
            );
        }
    }

    /// A session-replacing re-spawn tears the live session down BEFORE
    /// re-spawning, so if the re-spawned agent fails to connect the
    /// session is momentarily agent-less. That failure must be
    /// recoverable (`ConnectionFailed { fatal: false }`), and the task's
    /// exit must leave no lingering pooled agent under the key. (The
    /// synchronous `get_agent_handle` Err arm is defensive/near-
    /// unreachable - `Agent::spawn` is infallible - so this covers the
    /// realistic async failure path instead.)
    #[tokio::test]
    async fn respawn_connection_failure_is_nonfatal_and_releases_the_session() {
        let (workspace, mut update_rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("respawn-fail-uuid");

        let (handle, _agent_cmds) = Agent::testing_stub();
        let arc = Arc::new(handle);
        // Register the re-spawned session under `key` with `arc` pooled -
        // the SAME Arc the task holds, so the exit cleanup recognises it.
        workspace.pool.lock().insert(
            key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&arc),
                account: forge_gateway::AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        let domain = workspace.register_domain_session(key.clone(), Some(Arc::clone(&arc)));
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();

        let mut task = SessionTask {
            key: key.clone(),
            handle: arc,
            command_rx,
            domain,
            update_tx: workspace.update_sender(),
            connected_once: true, // a session-replacing re-spawn
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        // The re-spawned agent fails to connect.
        task.translate_event(AgentEvent::ConnectionFailed {
            message: "spawn failed".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });

        let mut saw_nonfatal = false;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::ConnectionFailed { key: failed_key, fatal, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                assert!(!fatal, "a failed re-spawn is recoverable, not fatal");
                assert_eq!(failed_key, key);
                saw_nonfatal = true;
            }
        }
        assert!(saw_nonfatal, "the failed re-spawn emits ConnectionFailed with fatal=false");

        // The dead spawn's registrations are released in the arm itself,
        // before the task exits - no lingering agent under the key.
        assert!(
            !workspace.pool.lock().contains_key(&key),
            "a failed re-spawn leaves no lingering pooled agent",
        );
    }

    /// The named failure kind has to survive the join. `translate_event`
    /// is the only production site that hands it to the worker-failure
    /// handler, and the default there would put the message heuristic back
    /// in charge: a `CwdNotFound` renders the directory it could not
    /// enter, and for a worker that directory runs through
    /// `.claude/worktrees/<label>`, so the row would be deleted and the
    /// lead told the worktree could not be created.
    #[tokio::test]
    async fn a_named_spawn_failure_kind_reaches_the_worker_handler() {
        let (workspace, _update_rx) = crate::Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        let db_dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        let project_dir = tempfile::tempdir().expect("project dir");
        workspace.seed_test_project("proj-x", &project_dir.path().to_string_lossy());
        let project_key = workspace.project_key_for_name("proj-x").expect("seeded project");
        // The row a worktree-creation verdict would delete.
        workspace
            .record_worker_row(
                &project_key,
                "reviewer",
                "reviewer-uuid",
                "c",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
                None,
            )
            .expect("seed the worker's row");

        let worker_slot = SessionSlot::from_str_for_test("worker-uuid");
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "reviewer".to_owned(),
                charter: "c".to_owned(),
                slot: worker_slot.clone(),
                session_id: Some(forge_primitives::SessionId::new("reviewer-uuid")),
                status: forge_primitives::WorkerLiveness::Spawning,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::from_str_for_test("lead-uuid"),
                needs_tag: false,
                is_git_repo_at_spawn: true,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );

        let (handle, _agent_cmds) = Agent::testing_stub();
        let arc = Arc::new(handle);
        let domain = workspace.register_domain_session(worker_slot.clone(), Some(Arc::clone(&arc)));
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: worker_slot.clone(),
            handle: arc,
            command_rx,
            domain,
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.translate_event(AgentEvent::ConnectionFailed {
            message: "forge-sdk session resume failed: claude subprocess working directory \
                      `/x/.claude/worktrees/reviewer` does not exist"
                .to_owned(),
            kind: SpawnFailureKind::WorkingDirMissing,
        });

        let rows = workspace.worker_rows_for_project(&project_key);
        assert!(
            rows.iter().any(|row| row.label == "reviewer"),
            "a named missing-working-directory failure keeps the worker's row rather than \
             deleting it as a worktree that could not be created; rows left {:?}",
            rows.iter().map(|row| row.label.clone()).collect::<Vec<_>>(),
        );
    }

    /// Common harness for the `execute_command_via_handle` tests
    /// below: build a fresh stub handle + drain channel, return both.
    fn stub_handle_with_rx()
    -> (Arc<AgentHandle>, tokio::sync::mpsc::UnboundedReceiver<forge_primitives::AgentCommand>)
    {
        let (handle, rx) = Agent::testing_stub();
        (Arc::new(handle), rx)
    }

    /// `Command::Prompt` reaches the underlying agent's command
    /// dispatcher as `PromptWithImages`.
    #[test]
    fn execute_prompt_forwards_to_handle() {
        let (handle, mut rx) = stub_handle_with_rx();
        let key = SessionSlot::from_str_for_test("sess");
        execute_command_via_handle(
            &handle,
            &key,
            Some("sess-1"),
            None,
            Command::Prompt { key: key.clone(), text: "hi".into(), attachments: Vec::new() },
        )
        .expect("dispatch succeeds");
        let cmd = rx.try_recv().expect("command queued");
        assert!(matches!(
            cmd,
            forge_primitives::AgentCommand::PromptWithImages { session_id, .. }
                if session_id == "sess-1"
        ));
    }

    /// A prompt is recorded on the seat as waiting, announced with its words,
    /// and sent under the SAME id - which is the whole mechanism: the CLI's
    /// lifecycle frames carry only the id and the state, so the row and the
    /// frames are one thing by id or not at all.
    #[tokio::test]
    async fn executing_a_prompt_records_and_announces_it() {
        let (workspace, mut updates) = crate::Workspace::testing_stub();
        workspace.seed_test_project("qp", "/tmp/qp");
        let key = SessionSlot::from_str_for_test("qp-lead");
        let domain = Arc::new(parking_lot::Mutex::new(DomainSession::new(key.clone(), None)));
        // A connected seat: the id is what the prompt is addressed to, and a
        // task that never connected drops the send rather than recording it.
        domain.lock().session_id = Some(forge_primitives::SessionId::new("qp-session"));
        let (handle, mut agent_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        task.execute_command(Command::Prompt {
            key: key.clone(),
            text: "the queued words".to_owned(),
            attachments: Vec::new(),
        });

        let rows = domain.lock().prompt_queue.clone();
        assert_eq!(rows.len(), 1, "the prompt is on the seat's queue");
        assert_eq!(rows[0].text, "the queued words");
        assert_eq!(rows[0].source, PromptSource::You);

        let sent = agent_rx.try_recv().expect("the prompt reaches the agent");
        let forge_primitives::AgentCommand::PromptWithImages { uuid, .. } = sent else {
            panic!("expected a prompt, got {sent:?}");
        };
        assert_eq!(
            uuid, rows[0].uuid,
            "the recorded row and the frame share one id, which is what the lifecycle frames resolve against",
        );

        let announced: Vec<crate::protocol::SessionUpdate> =
            std::iter::from_fn(|| updates.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
        assert!(
            announced.iter().any(|update| matches!(
                update,
                crate::protocol::SessionUpdate::PromptQueued { uuid: announced, text, .. }
                    if announced == &rows[0].uuid && text == "the queued words"
            )),
            "the row's words ride the announcement, because no lifecycle frame carries them: {announced:?}",
        );
    }

    /// A prompt held because it arrived mid-turn goes out when that turn's
    /// Result lands: the seat is idle again, so it starts a turn of its own
    /// instead of folding into the one that just ended.
    #[tokio::test]
    async fn a_turn_end_delivers_the_prompt_held_for_it() {
        let (workspace, _updates) = crate::Workspace::testing_stub();
        workspace.seed_test_project("hp", "/tmp/hp");
        let key = SessionSlot::from_str_for_test("hp-worker");
        let domain = Arc::new(parking_lot::Mutex::new(DomainSession::new(key.clone(), None)));
        domain.lock().session_id = Some(forge_primitives::SessionId::new("hp-session"));
        domain.lock().turn_pending = true;
        let (handle, _agent_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        let held = crate::mcp::peers::types::WrappedPrompt {
            id: crate::mcp::peers::types::MessageId::mint(),
            kind: crate::mcp::peers::types::WrappedKind::Message,
            sender_name: "forge".to_owned(),
            sender_org: "Busytools".to_owned(),
            body: "the held words".to_owned(),
        };
        workspace.hold_peer_prompt_unless_turn_ended(
            &key,
            &SessionSlot::lead("Busytools", "hp"),
            held,
            || true,
        );
        workspace.enable_test_dispatch_intercept();

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "hp-session".to_owned(),
            msg: result_message("success", false),
        });

        let dispatched = workspace.drain_test_dispatch_buffer().into_iter().any(|cmd| {
            matches!(
                cmd,
                crate::protocol::Command::PromptUnder { text, source, .. }
                    if source == PromptSource::Peer && text.contains("the held words")
            )
        });
        assert!(dispatched, "the held prompt is delivered as the turn ends");
        assert!(
            workspace.take_turn_held_for_slot(&key).is_empty(),
            "and the hold is spent, not redelivered next turn",
        );
    }

    /// A transport death is NOT a turn end to deliver behind: the seat is
    /// gone, so the hold stays where the death path's expiry can tell its
    /// sender rather than being dispatched into a dying session, where it
    /// would drop unheard.
    #[tokio::test]
    async fn a_transport_death_does_not_drain_the_hold() {
        let (workspace, _updates) = crate::Workspace::testing_stub();
        workspace.seed_test_project("hd", "/tmp/hd");
        let key = SessionSlot::from_str_for_test("hd-worker");
        let domain = Arc::new(parking_lot::Mutex::new(DomainSession::new(key.clone(), None)));
        domain.lock().session_id = Some(forge_primitives::SessionId::new("hd-session"));
        domain.lock().turn_pending = true;
        let (handle, _agent_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        let held = crate::mcp::peers::types::WrappedPrompt {
            id: crate::mcp::peers::types::MessageId::mint(),
            kind: crate::mcp::peers::types::WrappedKind::Message,
            sender_name: "forge".to_owned(),
            sender_org: "Busytools".to_owned(),
            body: "while the transport dies".to_owned(),
        };
        workspace.hold_peer_prompt_unless_turn_ended(
            &key,
            &SessionSlot::lead("Busytools", "hd"),
            held,
            || true,
        );
        workspace.enable_test_dispatch_intercept();

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "hd-session".to_owned(),
            msg: serde_json::from_value(serde_json::json!({
                "type": "error",
                "error": "stream closed",
            }))
            .expect("parse error message"),
        });

        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "nothing is dispatched into a session whose transport just died",
        );
        assert_eq!(
            workspace.take_turn_held_for_slot(&key).len(),
            1,
            "the hold stays for the death path's expiry to acknowledge",
        );
    }

    /// A session whose CLI says it does not carry the lifecycle frames records
    /// NO queued rows: nothing could ever settle one, and a card that can never
    /// drain is worse than no card - that session draws its prompt the way it
    /// did before the pile existed.
    #[tokio::test]
    async fn a_cli_without_lifecycle_frames_draws_its_prompts_and_drains_the_pile() {
        let (workspace, mut updates) = crate::Workspace::testing_stub();
        workspace.seed_test_project("nf", "/tmp/nf");
        let key = SessionSlot::from_str_for_test("nf-lead");
        let domain = Arc::new(parking_lot::Mutex::new(DomainSession::new(key.clone(), None)));
        domain.lock().session_id = Some(forge_primitives::SessionId::new("nf-session"));
        let (handle, mut agent_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        // **The first prompt lands before the init frame**, which is the only
        // frame that can say the capability is absent - so it is recorded and
        // announced while the flag is still unknown.
        task.execute_command(Command::Prompt {
            key: key.clone(),
            text: "the first prompt".to_owned(),
            attachments: Vec::new(),
        });
        assert_eq!(
            domain.lock().prompt_queue.len(),
            1,
            "premise: recorded while the capability was unknown",
        );
        let announced: Vec<crate::protocol::SessionUpdate> =
            std::iter::from_fn(|| updates.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
        let first = announced
            .iter()
            .find_map(|update| match update {
                crate::protocol::SessionUpdate::PromptQueued { uuid, text, .. }
                    if text == "the first prompt" =>
                {
                    Some(uuid.clone())
                }
                _ => None,
            })
            .expect("the first prompt is announced while its capability is unknown");

        // The init frame from a CLI that does not advertise the capability is
        // what draws the waiting prompt and drains the pile.
        let init: forge_primitives::Message = serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "init",
            "session_id": "nf-session",
            "capabilities": ["interrupt_receipt_v1"],
        }))
        .expect("parse an init frame");
        task.translate_event(forge_agent::AgentEvent::SdkMessage {
            session_id: "nf-session".to_owned(),
            msg: init,
        });
        assert!(
            domain.lock().prompt_queue.is_empty(),
            "the init frame drains the pile it can no longer settle",
        );
        assert!(
            agent_rx.try_recv().is_ok(),
            "the prompt itself still reaches the agent: the pile is a view, not the send",
        );
        let drained: Vec<crate::protocol::SessionUpdate> =
            std::iter::from_fn(|| updates.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
        let row = drained.iter().find_map(|update| match update {
            crate::protocol::SessionUpdate::ChatAppended { msg, source, .. }
                if matches!(msg, forge_primitives::Message::User { .. }) =>
            {
                Some((msg, source))
            }
            _ => None,
        });
        let Some((msg, source)) = row else {
            panic!("the init frame draws the waiting prompt: {drained:?}");
        };
        assert_eq!(*source, Some(crate::protocol::PromptSource::You), "the reader's own send");
        let forge_primitives::Message::User { message, uuid, .. } = msg else {
            panic!("the flushed row is the user turn it draws: {msg:?}");
        };
        assert_eq!(uuid.as_deref(), Some(first.as_str()), "under the announcement's own id");
        assert!(
            message.content.iter().any(|block| matches!(
                block,
                forge_primitives::ContentBlock::Text { text, .. } if text == "the first prompt"
            )),
            "carrying the words the dispatch held: {message:?}",
        );
        assert!(
            drained.iter().any(|update| matches!(
                update,
                crate::protocol::SessionUpdate::PromptLifecycle { uuid, state, .. }
                    if uuid == &first && state == "started"
            )),
            "and settles the card it was waiting in: {drained:?}",
        );

        // **Every later prompt takes the dispatch fallback.** The flag is
        // known now, so the prompt is not recorded and the dispatch draws it.
        task.execute_command(Command::Prompt {
            key: key.clone(),
            text: "the second prompt".to_owned(),
            attachments: Vec::new(),
        });
        assert!(
            domain.lock().prompt_queue.is_empty(),
            "a prompt is recorded only where the CLI can settle it",
        );
        assert!(agent_rx.try_recv().is_ok(), "and it still reaches the agent");
        let later: Vec<crate::protocol::SessionUpdate> =
            std::iter::from_fn(|| updates.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
        assert!(
            !later.iter().any(|update| matches!(
                update,
                crate::protocol::SessionUpdate::PromptQueued { .. }
            )),
            "nothing is announced for a row that is not kept: {later:?}",
        );
        let drawn = later.iter().find_map(|update| match update {
            crate::protocol::SessionUpdate::ChatAppended { msg, source, .. }
                if matches!(msg, forge_primitives::Message::User { .. }) =>
            {
                Some((msg, source))
            }
            _ => None,
        });
        let Some((msg, source)) = drawn else {
            panic!("a seat that cannot follow a queue draws its row at dispatch: {later:?}");
        };
        assert_eq!(*source, Some(crate::protocol::PromptSource::You), "the reader's own send");
        let forge_primitives::Message::User { message, .. } = msg else {
            panic!("the fallback row is the user turn it draws: {msg:?}");
        };
        assert!(
            message.content.iter().any(|block| matches!(
                block,
                forge_primitives::ContentBlock::Text { text, .. }
                    if text == "the second prompt"
            )),
            "carrying the words the dispatch held: {message:?}",
        );
    }

    /// **The started row reaches every fanout subscriber, for each send.** The
    /// task emits it once; the transport's mirror and a view both get the same
    /// frame, and a second queued send draws its own row after the first.
    #[tokio::test]
    async fn a_started_row_reaches_every_fanout_subscriber_for_each_send() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "fanout-row");
        let (mut task, mut view_rx, _agent_rx) = nudge_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("fanout-session"));
        let mut mirror_rx = task.update_tx.subscribe(SubscriberRole::Observing);

        for (uuid, text) in [("fanout-1", "first send"), ("fanout-2", "second send")] {
            task.execute_command(Command::PromptUnder {
                key: slot.clone(),
                text: text.to_owned(),
                attachments: vec![forge_primitives::ImageAttachment {
                    data: "iVBORw0KGgo=".to_owned(),
                    mime_type: "image/png".to_owned(),
                }],
                uuid: uuid.to_owned(),
                source: crate::protocol::PromptSource::You,
                dispatch_id: None,
            });
        }
        for uuid in ["fanout-1", "fanout-2"] {
            task.translate_event(AgentEvent::SdkMessage {
                session_id: "fanout-session".to_owned(),
                msg: forge_primitives::Message::CommandLifecycle {
                    command_uuid: uuid.to_owned(),
                    state: "started".to_owned(),
                    uuid: format!("lifecycle-{uuid}"),
                    session_id: "fanout-session".to_owned(),
                    extras: forge_primitives::messages::Extras::new(),
                },
            });
        }

        for (name, rx) in [("a view", &mut view_rx), ("the transport's mirror", &mut mirror_rx)] {
            let mut drawn = Vec::new();
            while let Ok(frame) = rx.try_recv() {
                if let SessionUpdate::ChatAppended { msg, source, .. } = &*frame.update
                    && let forge_primitives::Message::User { uuid: Some(uuid), message, .. } = msg
                    && message
                        .content
                        .iter()
                        .any(|block| matches!(block, forge_primitives::ContentBlock::Image { .. }))
                {
                    drawn.push((uuid.clone(), *source));
                }
            }
            assert_eq!(
                drawn,
                vec![
                    ("fanout-1".to_owned(), Some(crate::protocol::PromptSource::You)),
                    ("fanout-2".to_owned(), Some(crate::protocol::PromptSource::You)),
                ],
                "{name} hears each send's row once, in order",
            );
        }
    }

    /// **Only a person's prompt draws the started row.** A machinery prompt's
    /// words ride its own forged row, and a cron fire's ride the delivery
    /// echo; a second row here would draw every delivery and the handoff
    /// brief twice.
    #[tokio::test]
    async fn a_machinery_prompt_draws_no_started_row() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "machinery-row");
        let (mut task, mut update_rx, _agent_rx) = nudge_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("machinery-session"));

        task.execute_command(Command::PromptUnder {
            key: slot.clone(),
            text: "machinery words".to_owned(),
            attachments: Vec::new(),
            uuid: "forge-1".to_owned(),
            source: crate::protocol::PromptSource::Forge,
            dispatch_id: None,
        });
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "machinery-session".to_owned(),
            msg: forge_primitives::Message::CommandLifecycle {
                command_uuid: "forge-1".to_owned(),
                state: "started".to_owned(),
                uuid: "lifecycle-forge-1".to_owned(),
                session_id: "machinery-session".to_owned(),
                extras: forge_primitives::messages::Extras::new(),
            },
        });

        let announced: Vec<SessionUpdate> = std::iter::from_fn(|| update_rx.try_recv().ok())
            .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
            .collect();
        assert!(
            !announced.iter().any(|update| matches!(
                update,
                SessionUpdate::ChatAppended {
                    msg: forge_primitives::Message::User { uuid: Some(id), .. },
                    ..
                } if id.as_str() == "forge-1"
            )),
            "a machinery prompt draws no row from the task: {announced:?}",
        );
        assert!(
            announced.iter().any(|update| matches!(
                update,
                SessionUpdate::PromptLifecycle { uuid, state, .. }
                    if uuid == "forge-1" && state == "started"
            )),
            "the lifecycle still advances: {announced:?}",
        );
    }

    /// **A refused or discarded prompt draws no row.** The CLI settles it
    /// without running: the queue entry leaves and no chat frame follows, so
    /// the pile's own ending line is the only place the words exist.
    #[tokio::test]
    async fn a_refused_or_discarded_prompt_draws_no_row() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "dropped-row");
        let (mut task, mut update_rx, _agent_rx) = nudge_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("dropped-session"));

        for (uuid, state) in [("refused-1", "refused"), ("discarded-1", "discarded")] {
            task.execute_command(Command::PromptUnder {
                key: slot.clone(),
                text: format!("{state} words"),
                attachments: Vec::new(),
                uuid: uuid.to_owned(),
                source: crate::protocol::PromptSource::You,
                dispatch_id: None,
            });
            assert_eq!(task.domain.lock().prompt_queue.len(), 1, "premise: the prompt waits");
            task.translate_event(AgentEvent::SdkMessage {
                session_id: "dropped-session".to_owned(),
                msg: forge_primitives::Message::CommandLifecycle {
                    command_uuid: uuid.to_owned(),
                    state: state.to_owned(),
                    uuid: format!("lifecycle-{uuid}"),
                    session_id: "dropped-session".to_owned(),
                    extras: forge_primitives::messages::Extras::new(),
                },
            });
            assert!(
                task.domain.lock().prompt_queue.is_empty(),
                "the settled prompt leaves the pile",
            );
            let announced: Vec<SessionUpdate> = std::iter::from_fn(|| update_rx.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
            assert!(
                !announced.iter().any(|update| matches!(
                    update,
                    SessionUpdate::ChatAppended { msg: forge_primitives::Message::User { uuid: Some(id), .. }, .. } if id.as_str() == uuid
                )),
                "a {state} prompt draws no row: {announced:?}",
            );
        }
    }

    /// **A dispatch that fails after recording draws the row and drains the
    /// card.** The prompt never reached the CLI, so no lifecycle frame is
    /// coming - the words draw over the failure, and the pile settles.
    #[tokio::test]
    async fn a_failed_dispatch_draws_the_row_and_drains_the_card() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "failed-dispatch");
        let (mut task, mut update_rx, agent_rx) = nudge_task_for(&workspace, &slot);
        task.domain.lock().session_id = Some(forge_primitives::SessionId::new("failed-session"));
        // The bridge's receiver is gone, so the prompt cannot reach the CLI.
        drop(agent_rx);

        task.execute_command(Command::PromptUnder {
            key: slot.clone(),
            text: "doomed words".to_owned(),
            attachments: Vec::new(),
            uuid: "failed-1".to_owned(),
            source: crate::protocol::PromptSource::You,
            dispatch_id: None,
        });

        assert!(
            task.domain.lock().prompt_queue.is_empty(),
            "the entry a failed dispatch leaves behind is dropped",
        );
        let announced: Vec<SessionUpdate> = std::iter::from_fn(|| update_rx.try_recv().ok())
            .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
            .collect();
        let row_at = announced
            .iter()
            .position(|update| {
                matches!(
                    update,
                    SessionUpdate::ChatAppended {
                        msg: forge_primitives::Message::User { uuid: Some(id), .. },
                        source: Some(crate::protocol::PromptSource::You),
                        ..
                    } if id == "failed-1"
                )
            })
            .expect("the failed prompt's words draw");
        let error_at = announced
            .iter()
            .position(|update| matches!(update, SessionUpdate::TurnError { .. }))
            .expect("the failure draws");
        assert!(row_at < error_at, "the words draw above the failure: {announced:?}");
        assert!(
            announced.iter().any(|update| matches!(
                update,
                SessionUpdate::PromptLifecycle { uuid, state, .. }
                    if uuid == "failed-1" && state == "started"
            )),
            "and the card settles: {announced:?}",
        );
    }

    /// **A prompt queued into an occupant that dies or is replaced settles
    /// into the pile's ending, not a forged row.** A live row would have no
    /// read carrier: the transcript keeps the enqueue attachment and no start,
    /// so a reload draws nothing. The words ride the queue announcement again
    /// and the discarded state turns the card into the ending line - the same
    /// carrier a refused or discarded prompt uses.
    #[tokio::test]
    async fn a_lost_queue_settles_each_prompt_into_the_pile_ending() {
        for replaced in [false, true] {
            let dir = tempfile::tempdir().expect("tempdir");
            let (workspace, _rx) =
                crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
            let label = if replaced { "lost-replaced" } else { "lost-failed" };
            let slot = SessionSlot::worker("TestOrg", "forge", label);
            let (mut task, mut update_rx, _agent_rx) = nudge_task_for(&workspace, &slot);
            task.domain.lock().session_id = Some(forge_primitives::SessionId::new("old-occupant"));
            task.connected_once = replaced;
            for (uuid, text) in [("lost-1", "first lost"), ("lost-2", "second lost")] {
                task.execute_command(Command::PromptUnder {
                    key: slot.clone(),
                    text: text.to_owned(),
                    attachments: Vec::new(),
                    uuid: uuid.to_owned(),
                    source: crate::protocol::PromptSource::You,
                    dispatch_id: None,
                });
            }
            while update_rx.try_recv().is_ok() {}

            let event = if replaced {
                connected_event("new-occupant", "/proj")
            } else {
                AgentEvent::ConnectionFailed {
                    message: "the child exited".to_owned(),
                    kind: forge_agent::client::SpawnFailureKind::Unclassified,
                }
            };
            task.translate_event(event);

            let announced: Vec<SessionUpdate> = std::iter::from_fn(|| update_rx.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
            let anchor = if replaced {
                announced
                    .iter()
                    .position(|update| matches!(update, SessionUpdate::SessionReplaced { .. }))
            } else {
                announced
                    .iter()
                    .position(|update| matches!(update, SessionUpdate::ConnectionFailed { .. }))
            }
            .unwrap_or_else(|| panic!("{label}: the occupant's own frame is missing"));
            for (uuid, text) in [("lost-1", "first lost"), ("lost-2", "second lost")] {
                let echoed = announced
                    .iter()
                    .position(|update| {
                        matches!(
                            update,
                            SessionUpdate::PromptQueued {
                                uuid: id,
                                source: crate::protocol::PromptSource::You,
                                text: said,
                                ..
                            } if id == uuid && said == text
                        )
                    })
                    .unwrap_or_else(|| {
                        panic!("{label}: {uuid}'s words reach the ending line: {announced:?}")
                    });
                let ended = announced
                    .iter()
                    .position(|update| {
                        matches!(
                            update,
                            SessionUpdate::PromptLifecycle { uuid: id, state, .. }
                                if id == uuid && state == "discarded"
                        )
                    })
                    .unwrap_or_else(|| panic!("{label}: {uuid}'s card settles into the ending"));
                assert!(
                    !announced.iter().any(|update| matches!(
                        update,
                        SessionUpdate::ChatAppended {
                            msg: forge_primitives::Message::User { uuid: Some(id), .. },
                            ..
                        } if id == uuid
                    )),
                    "{label}: {uuid} never draws a forged row",
                );
                // A replacement resets the page's conversation, so the ending
                // must follow it; a death is the other way round, with the
                // pile still standing as it settles.
                let ordered = if replaced {
                    echoed > anchor && ended > anchor
                } else {
                    echoed < anchor && ended < anchor
                };
                assert!(
                    ordered,
                    "{label}: the words and their settle sit with the occupant's frame"
                );
            }
        }
    }

    /// **A prompt held for a successor that never comes settles its mark.**
    /// The press never reached a model, so no lifecycle frame is coming: the
    /// composer would say "sending" for the life of the seat.
    #[tokio::test]
    async fn a_swap_that_fails_settles_the_held_prompt() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (workspace, _rx) =
            crate::Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        let slot = SessionSlot::worker("TestOrg", "forge", "held-settles");
        let (mut task, mut update_rx, _agent_rx) = nudge_task_for(&workspace, &slot);
        workspace.begin_swap(&slot);
        task.execute_command(Command::PromptUnder {
            key: slot.clone(),
            text: "held words".to_owned(),
            attachments: Vec::new(),
            uuid: "held-1".to_owned(),
            source: crate::protocol::PromptSource::You,
            dispatch_id: None,
        });

        task.translate_event(AgentEvent::ConnectionFailed {
            message: "the child never came up".to_owned(),
            kind: forge_agent::client::SpawnFailureKind::Unclassified,
        });

        let announced: Vec<SessionUpdate> = std::iter::from_fn(|| update_rx.try_recv().ok())
            .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
            .collect();
        assert!(
            announced.iter().any(|update| matches!(
                update,
                SessionUpdate::PromptLifecycle { uuid, state, .. }
                    if uuid == "held-1" && state == "cancelled"
            )),
            "the held press is settled: {announced:?}",
        );
    }

    /// The capability latch is per-occupant and re-reads.
    ///
    /// The flag and the pile go with the occupant that set them - the same
    /// drop the `Connected` arm runs - so a `/resume` onto a CLI that DOES
    /// advertise the frames gets its pile back, and one that does not cannot
    /// inherit a latched true beside rows nothing can settle. A latch that
    /// only ever wrote once would keep the pile silently off for the rest of
    /// the slot's life.
    #[tokio::test]
    async fn the_capability_latch_re_reads_on_a_new_occupant() {
        let (workspace, mut updates) = crate::Workspace::testing_stub();
        workspace.seed_test_project("latch", "/tmp/latch");
        let key = SessionSlot::from_str_for_test("latch-lead");
        let domain = Arc::new(parking_lot::Mutex::new(DomainSession::new(key.clone(), None)));
        domain.lock().session_id = Some(forge_primitives::SessionId::new("latch-session"));
        let (handle, _agent_rx) = Agent::testing_stub();
        let (_cmd_tx, command_rx) =
            tokio::sync::mpsc::unbounded_channel::<crate::protocol::Command>();
        let mut task = SessionTask {
            key: key.clone(),
            handle: Arc::new(handle),
            command_rx,
            domain: Arc::clone(&domain),
            update_tx: workspace.update_sender(),
            connected_once: false,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };

        let init = |capabilities: serde_json::Value| -> forge_primitives::Message {
            serde_json::from_value(serde_json::json!({
                "type": "system",
                "subtype": "init",
                "session_id": "latch-session",
                "capabilities": capabilities,
            }))
            .expect("parse an init frame")
        };

        // The first occupant does not advertise: the pile is off for it.
        task.translate_event(forge_agent::AgentEvent::SdkMessage {
            session_id: "latch-session".to_owned(),
            msg: init(serde_json::json!(["interrupt_receipt_v1"])),
        });
        assert_eq!(domain.lock().lifecycle_frames, Some(false), "the first init is read");

        // A new occupant: the per-occupant drop `Connected` runs.
        domain.lock().drop_background_tasks();
        assert_eq!(domain.lock().lifecycle_frames, None, "nothing has been advertised yet");
        assert!(domain.lock().prompt_queue.is_empty(), "nor is anything waiting");

        // The new occupant advertises, so its init is the first sight again -
        // and the pile works for it.
        task.translate_event(forge_agent::AgentEvent::SdkMessage {
            session_id: "latch-session".to_owned(),
            msg: init(serde_json::json!(["msg_lifecycle_v1"])),
        });
        assert_eq!(
            domain.lock().lifecycle_frames,
            Some(true),
            "the re-read is what gives the new occupant its pile",
        );

        task.execute_command(Command::Prompt {
            key: key.clone(),
            text: "recorded now".to_owned(),
            attachments: Vec::new(),
        });
        assert_eq!(
            domain.lock().prompt_queue.len(),
            1,
            "and a row is kept for a CLI that can settle it",
        );
        let announced: Vec<crate::protocol::SessionUpdate> =
            std::iter::from_fn(|| updates.try_recv().ok())
                .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                .collect();
        assert!(
            announced.iter().any(|update| matches!(
                update,
                crate::protocol::SessionUpdate::PromptQueued { text, .. } if text == "recorded now"
            )),
            "and announced: {announced:?}",
        );
    }

    /// `Command::Cancel` reaches the agent's command dispatcher.
    #[test]
    fn execute_cancel_forwards_to_handle() {
        let (handle, mut rx) = stub_handle_with_rx();
        let key = SessionSlot::from_str_for_test("sess");
        execute_command_via_handle(
            &handle,
            &key,
            Some("sess-1"),
            None,
            Command::Cancel { key: key.clone() },
        )
        .expect("dispatch succeeds");
        let cmd = rx.try_recv().expect("command queued");
        assert!(matches!(
            cmd,
            forge_primitives::AgentCommand::Cancel { session_id } if session_id == "sess-1"
        ));
    }

    /// `Command::SetMode` translates the typed `PermissionMode` back
    /// to its wire form on the way out to the bridge.
    #[test]
    fn execute_set_mode_uses_wire_form() {
        use forge_primitives::permission::PermissionMode;
        let (handle, mut rx) = stub_handle_with_rx();
        let key = SessionSlot::from_str_for_test("sess");
        execute_command_via_handle(
            &handle,
            &key,
            Some("sess-1"),
            None,
            Command::SetMode { key: key.clone(), mode: PermissionMode::Plan },
        )
        .expect("dispatch succeeds");
        let cmd = rx.try_recv().expect("command queued");
        match cmd {
            forge_primitives::AgentCommand::SetMode { session_id, mode } => {
                assert_eq!(session_id.as_str(), "sess-1");
                assert_eq!(mode, PermissionMode::Plan);
            }
            other => panic!("expected SetMode, got {other:?}"),
        }
    }

    /// `Command::Cancel` without a `session_id` (pre-Connect) logs
    /// and returns `Ok(())` rather than panicking.
    #[test]
    fn execute_command_without_session_id_is_dropped() {
        let (handle, mut rx) = stub_handle_with_rx();
        let key = SessionSlot::from_str_for_test("sess");
        let err = execute_command_via_handle(
            &handle,
            &key,
            None,
            None,
            Command::Cancel { key: key.clone() },
        )
        .expect_err("a no-session dispatch reports the drop, not Ok");
        assert!(err.to_string().contains("no active session"), "the error names the drop: {err}");
        // Nothing should have been queued.
        assert!(rx.try_recv().is_err());
    }

    fn background_tasks(tasks: Vec<serde_json::Value>) -> forge_primitives::Message {
        forge_primitives::Message::BackgroundTasksChanged {
            tasks,
            uuid: "u1".to_owned(),
            session_id: "worker".to_owned(),
            extras: serde_json::Map::new(),
        }
    }

    fn one_live_task() -> Vec<serde_json::Value> {
        vec![serde_json::json!({
            "task_id": "t1",
            "task_type": "local_bash",
            "description": "gh run watch",
        })]
    }

    /// The registry a PROCESSES view leads its rows with, with the command
    /// each task's own tool call carried: the bool alone told a view that
    /// something was running and nothing about what.
    ///
    /// The order is the CLI's own, from the capture: the card that names the
    /// command, then the registry that names the task, then `task_started`
    /// that links the two.
    #[test]
    fn the_registry_carries_each_tasks_own_command() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_backgrounded_bash("toolu_1", "gh run watch 123 --exit-status"));
        send(&mut task, background_tasks(one_live_task()));
        send(&mut task, a_task_started("t1", "toolu_1"));

        let held = task.domain.lock();
        let tasks = held.background_tasks.clone();
        assert_eq!(tasks.len(), 1, "the CLI's own entry is held: {tasks:?}");
        assert_eq!(tasks[0].task_id, "t1", "under the id the CLI gave it");
        assert_eq!(tasks[0].task_type, "local_bash", "with the kind a row routes on");
        assert_eq!(tasks[0].description, "gh run watch", "and the line the row leads with");
        assert_eq!(
            tasks[0].command.as_deref(),
            Some("gh run watch 123 --exit-status"),
            "and the command its own card carried, which the scan adopts on",
        );
        drop(held);

        send(&mut task, background_tasks(Vec::new()));
        assert!(
            task.domain.lock().background_tasks.is_empty(),
            "the whole set arrives each change, so an empty snapshot clears",
        );
    }

    /// The same link carries the CALL, the id a view jumps by: a registry row
    /// names the tool_use_id `task_started` held for its task, whichever order
    /// the two halves land in.
    #[test]
    fn the_registry_carries_the_tool_call_its_link_names() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        // Registry first, then the link - the CLI's own order.
        send(&mut task, background_tasks(one_live_task()));
        assert_eq!(
            task.domain.lock().background_tasks[0].tool_use_id,
            None,
            "before the link lands the row carries no call rather than a guess",
        );
        send(&mut task, a_task_started("t1", "toolu_1"));
        assert_eq!(
            task.domain.lock().background_tasks[0].tool_use_id.as_deref(),
            Some("toolu_1"),
            "the link fills the call once the registry is held",
        );

        // The reverse order on a fresh seat: the link first, then the snapshot.
        let key = SessionSlot::from_str_for_test("w-bg2");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        send(&mut task, a_task_started("t1", "toolu_1"));
        send(&mut task, background_tasks(one_live_task()));
        assert_eq!(
            task.domain.lock().background_tasks[0].tool_use_id.as_deref(),
            Some("toolu_1"),
            "and the snapshot fills from a link that arrived first",
        );
    }

    /// The command is held for ANY card that carries one, not only a card
    /// whose input asked to run in the background: the CLI backgrounds a bash
    /// three ways and two of them cannot show on the card, so gating on the
    /// flag left those tasks with no command - and a view that needs the
    /// command draws no row for them at all.
    #[test]
    fn a_task_backgrounded_after_its_card_still_gets_its_command() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        // The card as a foreground call leaves it: no `run_in_background`.
        send(&mut task, a_bash_card("toolu_fg", "sleep 30 && echo later", None));
        send(&mut task, background_tasks(one_live_task()));
        send(&mut task, a_task_started("t1", "toolu_fg"));

        let held = task.domain.lock().background_tasks.clone();
        assert_eq!(
            held[0].command.as_deref(),
            Some("sleep 30 && echo later"),
            "the command the task's own card carried crosses even though the card did not ask \
             for the background: the registry and the link are what scope it",
        );
    }

    /// The other half of that rule: the command a card carried is read only
    /// through a task that names it. A rostered task whose link points at a
    /// different card keeps no command, and a card no task names resolves
    /// nothing.
    #[test]
    fn a_rostered_task_reads_only_the_command_its_own_link_names() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_other", "echo unrelated", None));
        send(&mut task, a_bash_card("toolu_ours", "gh run watch 9", None));
        send(&mut task, background_tasks(one_live_task()));
        send(&mut task, a_task_started("t1", "toolu_ours"));

        let held = task.domain.lock().background_tasks.clone();
        assert_eq!(held.len(), 1, "one rostered task");
        assert_eq!(
            held[0].command.as_deref(),
            Some("gh run watch 9"),
            "the command the task's own link names, not the other card's",
        );
    }

    /// A task whose card forge never saw keeps its row and has no command:
    /// a rostered task with no recorded card still draws from its roster
    /// entry.
    #[test]
    fn a_task_with_no_card_still_carries_its_registry_row() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: background_tasks(one_live_task()),
        });

        let held = task.domain.lock();
        let tasks = held.background_tasks.clone();
        assert_eq!(tasks.len(), 1, "the roster entry is still drawn: {tasks:?}");
        assert_eq!(tasks[0].command, None, "and its command is absent rather than invented");
    }

    /// **A long foreground call is a row too.** The CLI tracks it like a
    /// backgrounded one - `task_started` when it outlives a beat, its own
    /// `task_notification` at the end - but never lists it in the registry,
    /// which is the background set. The set a view draws has to carry it in
    /// between, or a seat running a gate draws no processes at all.
    #[test]
    fn a_foreground_call_is_a_row_while_it_runs() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-fg");
        let (mut task, mut updates) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_fg", "sleep 110", None));
        send(&mut task, a_task_started("t-fg", "toolu_fg"));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 1, "the announced foreground call is a row: {held:?}");
        assert_eq!(held[0].task_id, "t-fg", "under the id the CLI gave it");
        assert!(!held[0].is_backgrounded, "and the CLI ran it in the foreground");
        assert_eq!(held[0].task_type, "local_bash", "with the kind a view routes on");
        assert_eq!(held[0].description, "gh run watch", "and the line the row leads with");
        assert_eq!(
            held[0].command.as_deref(),
            Some("sleep 110"),
            "and the command its own card carried, which the walk matches the process on",
        );
        assert_eq!(held[0].tool_use_id.as_deref(), Some("toolu_fg"), "its own reveal link");

        let announced = announced_tasks(&mut updates);
        assert_eq!(announced.len(), 1, "the update that pushes it to a view went out");
        assert_eq!(
            announced[0].iter().map(|task| task.task_id.as_str()).collect::<Vec<_>>(),
            held.iter().map(|task| task.task_id.as_str()).collect::<Vec<_>>(),
            "and it carries exactly the set the record reads, not the registry alone",
        );
    }

    /// The call's own ending frame withdraws its row, and the registry's
    /// whole-set snapshot never takes a running foreground task with it.
    #[test]
    fn a_foreground_row_is_held_across_a_snapshot_and_ends_with_its_notification() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-fg");
        let (mut task, mut updates) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_fg", "sleep 110", None));
        send(&mut task, a_task_started("t-fg", "toolu_fg"));
        send(&mut task, background_tasks(Vec::new()));

        assert_eq!(
            task.domain.lock().task_rows().len(),
            1,
            "the registry snapshot carries the background set, so it neither adds nor wipes a \
             foreground task",
        );

        send(&mut task, a_task_notification("t-fg", "completed", None));
        assert!(
            task.domain.lock().task_rows().is_empty(),
            "the notification is that call's ending, so its row leaves",
        );
        let announced = announced_tasks(&mut updates);
        assert_eq!(
            announced.last().map(Vec::len),
            Some(0),
            "and the withdrawal is pushed: {announced:?}",
        );
    }

    /// A task the registry already names is one row, not two: a backgrounded
    /// call reaches both the snapshot and `task_started`.
    #[test]
    fn a_background_task_announced_twice_is_one_row() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_backgrounded_bash("toolu_1", "gh run watch 123"));
        send(&mut task, background_tasks(one_live_task()));
        send(&mut task, a_task_started("t1", "toolu_1"));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 1, "one task, one row: {held:?}");
        assert!(
            held[0].is_backgrounded,
            "the registry's own entry is the one read, and it is backgrounded",
        );
        assert_eq!(
            held[0].command.as_deref(),
            Some("gh run watch 123"),
            "read from the registry's entry, which filled from the link",
        );
    }

    /// Background and foreground calls live at once are two rows, each saying
    /// which it is. A seat running a gate beside a backgrounded watch is this
    /// shape.
    #[test]
    fn a_background_and_a_foreground_call_live_at_once_are_two_rows() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-both");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_backgrounded_bash("toolu_bg", "gh run watch 123"));
        send(&mut task, background_tasks(one_live_task()));
        send(&mut task, a_task_started("t1", "toolu_bg"));
        send(&mut task, a_bash_card("toolu_fg", "sleep 110", None));
        send(&mut task, a_task_started("t-fg", "toolu_fg"));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 2, "two live calls, two rows: {held:?}");
        let background = held.iter().find(|row| row.task_id == "t1").expect("the registry row");
        assert!(background.is_backgrounded, "the registry row says backgrounded");
        let foreground = held.iter().find(|row| row.task_id == "t-fg").expect("the held row");
        assert!(!foreground.is_backgrounded, "the announced call says foreground");
        assert_eq!(foreground.command.as_deref(), Some("sleep 110"), "its own command");
    }

    /// One call, one row: a call the registry later names under another task
    /// id does not draw beside the hold that already had it.
    #[test]
    fn a_call_the_registry_names_under_another_task_id_is_one_row() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-call");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_shared", "sleep 60", None));
        send(&mut task, a_task_started("t-hold", "toolu_shared"));
        // The CLI restates the same call under a registry task id of its own.
        send(
            &mut task,
            background_tasks(vec![serde_json::json!({
                "task_id": "t-reg",
                "task_type": "local_bash",
                "description": "sleep 60",
            })]),
        );
        send(&mut task, a_task_started("t-reg", "toolu_shared"));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 1, "one call, one row: {held:?}");
        assert_eq!(held[0].task_id, "t-reg", "the CLI's own row is the one read");
        assert_eq!(held[0].tool_use_id.as_deref(), Some("toolu_shared"));
    }

    /// A cancelled turn settles its foreground row even though no ending frame
    /// ever comes: a foreground call cannot outlive the turn that ran it.
    #[test]
    fn a_cancelled_turn_settles_its_foreground_row() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-cancel");
        let (mut task, mut updates) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_fg", "sleep 110", None));
        send(&mut task, a_task_started("t-fg", "toolu_fg"));
        task.domain.lock().pending_cancel = true;
        send(&mut task, result_message("error_during_execution", true));

        assert!(
            task.domain.lock().task_rows().is_empty(),
            "the cancelled turn takes its own foreground hold with it",
        );
        let announced = announced_tasks(&mut updates);
        assert_eq!(
            announced.last().map(Vec::len),
            Some(0),
            "and the withdrawal is pushed: {announced:?}",
        );
    }

    /// Only a `local_bash` task is this feed's. A sub-agent's task belongs to
    /// the dispatch rows, and a frame a sub-agent produced is not the
    /// session's own row at all.
    #[test]
    fn an_agents_task_is_not_a_process_row() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-fg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(
            &mut task,
            serde_json::from_value(serde_json::json!({
                "type": "system",
                "subtype": "task_started",
                "task_id": "t-agent",
                "tool_use_id": "toolu_agent",
                "description": "a dispatched agent",
                "task_type": "local_agent",
                "uuid": "u4",
                "session_id": "worker",
            }))
            .expect("parse a local_agent task_started"),
        );
        send(
            &mut task,
            serde_json::from_value(serde_json::json!({
                "type": "system",
                "subtype": "task_started",
                "task_id": "t-sub",
                "tool_use_id": "toolu_sub",
                "description": "a sub-agent's own bash",
                "task_type": "local_bash",
                "parent_tool_use_id": "toolu_task",
                "uuid": "u5",
                "session_id": "worker",
            }))
            .expect("parse a dispatched task_started"),
        );

        assert!(
            task.domain.lock().task_rows().is_empty(),
            "neither an agent's task nor a dispatched call's belongs in the processes feed",
        );
    }

    /// A terminal `task_updated` settles the hold; a progress patch does not.
    #[test]
    fn a_terminal_task_update_settles_a_hold_and_a_progress_one_does_not() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-update");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_fg", "sleep 110", None));
        send(&mut task, a_task_started("t-fg", "toolu_fg"));

        send(&mut task, a_task_updated("t-fg", "running"));
        assert_eq!(
            task.domain.lock().task_rows().len(),
            1,
            "a progress patch states no ending, so the hold stands",
        );

        send(&mut task, a_task_updated("t-fg", "completed"));
        assert!(task.domain.lock().task_rows().is_empty(), "the terminal patch ends the hold");
    }

    /// A backgrounded hold is not the turn's to settle: the call outlives the
    /// turn that started it, and the registry is where its life is read.
    #[test]
    fn a_background_hold_survives_the_turn_end() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg-turn");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_task_started_with("t-bg", Some("toolu_bg"), true));
        task.domain.lock().pending_cancel = true;
        send(&mut task, result_message("error_during_execution", true));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 1, "the backgrounded hold outlives the turn: {held:?}");
        assert!(held[0].is_backgrounded, "and it still says so");
    }

    /// A new occupant's calls are its own: the previous CLI's holds go with
    /// it, exactly as its registry does.
    #[test]
    fn a_new_occupant_clears_the_announced_holds() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-occupant");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_fg", "sleep 110", None));
        send(&mut task, a_task_started("t-fg", "toolu_fg"));
        assert_eq!(task.domain.lock().task_rows().len(), 1, "the hold is up");

        task.translate_event(a_connected("worker-2"));
        assert!(
            task.domain.lock().task_rows().is_empty(),
            "a new occupant starts with no holds of the last one's",
        );
    }

    /// Two announcements of one call are one row even before the registry
    /// names either: the call is the identity.
    #[test]
    fn two_announcements_of_one_call_are_one_row() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-call-only");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_shared", "sleep 60", None));
        send(&mut task, a_task_started("t-one", "toolu_shared"));
        send(&mut task, a_task_started("t-two", "toolu_shared"));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 1, "one call, one row: {held:?}");
        assert_eq!(held[0].task_id, "t-one", "the first announcement holds the call");
    }

    /// A task announced with no call still draws: the row is the task's.
    #[test]
    fn a_task_with_no_call_still_draws() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bare");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_task_started_with("t-bare", None, false));

        let held = task.domain.lock().task_rows();
        assert_eq!(held.len(), 1, "a call-less task is still a row: {held:?}");
        assert_eq!(held[0].tool_use_id, None, "with no reveal link rather than a guess");
    }

    /// The ending may name the other task id: one call can be announced
    /// twice, and the frame's own call is the join.
    #[test]
    fn an_ending_frame_settles_the_hold_by_its_call_too() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-end-call");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_bash_card("toolu_shared", "sleep 60", None));
        send(&mut task, a_task_started("t-one", "toolu_shared"));
        send(&mut task, a_task_notification("t-other", "completed", Some("toolu_shared")));

        assert!(
            task.domain.lock().task_rows().is_empty(),
            "the call's own ending settles it, whichever task id it names",
        );
    }

    /// The `TaskStop` path's shape, in the wire's own order: the registry
    /// snapshot names the task BEFORE `task_started` links it (the CLI's
    /// captured order), the stop sends no ending and no registry change, and
    /// a later change to the set leaves the task out. The registry is the
    /// whole background set, so the row goes with it instead of resurfacing.
    #[test]
    fn a_background_hold_leaves_when_the_registry_stops_naming_its_task() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-stop");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        let send = |task: &mut SessionTask, msg: forge_primitives::Message| {
            task.translate_event(AgentEvent::SdkMessage { session_id: "worker".to_owned(), msg });
        };

        send(&mut task, a_backgrounded_bash("toolu_stop", "gh run watch 9"));
        send(
            &mut task,
            background_tasks(vec![serde_json::json!({
                "task_id": "t-stop",
                "task_type": "local_bash",
                "description": "a stopped watch",
            })]),
        );
        send(&mut task, a_task_started_with("t-stop", Some("toolu_stop"), true));
        assert_eq!(task.domain.lock().task_rows().len(), 1, "named while it runs");

        // The stop sends no ending and no registry change, so the only
        // evidence left is a set that stops naming the task.
        send(&mut task, background_tasks(Vec::new()));
        assert!(
            task.domain.lock().task_rows().is_empty(),
            "a backgrounded hold is the registry's to keep, and the set that leaves it out takes it",
        );
    }

    fn a_backgrounded_bash(id: &str, command: &str) -> forge_primitives::Message {
        a_bash_card(id, command, Some(true))
    }

    fn a_task_notification(
        task_id: &str,
        status: &str,
        tool_use_id: Option<&str>,
    ) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_notification",
            "task_id": task_id,
            "tool_use_id": tool_use_id,
            "status": status,
            "output_file": "",
            "summary": "done",
            "uuid": "u3",
            "session_id": "worker",
        }))
        .expect("parse a task_notification message")
    }

    /// A Bash card, with the `run_in_background` flag only when the caller
    /// says the card carried one.
    fn a_bash_card(
        id: &str,
        command: &str,
        run_in_background: Option<bool>,
    ) -> forge_primitives::Message {
        let mut input = serde_json::json!({ "command": command });
        if let Some(flag) = run_in_background {
            input["run_in_background"] = serde_json::Value::Bool(flag);
        }
        serde_json::from_value(serde_json::json!({
            "type": "assistant",
            "uuid": "a1",
            "session_id": "worker",
            "message": {
                "id": "m1",
                "role": "assistant",
                "model": "claude-opus-5",
                "content": [{
                    "type": "tool_use",
                    "id": id,
                    "name": "Bash",
                    "input": input,
                }],
            },
        }))
        .expect("parse an assistant message")
    }

    fn a_task_started(task_id: &str, tool_use_id: &str) -> forge_primitives::Message {
        a_task_started_with(task_id, Some(tool_use_id), false)
    }

    /// The same frame with the CLI's backgrounding flag as the wire carried
    /// it, and the call optional - a task can be announced with no call.
    fn a_task_started_with(
        task_id: &str,
        tool_use_id: Option<&str>,
        is_backgrounded: bool,
    ) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_started",
            "task_id": task_id,
            "tool_use_id": tool_use_id,
            "description": "gh run watch",
            "task_type": "local_bash",
            "is_backgrounded": is_backgrounded,
            "uuid": "u2",
            "session_id": "worker",
        }))
        .expect("parse a task_started message")
    }

    fn a_task_updated(task_id: &str, status: &str) -> forge_primitives::Message {
        serde_json::from_value(serde_json::json!({
            "type": "system",
            "subtype": "task_updated",
            "task_id": task_id,
            "patch": { "status": status },
            "uuid": "u6",
            "session_id": "worker",
        }))
        .expect("parse a task_updated message")
    }

    /// A fresh occupant in the same slot, which resets everything a previous
    /// CLI process owned.
    fn a_connected(session_id: &str) -> AgentEvent {
        AgentEvent::Connected {
            session_id: session_id.to_owned(),
            cwd: "/tmp/connected".to_owned(),
            current_model: forge_primitives::CurrentModel {
                resolved_id: "claude".to_owned(),
                display_name_short: "claude".to_owned(),
                display_name_long: "claude".to_owned(),
                requested_id: None,
                catalog_id: None,
                supports_effort: false,
                supported_effort_levels: Vec::new(),
                supports_auto_mode: None,
                supports_adaptive_thinking: None,
                is_authoritative: true,
            },
            available_models: Vec::new(),
            mode: None,
            history_updates: None,
            compaction_count: 0,
        }
    }

    /// The session's own registry follows the CLI's snapshot, which
    /// carries the whole set every change - so an empty one clears rather
    /// than adding to what was there.
    #[test]
    fn background_work_follows_the_cli_snapshot() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: background_tasks(one_live_task()),
        });
        assert!(
            task.domain.lock().background_work,
            "a snapshot naming a live task is background work",
        );

        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: background_tasks(Vec::new()),
        });
        assert!(
            !task.domain.lock().background_work,
            "the whole set arrives each change, so an empty snapshot clears it",
        );
    }

    /// The CLI never sends a terminal `background_tasks_changed` for a
    /// session that died, so without this the registry stays true behind a
    /// subprocess that is gone and the row spins forever.
    #[test]
    fn a_connection_failure_drops_background_work() {
        let (workspace, _rx) = crate::Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-bg-fail");
        let (mut task, _update_rx) = review_task_for(&workspace, &key);
        task.translate_event(AgentEvent::SdkMessage {
            session_id: "worker".to_owned(),
            msg: background_tasks(one_live_task()),
        });
        assert!(task.domain.lock().background_work, "precondition: the snapshot armed it");

        task.translate_event(AgentEvent::ConnectionFailed {
            message: "the subprocess exited".to_owned(),
            kind: SpawnFailureKind::Unclassified,
        });

        assert!(
            !task.domain.lock().background_work,
            "a dead subprocess has no live background work, whatever the last snapshot said",
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod connected_hook_tests {
    use super::*;
    use crate::Workspace;
    use crate::protocol::Command;
    use crate::target::ProjectKey;

    /// A project's lead slot: the label is what marks the role, so a
    /// project whose name looks worker-shaped is still a lead.
    fn lead_slot(project_name: &str) -> crate::SessionSlot {
        crate::SessionSlot::lead("TestOrg", project_name)
    }

    /// Seed `proj-x` with one persisted worker row and return the
    /// tempdir backing the store, whose lifetime must outlive the test.
    ///
    /// The project path is a real directory: a non-git worker runs in the
    /// project root, so the wave checks that root is there before
    /// re-spawning it.
    fn seed_project_with_one_worker_row(
        workspace: &Arc<Workspace>,
        label: &str,
    ) -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let project_path = dir.path().join("proj-x");
        std::fs::create_dir_all(&project_path).expect("create the project dir");
        let project_path = project_path.to_string_lossy().into_owned();
        workspace.seed_test_project("proj-x", &project_path);
        let project_key = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&project_path)),
        );
        workspace
            .record_worker_row(
                &project_key,
                label,
                &format!("{label}-test-id"),
                &format!("charter for {label}"),
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the worker row");
        dir
    }

    /// A lead Connected for a project with a persisted worker triggers
    /// one `Command::SpawnWorker` per row.
    #[test]
    fn lead_connected_with_a_worker_row_triggers_respawn() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let _db = seed_project_with_one_worker_row(&workspace, "implementer");
        workspace.enable_test_dispatch_intercept();

        on_connected_for_test(&workspace, &lead_slot("proj-x"), "lead-uuid");

        let dispatched = workspace.drain_test_dispatch_buffer();
        let spawns: Vec<&Command> =
            dispatched.iter().filter(|c| matches!(c, Command::SpawnWorker { .. })).collect();
        assert_eq!(spawns.len(), 1, "one SpawnWorker per stored worker");
    }

    /// **A closed lead does not bring its workers back.** The boot wave
    /// never spawns a closed lead, so its Connected never runs; this pins
    /// the same guarantee at the hook, so it does not rest on that alone.
    #[test]
    fn a_closed_lead_does_not_respawn_its_workers() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let _db = seed_project_with_one_worker_row(&workspace, "implementer");
        workspace.enable_test_dispatch_intercept();
        let lead = lead_slot("proj-x");
        workspace.record_session_id(lead.org(), lead.project(), lead.label(), "lead-id");
        workspace.record_seat_state(&lead, crate::store::sessions::SeatState::Closed);

        on_connected_for_test(&workspace, &lead, "lead-uuid");

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            !dispatched.iter().any(|command| matches!(command, Command::SpawnWorker { .. })),
            "the stop stands: no worker comes back for a closed lead",
        );
    }

    /// A lead Connected for a project with no persisted workers is
    /// a no-op - nothing dispatched.
    ///
    /// UNTESTED: this cannot tell the empty-set early return from
    /// falling through and iterating an empty slice, and deleting the
    /// store setup below passes too. What is hard is not the harness -
    /// `workspace::worker_respawn_tests` already has one - but that
    /// observing the skipped scan means asserting on private state or
    /// racing the spawned task. Recorded so the gap stays findable.
    #[test]
    fn lead_connected_without_a_worker_row_does_nothing() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        workspace.enable_test_dispatch_intercept();
        workspace.seed_test_project("proj-y", "/tmp/proj-y");

        on_connected_for_test(&workspace, &lead_slot("proj-y"), "lead-uuid");

        assert!(workspace.drain_test_dispatch_buffer().is_empty());
    }

    /// A worker's Connected does NOT trigger the respawn hook - the
    /// slot's label is what stops it.
    ///
    /// The project's name is the one a key-shaped parse would have read
    /// as a worker, so a reintroduced parse would classify the project
    /// itself and the hook would have to be stopped by the label alone.
    /// A persisted row is necessary for this to have teeth and is not
    /// sufficient.
    #[test]
    fn worker_connected_does_not_trigger_respawn() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        // A project named like the worker key shape the old parse read.
        let lookalike = "worker_wp_planner_abc";
        workspace.seed_test_project(lookalike, "/tmp/wp");
        let project_key = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some("/tmp/wp")),
        );
        workspace
            .record_worker_row(
                &project_key,
                "planner",
                "planner-test-id",
                "charter for planner",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the worker row");
        workspace.enable_test_dispatch_intercept();

        let worker = crate::SessionSlot::worker("TestOrg", lookalike, "planner");
        on_connected_for_test(&workspace, &worker, "worker-uuid");

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().all(|c| !matches!(c, Command::SpawnWorker { .. })),
            "a worker's own Connected does not respawn the team",
        );
    }

    /// Idempotency: a second Connected event for the same lead must
    /// not double-spawn. The first call inserts WorkerEntries into
    /// `live_workers`; the second call's `list_live_workers(...).is_empty()`
    /// gate trips and the trigger no-ops.
    #[test]
    fn second_lead_connected_does_not_double_spawn() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let _db = seed_project_with_one_worker_row(&workspace, "implementer");
        workspace.enable_test_dispatch_intercept();

        let lead = lead_slot("proj-x");

        // First Connected: triggers the respawn (1 SpawnWorker).
        on_connected_for_test(&workspace, &lead, "lead-uuid");
        let after_first = workspace.drain_test_dispatch_buffer();
        let first_spawns: usize =
            after_first.iter().filter(|c| matches!(c, Command::SpawnWorker { .. })).count();
        assert_eq!(first_spawns, 1, "first Connected respawns the workers");

        // Simulate the workers having become live (the production
        // flow does this via `handle_spawn_worker`'s
        // `insert_live_worker`; the test intercept skipped that
        // path so we seed it manually for the idempotency gate).
        let project_key = workspace.project_key_for_name("proj-x").expect("seeded project");
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "implementer".into(),
                charter: "test".into(),
                slot: SessionSlot::from_str_for_test("worker-uuid"),
                session_id: None,
                status: forge_primitives::WorkerLiveness::Running,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::from_str_for_test("lead-uuid"),
                needs_tag: false,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );

        // Second Connected: gate trips, no new SpawnWorker.
        on_connected_for_test(&workspace, &lead, "lead-uuid");
        let after_second = workspace.drain_test_dispatch_buffer();
        let second_spawns: usize =
            after_second.iter().filter(|c| matches!(c, Command::SpawnWorker { .. })).count();
        assert_eq!(second_spawns, 0, "second Connected must not double-spawn");
    }

    /// Helper: insert a live ad-hoc worker carrying `kick` under the
    /// seeded project, returning its slot for `on_connected_for_test`.
    #[cfg(test)]
    fn seed_adhoc_worker_with_kick(
        workspace: &Arc<Workspace>,
        label: &str,
        kick: Option<String>,
    ) -> crate::SessionSlot {
        workspace.seed_test_project("forge", "/tmp/forge");
        let project_key = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project present")
            .key;
        let slot = crate::SessionSlot::worker("TestOrg", "forge", label);
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: label.to_owned(),
                charter: "ad-hoc".into(),
                slot: slot.clone(),
                session_id: None,
                status: forge_primitives::WorkerLiveness::Running,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: crate::SessionSlot::lead("TestOrg", "forge"),
                needs_tag: false,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick,
            },
        );
        slot
    }

    /// A worker spawned with `agents__spawn(kick=...)` gets that kick
    /// delivered as its first turn, verbatim, through the rate-limited
    /// dispatcher.
    #[tokio::test(start_paused = true)]
    async fn worker_with_inline_kick_dispatches_it_as_first_turn() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        let synth = seed_adhoc_worker_with_kick(
            &workspace,
            "scratch",
            Some("Begin: triage the failing test now.".into()),
        );

        on_connected_for_test(&workspace, &synth, "worker-uuid");
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let dispatched = workspace.drain_test_dispatch_buffer();
        let prompts: Vec<&Command> = dispatched
            .iter()
            .filter(|c| matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. }))
            .collect();
        assert_eq!(prompts.len(), 1, "inline-kick worker gets exactly one kick");
        if let Command::Prompt { key, text, .. } | Command::PromptUnder { key, text, .. } =
            prompts[0]
        {
            assert_eq!(key, &synth, "kick targets the worker's own slot");
            assert_eq!(
                text, "Begin: triage the failing test now.",
                "inline kick delivered verbatim",
            );
        }
    }

    /// A boot spawn that resumed a lead hands the restart note to the
    /// Connected hook, which kicks it once as the lead's first turn. The
    /// hook takes the note, so a reconnect repeats nothing; a worker slot
    /// never takes a lead's note.
    #[tokio::test(start_paused = true)]
    async fn a_lead_restart_note_is_kicked_once_and_only_for_a_lead() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        let lead = lead_slot("proj-x");
        let mut domain = DomainSession::new(lead.clone(), None);
        domain.pending_lead_resume_note = Some("continue where you left off".to_owned());
        let domain = Mutex::new(domain);

        maybe_kick_lead_on_connected(&workspace, &lead, &domain);
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let dispatched = workspace.drain_test_dispatch_buffer();
        let prompts: Vec<&Command> = dispatched
            .iter()
            .filter(|c| matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. }))
            .collect();
        assert_eq!(prompts.len(), 1, "a resumed lead is kicked exactly once");
        if let Command::Prompt { key, text, .. } | Command::PromptUnder { key, text, .. } =
            prompts[0]
        {
            assert_eq!(key, &lead, "the note targets the lead's own slot");
            assert_eq!(text, "continue where you left off", "the note arrives verbatim");
        }

        maybe_kick_lead_on_connected(&workspace, &lead, &domain);
        let worker = crate::SessionSlot::from_str_for_test("w");
        let mut worker_domain = DomainSession::new(worker.clone(), None);
        worker_domain.pending_lead_resume_note = Some("never delivered".to_owned());
        maybe_kick_lead_on_connected(&workspace, &worker, &Mutex::new(worker_domain));
        // The dispatcher fires one kick per interval, so the clock has to
        // move before a second enqueue can reach the buffer: without the
        // advance, a hook that left the note in place would read as clean.
        tokio::time::advance(std::time::Duration::from_secs(2)).await;
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;
        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "a reconnect after the note was taken and a worker slot deliver nothing",
        );
    }

    /// #695: the same inline kick with an underscore in the label as the
    /// only variable. `worker_with_inline_kick_dispatches_it_as_first_turn`
    /// above is the control - same fixture, same seed, plain label - which
    /// is what makes a failure here mean the label rather than the harness.
    #[tokio::test(start_paused = true)]
    async fn worker_with_an_underscore_label_dispatches_its_kick() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        let synth = seed_adhoc_worker_with_kick(
            &workspace,
            "code_review",
            Some("Begin: review the open diff.".into()),
        );

        on_connected_for_test(&workspace, &synth, "worker-uuid");
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let dispatched = workspace.drain_test_dispatch_buffer();
        let prompts: Vec<&Command> = dispatched
            .iter()
            .filter(|c| matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. }))
            .collect();
        assert_eq!(prompts.len(), 1, "an underscore-labelled worker gets its kick");
        if let Command::Prompt { text, .. } | Command::PromptUnder { text, .. } = prompts[0] {
            assert_eq!(text, "Begin: review the open diff.", "the kick arrives verbatim");
        }
    }

    /// A live worker whose entry carries no kick gets none - it idles
    /// until the lead sends an agents__send_message.
    #[tokio::test(start_paused = true)]
    async fn worker_without_inline_kick_for_adhoc_label_does_not_kick() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        let synth = seed_adhoc_worker_with_kick(&workspace, "scratch", None);

        on_connected_for_test(&workspace, &synth, "worker-uuid");
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let dispatched = workspace.drain_test_dispatch_buffer();
        let prompts: Vec<&Command> = dispatched
            .iter()
            .filter(|c| matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. }))
            .collect();
        assert!(prompts.is_empty(), "a live entry carrying no kick gets none");
    }

    /// A label with no live `WorkerEntry` of its own gets no kick, even
    /// when the project has a live worker holding one. The other entry
    /// is what gives this teeth: with an empty project the lookup has
    /// nothing to wrongly return. The drainer has to be running too -
    /// without it a mis-delivered kick only reaches the queue, and the
    /// dispatch buffer stays empty for the wrong reason.
    #[tokio::test(start_paused = true)]
    async fn worker_connected_for_an_unmatched_label_does_not_take_another_workers_kick() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        // One live worker, carrying a kick, under a DIFFERENT label.
        seed_adhoc_worker_with_kick(&workspace, "other", Some("not yours".into()));
        // A label with no entry of its own, in the same project.
        let other_label = crate::SessionSlot::worker("TestOrg", "forge", "scratchpad");

        on_connected_for_test(&workspace, &other_label, "worker-uuid");
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched
                .iter()
                .all(|c| !matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. })),
            "a label with no entry of its own must not be handed another worker's kick",
        );
    }

    /// The guard directly, with no preconditions to decay: a lead key
    /// A label may contain underscores, and the kick hook matches on the
    /// label as a whole string rather than on any parse of it.
    #[tokio::test(start_paused = true)]
    async fn a_worker_label_with_an_underscore_keeps_its_kick() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        let slot = seed_adhoc_worker_with_kick(&workspace, "code_review", Some("go".into()));

        on_connected_for_test(&workspace, &slot, "worker-uuid");
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|c| matches!(
                c, Command::Prompt { text, .. } | Command::PromptUnder { text, .. }
                    if text == "go"
            )),
            "an underscore in the label must not cost the kick: {dispatched:?}",
        );
    }
}