forge_workspace/

workspace.rs

//! The orchestrator.

use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use anyhow::Result;
use forge_agent::AgentHandle;
use forge_agent::client::SessionLaunchSettings;
use forge_agent::env::cli_version::CliVersionInfo;
use forge_primitives::cloud::service_status::ServiceIssue;
use forge_primitives::settings::{SettingsEditOp, SettingsEditRequest};
use forge_primitives::tasks::TaskId;
use forge_primitives::{AvailableAgent, AvailableCommand, Message, SDKSessionInfo, SessionId};
use std::io::Write as _;

use crate::gotify::GotifySubsystem;
use crate::mcp::peers::types::{MessageId, WrappedKind, WrappedPrompt};
use parking_lot::Mutex;
use tokio::sync::mpsc;
use tracing::Instrument;

/// `path` with its longest existing prefix resolved through symlinks and the
/// rest kept as spelled: `canonicalize` fails wholesale once the last
/// component is gone, and the two sides of a comparison then use different
/// spellings of the same directory.
fn resolve_existing_prefix(path: &Path) -> PathBuf {
    if let Ok(resolved) = std::fs::canonicalize(path) {
        return resolved;
    }
    let mut missing = Vec::new();
    let mut head = path.to_path_buf();
    while let Some(parent) = head.parent().map(Path::to_path_buf) {
        let Some(name) = head.file_name() else { break };
        missing.push(name.to_owned());
        if let Ok(resolved) = std::fs::canonicalize(&parent) {
            let mut out = resolved;
            for part in missing.iter().rev() {
                out.push(part);
            }
            return out;
        }
        head = parent;
    }
    path.to_path_buf()
}

/// Why a settings save did not write.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SettingsSaveError {
    /// The file's raw text moved since the page loaded it.
    Stale,
    /// An edit or the candidate failed validation. `key_path` anchors the
    /// first edit that fails on its own, where one does.
    Invalid { message: String, key_path: Option<String> },
    /// A guard refused the save. `key_path` anchors the refusal at one of the
    /// save's keys where the guard names one.
    Refused { message: String, key_path: Option<String> },
    /// The file could not be read or written.
    Io(String),
}

impl std::fmt::Display for SettingsSaveError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Stale => f.write_str("forge.toml has changed since this page loaded it"),
            Self::Invalid { message, .. } | Self::Refused { message, .. } | Self::Io(message) => {
                f.write_str(message)
            }
        }
    }
}

impl From<crate::settings_write::WriteError> for SettingsSaveError {
    fn from(error: crate::settings_write::WriteError) -> Self {
        Self::Invalid { message: error.message, key_path: error.key_path }
    }
}

/// The state a spawn marks its seat with: open, no turn in flight. The
/// rollback restores only while the row still holds it, so a close landing
/// mid-spawn is never undone.
const SPAWNED_SEAT_STATE: crate::store::sessions::SeatState =
    crate::store::sessions::SeatState::Idle;

/// Undo a spawn's own side effects when it is refused before the session is
/// pooled: the id it recorded, the seat state it moved, and a domain handle
/// it created. Armed from the id record to the pool insert; an unarmed guard
/// does nothing, so the pooled and refused paths both end in a plain drop.
struct SpawnRollback {
    workspace: Arc<Workspace>,
    slot: SessionSlot,
    stored: Option<String>,
    prior_seat_state: Option<crate::store::sessions::SeatState>,
    domain_created: bool,
    armed: bool,
}

impl Drop for SpawnRollback {
    fn drop(&mut self) {
        if !self.armed {
            return;
        }
        if self.domain_created {
            self.workspace.domain_handles.lock().remove(&self.slot);
        }
        self.workspace.forget_spawn_id(&self.slot, self.stored.as_deref());
        self.workspace.restore_seat_state(&self.slot, self.prior_seat_state, SPAWNED_SEAT_STATE);
    }
}

/// The project pairs and account names a batch leaves behind, read off the
/// batch and the loaded document rather than a second load: a removal drops
/// an entry, and a set on one of the naming fields renames it. The loaded
/// candidate is checked again after validation, so a shape this misses is
/// still caught.
fn departures_from_edits(
    before: &LoadedConfig,
    edits: &[SettingsEditRequest],
    document: &forge_primitives::SettingsDocument,
) -> (HashSet<(String, String)>, HashSet<String>) {
    let mut projects: HashSet<(String, String)> =
        before.projects.iter().map(|project| (project.org.clone(), project.name.clone())).collect();
    let mut accounts: HashSet<String> =
        before.accounts.iter().map(|account| account.display_name.clone()).collect();
    let row =
        |path: &str| document.areas.iter().flat_map(|area| &area.keys).find(|key| key.path == path);
    let pattern_of = |edit: &SettingsEditRequest| {
        if edit.pattern.is_empty() {
            row(&edit.key_path).map(|key| key.pattern.clone())
        } else {
            Some(edit.pattern.clone())
        }
    };
    // **The writer applies renames last**, so the simulation does too - a
    // batch that removes one entry and renames another into its place is
    // legitimate, and applying the rename first reads both as departures.
    let mut rest = Vec::new();
    let mut nested_renames = Vec::new();
    let mut entry_renames = Vec::new();
    for edit in edits {
        match pattern_of(edit) {
            Some(pattern) if pattern == "orgs[].projects[].name" => nested_renames.push(edit),
            Some(pattern)
                if matches!(
                    pattern.as_str(),
                    "orgs[].name" | "accounts[].display_name" | "slack[].workspace"
                ) =>
            {
                entry_renames.push(edit);
            }
            _ => rest.push(edit),
        }
    }
    for edit in rest.into_iter().chain(nested_renames).chain(entry_renames) {
        if edit.op == SettingsEditOp::Remove && edit.pattern.is_empty() {
            if edit.area == "accounts" {
                if let Some(name) = edit.key_path.strip_prefix("accounts.") {
                    accounts.remove(name);
                }
            } else if edit.area == "projects"
                && let Some(project) = before.projects.iter().find(|project| {
                    edit.key_path == format!("orgs.{}.projects.{}", project.org, project.name)
                })
            {
                projects.remove(&(project.org.clone(), project.name.clone()));
            }
            continue;
        }
        if edit.op != SettingsEditOp::Set {
            continue;
        }
        let pattern = if edit.pattern.is_empty() {
            row(&edit.key_path).map(|key| key.pattern.clone())
        } else {
            Some(edit.pattern.clone())
        };
        let Some(pattern) = pattern else { continue };
        let Some(key) = row(&edit.key_path) else { continue };
        let renamed = edit.value.as_ref().and_then(serde_json::Value::as_str);
        match pattern.as_str() {
            "orgs[].projects[].name" => {
                if let (Some(org), Some(project)) = (key.group.first(), key.group.get(1)) {
                    projects.remove(&(org.clone(), project.clone()));
                    if let Some(name) = renamed {
                        projects.insert((org.clone(), name.to_owned()));
                    }
                }
            }
            "orgs[].name" => {
                if let (Some(org), Some(name)) = (key.group.first(), renamed) {
                    let moved: Vec<(String, String)> =
                        projects.iter().filter(|(held, _)| held == org).cloned().collect();
                    for (_, project) in moved {
                        projects.remove(&(org.clone(), project.clone()));
                        projects.insert((name.to_owned(), project));
                    }
                }
            }
            "accounts[].display_name" => {
                if let Some(old) = key.group.first() {
                    accounts.remove(old);
                    if let Some(name) = renamed {
                        accounts.insert(name.to_owned());
                    }
                }
            }
            _ => {}
        }
    }
    (projects, accounts)
}

/// Replace `path` with `contents` through a temp file in the same directory:
/// a reader sees the old file or the new one, never a half-written one, and
/// the config watcher's re-arm survives the rename.
///
/// **The temp never widens the file.** It is created 0600 and takes the
/// destination's mode before the rename: `forge.toml` holds every account,
/// Slack, Gotify and System One token, and a save must keep whatever mode the
/// operator gave it. A symlinked path is written through to its target, so a
/// save cannot replace the link with a regular file.
/// Why a config write did not land.
#[derive(Debug)]
enum WriteRefusal {
    /// The file moved after the page's fingerprint was checked.
    Stale,
    Io(std::io::Error),
}

fn write_atomically(
    path: &Path,
    contents: &str,
    expected: Option<&str>,
) -> Result<(), WriteRefusal> {
    let target = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
    let directory = target.parent().unwrap_or_else(|| Path::new("."));
    let temporary = directory.join(format!(".forge.toml.settings-{}", std::process::id()));
    let outcome = (|| {
        let mut options = std::fs::OpenOptions::new();
        options.write(true).create(true).truncate(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt as _;
            options.mode(0o600);
        }
        let mut file = options.open(&temporary).map_err(WriteRefusal::Io)?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt as _;
            let mode = std::fs::metadata(&target).map_or(0o600, |meta| meta.permissions().mode());
            file.set_permissions(std::fs::Permissions::from_mode(mode))
                .map_err(WriteRefusal::Io)?;
        }
        file.write_all(contents.as_bytes()).map_err(WriteRefusal::Io)?;
        file.sync_all().map_err(WriteRefusal::Io)?;
        // **The file may have moved since the page's fingerprint was
        // checked.** Reading it here, after the temp is written and before
        // the rename, is the last moment the check can run.
        if let Some(expected) = expected {
            let current = std::fs::read_to_string(&target).map_err(WriteRefusal::Io)?;
            if crate::config::fingerprint_of(&current) != expected {
                return Err(WriteRefusal::Stale);
            }
        }
        std::fs::rename(&temporary, &target).map_err(WriteRefusal::Io)?;
        // **The rename already landed.** A directory fsync that fails leaves
        // the file replaced and only its durability unknown, so the save is
        // not reported as failed for it.
        if let Ok(held) = std::fs::File::open(directory)
            && let Err(error) = held.sync_all()
            && error.kind() != std::io::ErrorKind::InvalidInput
        {
            tracing::warn!(
                path = %target.display(),
                %error,
                "the config's directory could not be synced after the rename",
            );
        }
        Ok(())
    })();
    if outcome.is_err() {
        let _ = std::fs::remove_file(&temporary);
    }
    outcome
}

use forge_gateway::AccountKey;
use forge_gateway::ProviderHost as _;

use crate::config::{ConfigReload, LoadedConfig, LoadedProject, load_from_dir};
use crate::domain_session::DomainSession;
use crate::error::WorkspaceError;
use crate::protocol::{Command, DispatchError, NoticeSeverity, PromptSource, SessionUpdate};
use crate::session_task::SessionTask;
use crate::spawn;
use crate::target::{ProjectKey, SessionSlot, SessionTarget};
use crate::update_fanout::{SeatUpdate, SubscriberRole, UpdateFanout};
use crate::views::{AccountLoadingRow, ProjectView, SessionView};

#[cfg(any(test, feature = "testing"))]
pub(crate) mod testing;

/// How often the claude version probe re-runs after the boot fetch.
/// Versions change rarely, so a few minutes is ample - the point is only
/// to recover a transient boot failure, not to track releases tightly.
const CLI_VERSION_REFRESH_INTERVAL: Duration = Duration::from_secs(300);

/// The CLI's model-slot variables: the project's `model` key is
/// stamped into all of them at spawn, so one model serves the main
/// loop, subagents and background slots alike.
const MODEL_SLOT_VARIABLES: [&str; 5] = [
    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
    "ANTHROPIC_DEFAULT_OPUS_MODEL",
    "ANTHROPIC_DEFAULT_SONNET_MODEL",
    "ANTHROPIC_SMALL_FAST_MODEL",
    "CLAUDE_CODE_SUBAGENT_MODEL",
];

/// The env the CLI takes its auto-compaction window from: the `[models]`
/// table's `auto_compact_window` is stamped here for the project's model.
const AUTO_COMPACT_WINDOW_ENV: &str = "CLAUDE_CODE_AUTO_COMPACT_WINDOW";

/// A project's walk blocked by a rotation cooldown, as the walk's own
/// `BudgetExhausted` reports it.
pub(crate) struct ProjectCooling {
    pub(crate) org: String,
    pub(crate) model: String,
    pub(crate) tried: usize,
    pub(crate) reset_in: Duration,
}

/// Max attempts for `tag_session_with_retry` to find the worker's
/// `<session_id>.jsonl` and append the tag row. claude CLI writes the
/// file lazily on the first user turn - workers with an `initial_prompt`
/// usually land within ~100 ms-2 s of `Connected`. 30 attempts at
/// 100 ms = ~3 s wall caps the window generously without burning
/// resources. Idle-spawned workers (no prompt) never produce a JSONL
/// at all until the first `DeliverWorkerPrompt`; for those we exit
/// the retry with `Io(NotFound)`, mark the entry `needs_tag = true`,
/// and retry opportunistically when the first turn arrives.
const WORKER_TAG_RETRY_ATTEMPTS: u32 = 30;

/// Delay between `tag_session` retry attempts when the JSONL is not
/// yet on disk. 100 ms is short enough to land within one or two ticks
/// of claude's first write and large enough that 30 retries cap the
/// total wait at a few seconds.
const WORKER_TAG_RETRY_DELAY: Duration = Duration::from_millis(100);

/// Minimum gap between successive worker-kick dispatches (#259).
/// Multi-worker teams hit Anthropic's per-IP burst limit when all
/// `maybe_kick_worker_on_connected` paths fire `Command::Prompt`
/// within the same tick at boot; routing every kick through a
/// workspace-level mpsc + a drainer task that sleeps this interval
/// between sends spreads them out enough to avoid the burst
/// rejection. The first kick in an empty channel fires with zero
/// added latency; only subsequent kicks pay the sleep. Worst case
/// at typical team sizes (7-10 workers) is ~5-7 s to fully kick
/// the cohort, vs ~1 s pre-#259 with most kicks rejected.
const KICK_DISPATCH_INTERVAL: Duration = Duration::from_millis(750);

/// The words a continued seat's model receives, and what the row says to
/// whoever reads it: forge is the one that resumed the turn, and the work
/// already done is not to be repeated.
fn auto_continue_prompt(reason: &str) -> String {
    format!(
        "forge continued this session automatically after the previous turn failed: {reason}. \
Pick up exactly where you stopped - everything completed before the failure is in the history \
above, so do not restart the task, and do not repeat any step, tool call or side effect that \
already completed."
    )
}

/// Delegation block appended to a Lead session's system prompt.
///
/// Lead-only: `agents__spawn` refuses a worker caller, so a worker
/// given this block would be told to call a tool that rejects it.
///
/// Matches the shipped-prompt constants in `forge-agent`: one escaped
/// literal, no runtime assembly.
const LEAD_DELEGATION_PREAMBLE: &str = "\
You can delegate work to worker sessions via the \
mcp__forge__agents__ tools. Spawn one with \
agents__spawn(label=\"<name>\", charter=\"<its mission>\") - the charter \
is required and is what defines that worker; talk to it with \
agents__send_message; list your live workers with agents__list; \
revise a worker's stored charter or kicks with agents__update, which \
takes effect on its next restart. agents__spawn always creates the \
worker in YOUR project. The same family reaches other projects' \
agents: a message takes an org and project, plus a label to name a \
worker rather than that project's own agent. At most one live worker \
exists per label - if it already exists, message it instead of \
spawning again. Run independent pieces in parallel, up to the \
project's capacity; a merge conflict is not, by itself, a reason to \
hold a piece - start it, resolve the conflict and re-run the gates. \
Only genuine shared-state ordering serializes: one in-flight migration \
sequence, main's merge queue, a release/version line. Before you park \
a dispatch decision - spawn now, queue behind a worker, or inline - \
decide whether the options genuinely differ; when they do, put the \
enumerated options and the context that bears on them to \
systemone__ask_choice when your tools include it, and without it \
decide it yourself. Either way, report the decision where the work is \
reported. \
Spawned workers are durable: they survive forge restarts and re-spawn \
automatically, resuming where they left off, until you explicitly \
despawn them with agents__despawn (or close their row in the Projects \
pane). Despawn a worker once its work is truly done, otherwise it keeps \
coming back on every restart. A PR review loop \
fans out as ephemeral in-session subagents, not workers - a reviewer \
spawned as a worker lingers as a durable row and worktree after its \
round ends. Give each worker the whole cut to land. A work cut - one \
feature, one issue, one fix - lands whole: one branch, one review, one \
look, one merge. Never slice it into pieces that land one after \
another, and never show or merge an intermediate step on the way. \
The look is the one that cut is owed: a feature waits for the user's \
own look before merge; a fix merges after the review loop as usual. A \
plan, spec or design the user must review reaches them through \
`documents__hand_off` with `reviewable: true`, never as a path in \
chat. Workers build; subagents review, unless the user wants a \
reviewer kept on as a long-lived worker.";

/// Forge-supplied resume kick for a worker whose row carries no
/// `resume_kick` of its own. On a resuming re-spawn forge delivers this
/// constant as the worker's first turn - telling it to continue rather
/// than start the task over.
pub(crate) const DYNAMIC_WORKER_RESTART_NOTE: &str = "This session was restarted by forge. Your prior conversation and progress are in the history above. Continue where you left off; do not restart the task. If the history's timestamps disagree with the clock and the live schedules, believe the clock and the schedules, and still do the concrete asks.";

/// The first turn a boot spawn delivers to a lead it hands a stored
/// session id to. A lead has no kick of its own, so this note is what
/// turns a resumed conversation into work continued rather than a seat
/// idle at a prompt. The handoff and the board are the source of what
/// was in flight: a `--resume` that the CLI refuses falls back to a
/// fresh session, so the history is named conditionally rather than
/// relied on.
pub const LEAD_RESTART_NOTE: &str = "forge restarted. Read the project handoff (`handoff.md` in the project's memory directory) and the task board before acting; they say what was in flight. Continue that work and do not restart what is finished. If a prior conversation is in the history above, treat it as the record of this seat's last run. The last turn was interrupted, so its final tool call may not have completed - check the state before continuing. Anything you sent before the restart may not have arrived; confirm it did before relying on it. If the history's timestamps disagree with the clock and the live schedules, believe the clock and the schedules.";

/// One project a boot opens, and the kick its last state earns: the
/// restart note when a turn was cut off, nothing when the seat was parked.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BootWaveTarget {
    pub project_name: String,
    pub resume_kick: Option<String>,
}

/// The restart note a boot spawn hands its seat: only a spawn carrying a
/// stored id to resume delivers one, so a first boot or `--new` clears
/// whatever a previous spawn left. A resume the CLI refuses still takes
/// the note, whose wording does not depend on history.
fn resume_kick_for(resumed: bool, requested: Option<String>) -> Option<String> {
    if resumed { requested } else { None }
}

/// One enqueue onto the workspace-level worker-kick channel
/// (#259). Built by `maybe_kick_worker_on_connected` and
/// `maybe_kick_lead_on_connected` (and any future kick site); drained by
/// the workspace's
/// `start_kick_dispatcher` task, which fires one `Command::Prompt`
/// per `KICK_DISPATCH_INTERVAL` tick. Same payload shape as the
/// existing `Command::Prompt` carries (no attachments are ever
/// part of a kick prompt - kicks are pure text).
#[derive(Debug)]
pub(crate) struct KickRequest {
    pub slot: SessionSlot,
    pub prompt_body: String,
}

/// Per-session chip the Projects pane renders next to each row.
/// Carries the assigned account display name + the visual-state
/// category derived by `Workspace::session_chip_for`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct SessionChipInfo {
    /// Account `display_name` from forge.toml `[[accounts]]`.
    pub account_name: String,
    /// Render category: drives the chip's color + optional prefix
    /// glyph.
    pub state: SessionChipState,
}

/// Visual category for a session chip. The renderer maps these to
/// foreground colors + (for `Bailed` alone) a leading `⚠ ` glyph.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionChipState {
    /// Account is Ready and within budget. DIM foreground.
    Normal,
    /// Account is Ready but at least one usage window (5h or weekly)
    /// is currently at the cap. Yellow foreground signals "still
    /// spawns but expect throttling until the window resets." When
    /// every account that declares the model is capped the walk takes
    /// one anyway, so the chip shows this state.
    AtCap,
    /// Account Bailed on an auth failure (rejected or expired
    /// credentials). Red foreground + `⚠ ` prefix; the repair is an
    /// env edit plus a restart.
    Bailed,
    /// Account Bailed on a transient failure (rate limit, unreachable
    /// endpoint, malformed response). Warning yellow, no glyph - the
    /// same split the account rows render; the pollers heal it.
    Degraded,
    /// Every account serving the project is inside a rotation cooldown, so
    /// a spawn is refused until the soonest reset. Unlike `AtCap` the walk
    /// will not take this account now; the window that is spent and when
    /// it lifts come from the account's own reading.
    RateLimited,
}

/// What a session is waiting on a person for. The kind a needs-you row
/// names, since "asked you a question" and "a permission prompt is
/// waiting" are different asks with the same mark.
///
/// **One variant per ask source, and every source is here.** A question and
/// a permission park in the session's pending set; a Slack draft, the
/// browser, terminal and document hand-offs, a settings write and a vault
/// call each park in a registry of the workspace's own. The split between
/// those places is what let a terminal hand-off draw in the dock and mark
/// nothing (#2954), the third time a kind was missed;
/// [`Workspace::pending_interaction`] reads every source through one order.
/// A new ask kind fails the build in the guard test's census until it is
/// named there, and the census is what parks one of each and asserts the
/// needs-you path answers it - so a kind cannot be named without being
/// covered.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PendingInteractionKind {
    Question,
    Permission,
    SlackDraft,
    BrowserHandOff,
    TerminalHandOff,
    DocumentHandOff,
    SettingsWrite,
    Vault,
}

/// The dedupe key for a delivered Slack message: one destination is
/// (project, owner, conversation, ts, edited), so a lead and a worker in
/// one project never starve each other as "already delivered". The edit
/// ts is part of the identity because an edit keeps the message's own
/// `ts`: without it a correction reads as a re-run of the delivery it
/// corrects and never reaches the session.
pub(crate) type SlackDeliveryKey = (String, Option<String>, String, String, Option<String>);

/// Multi-session orchestrator. Owns the project catalog snapshot
/// loaded from `<config_dir>/forge.toml` and the pool of currently
/// One composed Slack message held for a decision: the session that asked,
/// the draft itself, and the sender the blocked Slack handler awaits.
///
/// The draft rides beside the sender for the same reason the permission and
/// question requests do - the stream carries it once, so a view that attached
/// after it landed has nothing else to draw the dock from.
pub(crate) type ParkedSlackDraft = (
    SessionSlot,
    forge_primitives::slack::SlackDraft,
    tokio::sync::oneshot::Sender<forge_primitives::slack::SlackDraftAnswer>,
);

/// One parked browser hand-off: the session that asked, the hand-off itself,
/// and the sender the blocked `browser_hand_off` handler awaits.
///
/// It rides beside the sender for the same reason the Slack draft does - the
/// update carries it once, so a view that attached after it landed has nothing
/// else to draw the dock from - and the sender is what makes the wait end: no
/// clock ends it, only an answer, or the handler's own drop.
pub(crate) type ParkedBrowserHandOff = (
    SessionSlot,
    forge_primitives::browser::HandOff,
    tokio::sync::oneshot::Sender<forge_primitives::browser::HandOffEnding>,
);

/// One parked terminal hand-off: the session that asked, the hand-off itself,
/// and the sender the blocked `terminal__hand_off` handler awaits. No clock
/// ends it - only an answer, or the handler's own drop.
pub(crate) type ParkedTerminalHandOff = (
    SessionSlot,
    forge_primitives::terminal::TerminalHandOff,
    tokio::sync::oneshot::Sender<forge_primitives::browser::HandOffEnding>,
);

/// A seat's occupant that died, held until a reader has been shown the
/// seat AND the recovery has announced itself - so a crash nobody watched
/// is still readable when someone looks, and the recovery that answers it
/// is announced exactly once. The two are spent independently: showing the
/// seat takes the row's trace, and the connect takes the announcement,
/// whichever comes first.
struct SeatDeath {
    /// The session that ended.
    occupant: SessionId,
    /// What the seat's failure said when it died, which the row keeps
    /// drawing after the recovering connect clears the failure itself.
    reason: String,
    /// Whether the recovery's connect has announced it already.
    announced: bool,
    /// Whether a reader has been shown the seat since.
    shown: bool,
}

/// Where a dead seat's heal has got to while it is between attempts: the
/// attempt number the row names, and when the next one fires.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct HealProgress {
    pub attempt: u32,
    pub next_at: SystemTime,
}

/// Which operation holds a composed path. Re-entrancy needs the same
/// owner AND the same operation, so a despawn cannot slip into a resume's
/// claim on one label and delete the tree that resume already ensured.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum WorktreeOp {
    Spawn,
    Despawn,
}

#[derive(Debug, Clone)]
struct WorktreeClaim {
    project_key: ProjectKey,
    label: String,
    op: WorktreeOp,
    count: usize,
}

/// A held claim on a composed worker-worktree path. Released on drop, so
/// every early return lets the next spawn or despawn through.
#[derive(Debug)]
pub(crate) struct WorktreeClaimGuard {
    claims: Arc<parking_lot::Mutex<HashMap<std::path::PathBuf, WorktreeClaim>>>,
    path: std::path::PathBuf,
}

impl Drop for WorktreeClaimGuard {
    fn drop(&mut self) {
        let mut claims = self.claims.lock();
        let Some(claim) = claims.get_mut(&self.path) else {
            return;
        };
        // The entry cannot change hands while this guard lives: it only
        // leaves the map when every guard has dropped.
        claim.count = claim.count.saturating_sub(1);
        if claim.count == 0 {
            claims.remove(&self.path);
        }
    }
}

/// A test's pause inside [`Workspace::live_seats`]: the sender fires once a
/// capture is held, and a message on the receiver releases it.
#[cfg(any(test, feature = "testing"))]
type LiveSeatsGate = (std::sync::mpsc::Sender<()>, std::sync::mpsc::Receiver<()>);

/// spawned [`forge_agent::Agent`] handles, one per active session.
///
/// Construct via [`Workspace::new`]; consume via
/// [`Workspace::get_agent_handle`]; drain on exit via
/// [`Workspace::shutdown`].
pub struct Workspace {
    /// Retained so error messages can reference the `forge.toml`
    /// path the workspace was constructed from, and so the per-account
    /// config-dir binding can re-resolve from here.
    config_dir: PathBuf,
    /// `pub(crate)` so the impl block in [`crate::gotify`] can read the
    /// `[gotify]` section. Swapped whole by [`Workspace::reload_config`],
    /// which is why readers take an owned snapshot rather than a reference.
    pub(crate) config: parking_lot::RwLock<Arc<LoadedConfig>>,
    /// The effective-config document, rebuilt on every applied reload and
    /// shared by every socket connection. `None` until the server names the
    /// build that carries it.
    settings: tokio::sync::watch::Sender<Option<Arc<forge_primitives::SettingsDocument>>>,
    /// The forge version the document carries, set once by the server at
    /// boot. A workspace with no server (tests) leaves it empty.
    settings_version: std::sync::OnceLock<String>,
    /// One settings save at a time: the file is read, edited, validated and
    /// replaced under this lock, so two saves cannot interleave.
    settings_write: parking_lot::Mutex<()>,
    /// Odd while a reload is swapping state, even when settled. A spawn
    /// reads it before resolving and re-checks after, so a resolution that
    /// straddled the swap retries rather than pairing an old project pin
    /// with the new pool.
    reload_generation: std::sync::atomic::AtomicU64,
    /// Held across a reload's odd-to-even swap, so a spawn that sees an odd
    /// generation waits on this rather than spinning on the counter.
    reload_gate: std::sync::Mutex<()>,
    /// The `[systemone]` decision client, built at boot when the section
    /// is present and enabled; the session MCP servers are handed a
    /// facade over it. `None` keeps the systemone tools out of every
    /// session. Rebuilt by [`Workspace::reload_config`].
    pub(crate) systemone: parking_lot::RwLock<Option<Arc<forge_system_one::SystemOneClient>>>,
    /// The `[vault]` credential session, built at boot when the section is
    /// present; the family's tools are handed a facade over it. `None` keeps
    /// the vault tools out of every session. Rebuilt by
    /// [`Workspace::reload_config`] only when the section itself changed, so
    /// an unrelated settings save never locks a live vault.
    pub(crate) vault: parking_lot::RwLock<Option<Arc<crate::vault::VaultSession>>>,
    /// The per-seat voice service, built on first use: its sink and its note
    /// dispatch hold a `Weak<Workspace>`, which does not exist while the
    /// value is still being constructed.
    pub(crate) voice: std::sync::OnceLock<Arc<crate::voice::VoiceService>>,
    /// The last voice preview's render failure, for the settings card to
    /// draw. Cleared when the next preview is asked for.
    pub(crate) voice_preview_error: std::sync::Mutex<Option<String>>,
    /// Catalog of sessions per project. Populated by the background
    /// catalog scan once [`Workspace::start_catalog_scan`] runs;
    /// mutated in-place by [`Workspace::record_connected_session`]
    /// each time a freshly spawned session reaches `Connected`, so the
    /// Projects pane's drilldown stays current without forcing a full
    /// disk re-scan. Held under a Mutex because multiple in-process
    /// tasks (the pane render, the connect-flow event handler) reach
    /// for it across `await` points; `Arc` so the scan task can swap
    /// its contents without holding an `Arc<Workspace>` cycle.
    catalog: Arc<Mutex<HashMap<ProjectKey, Vec<SDKSessionInfo>>>>,
    /// forge's machine-local app-support base, resolved once at
    /// construction: the single-instance lock, the durable store and the
    /// dictation catalogue cache all sit under it. `None` means boot
    /// resolution failed (already warned there); hard rule #14 forbids a
    /// cwd fallback.
    pub(crate) app_support: Option<PathBuf>,
    /// Live Agents keyed by the session slot. `parking_lot::Mutex` so the
    /// public methods can take `&self`. `pub(crate)` so sibling
    /// modules (`spawn::handle_deliver_worker_prompt_to_lead`,
    /// `mcp::workers::facade::ProdWorkerFacade`) can probe pool
    /// membership for lead-delivery gating without an extra method
    /// wrapper.
    pub(crate) pool: Mutex<HashMap<SessionSlot, PooledAgent>>,
    /// A stand-in for the handle a cold spawn would create. The settings a
    /// spawn launches with are otherwise unobservable: a pooled slot never
    /// reaches the launch, and a cold one ends in a real subprocess. `None`
    /// in production and in every test that does not install one, so a
    /// spawn runs always.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_spawn_handle: Mutex<Option<forge_agent::AgentHandle>>,
    /// The `forge` MCP server the last spawn built, kept because a stand-in
    /// replaces `Agent::spawn`, so the server it would have been handed is
    /// otherwise dropped unobserved -
    /// and a test that has to drive a tool through the spawn's OWN
    /// composition (which facade it was built with) needs it.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_spawn_server: Mutex<Option<forge_sdk::mcp::server::McpServer>>,
    /// The account state map, owned by the gateway and reached through
    /// its pool. It carries account health state updated on every spawn
    /// and refreshed by the in-memory usage poller, and it is what the
    /// gateway's selection walk reads to choose an account.
    pub(crate) accounts: Arc<forge_gateway::AccountPool>,
    /// Dictation preflight: the per-model progress the launchpad
    /// renders, the flag Escape sets, and the loaded engine held for
    /// the run. Populated by `start_dictate_preflight`; inert when
    /// `[dictate] enabled` is false.
    pub(crate) dictate: Arc<crate::dictate::DictateState>,
    /// Live dictation: the takes being fed frames and the submitted
    /// takes still awaiting a transcript. Driven by
    /// `Command::DictateStream` / `Command::DictateStop`.
    pub(crate) dictate_runtime: Mutex<crate::dictate::DictateRuntime>,
    /// The server's browser fleet, installed once at boot by forge-server.
    /// `None` is a workspace with no browser host (tests, a view): the
    /// browser tools then name their refusal.
    pub(crate) browser_host: std::sync::OnceLock<Arc<dyn crate::browser::BrowserHost>>,
    /// **Captures do not overlap**: the generation ranks whole captures, so
    /// the mint and the reads it labels happen under this one lock.
    live_seats_lock: std::sync::Mutex<()>,
    /// The generation each [`Self::live_seats`] capture takes, so the fleet
    /// can drop a snapshot older than the one it last applied.
    live_seats_generation: std::sync::atomic::AtomicU64,
    /// A test's hold between [`Self::live_seats`]'s mint and its reads, so a
    /// capture can be opened across a seat change. Test-only.
    #[cfg(any(test, feature = "testing"))]
    live_seats_gate: Mutex<Option<LiveSeatsGate>>,
    /// How many client connections are attached, noted by the transport per
    /// connection. A document hand-off reads it before claiming an open: only
    /// a client that draws a document viewer is counted.
    pub(crate) attached_clients: std::sync::atomic::AtomicUsize,
    /// The parked document hand-offs, under their ids: each holds the
    /// awaiting tool's sender until the reader's answer releases it.
    pub(crate) document_handoffs:
        parking_lot::Mutex<HashMap<uuid::Uuid, crate::documents::ParkedDocument>>,
    /// The model catalogue: the last fetched feed and what the last check
    /// did. Loaded from its cache at boot, refreshed by
    /// `start_dictate_catalogue` and `Command::DictateCatalogueCheck`, and
    /// read by the models page through `dictate_models`.
    pub(crate) dictate_catalogue: Mutex<crate::catalogue::CatalogueState>,
    /// Where the last model install got to. Set by
    /// `Command::DictateInstall`, read by the models page through
    /// `dictate_install`.
    pub(crate) dictate_install: Mutex<crate::install::InstallState>,
    /// How a plugin action reaches `claude` plus the disk scan the actions
    /// and the Extensions read share. Real in production; a test swaps it
    /// so a whole action runs without shelling out or touching `~/.claude`.
    pub(crate) plugin_cli: Mutex<crate::plugins::PluginCli>,
    /// The last plugin update run or check, in flight or finished: what a
    /// view attaching mid-run reads, and the guard that keeps one run at a
    /// time (a second press is refused while this is unfinished).
    pub(crate) plugin_run: Mutex<Option<forge_primitives::plugins::PluginUpdateRun>>,
    /// One plugin CLI action at a time; cleared when its task ends, panic
    /// included, so a crashed task never wedges the surface.
    pub(crate) plugin_action_running: std::sync::atomic::AtomicBool,
    /// Where the last model activation got to. Set by
    /// `Command::DictateActivate`, read by the models page through
    /// `dictate_activate`.
    pub(crate) dictate_activate: Mutex<crate::install::ActivateState>,
    /// Where the last bench got to, and the flag its Stop sets. Read by
    /// the models page through `dictate_bench` and `bench_results`.
    pub(crate) dictate_bench: Mutex<crate::bench::BenchState>,
    pub(crate) dictate_bench_cancel: std::sync::atomic::AtomicBool,
    /// Where the speaking loop's bench got to, and the flag its Stop sets.
    /// Read by the models page through `speaking_bench` and its results.
    pub(crate) speaking_bench: Mutex<crate::bench::SpeakingBenchState>,
    pub(crate) speaking_bench_cancel: std::sync::atomic::AtomicBool,
    /// One bench at a time across both directions: a single claim taken
    /// before either state is written, so two presses cannot both pass the
    /// check and load two engines.
    pub(crate) bench_claim: std::sync::atomic::AtomicBool,
    /// The last read-aloud write's failure, when there was one: a stop
    /// whose write fails has no dispatch left to answer, so the page reads
    /// it here instead. Cleared when the next recording starts.
    pub(crate) read_aloud_error: Mutex<Option<String>>,
    /// A test's own catalogue source, so a check can run against a
    /// loopback server instead of GitHub. Not present in production
    /// builds.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_catalogue_source: Mutex<Option<forge_dictate::catalogue::CatalogueSource>>,
    /// A test's own cleanup source, on the same terms.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_cleanup_source: Mutex<Option<forge_dictate::cleanup::CleanupSource>>,
    /// A test's own catalogue directory, so a check never writes to the
    /// real app-support dir. Not present in production builds.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_catalogue_dir: Mutex<Option<std::path::PathBuf>>,
    /// A test's own read-aloud set directory, so an arming never writes to
    /// the real app-support dir. Not present in production builds.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_read_aloud_dir: Mutex<Option<std::path::PathBuf>>,
    /// Fan-out [`SessionUpdate`] sender: every producer inside the workspace
    /// holds a clone, and it hands each update to every subscriber.
    /// `pub(crate)` so the impl block in [`crate::crons`] can reach it.
    pub(crate) update_tx: UpdateFanout,
    /// Per-session [`Command`] sender map. Populated when
    /// [`Self::get_agent_handle`] spawns the first `SessionTask` for a
    /// key; cleared on [`Self::release_session_with_cascade`] and [`Self::shutdown`].
    #[cfg(any(test, feature = "testing"))]
    pub(crate) command_senders: Mutex<HashMap<SessionSlot, mpsc::UnboundedSender<Command>>>,
    #[cfg(not(any(test, feature = "testing")))]
    command_senders: Mutex<HashMap<SessionSlot, mpsc::UnboundedSender<Command>>>,
    /// Per-session teardown-completion signals, minted beside the command
    /// channel. The task marks its slot done as it drops - after its exit
    /// path has reaped the subprocess - and every waiter subscribes rather
    /// than taking the one receiver: the despawn holds its worktree removal
    /// until then (#1767), and a shutdown holds its exit until every slot
    /// answers. An entry stays after its task fires and is replaced when
    /// the slot respawns, so the map holds one small sender per slot this
    /// process has ever spawned - the price of a late reader still finding
    /// the answer.
    session_teardowns: Mutex<HashMap<SessionSlot, tokio::sync::watch::Sender<bool>>>,
    /// Set before a shutdown tears anything down. From then on no session
    /// may start - the boot wave, a cron tick and the socket all race the
    /// drain - and the mint refuses under the same lock the drain takes,
    /// which is what keeps a late spawn out of the awaited set.
    shutting_down: std::sync::atomic::AtomicBool,
    /// Per-project list of live worker sessions. In-memory only -
    /// wiped on forge restart by design (workers are ephemeral at the
    /// forge UI level; their JSONLs persist on disk). Mutated via
    /// `insert_live_worker` / `remove_latest_worker` / `drain_live_workers`.
    live_workers: Mutex<HashMap<ProjectKey, Vec<crate::mcp::workers::types::WorkerEntry>>>,
    /// The per-lead clock of the injected board sweep, keyed by the
    /// lead's slot. In memory only, so a restart re-arms every lead:
    /// the sweep is a moment, not a schedule the store should own.
    /// `pub(crate)` so the impl block in [`crate::idle_sweep`] can
    /// reach it.
    pub(crate) idle_sweeps: Mutex<HashMap<SessionSlot, crate::idle_sweep::SweepClock>>,
    /// One claim per composed worker-worktree path, held while a spawn's
    /// ensure/insert or a despawn's removal is in flight. The live
    /// registry is per project; this is the repository-wide one, so two
    /// projects composing the same path cannot both act on it.
    worktree_claims: Arc<parking_lot::Mutex<HashMap<PathBuf, WorktreeClaim>>>,
    /// The `(project, label)` pairs whose despawn cleanup is still running.
    /// The label's worktree is being torn down for that whole window, so a
    /// spawn taking the label now would enter a directory the removal is
    /// about to delete. Held from the cleanup's handoff until it finishes,
    /// and released by its own `Drop` so a panicking cleanup cannot leave a
    /// label blocked forever. In-memory only, like the rest of the worker
    /// registry.
    despawn_cleanups: Mutex<HashSet<(ProjectKey, String)>>,
    /// Why the last spawn or connection for a slot failed, keyed by slot.
    /// Survives the failed attempt itself, which is what a `DomainSession`
    /// cannot: a connection failure releases the session, so by the time a
    /// view reads the slot there is nothing left to say the attempt ever
    /// happened. Written before that release and cleared when a session
    /// for the slot comes up again, so it reports an unrecovered failure
    /// rather than a history.
    spawn_failures: Mutex<HashMap<SessionSlot, String>>,
    /// The occupant that died on a slot, keyed by slot, held until a
    /// reader has been shown the seat again or a new turn commits there.
    /// [`Self::spawn_failures`] says an attempt failed; this says the seat
    /// HAD something running and it ended under its own process, which is
    /// what lets the recovery be announced as a resume or a restart under
    /// a new id rather than reading as a plain connect - and what keeps
    /// the failure and its reason on the row until someone has looked.
    deaths: Mutex<HashMap<SessionSlot, SeatDeath>>,
    /// Where each dead seat's heal has got to while it is restarting,
    /// keyed by slot. The healing supervisor writes it between attempts;
    /// every row that draws the seat reads it, and a lead has no worker
    /// entry for the state to live on instead.
    heal_progress: Mutex<HashMap<SessionSlot, HealProgress>>,
    /// The auto-heal supervisor, built on the first death that reaches it.
    /// It holds a `Weak<Workspace>`, which does not exist while the value
    /// is still being constructed.
    healing: std::sync::OnceLock<Arc<crate::healing::Healing>>,
    /// The seats a view is showing, each with the working-tree scan loop it
    /// runs. Empty is the quiet case: a seat nobody holds is not scanned.
    pub(crate) held_work_seats: crate::work::HeldSeats,
    /// Shared [`DomainSession`] handles, one per active `SessionTask`.
    /// `pub(crate)` so crate-internal spawn and delivery paths can
    /// reach a session's `DomainSession` directly.
    pub(crate) domain_handles: Mutex<HashMap<SessionSlot, Arc<Mutex<DomainSession>>>>,
    /// The session that submitted the reviews on a `(project, branch)` -
    /// the target for a worker's review-activity notice. Set by
    /// [`Self::submit_review`]; latest submit wins (the reviewer is one
    /// human whose session may rekey across a resume). `pub(crate)` so
    /// the impl block in [`crate::review`] can reach it.
    pub(crate) review_origin: Mutex<HashMap<(String, String), SessionSlot>>,
    /// Review actions a caller took during its current turn, keyed by the
    /// caller's [`SessionSlot`]. Appended by [`Self::review_reply`] /
    /// [`Self::review_resolve`] and drained into one notice per review at
    /// the caller's turn end ([`Self::drain_review_activity`]).
    /// `pub(crate)` so the impl block in [`crate::review`] can reach it.
    pub(crate) review_activity:
        Mutex<HashMap<SessionSlot, Vec<crate::mcp::review::ReviewActivity>>>,
    /// The process's subsystem supervisor: every long-lived background task
    /// registers here, so a death is named and a restart is bounded.
    pub(crate) supervisor: Arc<forge_supervise::Supervisor>,
    /// Set the first time [`Self::start_dictate_preflight`] runs, so a
    /// second call cannot spawn a second prewarm over the same models. Set
    /// before the `[dictate] enabled` gate: the flag reads "the boot wave
    /// asked for the prewarm", which is the one call a test can watch
    /// without a 3 GB fetch.
    dictate_preflight_started: std::sync::atomic::AtomicBool,
    /// Records that the boot wave asked for the prewarm, set before the
    /// `[tts] enabled` gate: the flag reads "the wave asked", which is the
    /// one call a test can watch without the weights. It is not a dispatch
    /// guard; the guard only stops a second load of the same engine.
    pub(crate) voice_prewarm_started: std::sync::atomic::AtomicBool,
    /// Set once the prewarm is dispatched, after the enabled gate, so a
    /// second call cannot spawn a second load of the same engine.
    pub(crate) voice_prewarm_dispatched: std::sync::atomic::AtomicBool,
    /// The gateway's listener + session bindings. Children are stamped
    /// with a base URL that names this listener, and every spawn
    /// registers here.
    pub(crate) gateway: Arc<forge_gateway::forward::Gateway>,
    /// `true` once the listener's port is bound. The boot gate stays
    /// shut until it is, because every session's base URL names it.
    gateway_ready: std::sync::atomic::AtomicBool,
    /// The port the listener binds: `[gateway] port` or the default.
    gateway_port: u16,
    /// The listener's bound URL, stored when the port is taken. The
    /// stamp reads THIS, not the config value, so the base URL a child
    /// is stamped with is structurally the one that answers.
    gateway_url: Mutex<Option<String>>,
    /// The bind failure, if the listener could not start. Surfaced by
    /// the launchpad's gate label; `None` while loading or bound.
    gateway_bind_error: Mutex<Option<String>>,
    /// Sender half of the worker-kick channel (#259). Cloned via
    /// [`Self::enqueue_kick`] by `maybe_kick_worker_on_connected`
    /// (and any future kick site). The matching receiver lives in
    /// `kick_dispatcher_rx_slot` until [`Self::start_kick_dispatcher`]
    /// takes it out and spawns the drainer task.
    kick_dispatcher_tx: mpsc::UnboundedSender<KickRequest>,
    /// Single-take slot holding the matching receiver.
    /// [`Self::start_kick_dispatcher`] pops it on first call and
    /// hands it to the drainer task; subsequent calls find `None`
    /// and no-op (mirrors `start_usage_poller`'s guard against
    /// duplicate spawns).
    kick_dispatcher_rx_slot: Mutex<Option<mpsc::UnboundedReceiver<KickRequest>>>,
    /// Single-instance lock file held open for the process lifetime.
    /// `Workspace::new` takes an exclusive flock on a machine-local
    /// lockfile keyed by the config dir (see [`crate::single_instance`])
    /// so a second forge on the same config dir refuses to start; the
    /// flock releases when this `File` drops (Workspace teardown / process
    /// exit / crash). Held purely for that side effect - never read.
    /// `None` in `testing_stub` and on the degraded acquire path.
    _single_instance_lock: Option<std::fs::File>,
    /// Durable forge crons (`mcp__forge__cron`). In-memory working set,
    /// loaded at boot from the machine-local redb store ([`crate::store::cron`])
    /// and persisted back after every mutation - create/delete, the
    /// scheduler's fire-advance, and boot catch-up - through the one
    /// [`Workspace::with_crons_mut`] path. The single-instance guard keeps
    /// this the only process holding that store, so this mutex alone
    /// serialises writes.
    /// `pub(crate)` so the impl block in [`crate::crons`] can reach it.
    pub(crate) crons: Mutex<Vec<forge_primitives::CronEntry>>,
    /// Set at boot when the durable crons could not be loaded: the store
    /// could not open, or its read failed. The in-memory set is empty while
    /// rows may still be on disk, so it is not the registry. `cron__list`
    /// refuses on it rather than answering an empty array a caller would read
    /// as "you have no crons".
    ///
    /// It gates `cron__list` only: under the same failed load `delete_cron`
    /// still answers `NoSuchCron` from the empty set, and `create_cron` still
    /// promises durability while `persist_cron` returns quietly. Both predate
    /// this cut and the charter's list-then-delete flow is gated by the list
    /// refusal; the siblings are #2943.
    pub(crate) crons_load_failed: std::sync::atomic::AtomicBool,
    /// The live task list (`mcp__forge__tasks`). In-memory working set,
    /// loaded from the machine-local store at boot and persisted back
    /// after every mutation through the one [`Workspace::with_tasks_mut`]
    /// path. `pub(crate)` so the impl block in [`crate::tasks`] can reach
    /// it.
    pub(crate) tasks: Mutex<Vec<forge_primitives::tasks::Task>>,
    /// Payloads addressed to a slot that had no live session when they
    /// arrived - a peer prompt, a fired cron, a Gotify notification, a
    /// Slack message - keyed by `(org, project, label)` (`None` = lead),
    /// the triple the `sessions` table uses. The slot's session drains
    /// its own bucket on first `Connected`. `pub(crate)` so the impl
    /// block in [`crate::parked`] can reach it.
    pub(crate) parked_by_slot: Mutex<crate::parked::ParkedMap>,
    /// The brief a handoff wrote, waiting for the successor it was written
    /// for to connect. Taken by the session task on that connect, which is
    /// what makes the brief the new occupant's first turn. `pub(crate)` so
    /// the impl block in [`crate::handoff`] can reach it.
    pub(crate) pending_handoffs:
        Mutex<std::collections::HashMap<SessionSlot, crate::handoff::PendingBrief>>,
    /// Seats whose occupant is being swapped by a handoff: from the moment
    /// the brief is built until the successor connects, a prompt aimed at one
    /// is held rather than run by the session leaving.
    pub(crate) swapping: Mutex<std::collections::HashMap<SessionSlot, u64>>,
    /// Mints a swap's token, so a build that lost the seat cannot spawn.
    pub(crate) swap_epochs: std::sync::atomic::AtomicU64,
    /// Prompts held for a swapping seat, delivered to its successor after the
    /// brief, in arrival order.
    pub(crate) held_prompts:
        Mutex<std::collections::HashMap<SessionSlot, Vec<crate::handoff::HeldPrompt>>>,
    /// Active Gotify subscriptions (`mcp__forge__gotify`). The set the
    /// stream matches each inbound message against. Durable ones (lead /
    /// team-worker) are also persisted to `db` and reloaded here
    /// at boot; ephemeral ad-hoc-worker ones live only in memory.
    /// `pub(crate)` so the impl block in [`crate::gotify`] can reach it.
    pub(crate) gotify_subs: Mutex<Vec<forge_primitives::GotifySubscription>>,
    /// Machine-local redb store. Backs durable crons ([`crate::store::cron`]),
    /// Gotify and Slack subscriptions ([`crate::store::gotify`],
    /// [`crate::store::slack`]) and persisted sessions
    /// ([`crate::store::sessions`]). `None` when the DB couldn't
    /// open (degrade to in-memory-only, no persistence) or in
    /// `testing_stub`. `pub(crate)` so the impl block in
    /// [`crate::review`] can reach it.
    pub(crate) db: Arc<Mutex<Option<crate::store::Db>>>,
    /// Whether the boot catalog scan has populated `catalog`. The scan
    /// runs in the background off the boot path; the Projects pane and
    /// the session lookups read the catalog it fills.
    catalog_loaded: Arc<std::sync::atomic::AtomicBool>,
    /// How [`Workspace::refresh_pricing`] fetches the litellm table. The
    /// real fetch in production; a test constructor scripts it so the
    /// refill is drivable without the network.
    pricing_fetcher: PricingFetcher,
    /// Idempotence guard for [`Workspace::start_catalog_scan`].
    catalog_scan_started: std::sync::atomic::AtomicBool,
    /// The installed and npm-published `claude` CLI versions, merged from
    /// every probe so far. One answer for every viewer, so it lives here
    /// rather than in the view that happened to probe first; `None` until
    /// the boot probe lands.
    cli_version: Arc<Mutex<Option<CliVersionInfo>>>,
    /// The last fatal error, held so a view that was not subscribed when it
    /// fired can still learn of it: the update carries no state of its own
    /// and nothing else in the core records it.
    last_fatal_error: Mutex<Option<forge_primitives::error::AppError>>,
    /// The statuspage's last answer, held so a view that attached after the
    /// probe landed can read it rather than having missed the one update
    /// that carried it. `None` until the probe answers.
    service_status: Arc<Mutex<Option<ServiceIssue>>>,
    /// Idempotence guard for the service-status probe.
    service_status_probe_started: std::sync::atomic::AtomicBool,
    /// Whether the Gotify stream is currently connected. Set by the
    /// subsystem pump on `Connected` / `Disconnected`, and cleared by the
    /// stop path and the pump's exit guard; read by the Inspector's status
    /// line.
    /// `pub(crate)` so the impl block in [`crate::gotify`] can reach it.
    pub(crate) gotify_connected: Mutex<bool>,
    /// Gotify application name -> numeric appid map, fetched from the
    /// server's `/application` list on subsystem start and refreshed on
    /// each reconnect. Resolves an `application` name filter to the appid
    /// inbound messages carry, and the reverse lookup for the envelope.
    /// `pub(crate)` so the impl block in [`crate::gotify`] can reach it.
    pub(crate) gotify_app_index: Mutex<HashMap<String, u64>>,
    /// Shutdown handle for the running Gotify subsystem. `Some` while the
    /// pump runs; dropping/sending stops it, and the pump's own exit guard
    /// clears it when the task ends. `None` when idle (no subscriptions) or
    /// unconfigured. Guards against double-starting.
    /// `pub(crate)` so the impl block in [`crate::gotify`] can reach it.
    pub(crate) gotify_subsystem: Mutex<Option<GotifySubsystem>>,
    /// One Slack client per `[[slack]]` entry, resolved at boot. Empty
    /// keeps the Slack connector dormant. `pub(crate)` so the impl
    /// blocks in [`crate::slack`] and `crate::mcp::slack` can reach it.
    pub(crate) slack: Arc<crate::slack::SlackWorkspaces>,
    /// Active Slack subscriptions (`mcp__forge__slack`). The set each
    /// workspace's pump sweeps. Durable ones are also persisted to `db`
    /// and reloaded here at boot. `pub(crate)` so the impl block in
    /// [`crate::slack`] can reach it.
    pub(crate) slack_subs: Mutex<Vec<forge_primitives::slack::SlackSubscription>>,
    /// Shutdown handles for the running Slack pumps, one per workspace
    /// label. Slack has a pump per `[[slack]]` entry where Gotify has a
    /// single server and a single handle.
    pub(crate) slack_subsystem:
        Mutex<std::collections::BTreeMap<String, tokio::sync::oneshot::Sender<()>>>,
    /// Per-workspace pump liveness for the Inspector's SLACK section.
    /// Keyed by label for the same reason.
    pub(crate) slack_connected: Mutex<std::collections::BTreeMap<String, bool>>,
    /// Conversations forge has a post in flight into, keyed
    /// `(workspace, the resolved conversation)`, each entry a stamp per
    /// live call: one post call with its ledger write, or one upload's
    /// shares read. The sweep skips a conversation while any stamp is
    /// within budget, because the message can reach history before its ts
    /// is ledgered; a stamp past the request timeout is expired, never
    /// obeyed, so a stalled call cannot silence the conversation.
    pub(crate) slack_inflight:
        Mutex<std::collections::HashMap<(String, String), Vec<crate::slack::SlackPostStamp>>>,
    /// The authenticated user's id per workspace, resolved once by the
    /// boot `auth.test` and needed to recognise `<@U...>` mentions.
    pub(crate) slack_user_ids: Mutex<std::collections::BTreeMap<String, String>>,
    /// Display names resolved per `(workspace, user id)`, so a message from
    /// a known author costs no `users.info` call.
    pub(crate) slack_user_names: Mutex<std::collections::BTreeMap<(String, String), String>>,
    /// `(workspace, user id)` pairs whose failed lookup has been reported, so
    /// a persistent failure says so once rather than on every tick.
    pub(crate) slack_author_failures: Mutex<std::collections::HashSet<(String, String)>>,
    /// `(workspace, user id)` pairs whose failed DRAFT tag lookup has been
    /// reported. Kept apart from the author set so a draft's miss does not
    /// spend the once-per-author line the sweep relies on.
    pub(crate) slack_draft_user_failures: Mutex<std::collections::HashSet<(String, String)>>,
    /// `(workspace, conversation, parent ts)` whose failed thread read has
    /// been reported, so a persistent failure says so once rather than on
    /// every park.
    pub(crate) slack_thread_failures: Mutex<std::collections::HashSet<(String, String, String)>>,
    /// When each followed thread was last read whole, keyed
    /// `(workspace, conversation, parent ts)`. In memory: a restart costs one
    /// extra whole read per thread, which is cheaper than a schema.
    pub(crate) slack_thread_full_reads:
        Mutex<std::collections::HashMap<(String, String, String), std::time::Instant>>,
    /// Followed threads whose next walk is their first since the row was
    /// created, keyed the same way.
    pub(crate) slack_thread_first_walks: Mutex<std::collections::HashSet<(String, String, String)>>,
    /// Cache of each thread row's persisted edit stamp, keyed the same way: an
    /// edit is measured against this, never against the reply cursor. A miss
    /// reads the row, because the stamp has to outlive the process.
    pub(crate) slack_thread_edit_watermarks:
        Mutex<std::collections::HashMap<(String, String, String), String>>,
    /// Conversations whose own-post ledger could not be read this run,
    /// keyed `(workspace, conversation)`. The read is retried on every
    /// message; this only decides whether the failure is worth a line a
    /// reader sees, once rather than per message.
    pub(crate) slack_ledger_failures: Mutex<std::collections::HashSet<(String, String)>>,
    /// Composed Slack messages held for the user's decision, keyed by
    /// draft id and carrying the session that asked. The owner is stored
    /// beside it so an answer is only ever applied by the session it was
    /// addressed to.
    pub(crate) slack_drafts: Mutex<HashMap<uuid::Uuid, ParkedSlackDraft>>,
    /// Browser hand-offs parked for the person at a client, keyed by their id
    /// and carrying the session that asked. The owner is stored beside each so
    /// an answer is only ever applied by the session it was addressed to; the
    /// blocked `browser_hand_off` handler awaits the sender, with no timeout,
    /// for as long as the person takes.
    pub(crate) browser_handoffs: Mutex<HashMap<uuid::Uuid, ParkedBrowserHandOff>>,
    /// The per-seat terminals, created lazily on first use and living as long
    /// as the seat: `/new`, `/resume` and a handoff leave the PTY, its shell
    /// and its scrollback untouched; a release ends the seat and its
    /// terminal.
    pub(crate) terminals: Mutex<HashMap<SessionSlot, Arc<crate::terminal::TerminalEntry>>>,
    /// Terminal hand-offs parked for the person at a client, keyed by their
    /// id and carrying the session that asked. The blocked `terminal__hand_off`
    /// handler awaits the sender, with no timeout, for as long as the person
    /// takes.
    pub(crate) terminal_handoffs: Mutex<HashMap<uuid::Uuid, ParkedTerminalHandOff>>,
    /// The id the next terminal takes. **One per seat today**, but the wire
    /// carries an id so a second terminal per seat is additive rather than a
    /// protocol change.
    pub(crate) next_terminal_id: std::sync::atomic::AtomicU16,
    /// Configuration writes held for the reader's approval, keyed by the
    /// write's id and carrying the session that asked. Its own registry for
    /// the same reason the draft's is: a held write exists on a seat with no
    /// domain, and nothing reaches `forge.toml` until the blocked handler's
    /// oneshot is answered.
    pub(crate) settings_writes:
        Mutex<HashMap<uuid::Uuid, crate::settings_ask::ParkedSettingsWrite>>,
    /// Vault calls held for the reader's approval, keyed by the call's id and
    /// carrying the session that asked. Its own registry for the same reason
    /// the settings write's is: a held call exists on a seat with no domain,
    /// and no operation runs in the vault until the blocked handler's oneshot is
    /// answered.
    pub(crate) parked_vault_asks: Mutex<HashMap<uuid::Uuid, crate::vault_ask::ParkedVaultAsk>>,
    /// How many asks have ever arrived for a seat. **The ask's identity on the
    /// wire**: one ask replacing another reads as a different ask, and
    /// answering one of several leaves the number where it was.
    pending_seq: Mutex<HashMap<SessionSlot, u64>>,
    /// Slack messages handed to a session recently, keyed by
    /// `(project, owner, conversation, ts)`. A sweep re-runs a batch
    /// whenever a 429 lands mid-sweep, a watermark write fails, or the
    /// process dies between the two - this is what makes that re-run
    /// idempotent rather than a re-delivery.
    pub(crate) slack_recently_delivered: Mutex<HashMap<SlackDeliveryKey, std::time::Instant>>,
    /// Set at boot when the durable Slack subscriptions could not be
    /// read. The Inspector SLACK section reads it: without it the empty
    /// subscription set would hide the failure.
    pub(crate) slack_load_failed: std::sync::atomic::AtomicBool,
    /// The last time each workspace's user-id retry ran, so a failing
    /// `auth.test` is retried at most once a minute rather than per sweep.
    pub(crate) slack_user_id_retries: Mutex<std::collections::BTreeMap<String, SystemTime>>,
    /// Set the first time [`Workspace::start_slack_verification`] runs.
    /// Subsequent calls early-return to avoid spawning duplicate probes.
    pub(crate) slack_verification_started: std::sync::atomic::AtomicBool,
    /// Per-project in-flight guard for the lead Connected
    /// hook's catalog scan. Inserted synchronously when
    /// `respawn_workers_for_lead` starts; removed when
    /// the async scan completes and dispatches its SpawnWorker
    /// commands. A concurrent second Connected (e.g. a fast /new
    /// reconnect) checking this set sees the entry and skips its own
    /// respawn, preventing duplicate worker sets while the scan
    /// is in flight. The existing `live_workers.is_empty()` gate
    /// covers the post-dispatch case.
    respawn_in_flight: Mutex<std::collections::HashSet<ProjectKey>>,
    /// The cron ids the LAST `fire_due_crons` pass found unwakeable, so
    /// the first warning about one is a `WARN` and the repeats are not.
    ///
    /// Not a cache: nothing but that warning's level reads it, and it
    /// holds only what the most recent pass saw, replaced wholesale at the
    /// end of each pass. That is what stops an entry outliving its
    /// condition - a cron that fires, advances or is deleted is simply
    /// absent from the next pass's set, so one that goes unwakeable again
    /// is new again and warns at `WARN` again. A set that never cleared
    /// would silence a cron that is firing.
    unwakeable_crons: Mutex<std::collections::HashSet<forge_primitives::CronId>>,
    /// The cron ids the last `fire_due_crons` pass found cooling, with the
    /// time each last warned. Replaced wholesale each pass, like
    /// `unwakeable_crons`, so an episode that clears drops its marker and a
    /// later one warns again.
    cooling_crons: Mutex<std::collections::HashMap<forge_primitives::CronId, SystemTime>>,
    /// Test-only intercept buffer for app-level Commands. When
    /// `Some`, `dispatch` captures the command into the buffer
    /// instead of routing it to the spawn::* handler - used by
    /// respawn tests to assert what would have been
    /// dispatched without spinning up real subprocesses. Always
    /// `None` in production (no enable hook outside test cfg).
    #[cfg(any(test, feature = "testing"))]
    command_intercept: Mutex<Option<Vec<Command>>>,
    /// Test-only project overlay. Entries appended via
    /// `seed_test_project` are searched first in
    /// `find_project_view_by_name` so tests can drive the
    /// Connected-hook respawn trigger without writing a
    /// real `forge.toml`. Empty in production.
    #[cfg(any(test, feature = "testing"))]
    test_extra_projects: Mutex<Vec<LoadedProject>>,
    /// Test-only stand-in for the CLI's per-user preferences document, so
    /// a view fixture reads an ignore preference without the machine's
    /// real `$HOME/.claude.json`. `None` means no fixture seeded one, and
    /// the read goes to the file.
    #[cfg(any(test, feature = "testing"))]
    test_user_preferences: Mutex<Option<serde_json::Value>>,
    /// Test-only stand-in for a seat's live `claude` pid, so a fixture seat's
    /// held loop walks a real process tree with no CLI behind it. A seat with
    /// no entry reads the pid off its own handle, as production does.
    #[cfg(any(test, feature = "testing"))]
    test_claude_pid: Mutex<std::collections::HashMap<SessionSlot, u32>>,
    /// Test-only gate every stale read waits on before it scans, so a fixture
    /// can hold a read in flight and see what a hold answers first. `None`
    /// means reads run as they do in production.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) test_scan_gate: Mutex<Option<Arc<tokio::sync::Semaphore>>>,
}

/// Pool entry wrapping the live `Arc<AgentHandle>`, the account key
/// the subprocess is bound to, the permission mode that spawn resolved
/// for its project, and the session registration a respawn re-sends.
pub(crate) struct PooledAgent {
    pub handle: Arc<AgentHandle>,
    /// The account the subprocess is bound to, resolved at spawn.
    pub account: AccountKey,
    /// The permission mode this session spawned with, from its
    /// project; `None` when the spawn resolved to no project and the
    /// launcher default applied. The dispatch path reads it to stamp
    /// the same mode onto `/new` and `/resume` re-spawns.
    pub permission_mode: Option<forge_primitives::permission::PermissionMode>,
    /// The session's registration, captured at spawn; a `/new` or
    /// `/resume` respawn re-registers it so the fresh child gets a
    /// fresh binding and env set.
    pub registration: Option<forge_gateway::binding::Registration>,
    /// The id the child currently runs under, as its spawn resolved it
    /// and as `Connected` refreshed it. The slot is the pool's key; this
    /// is the occupant the CLI knows, and what a caller holding only the
    /// slot needs for a CLI argument or a transcript path.
    pub session_id: String,
}

/// Why `insert_live_worker_if_label_absent` refused an insert. Decided
/// under the same lock acquisition as the insert, so the refusal and
/// the pool state can never disagree.
#[derive(Debug)]
pub enum LiveWorkerRefusal {
    /// A live (non-`Failed`) worker already holds the label.
    LabelLive(SessionSlot),
    /// The label's previous despawn is still cleaning up: its worktree is
    /// mid-removal, so a worker admitted onto the label now would be handed
    /// the very directory the removal is about to delete.
    CleanupPending,
    /// The project's worker cap is reached: `live` workers are up
    /// against a cap of `cap`.
    AtCap { live: usize, cap: usize },
}

/// One label's in-flight despawn cleanup, released when it drops.
///
/// Held from the despawn's mark (taken before its teardown) until the
/// cleanup finishes, so a spawn for the same label is refused rather than
/// handed a worktree that the removal is deleting. `Drop` rather than a
/// plain clear at the end: a cleanup that unwinds mid-removal must not
/// leave the label unspawnable for the rest of the run.
pub(crate) struct DespawnCleanupPending {
    workspace: Arc<Workspace>,
    project_key: ProjectKey,
    label: String,
}

impl Drop for DespawnCleanupPending {
    fn drop(&mut self) {
        self.workspace
            .despawn_cleanups
            .lock()
            .remove(&(self.project_key.clone(), self.label.clone()));
    }
}

/// The session a worker label resumes onto.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum ResumeTarget {
    /// A prior session for the label, named by id.
    Found {
        session_id: String,
        /// The matched tag row predates the `project` field, so the
        /// adopting project must stamp it: the migration window is one
        /// adoption, not one per project forever.
        restamp: bool,
    },
    /// The label has no prior session to resume.
    None,
}

/// Kick off the catalog scan on the tokio runtime. Idempotent via
/// `started`; a caller with no runtime gets a warn and an
/// immediately-ready flag with an empty catalog rather than a scan
/// nobody can await. A monitor on the scan task publishes readiness
/// even if the scan dies, so a reader never waits on a readiness that
/// will never come.
fn spawn_background_catalog_scan(
    catalog: &Arc<Mutex<HashMap<ProjectKey, Vec<SDKSessionInfo>>>>,
    db: &Arc<Mutex<Option<crate::store::Db>>>,
    config_dir: &Path,
    update_tx: &UpdateFanout,
    loaded: &Arc<std::sync::atomic::AtomicBool>,
    started: &std::sync::atomic::AtomicBool,
) {
    if started.swap(true, std::sync::atomic::Ordering::AcqRel) {
        return;
    }
    let run = run_background_catalog_scan(
        Arc::clone(catalog),
        Arc::clone(db),
        config_dir.to_path_buf(),
        update_tx.clone(),
        Arc::clone(loaded),
    );
    if let Ok(handle) = tokio::runtime::Handle::try_current() {
        let task = handle.spawn(run);
        let loaded = Arc::clone(loaded);
        handle.spawn(async move {
            if let Err(error) = task.await {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "catalog scan task died; publishing readiness so a reader sees an empty catalog rather than waiting",
                );
                loaded.store(true, std::sync::atomic::Ordering::Release);
            }
        });
    } else {
        tracing::warn!(
            target: "forge_workspace::workspace",
            config_dir = %config_dir.display(),
            "no tokio runtime at construction; the catalog scan is skipped and the catalog starts empty",
        );
        loaded.store(true, std::sync::atomic::Ordering::Release);
    }
}

/// One probe call, boxed so the task that runs it is not generic over the
/// future's type.
type CliVersionProbe = std::pin::Pin<Box<dyn std::future::Future<Output = CliVersionInfo> + Send>>;

/// How the probe task gets a snapshot. [`Workspace::new`] passes the real
/// probe; every test constructor passes a script, so the scheduling around
/// the probe is drivable without spawning `claude --version` or reaching
/// npm.
type CliVersionProber = Box<dyn Fn() -> CliVersionProbe + Send + Sync>;

/// The real probe: `claude --version` and npm's `latest` dist-tag.
fn real_cli_version_prober() -> CliVersionProber {
    Box::new(|| Box::pin(forge_agent::env::cli_version::fetch_info()))
}

/// One service-status probe call, boxed for the same reason the version
/// probe's is.
type ServiceStatusProbe =
    std::pin::Pin<Box<dyn std::future::Future<Output = Option<ServiceIssue>> + Send>>;

/// How the service-status probe gets its answer. `Workspace::new` passes the
/// real fetch; a test passes a script, so the boot path is drivable without
/// reaching the statuspage.
type ServiceStatusProber = Box<dyn Fn() -> ServiceStatusProbe + Send + Sync>;

/// The real probe: the public statuspage summary.
fn real_service_status_prober() -> ServiceStatusProber {
    Box::new(|| Box::pin(forge_agent::cloud::service_status::fetch_service_status()))
}

/// One pricing fetch, boxed so `refresh_pricing` is not generic over the
/// future's type.
pub type PricingFetch = std::pin::Pin<Box<dyn std::future::Future<Output = Option<String>> + Send>>;

/// How the pricing refill gets its table. `Workspace::new` passes the real
/// litellm fetch; a test constructor passes a script, so the refill's
/// fetch-to-rescan path is drivable without the network.
pub type PricingFetcher = std::sync::Arc<dyn Fn() -> PricingFetch + Send + Sync>;

/// The real fetch: the litellm pricing file.
fn real_pricing_fetcher() -> PricingFetcher {
    std::sync::Arc::new(|| Box::pin(forge_agent::env::token_usage::pricing::fetch_litellm()))
}

/// The fetch a test workspace gets: nothing to fetch, so a kicked refill
/// has nothing to reach - the same no-network promise `new_for_test`
/// already makes for its boot probes.
#[cfg(any(test, feature = "testing"))]
fn inert_pricing_fetcher() -> PricingFetcher {
    std::sync::Arc::new(|| Box::pin(async { None }))
}

/// The fetch a constructor that names none gets.
#[cfg(any(test, feature = "testing"))]
fn default_pricing_fetcher() -> PricingFetcher {
    inert_pricing_fetcher()
}

/// The fetch a constructor that names none gets.
#[cfg(not(any(test, feature = "testing")))]
fn default_pricing_fetcher() -> PricingFetcher {
    real_pricing_fetcher()
}

/// Kick off the statuspage probe on the tokio runtime: one fetch, then the
/// answer is held. A caller with no runtime gets a warn and holds no status
/// rather than a task nobody would run.
fn spawn_background_service_status_probe(
    started: &std::sync::atomic::AtomicBool,
    service_status: &Arc<Mutex<Option<ServiceIssue>>>,
    update_tx: &UpdateFanout,
    prober: ServiceStatusProber,
) {
    if started.swap(true, std::sync::atomic::Ordering::AcqRel) {
        return;
    }
    // Without this line a probe that stops running is invisible: the only
    // other record is the warning for a missing runtime, which is a
    // different failure.
    tracing::info!(
        target: "forge_workspace::workspace",
        event_name = "service_status_probe_started",
        "the statuspage probe is running",
    );
    let run = run_service_status_probe(Arc::clone(service_status), update_tx.clone(), prober);
    if let Ok(handle) = tokio::runtime::Handle::try_current() {
        handle.spawn(run);
    } else {
        tracing::warn!(
            target: "forge_workspace::workspace",
            event_name = "service_status_probe_skipped",
            "no tokio runtime at construction; the statuspage is not probed and no view reads a service status this run",
        );
    }
}

/// The statuspage probe, off the boot path. Its answer is held before it is
/// announced, so a view that attaches afterwards reads it rather than having
/// missed the one update that carried it.
async fn run_service_status_probe(
    service_status: Arc<Mutex<Option<ServiceIssue>>>,
    update_tx: UpdateFanout,
    prober: ServiceStatusProber,
) {
    let Some(issue) = prober().await else {
        return;
    };
    let update =
        SessionUpdate::ServiceStatus { severity: issue.severity, message: issue.message.clone() };
    *service_status.lock() = Some(issue);
    let _ = update_tx.send(update);
}

/// The claude version probe, off the boot path. Each result is merged into
/// the store, which wakes the views when it changed what they draw.
async fn run_cli_version_probe(
    cli_version: Arc<Mutex<Option<CliVersionInfo>>>,
    update_tx: UpdateFanout,
    prober: Arc<CliVersionProber>,
) {
    let mut interval = tokio::time::interval(CLI_VERSION_REFRESH_INTERVAL);
    interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
    loop {
        // The first tick completes immediately, so this is the boot fetch;
        // later ticks only recover a transient miss.
        interval.tick().await;
        let snapshot = prober().await;
        store_cli_version(&cli_version, &update_tx, snapshot);
    }
}

/// Merge one probe result into the store and wake the views when it moved
/// what they draw.
fn store_cli_version(
    store: &Mutex<Option<CliVersionInfo>>,
    update_tx: &UpdateFanout,
    next: CliVersionInfo,
) {
    let changed = {
        let mut held = store.lock();
        let merged = merge_cli_version(held.as_ref(), next);
        // A view draws the two versions, not the snapshot's presence: the
        // first probe that resolves nothing holds a snapshot and changes
        // nothing on screen, so it wakes nobody.
        let held_draws = match held.as_ref() {
            Some(held) => (held.installed.as_deref(), held.latest.as_deref()),
            None => (None, None),
        };
        let merged_draws = (merged.installed.as_deref(), merged.latest.as_deref());
        let changed = held_draws != merged_draws;
        *held = Some(merged);
        changed
    };
    if changed {
        let _ = update_tx.send(SessionUpdate::CliVersionChanged);
    }
}

/// Merge a freshly-probed snapshot over the held one, keeping a
/// previously-resolved field when the new probe came back `None` for it: a
/// failed network probe must not wipe a `latest` an earlier one found.
fn merge_cli_version(prev: Option<&CliVersionInfo>, next: CliVersionInfo) -> CliVersionInfo {
    let Some(prev) = prev else { return next };
    CliVersionInfo {
        installed: next.installed.or_else(|| prev.installed.clone()),
        latest: next.latest.or_else(|| prev.latest.clone()),
    }
}

/// The boot catalog scan, off the boot path. Reads the workspace's own
/// `config_dir` (canonicalized, so the redb tag-cache keys are the same
/// ones any other scan writes even when the config dir path carries a
/// symlink component) with the redb tag cache - only bytes appended
/// since the last scan are read end to end - swaps the grouped catalog
/// in one lock, prunes cache rows of transcripts that no longer exist,
/// and only then publishes readiness and `SessionUpdate::CatalogLoaded`.
async fn run_background_catalog_scan(
    catalog: Arc<Mutex<HashMap<ProjectKey, Vec<SDKSessionInfo>>>>,
    db: Arc<Mutex<Option<crate::store::Db>>>,
    config_dir: PathBuf,
    update_tx: UpdateFanout,
    loaded: Arc<std::sync::atomic::AtomicBool>,
) {
    // The tag cache is one key space with any other scan of this config
    // dir. Without a projects tree the scan still runs and finds an
    // empty catalog.
    let scan_root = catalog_scan_root(&config_dir)
        .unwrap_or_else(|| std::fs::canonicalize(&config_dir).unwrap_or(config_dir.clone()));
    let tag_cache = std::sync::Arc::new(load_session_tag_cache(db.lock().as_ref()));
    let catalog_entries = forge_agent::userdata::catalog::scan::list_sessions(
        &scan_root,
        None, // every project in the catalog
        None, // no limit
        0,
        forge_agent::userdata::catalog::scan::Workers::Hidden,
        Some(&tag_cache),
    )
    .await;
    persist_session_tag_cache(db.lock().as_ref(), &tag_cache);

    // Group sessions by project key derived from each session's cwd.
    // Sessions without a cwd are skipped - they can't be associated
    // with a project view.
    let mut grouped: HashMap<ProjectKey, Vec<SDKSessionInfo>> = HashMap::new();
    for entry in catalog_entries {
        if let Some(cwd) = entry.cwd.as_deref() {
            let key = ProjectKey::new(
                forge_agent::userdata::catalog::scan::project_key_for_directory(Some(cwd)),
            );
            grouped.entry(key).or_default().push(entry);
        }
    }
    // The catalog scan returns entries sorted by `last_modified`
    // descending; the per-project Vec inherits that ordering thanks
    // to push order being preserved.
    //
    // Sessions recorded live while the scan ran sit in the catalog
    // already (record_connected_session) and their transcripts may not
    // be on disk yet, so the disk-built map absorbs them rather than
    // replacing them.
    {
        let mut current = catalog.lock();
        for (key, entries) in current.drain() {
            let slot = grouped.entry(key).or_default();
            // The recorded list is newest-first; inserting each at the
            // head in reverse lands the newest back on top.
            for entry in entries.into_iter().rev() {
                if !slot.iter().any(|s| s.session_id == entry.session_id) {
                    slot.insert(0, entry);
                }
            }
        }
        *current = grouped;
    }

    if let Some(db) = db.lock().as_ref() {
        match crate::store::session_tags::prune_missing(db) {
            Ok(0) => {}
            Ok(count) => tracing::info!(
                target: "forge_workspace::workspace",
                count,
                "pruned session tag rows whose transcripts no longer exist",
            ),
            Err(error) => tracing::warn!(
                target: "forge_workspace::workspace",
                %error,
                "pruning stale session tag rows failed; the table keeps rows of deleted transcripts",
            ),
        }
    }

    loaded.store(true, std::sync::atomic::Ordering::Release);
    let _ = update_tx.send(SessionUpdate::CatalogLoaded);
}

/// The previous run's tag scans, or an empty cache when there is no
/// store: a missing cache costs a full re-scan, never a wrong answer.
fn load_session_tag_cache(
    db: Option<&crate::store::Db>,
) -> forge_agent::userdata::catalog::scan::SessionTagCache {
    let prior = db
        .map(|db| {
            crate::store::session_tags::load_all(db).unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "loading the session tag cache failed; every transcript will be re-scanned",
                );
                std::collections::HashMap::new()
            })
        })
        .unwrap_or_default();
    forge_agent::userdata::catalog::scan::SessionTagCache::new(prior)
}

fn persist_session_tag_cache(
    db: Option<&crate::store::Db>,
    cache: &forge_agent::userdata::catalog::scan::SessionTagCache,
) {
    let updates = cache.updates();
    if let Some(db) = db
        && let Err(error) = crate::store::session_tags::store_all(db, &updates)
    {
        tracing::warn!(
            target: "forge_workspace::workspace",
            %error,
            "storing the session tag cache failed; the next boot re-scans what it covered",
        );
    }
}

/// This config dir's redb store: `<app_support>/stores/<stable-key>.redb`.
///
/// **The key is stable across Rust releases** ([`forge_sdk::config_dir_store_key`]),
/// unlike the lock's `config_dir_hash`: a nightly bump must not open a new
/// empty store and orphan every row.
fn store_path(app_support: &Path, config_dir: &Path) -> PathBuf {
    crate::store::path_for(app_support, config_dir)
}

/// Whether this path is the home directory's `.claude`, the default config
/// dir.
///
/// The pre-split machine-wide store is the default config dir's state, so
/// only that config dir may adopt it. A scratch or second config dir booting
/// first must not take it; such a dir leaves the legacy file in place.
fn is_default_config_dir(config_dir: &Path) -> bool {
    let Some(home) = dirs::home_dir() else { return false };
    let default = home.join(".claude");
    match (config_dir.canonicalize(), default.canonicalize()) {
        (Ok(ours), Ok(theirs)) => ours == theirs,
        _ => config_dir == default,
    }
}

/// What a boot should do with the pre-split store.
enum Adoption {
    /// Nothing is stranded: there is no legacy file, this config dir already
    /// has its own store, or the legacy file belongs to another config dir.
    Settled,
    /// The legacy file is this default config dir's state and could not be
    /// moved this boot. Opening a fresh store would hide the file for good -
    /// the next boot sees a target and never looks again - so this run goes
    /// memory-only and the next boot retries.
    Deferred,
}

/// Adopt the pre-split machine-wide store into this config dir's own, once.
///
/// **Only the default config dir adopts** (see [`is_default_config_dir`]),
/// and the file is probe-opened first: a store another forge still holds is
/// left where it is rather than renamed behind its back.
fn adopt_legacy_store(app_support: &Path, config_dir: &Path, path: &Path) -> Adoption {
    let legacy = app_support.join("db.redb");
    if path.exists() || !legacy.is_file() {
        return Adoption::Settled;
    }
    if !is_default_config_dir(config_dir) {
        tracing::info!(
            target: "forge_workspace::workspace",
            event_name = "store_legacy_left_in_place",
            legacy = %legacy.display(),
            config_dir = %config_dir.display(),
            "the machine-wide store belongs to the home config dir, so it is left there; a \
             custom-only install can move it under stores/ by hand to keep its rows",
        );
        return Adoption::Settled;
    }
    adopt_legacy_store_from(&legacy, path)
}

/// The adoption itself, with the default-dir verdict already decided.
fn adopt_legacy_store_from(legacy: &Path, path: &Path) -> Adoption {
    match crate::store::Db::open(legacy) {
        // The probe takes the file's own lock and drops it again, so a store
        // another process holds is refused here rather than moved under it.
        Ok(probe) => drop(probe),
        Err(error) => {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "store_legacy_in_use",
                %error,
                legacy = %legacy.display(),
                "the machine-wide store is held by another process; this run has no durable \
                 state and the next boot retries the adoption",
            );
            return Adoption::Deferred;
        }
    }
    match std::fs::rename(legacy, path) {
        Ok(()) => {
            tracing::info!(
                target: "forge_workspace::workspace",
                event_name = "store_legacy_adopted",
                from = %legacy.display(),
                to = %path.display(),
                "the machine-wide store is adopted by the default config dir",
            );
            Adoption::Settled
        }
        Err(error) => {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "store_legacy_adopt_failed",
                %error,
                from = %legacy.display(),
                to = %path.display(),
                "the machine-wide store could not be adopted; this run has no durable state and \
                 the next boot retries",
            );
            Adoption::Deferred
        }
    }
}

/// Open this config dir's redb store, creating the directories first.
/// Returns `None` (with a warn) when they can't be created or the DB can't
/// open - forge then runs without durable crons, subscriptions, tasks or
/// dynamic workers this session (hard rule #14: no cwd fallback).
///
/// **The store is keyed by the config dir, as the lock is.** A machine-wide
/// `<app_support>/db.redb` from before the split is adopted once, by the
/// default config dir; a second config dir starts empty, which is the
/// isolation this keying exists for.
fn open_db(app_support: &Path, config_dir: &Path) -> Option<crate::store::Db> {
    // **One key space.** `config_dir_store_key` falls back to the raw path
    // when it cannot canonicalise, so a dir that fails once and resolves
    // later would open a second, empty store. The boot has already created
    // the config dir; a path that still cannot canonicalise gets no durable
    // state rather than a key that may move.
    let Ok(canonical) = config_dir.canonicalize() else {
        tracing::warn!(
            target: "forge_workspace::workspace",
            event_name = "store_dir_unresolved",
            config_dir = %config_dir.display(),
            "the config dir cannot be canonicalised, so its store key would not be stable; \
             durable crons, subscriptions, tasks and dynamic workers will not persist",
        );
        return None;
    };
    let path = store_path(app_support, &canonical);
    let stores = path.parent()?;
    if let Err(error) = std::fs::create_dir_all(stores) {
        tracing::warn!(
            target: "forge_workspace::workspace",
            event_name = "store_dir_create_failed",
            %error,
            path = %stores.display(),
            "creating the app-support stores dir failed; durable crons, subscriptions, tasks and dynamic workers will not persist",
        );
        return None;
    }
    if let Adoption::Deferred = adopt_legacy_store(app_support, config_dir, &path) {
        return None;
    }
    match crate::store::Db::open(&path) {
        Ok(db) => Some(db),
        Err(error) => {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "store_open_failed",
                %error,
                path = %path.display(),
                "opening the redb store failed; durable crons, subscriptions, tasks and dynamic workers will not persist",
            );
            None
        }
    }
}

/// The configured projects as the session store keys them: the catalog
/// key a `dynamic_workers` row carries, plus the org and name a
/// `sessions` row is keyed by.
fn project_identities(config: &LoadedConfig) -> Vec<crate::store::sessions::ProjectIdentity> {
    config
        .projects
        .iter()
        .map(|project| crate::store::sessions::ProjectIdentity {
            key: forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                &project.path.to_string_lossy(),
            )),
            org: project.org.clone(),
            name: project.name.clone(),
        })
        .collect()
}

/// The gateway's per-org walk order. Orgs are load-validated to share one
/// pin, so the first project of an org states it.
fn org_pins(config: &LoadedConfig) -> HashMap<String, forge_gateway::selection::OrgPin> {
    let mut pins: HashMap<String, forge_gateway::selection::OrgPin> = HashMap::new();
    for project in &config.projects {
        let pin =
            pins.entry(project.org.clone()).or_insert_with(|| forge_gateway::selection::OrgPin {
                accounts: project.accounts.clone(),
                fallback_accounts: project.fallback_accounts.clone(),
            });
        debug_assert_eq!(pin.accounts, project.accounts, "org pin drifted");
        debug_assert_eq!(pin.fallback_accounts, project.fallback_accounts, "org pin drifted");
    }
    pins
}

/// The scan root for one config dir: the canonical parent of its
/// resolved `projects` dir, or the canonical config dir itself when
/// the resolved tree is not named `projects` (the walk descends into
/// `<root>/projects`, so the target's parent would miss it). `None`
/// when there is no projects tree.
fn catalog_scan_root(config_dir: &std::path::Path) -> Option<PathBuf> {
    let projects = match std::fs::canonicalize(config_dir.join("projects")) {
        Ok(projects) => projects,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            tracing::debug!(
                target: "forge_workspace::workspace",
                config_dir = %config_dir.display(),
                "no projects tree; the catalog scan finds nothing here",
            );
            return None;
        }
        Err(error) => {
            tracing::warn!(
                target: "forge_workspace::workspace",
                config_dir = %config_dir.display(),
                %error,
                "cannot resolve this config dir's projects tree; its sessions are invisible to the scan",
            );
            return None;
        }
    };
    if projects.file_name().is_some_and(|name| name.to_str() == Some("projects")) {
        Some(projects.parent().map_or_else(|| config_dir.to_path_buf(), PathBuf::from))
    } else {
        Some(std::fs::canonicalize(config_dir).unwrap_or_else(|_| config_dir.to_path_buf()))
    }
}

/// A forge command's answer: what the reader is told, and how loudly.
///
/// **Returned rather than emitted where the command is handled**, because the
/// answer has to land AFTER the words that asked for it: the dispatcher echoes
/// those once the command has landed, and a notice sent from the handler
/// arrived first, which every client that draws the stream in order put above
/// the prompt it answers.
type ForgeAnswer = (NoticeSeverity, String);

/// The line a forge name invoked wrongly is answered with.
///
/// Answered rather than acted on, and never left to fall through as a prompt:
/// a mistyped command reaching the model reads as a question.
fn forge_misuse(usage: &str) -> ForgeAnswer {
    (NoticeSeverity::Error, usage.to_owned())
}

/// Record the surface a spawn hands its child.
///
/// The child fetches this list once and keeps it for its life, so this line
/// is the only statement of what it was given; the boot init frame's own
/// answer is recorded beside it.
fn record_session_tool_surface(slot: &SessionSlot, lead: bool, names: &[&str]) {
    tracing::debug!(
        target: "forge_workspace::mcp",
        event_name = "session_tool_surface",
        slot = %slot.display(),
        lead,
        count = names.len(),
        tools = %names.join(","),
        "the forge tool surface handed to this spawn",
    );
}

#[cfg(test)]
mod record_session_tool_surface_tests {
    use super::record_session_tool_surface;
    use crate::SessionSlot;
    use std::sync::{Arc, Mutex};
    use tracing::field::{Field, Visit};
    use tracing_subscriber::layer::SubscriberExt as _;

    #[derive(Clone, Debug)]
    struct CaughtEvent {
        level: tracing::Level,
        target: String,
        fields: Vec<(String, String)>,
    }

    impl CaughtEvent {
        fn field(&self, name: &str) -> Option<&str> {
            self.fields.iter().find(|(key, _)| key == name).map(|(_, value)| value.as_str())
        }
    }

    #[derive(Clone, Default)]
    struct Caught(Arc<Mutex<Vec<CaughtEvent>>>);

    struct Fields(Vec<(String, String)>);

    impl Visit for Fields {
        fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
            self.0.push((field.name().to_owned(), format!("{value:?}")));
        }

        fn record_str(&mut self, field: &Field, value: &str) {
            self.0.push((field.name().to_owned(), value.to_owned()));
        }

        fn record_bool(&mut self, field: &Field, value: bool) {
            self.0.push((field.name().to_owned(), value.to_string()));
        }

        fn record_u64(&mut self, field: &Field, value: u64) {
            self.0.push((field.name().to_owned(), value.to_string()));
        }

        fn record_i64(&mut self, field: &Field, value: i64) {
            self.0.push((field.name().to_owned(), value.to_string()));
        }
    }

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

    /// **The spawn's line is the artifact a "which list was that session
    /// handed" report is answered from**, so it is pinned field by field:
    /// a block that stops emitting, drops the slot, or changes the level
    /// fails here rather than leaving the record silently thinner.
    #[test]
    fn the_record_names_the_slot_kind_count_and_every_tool() {
        let caught = Caught::default();
        let subscriber = tracing_subscriber::registry().with(caught.clone());
        let slot = SessionSlot::worker("Busytools", "forge", "surface");
        let displayed = slot.display();
        tracing::subscriber::with_default(subscriber, || {
            record_session_tool_surface(&slot, false, &["agents__list", "browser_form_state"]);
        });

        let events = caught.0.lock().expect("capture");
        let event = events.last().expect("the record was emitted");
        assert_eq!(
            event.level,
            tracing::Level::DEBUG,
            "a spawn's surface is the session's own fact"
        );
        assert_eq!(
            event.target, "forge_workspace::mcp",
            "it lands under the default filter's target"
        );
        assert_eq!(event.field("event_name"), Some("session_tool_surface"));
        assert_eq!(event.field("slot"), Some(displayed.as_str()));
        assert_eq!(event.field("lead"), Some("false"));
        assert_eq!(event.field("count"), Some("2"));
        assert_eq!(event.field("tools"), Some("agents__list,browser_form_state"));
    }
}

impl Workspace {
    /// Builds a Workspace, kicks off the background catalog scan and the
    /// claude version probe, and loads `<config_dir>/forge.toml`. Errors if
    /// `forge.toml` is missing or malformed (e.g. no `[[orgs]]` entries, no
    /// `[[orgs.projects]]` entries, unknown account references). No
    /// Agents are spawned on success. The session catalog starts empty
    /// and fills when the scan lands - see [`Workspace::start_catalog_scan`].
    pub fn new(config_dir: PathBuf) -> Result<Self, WorkspaceError> {
        Self::new_impl(
            config_dir,
            None,
            true,
            Some(real_cli_version_prober()),
            Some(real_service_status_prober()),
            Some(real_pricing_fetcher()),
        )
    }

    /// Like [`Workspace::new`] but puts forge's whole app-support base -
    /// the redb store and the single-instance lock - under a tempdir
    /// inside `config_dir` rather than the real machine
    /// `app_support_dir`, so tests never touch the user's durable store
    /// or contend for their live lock. The catalog scan does NOT
    /// auto-start; tests opt in via [`Workspace::start_catalog_scan`]
    /// so the catalog stays empty until a fixture asks for it. Neither
    /// boot probe starts either: a test workspace reaches no network.
    #[cfg(any(test, feature = "testing"))]
    pub fn new_for_test(config_dir: PathBuf) -> Result<Self, WorkspaceError> {
        Self::new_for_test_impl(config_dir, None, None)
    }

    /// [`Workspace::new_for_test`] with the pricing refill driven by
    /// `fetcher` rather than by the inert default, so the refill's
    /// fetch-to-rescan path is exercisable without the network.
    #[cfg(any(test, feature = "testing"))]
    pub fn new_for_test_with_pricing_fetcher(
        config_dir: PathBuf,
        fetcher: PricingFetcher,
    ) -> Result<Self, WorkspaceError> {
        Self::new_for_test_impl(config_dir, None, Some(fetcher))
    }

    /// [`Workspace::new_for_test`] with `prober` driving the claude version
    /// probe in place of the real one, so a test drives the constructor's
    /// own launch without spawning `claude --version` or reaching npm.
    #[cfg(any(test, feature = "testing"))]
    pub fn new_for_test_with_cli_version_prober(
        config_dir: PathBuf,
        prober: CliVersionProber,
    ) -> Result<Self, WorkspaceError> {
        Self::new_for_test_impl(config_dir, Some(prober), None)
    }

    #[cfg(any(test, feature = "testing"))]
    fn new_for_test_impl(
        config_dir: PathBuf,
        cli_version_prober: Option<CliVersionProber>,
        pricing_fetcher: Option<PricingFetcher>,
    ) -> Result<Self, WorkspaceError> {
        let app_support = config_dir.join("app-support");
        let workspace = Self::new_impl(
            config_dir,
            Some(app_support),
            false,
            cli_version_prober,
            None,
            pricing_fetcher,
        )?;
        // Tests never start the listener; the boot gate reads open so
        // spawn paths are exercisable, and the I2 test flips it back to
        // closed explicitly when it needs the refusal.
        workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
        Ok(workspace)
    }

    /// Run the catalog scan in the background and signal readiness
    /// when it lands. `[`Workspace::new`] calls this during
    /// construction; tests built on `new_for_test` opt in explicitly so
    /// the catalog stays empty until a fixture asks for it. Idempotent -
    /// a second call is a no-op.
    pub fn start_catalog_scan(&self) {
        spawn_background_catalog_scan(
            &self.catalog,
            &self.db,
            &self.config_dir,
            &self.update_tx,
            &self.catalog_loaded,
            &self.catalog_scan_started,
        );
    }

    /// Whether the background catalog scan has populated the catalog.
    /// False from construction until the scan lands; always true when
    /// constructed without a tokio runtime (nothing would run it).
    ///
    /// [`Self::resumable_sessions`] reads it: a lead's list is the catalog's
    /// group once the scan has landed, and the directory's own read until
    /// then, so the two sources are told apart rather than an unscanned
    /// catalog being read as a project with no sessions. Tests also await it
    /// to sequence a fixture against the scan.
    pub fn catalog_ready(&self) -> bool {
        self.catalog_loaded.load(std::sync::atomic::Ordering::Acquire)
    }

    /// The process's subsystem supervisor. Every long-lived background task
    /// registers here, so a death is named and a restart is bounded.
    pub fn supervisor(&self) -> &Arc<forge_supervise::Supervisor> {
        &self.supervisor
    }

    /// Kick off the claude version probe on the tokio runtime: one fetch at
    /// boot, then a re-probe every [`CLI_VERSION_REFRESH_INTERVAL`]. The
    /// constructor is the only production caller, and the prober it takes
    /// is what lets a test drive this same launch. Idempotent - a second
    /// call is a no-op.
    fn start_cli_version_probe(&self, prober: CliVersionProber) {
        // **No runtime means no probe this run.** The registry would defer
        // the member until a runtime appeared, but a workspace built outside
        // one is a test's or a caller's construction, not a boot: say so
        // once and hold no version rather than start a task nobody would
        // run.
        if tokio::runtime::Handle::try_current().is_err() {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "cli_version_probe_skipped",
                "no tokio runtime at construction; the claude version probe is skipped and the views show no claude version this run",
            );
            return;
        }
        let cli_version = Arc::clone(&self.cli_version);
        let update_tx = self.update_tx.clone();
        let prober = Arc::new(prober);
        self.supervisor.spawn("cli_version_probe", forge_supervise::Policy::backoff(), move || {
            let cli_version = Arc::clone(&cli_version);
            let update_tx = update_tx.clone();
            let prober = Arc::clone(&prober);
            async move { run_cli_version_probe(cli_version, update_tx, prober).await }
        });
    }

    /// The `claude` CLI versions the core holds: what is installed on this
    /// machine and what npm publishes, both `None` until the boot probe
    /// resolves them. The same answer for every viewer, so a view reads it
    /// here rather than probing for itself. A change arrives as
    /// [`SessionUpdate::CliVersionChanged`].
    pub fn cli_version(&self) -> Option<CliVersionInfo> {
        self.cli_version.lock().clone()
    }

    /// Shared constructor body. `app_support` supplies the app-support
    /// base dir; `None` resolves the real machine `app_support_dir` and
    /// degrades to no lock and no durable store on failure (hard rule
    /// #14: no cwd fallback).
    ///
    /// `cli_version_prober` and `service_status_prober` are `None` for a
    /// workspace built by a test. Both probes fetch over the network at boot
    /// and announce the answer on the core's own stream, so a test workspace
    /// that ran them would both depend on a remote service's health and hand
    /// every test a slot-less update it never emitted.
    fn new_impl(
        config_dir: PathBuf,
        app_support: Option<PathBuf>,
        catalog_scan: bool,
        cli_version_prober: Option<CliVersionProber>,
        service_status_prober: Option<ServiceStatusProber>,
        pricing_fetcher: Option<PricingFetcher>,
    ) -> Result<Self, WorkspaceError> {
        let config = load_from_dir(&config_dir)?;

        // Create forge's own config subfolder before anything writes into
        // it (the lock, the cron + state stores all live under it). Hard-
        // fail if it can't be created: forge can persist nothing without a
        // writable config dir, so degrading is pointless.
        crate::config::ensure_forge_data_dir(&config_dir).map_err(|source| {
            WorkspaceError::DataDirUnavailable {
                path: crate::config::forge_data_dir(&config_dir),
                source,
            }
        })?;

        // forge's machine-local app-support base, resolved once: the
        // single-instance lock and the redb store both sit under it.
        // `Some` comes from the test constructor, which points the whole
        // base at a tempdir. `None` degrades to no lock and no durable
        // store rather than falling back to cwd (hard rule #14).
        let app_support = match app_support {
            Some(dir) => Some(dir),
            None => match forge_sdk::app_support_dir() {
                Ok(dir) => Some(dir),
                Err(error) => {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        %error,
                        "app-support dir unresolved; the single-instance guard is skipped and durable state will not persist",
                    );
                    None
                }
            },
        };

        // Single-instance guard: forge runs one process per config dir.
        // The held File is stored on `Self` for the process lifetime;
        // flock auto-releases on exit/crash. A second forge on the same
        // config dir hard-fails here.
        let single_instance_lock = match app_support.as_deref() {
            Some(base) => match crate::single_instance::acquire(&config_dir, base) {
                Ok(lock) => lock,
                Err(crate::single_instance::AcquireError::AlreadyRunning { pid }) => {
                    return Err(WorkspaceError::AlreadyRunning { pid });
                }
            },
            None => None,
        };
        // The guard fell open (lockfile unopenable or flock unsupported).
        // forge still boots, but the cron store's single-writer assumption
        // no longer holds - surface it loudly rather than leaving it at the
        // module-internal warn `acquire` already logged.
        if single_instance_lock.is_none() {
            tracing::error!(
                target: "forge_workspace::workspace",
                config_dir = %config_dir.display(),
                "single-instance guard unavailable; on-disk state (crons, usage cache, settings) is NOT protected against a second forge on this config dir - check the dir is writable and on a flock-capable filesystem",
            );
        }

        // Open the machine-local redb store: durable crons, Gotify and Slack
        // subscriptions all live in it. A failure to resolve the app-
        // support dir or open the DB degrades to no durable state this run
        // (non-fatal, like the state cache) - no cwd fallback (hard rule #14).
        let mut db = app_support.as_deref().and_then(|base| open_db(base, &config_dir));

        // Load durable forge crons into the in-memory working set. Boot
        // catch-up for entries that came due while forge was down runs after
        // construction, once the dispatch machinery is live. A failed load
        // leaves the set empty while rows may still be on disk, so mark the
        // run's crons unavailable rather than letting `cron__list` report an
        // empty registry.
        let mut crons_load_failed = false;
        let crons = if let Some(db) = &db {
            crate::store::cron::list(db).unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "loading durable crons failed; starting with none this run",
                );
                crons_load_failed = true;
                Vec::new()
            })
        } else {
            crons_load_failed = true;
            Vec::new()
        };
        let tasks = match &db {
            Some(db) => crate::store::tasks::list(db).unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "loading durable tasks failed; starting with none this run",
                );
                Vec::new()
            }),
            None => Vec::new(),
        };
        let gotify_subs = match &db {
            Some(db) => crate::store::gotify::list(db).unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "loading durable Gotify subscriptions failed; starting with none",
                );
                Vec::new()
            }),
            None => Vec::new(),
        };
        let mut slack_load_failed = false;
        let slack_subs = match &db {
            Some(db) => crate::store::slack::list(db).unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "loading durable Slack subscriptions failed; starting with none",
                );
                slack_load_failed = true;
                Vec::new()
            }),
            None => Vec::new(),
        };

        // The boot moves anything still in `dynamic_workers` onto
        // `sessions`, so a worker persisted before this build has a row
        // the re-spawn wave can read, and drops the retired table once
        // nothing is left in it. Non-fatal, like the loads above.
        let mut swept_clean = false;
        if let Some(db) = &db {
            match crate::store::sessions::migrate_from_dynamic_workers(
                db,
                &project_identities(&config),
            ) {
                Ok(outcome) => {
                    if outcome.unkeyable > 0 {
                        tracing::warn!(
                            target: "forge_workspace::workspace",
                            unkeyable = outcome.unkeyable,
                            "the retired worker table holds rows no configured project can key; \
                             they stay there and the table is not dropped",
                        );
                    }
                    swept_clean = outcome.drained();
                }
                Err(error) => tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "migrating persisted workers into the sessions table failed; the retired \
                     table is left in place for the next boot",
                ),
            }
        }
        // The boot wave derives the open set from `seat_state`, so a row
        // written before the field existed is seeded `idle` here: the first
        // boot on this build opens every project whose lead ever spawned,
        // and every boot after reads an explicit state. Non-fatal, like the
        // sweep above.
        if let Some(db) = &db {
            match crate::store::sessions::seed_seat_state(db) {
                Ok(seeded) if seeded > 0 => tracing::info!(
                    target: "forge_workspace::sessions",
                    event_name = "seat_state_seeded",
                    rows = seeded,
                    "seeded the seats written before the seat-state field",
                ),
                Ok(_) => {}
                Err(error) => tracing::warn!(
                    target: "forge_workspace::sessions",
                    event_name = "seat_state_seed_failed",
                    %error,
                    "seeding the seats written before the seat-state field failed; the rows it \
                     did not reach read as absent, and the boot opens nothing for them",
                ),
            }
        }
        // Drop the retired table only once every row it held has been
        // copied, and reclaim its pages - a copied table is still
        // allocated. A sweep that errored, that left a row it could not
        // key, or that did not run at all leaves rows there and only
        // there, so dropping on any of those would lose a worker the user
        // believes is durable, silently and with nothing to say which
        // label went. A store that never had the table drops nothing.
        if swept_clean && let Some(db) = db.as_mut() {
            match crate::store::dynamic_workers::drop_table(db) {
                Ok(true) => {
                    if let Err(error) = db.compact() {
                        tracing::warn!(
                            target: "forge_workspace::workspace",
                            %error,
                            "compacting the store after dropping the retired worker table failed",
                        );
                    }
                }
                Ok(false) => {}
                Err(error) => tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "dropping the retired dynamic_workers table failed; it stays for the next boot",
                ),
            }
        }
        // The catalog table outlived its module: deleting the machinery
        // left the rows behind, and nothing reads or writes them now, so
        // there is nothing to drain first. A store that never cached a
        // catalog drops nothing.
        if let Some(db) = db.as_mut() {
            match crate::store::model_catalog::drop_table(db) {
                Ok(true) => {
                    if let Err(error) = db.compact() {
                        tracing::warn!(
                            target: "forge_workspace::workspace",
                            %error,
                            "compacting the store after dropping the retired model catalog table failed",
                        );
                    }
                }
                Ok(false) => {}
                Err(error) => tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "dropping the retired model_catalog table failed; it stays for the next boot",
                ),
            }
        }
        // The fired-prompt pairings had no retention: every fire added a row
        // and nothing took one away. A boot drops the ones past the window.
        if let Some(db) = &db {
            match crate::store::cron_names::prune_expired(db, std::time::SystemTime::now()) {
                Ok(0) => {}
                Ok(removed) => tracing::debug!(
                    target: "forge_workspace::workspace",
                    event_name = "cron_names_pruned",
                    removed,
                    "dropped fired-prompt pairings older than the retention window",
                ),
                Err(error) => tracing::warn!(
                    target: "forge_workspace::workspace",
                    event_name = "cron_names_prune_failed",
                    %error,
                    "sweeping old fired-prompt pairings failed; they stay until the next boot",
                ),
            }
        }
        // The settings table held one row, the `/spinner` override, which went
        // with the spinner.
        if let Some(db) = db.as_mut() {
            match crate::store::settings::drop_table(db) {
                Ok(true) => {
                    if let Err(error) = db.compact() {
                        tracing::warn!(
                            target: "forge_workspace::workspace",
                            %error,
                            "compacting the store after dropping the retired settings table failed",
                        );
                    }
                }
                Ok(false) => {}
                Err(error) => tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "dropping the retired settings table failed; it stays for the next boot",
                ),
            }
        }

        // Resolved here rather than lazily so a malformed `[[slack]]`
        // entry refuses the boot, the way the rest of forge.toml does.
        // The client goes through the same TLS-trust helper the Gotify
        // seam uses, so NODE_EXTRA_CA_CERTS behaves identically.
        let slack_http = forge_agent::http_trust::with_extra_roots(reqwest::Client::builder())
            .build()
            .map_err(|error| WorkspaceError::ConfigInvalid {
                path: crate::config::forge_data_dir(&config_dir).join("forge.toml"),
                message: format!("slack http client: {error}"),
            })?;
        let slack = Arc::new(
            crate::slack::SlackWorkspaces::from_config(&config.slack, &slack_http).map_err(
                |message| WorkspaceError::ConfigInvalid {
                    path: crate::config::forge_data_dir(&config_dir).join("forge.toml"),
                    message,
                },
            )?,
        );
        let systemone = crate::systemone::client_for(
            config.systemone.as_ref(),
            &crate::config::forge_data_dir(&config_dir).join("forge.toml"),
        )?
        .map(Arc::new);
        // Built above the struct rather than with it: the vault session
        // announces a rotation through this fan-out, and the session is made
        // before the struct's own field exists.
        let update_tx = UpdateFanout::default();
        let vault = match config.vault.as_ref() {
            Some(vault_config) => Some(Arc::new(
                crate::vault::VaultSession::with_client(
                    vault_config,
                    app_support.as_deref(),
                    &config_dir,
                    crate::vault::production_client(&vault_config.url).map_err(|error| {
                        WorkspaceError::ConfigInvalid {
                            path: crate::config::forge_data_dir(&config_dir).join("forge.toml"),
                            message: format!("[vault] {error}"),
                        }
                    })?,
                    update_tx.clone(),
                )
                .map_err(|error| WorkspaceError::ConfigInvalid {
                    path: crate::config::forge_data_dir(&config_dir).join("forge.toml"),
                    message: format!("[vault] {error}"),
                })?,
            )),
            None => None,
        };

        // Catalog scan reads against the workspace's canonical
        // `config_dir` (where forge.toml lives). Each spawn binds to
        // its own account `config_dir` separately; multi-account
        // catalog merge is a separate concern.
        // The scan itself runs in the background (#794): reading every
        // transcript end to end for its worker tag was the bulk of the
        // pre-paint pause. The catalog starts empty and fills when the
        // scan lands; nothing on a spawn path waits for it.
        let catalog = Arc::new(Mutex::new(HashMap::new()));

        let accounts = Arc::new(forge_gateway::AccountPool::new(&config.accounts));
        // The forward leg's client comes from the host port, like every
        // other outbound path: the inference upstream then carries the
        // same extra trust roots the probes do.
        let forward_http = forge_agent::cloud::AgentHost
            .streaming_http_client(
                forge_gateway::forward::FORWARD_CONNECT_TIMEOUT,
                forge_gateway::forward::FORWARD_IDLE_TIMEOUT,
            )
            .map_err(|error| WorkspaceError::ConfigInvalid {
                path: crate::config::forge_data_dir(&config_dir).join("forge.toml"),
                message: format!("forward-leg http client: {error}"),
            })?;
        let gateway =
            Arc::new(forge_gateway::forward::Gateway::new(Arc::clone(&accounts), forward_http));
        // Hand the gateway each org's walk order so an unbound session
        // can select an account from its path alone - the restart case,
        // where the bindings are gone but the config is loaded.
        gateway.set_org_pins(org_pins(&config));
        gateway.set_rotation_numbers(config.gateway_rotation);

        // Seed account usage from the machine-local store so usage
        // reads have data immediately at cold boot.
        // Anthropic's /api/oauth/usage rate-limiter can stall the first
        // live probe for 30 s+; without seed data every account reads as
        // unknown during that window, so nothing is demoted for being at
        // its cap. The background poller refreshes these snapshots on the
        // configured interval (60 s by default) - the cache is purely
        // "last known value" seed.
        let state = match &db {
            Some(db) => crate::account_cache::load(db),
            None => crate::account_cache::ForgeState::empty(),
        };
        accounts.seed_from_cache(&state.account_usage);

        let gateway_port = config.gateway_port;
        let (kick_dispatcher_tx, kick_dispatcher_rx) = mpsc::unbounded_channel::<KickRequest>();
        let config_dictate = config.dictate.clone();
        let db = Arc::new(Mutex::new(db));
        let catalog_loaded = Arc::new(std::sync::atomic::AtomicBool::new(false));
        let catalog_scan_started = std::sync::atomic::AtomicBool::new(false);
        if catalog_scan {
            spawn_background_catalog_scan(
                &catalog,
                &db,
                &config_dir,
                &update_tx,
                &catalog_loaded,
                &catalog_scan_started,
            );
        }
        // The version facts are the same for every viewer, so the core
        // probes them once and both views read one answer.
        let cli_version = Arc::new(Mutex::new(None));
        // The statuspage answer is the same for every viewer too, and it
        // has to outlive the view that used to fetch it.
        let service_status: Arc<Mutex<Option<ServiceIssue>>> = Arc::new(Mutex::new(None));
        let (settings, _settings_rx) = tokio::sync::watch::channel(None);
        let workspace = Self {
            config_dir,
            config: parking_lot::RwLock::new(Arc::new(config)),
            settings,
            settings_version: std::sync::OnceLock::new(),
            settings_write: parking_lot::Mutex::new(()),
            reload_generation: std::sync::atomic::AtomicU64::new(0),
            reload_gate: std::sync::Mutex::new(()),
            systemone: parking_lot::RwLock::new(systemone),
            vault: parking_lot::RwLock::new(vault),
            voice: std::sync::OnceLock::new(),
            voice_preview_error: std::sync::Mutex::new(None),
            catalog,
            app_support,
            pool: Mutex::new(HashMap::new()),
            pricing_fetcher: pricing_fetcher.unwrap_or_else(default_pricing_fetcher),
            #[cfg(any(test, feature = "testing"))]
            test_spawn_handle: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_spawn_server: Mutex::new(None),
            accounts,
            gateway,
            gateway_ready: std::sync::atomic::AtomicBool::new(false),
            shutting_down: std::sync::atomic::AtomicBool::new(false),
            gateway_port,
            gateway_url: Mutex::new(None),
            gateway_bind_error: Mutex::new(None),
            dictate: Arc::new(crate::dictate::DictateState::new(&config_dictate)),
            dictate_runtime: Mutex::new(crate::dictate::DictateRuntime::default()),
            browser_host: std::sync::OnceLock::new(),
            live_seats_lock: std::sync::Mutex::new(()),
            live_seats_generation: std::sync::atomic::AtomicU64::new(0),
            #[cfg(any(test, feature = "testing"))]
            live_seats_gate: Mutex::new(None),
            attached_clients: std::sync::atomic::AtomicUsize::new(0),
            document_handoffs: parking_lot::Mutex::new(HashMap::new()),
            dictate_catalogue: Mutex::new(crate::catalogue::CatalogueState::default()),
            dictate_install: Mutex::new(crate::install::InstallState::default()),
            plugin_cli: Mutex::new(crate::plugins::PluginCli::real()),
            plugin_run: Mutex::new(None),
            plugin_action_running: std::sync::atomic::AtomicBool::new(false),
            dictate_activate: Mutex::new(crate::install::ActivateState::default()),
            dictate_bench: Mutex::new(crate::bench::BenchState::default()),
            dictate_bench_cancel: std::sync::atomic::AtomicBool::new(false),
            speaking_bench: Mutex::new(crate::bench::SpeakingBenchState::default()),
            speaking_bench_cancel: std::sync::atomic::AtomicBool::new(false),
            bench_claim: std::sync::atomic::AtomicBool::new(false),
            read_aloud_error: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_catalogue_source: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_cleanup_source: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_catalogue_dir: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_read_aloud_dir: Mutex::new(None),
            update_tx,
            command_senders: Mutex::new(HashMap::new()),
            session_teardowns: Mutex::new(HashMap::new()),
            live_workers: Mutex::new(HashMap::new()),
            idle_sweeps: Mutex::new(HashMap::new()),
            worktree_claims: Arc::new(parking_lot::Mutex::new(HashMap::new())),
            despawn_cleanups: Mutex::new(HashSet::new()),
            spawn_failures: Mutex::new(HashMap::new()),
            deaths: Mutex::new(HashMap::new()),
            heal_progress: Mutex::new(HashMap::new()),
            healing: std::sync::OnceLock::new(),
            held_work_seats: crate::work::HeldSeats::default(),
            domain_handles: Mutex::new(HashMap::new()),
            review_origin: Mutex::new(HashMap::new()),
            review_activity: Mutex::new(HashMap::new()),
            supervisor: Arc::new(forge_supervise::Supervisor::new()),
            dictate_preflight_started: std::sync::atomic::AtomicBool::new(false),
            voice_prewarm_started: std::sync::atomic::AtomicBool::new(false),
            voice_prewarm_dispatched: std::sync::atomic::AtomicBool::new(false),
            kick_dispatcher_tx,
            kick_dispatcher_rx_slot: Mutex::new(Some(kick_dispatcher_rx)),
            _single_instance_lock: single_instance_lock,
            crons: Mutex::new(crons),
            crons_load_failed: std::sync::atomic::AtomicBool::new(crons_load_failed),
            tasks: Mutex::new(tasks),
            parked_by_slot: Mutex::new(HashMap::new()),
            pending_handoffs: Mutex::new(HashMap::new()),
            swapping: Mutex::new(HashMap::new()),
            swap_epochs: std::sync::atomic::AtomicU64::new(0),
            held_prompts: Mutex::new(HashMap::new()),
            gotify_subs: Mutex::new(gotify_subs),
            db,
            catalog_loaded,
            catalog_scan_started,
            cli_version,
            last_fatal_error: Mutex::new(None),
            service_status,
            service_status_probe_started: std::sync::atomic::AtomicBool::new(false),
            gotify_connected: Mutex::new(false),
            gotify_app_index: Mutex::new(HashMap::new()),
            gotify_subsystem: Mutex::new(None),
            slack,
            slack_subs: Mutex::new(slack_subs),
            slack_subsystem: Mutex::new(std::collections::BTreeMap::new()),
            slack_connected: Mutex::new(std::collections::BTreeMap::new()),
            slack_inflight: Mutex::new(std::collections::HashMap::new()),
            slack_user_ids: Mutex::new(std::collections::BTreeMap::new()),
            slack_user_names: Mutex::new(std::collections::BTreeMap::new()),
            slack_author_failures: Mutex::new(std::collections::HashSet::new()),
            slack_draft_user_failures: Mutex::new(std::collections::HashSet::new()),
            slack_thread_failures: Mutex::new(std::collections::HashSet::new()),
            slack_thread_full_reads: Mutex::new(std::collections::HashMap::new()),
            slack_thread_first_walks: Mutex::new(std::collections::HashSet::new()),
            slack_thread_edit_watermarks: Mutex::new(std::collections::HashMap::new()),
            slack_ledger_failures: Mutex::new(std::collections::HashSet::new()),
            slack_drafts: Mutex::new(HashMap::new()),
            browser_handoffs: Mutex::new(HashMap::new()),
            terminals: Mutex::new(HashMap::new()),
            terminal_handoffs: Mutex::new(HashMap::new()),
            next_terminal_id: std::sync::atomic::AtomicU16::new(1),
            settings_writes: Mutex::new(HashMap::new()),
            parked_vault_asks: Mutex::new(HashMap::new()),
            pending_seq: Mutex::new(HashMap::new()),
            slack_recently_delivered: Mutex::new(HashMap::new()),
            slack_load_failed: std::sync::atomic::AtomicBool::new(slack_load_failed),
            slack_user_id_retries: Mutex::new(std::collections::BTreeMap::new()),
            slack_verification_started: std::sync::atomic::AtomicBool::new(false),
            respawn_in_flight: Mutex::new(std::collections::HashSet::new()),
            unwakeable_crons: Mutex::new(std::collections::HashSet::new()),
            cooling_crons: Mutex::new(std::collections::HashMap::new()),
            #[cfg(any(test, feature = "testing"))]
            command_intercept: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_extra_projects: Mutex::new(Vec::new()),
            #[cfg(any(test, feature = "testing"))]
            test_user_preferences: Mutex::new(None),
            #[cfg(any(test, feature = "testing"))]
            test_claude_pid: Mutex::new(std::collections::HashMap::new()),
            #[cfg(any(test, feature = "testing"))]
            test_scan_gate: Mutex::new(None),
        };
        if let Some(prober) = cli_version_prober {
            workspace.start_cli_version_probe(prober);
        }
        if let Some(prober) = service_status_prober {
            workspace.start_service_status_probe(prober);
        }
        if workspace.db.lock().is_none() {
            // One user-visible notice for the whole best-effort-persist
            // class (durable crons, subscriptions): the
            // store is gone this run, so every one of those warns would
            // otherwise fire per-op into the log only.
            let _ = workspace.update_tx.send(SessionUpdate::ServiceStatus {
                severity: forge_primitives::cloud::service_status::ServiceSeverity::Warning,
                message: "Machine-local store unavailable this run; crons, tasks, Gotify and Slack subscriptions will not persist".to_owned(),
            });
        }
        Ok(workspace)
    }

    /// Effective `[server]` settings: whether the socket's listener starts
    /// and where it binds. Read by the binary entry point, which serves the
    /// socket - the workspace never does.
    pub fn server_config(&self) -> forge_primitives::ServerConfig {
        self.config_arc().server.clone()
    }

    /// The live config as one owned snapshot. A reload swaps the whole
    /// value, so every reader takes the snapshot it will use rather than a
    /// reference that a reload could pull out from under it.
    pub(crate) fn config_arc(&self) -> Arc<LoadedConfig> {
        Arc::clone(&self.config.read())
    }

    /// Whether a spawn's resolution ran entirely inside one settled config:
    /// the generation is odd while a reload swaps state, so the start must
    /// be even and equal to the end.
    fn resolution_held(generation: u64, settled: u64) -> bool {
        generation.is_multiple_of(2) && generation == settled
    }

    /// Re-read `<config_dir>/forge.toml` and apply what can change without
    /// a restart. A reload is a whole-config replacement: the parsed value
    /// goes through the same loader a boot uses, and only a valid file
    /// replaces the live config. An invalid file returns its error and
    /// leaves the previous config untouched, so a half-written save never
    /// loses a good config.
    ///
    /// What a reader sees after this returns equals what a boot on the same
    /// file would load. Running sessions keep what they spawned with; only
    /// their next use reads the new values.
    ///
    /// # Errors
    ///
    /// The file could not be read, parsed or validated, or the systemone
    /// client could not be built. Nothing was applied.
    pub fn reload_config(self: &Arc<Self>) -> Result<ConfigReload, WorkspaceError> {
        let next = crate::config::load_from_dir(&self.config_dir)?;
        let forge_toml = crate::config::forge_data_dir(&self.config_dir).join("forge.toml");
        let systemone =
            crate::systemone::client_for(next.systemone.as_ref(), &forge_toml)?.map(Arc::new);
        // The vault session is rebuilt only when its own section changed: a
        // config save that does not touch `[vault]` must not lock a live
        // vault and make the next tool call ask for the master password.
        let vault = match next.vault.as_ref() {
            Some(vault_config) if self.config.read().vault.as_ref() == Some(vault_config) => {
                self.vault.read().clone()
            }
            Some(vault_config) => Some(Arc::new(
                crate::vault::VaultSession::with_client(
                    vault_config,
                    self.app_support.as_deref(),
                    &self.config_dir,
                    crate::vault::production_client(&vault_config.url).map_err(|error| {
                        WorkspaceError::ConfigInvalid {
                            path: forge_toml.clone(),
                            message: format!("[vault] {error}"),
                        }
                    })?,
                    self.update_tx.clone(),
                )
                .map_err(|error| WorkspaceError::ConfigInvalid {
                    path: forge_toml.clone(),
                    message: format!("[vault] {error}"),
                })?,
            )),
            None => None,
        };

        let previous = self.config.read().clone();
        let reload = previous.diff(&next);
        let added_accounts: Vec<forge_gateway::AccountKey> = next
            .accounts
            .iter()
            .filter(|account| {
                !previous.accounts.iter().any(|old| old.display_name == account.display_name)
            })
            .map(|account| forge_gateway::AccountKey(account.display_name.clone()))
            .collect();

        // Odd while the swap runs. A spawn that resolves across it retries;
        // see `resolution_held`. **The gate is held for exactly that window**,
        // so a spawn that sees the odd number waits on it rather than
        // spinning on the counter.
        {
            let _settling =
                self.reload_gate.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
            self.reload_generation.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
            self.accounts.replace_accounts(&next.accounts);
            self.gateway.set_org_pins(org_pins(&next));
            // The setter rebuilds the rotation state, which would empty the
            // live cooldowns and streaks. Only a live change to the numbers is
            // allowed to do that: a port-only reload reports `server.port` as
            // restart-only and must keep the state.
            if reload.changed.iter().any(|path| path.starts_with("gateway.")) {
                self.gateway.set_rotation_numbers(next.gateway_rotation);
            }
            *self.systemone.write() = systemone;
            *self.vault.write() = vault;
            *self.config.write() = Arc::new(next);
            self.reload_generation.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
        }
        // The page reads the same catalogue the reload summary does, so its
        // frame follows every applied edit; a save that moved no drawn value
        // publishes nothing.
        self.publish_settings();

        // A new account starts `Loading`; kick the same probe a boot runs
        // so it does not wait for the poller's next tick.
        for key in added_accounts {
            let weak = Arc::downgrade(self);
            let span = tracing::info_span!("account_loading", account = %key.0);
            tokio::spawn(
                async move { crate::account_loader::run_account_loading(key, weak).await }
                    .instrument(span),
            );
        }

        // A project-only edit moves the roster, not the pool: the server
        // roster reads it on the next home read, and an `AccountsChanged`
        // frame here would claim a pool move that did not happen.
        if reload.moved("accounts.") {
            self.announce_accounts_changed();
        }
        Ok(reload)
    }

    /// Effective `[client]` settings: which of the sets forge ships a
    /// client draws with. Carried by the greeting, so a client never reads
    /// `forge.toml` itself.
    pub fn client_config(&self) -> forge_primitives::ClientConfig {
        self.config_arc().client.clone()
    }

    /// Name the build the settings frame carries, and publish the first
    /// document. The server calls this once at boot, before the socket
    /// serves; a second call keeps the first name.
    pub fn set_settings_version(&self, version: &str) {
        if self.settings_version.set(version.to_owned()).is_ok() {
            self.publish_settings();
        }
    }

    /// The effective-config document as it stood at the last load. Every
    /// connection takes its own receiver; a reload that changed a drawn value
    /// sends a new one to all of them.
    pub fn subscribe_settings(
        &self,
    ) -> tokio::sync::watch::Receiver<Option<Arc<forge_primitives::SettingsDocument>>> {
        self.settings.subscribe()
    }

    /// Apply a batched settings save to `forge.toml`.
    ///
    /// The file is read under the write lock, the page's fingerprint is
    /// compared with it, the edits are applied to its text, and the candidate
    /// is validated with the boot loader before an atomic replace. A save
    /// that fails validation writes nothing; the reload and its push are the
    /// watcher's, so every client learns the outcome from one frame.
    ///
    /// # Errors
    ///
    /// The file moved since the page loaded it, an edit or the candidate is
    /// not valid, a guard refused it, or the write failed.
    pub fn save_settings(
        &self,
        fingerprint: &str,
        edits: &[SettingsEditRequest],
    ) -> Result<(), SettingsSaveError> {
        let _one_at_a_time = self.settings_write.lock();
        let path = self.config_path();
        let candidate = self.settings_candidate(&path, fingerprint, edits)?;
        // **The file may have moved between the read and the write.**
        // `write_atomically` re-reads it after the temp exists and before
        // the rename, which is the last moment the check can run.
        write_atomically(&path, &candidate, Some(fingerprint)).map_err(|error| match error {
            WriteRefusal::Stale => SettingsSaveError::Stale,
            WriteRefusal::Io(error) => {
                SettingsSaveError::Io(format!("forge.toml could not be written: {error}"))
            }
        })
    }

    /// Validate a save's candidate without writing it.
    ///
    /// The same checks the save runs, over the whole batch, so a caller can
    /// refuse a write the file would never accept before asking the reader
    /// about it. Not the authority: [`Self::save_settings`] repeats every
    /// check under its write lock.
    pub(crate) fn validate_settings(
        &self,
        fingerprint: &str,
        edits: &[SettingsEditRequest],
    ) -> Result<(), SettingsSaveError> {
        let path = self.config_path();
        self.settings_candidate(&path, fingerprint, edits).map(|_candidate| ())
    }

    /// Build the save's candidate text and run it through every check short
    /// of the write.
    fn settings_candidate(
        &self,
        path: &std::path::Path,
        fingerprint: &str,
        edits: &[SettingsEditRequest],
    ) -> Result<String, SettingsSaveError> {
        let current = std::fs::read_to_string(path).map_err(|error| {
            SettingsSaveError::Io(format!("forge.toml could not be read: {error}"))
        })?;
        if crate::config::fingerprint_of(&current) != fingerprint {
            return Err(SettingsSaveError::Stale);
        }
        let config = self.config_arc();
        let version = self.settings_version.get().map(String::as_str).unwrap_or_default();
        let document = crate::settings::document(&config, version, path);

        // **The live-session and loading-account guards run before the
        // loader.** A removal that empties an org fails the loader's own
        // "no projects" rule, and the guard's refusal owes the reader first;
        // the departures are read off the batch itself here, then read again
        // from the loaded candidate below.
        let (departed_projects, departed_accounts) =
            departures_from_edits(&config, edits, &document);
        self.refuse_departures(&config, &departed_projects, &departed_accounts)?;

        // A project's tree must be there before the save lands: the loader
        // accepts any string, and a row pointing at nothing is a project
        // that can never start. An add carries the path in its value; a set
        // on the key replaces it. `~` expands as the loader expands it.
        for edit in edits {
            let path_value = match edit.op {
                SettingsEditOp::Add if edit.area == "projects" => {
                    edit.value.as_ref().and_then(|value| value.get("path"))
                }
                SettingsEditOp::Set
                    if document.areas.iter().flat_map(|area| &area.keys).any(|key| {
                        key.path == edit.key_path && key.pattern == "orgs[].projects[].path"
                    }) =>
                {
                    edit.value.as_ref()
                }
                _ => continue,
            };
            let named = path_value.and_then(serde_json::Value::as_str);
            let holds = named.is_some_and(|path| crate::config::expand_home(path).is_dir());
            if !holds {
                return Err(SettingsSaveError::Refused {
                    message: format!(
                        "a project needs a path that is a directory; `{}` is not",
                        named.unwrap_or("<unset>"),
                    ),
                    key_path: Some(edit.key_path.clone()),
                });
            }
        }

        let candidate = crate::settings_write::apply(&current, edits, &document)
            .map_err(SettingsSaveError::from)?;

        let after = match crate::config::load_from_text(path.to_path_buf(), &candidate) {
            Ok(config) => config,
            Err(error) => {
                // Anchor the refusal at the first edit that fails on its own;
                // the loader's own words carry the line and key it found.
                for edit in edits {
                    let Ok(one) = crate::settings_write::apply(
                        &current,
                        std::slice::from_ref(edit),
                        &document,
                    ) else {
                        continue;
                    };
                    if let Err(one_error) = crate::config::load_from_text(path.to_path_buf(), &one)
                    {
                        return Err(SettingsSaveError::Invalid {
                            message: one_error.to_string(),
                            key_path: Some(edit.key_path.clone()),
                        });
                    }
                }
                return Err(SettingsSaveError::Invalid {
                    message: error.to_string(),
                    key_path: None,
                });
            }
        };

        // **The guards are identity diffs, not op checks.** An entry the
        // save leaves absent (removed, or renamed through `name` /
        // `display_name`) is what the reload strands: a project's sessions
        // keep running but leave every roster, and a retired account still
        // loading leaves `all_accounts_loaded` false for the process's life
        // (#2681). Both are refused by name.
        let after_projects: HashSet<(String, String)> = after
            .projects
            .iter()
            .map(|project| (project.org.clone(), project.name.clone()))
            .collect();
        let after_accounts: HashSet<String> =
            after.accounts.iter().map(|account| account.display_name.clone()).collect();
        self.refuse_departures(&config, &after_projects, &after_accounts)?;

        if candidate == current {
            return Err(SettingsSaveError::Refused {
                message: "the file already matches this save; nothing was written".to_owned(),
                key_path: None,
            });
        }
        Ok(candidate)
    }

    /// Refuse a save that drops an entry something live depends on.
    fn refuse_departures(
        &self,
        before: &LoadedConfig,
        after_projects: &HashSet<(String, String)>,
        after_accounts: &HashSet<String>,
    ) -> Result<(), SettingsSaveError> {
        let before_projects: HashSet<(String, String)> = before
            .projects
            .iter()
            .map(|project| (project.org.clone(), project.name.clone()))
            .collect();
        let mut departed: Vec<&(String, String)> =
            before_projects.difference(after_projects).collect();
        departed.sort();
        for (org, project) in departed {
            let live = self.live_sessions_of(org, project);
            if !live.is_empty() {
                return Err(SettingsSaveError::Refused {
                    message: format!(
                        "project `{org} / {project}` has live sessions: {}; close them before \
                         removing or renaming it",
                        live.join(", "),
                    ),
                    key_path: None,
                });
            }
        }

        let before_accounts: HashSet<String> =
            before.accounts.iter().map(|account| account.display_name.clone()).collect();
        let mut departed: Vec<&String> = before_accounts.difference(after_accounts).collect();
        departed.sort();
        let held = self.accounts.ordered_account_keys();
        for name in departed {
            let key = AccountKey((*name).clone());
            if held.contains(&key)
                && self.accounts.loading_state(&key) == forge_gateway::LoadingState::Loading
            {
                return Err(SettingsSaveError::Refused {
                    message: format!(
                        "account `{name}` is still loading its usage; the save refuses \
                         until its probe settles",
                    ),
                    key_path: None,
                });
            }
        }
        Ok(())
    }

    /// The sessions a project currently has live, by their slots' display
    /// names. A removal refuses while any exists: the reload leaves a live
    /// session running but invisible.
    fn live_sessions_of(&self, org: &str, project: &str) -> Vec<String> {
        let mut live: Vec<String> = self
            .pool
            .lock()
            .keys()
            .chain(self.domain_handles.lock().keys())
            .filter(|slot| slot.org() == org && slot.project() == project)
            .map(SessionSlot::display)
            .collect();
        live.sort_unstable();
        live.dedup();
        live
    }

    /// The effective-config document as the socket holds it, built from the
    /// live config where the server has not published one yet (a test
    /// workspace, or the first moments before the greeting). The settings
    /// MCP tools read this one document, so a key they report and the value
    /// the page draws cannot disagree.
    pub(crate) fn settings_snapshot(&self) -> Arc<forge_primitives::SettingsDocument> {
        if let Some(document) = self.settings.borrow().clone() {
            return document;
        }
        let version = self.settings_version.get().map(String::as_str).unwrap_or_default();
        Arc::new(crate::settings::document(&self.config_arc(), version, &self.config_path()))
    }

    /// Build the document from the live config and publish it when it
    /// differs from what the socket already holds.
    fn publish_settings(&self) {
        let version = self.settings_version.get().map(String::as_str).unwrap_or_default();
        let config = self.config_arc();
        let document = Arc::new(crate::settings::document(&config, version, &self.config_path()));
        if self.settings.borrow().as_ref() != Some(&document) {
            self.settings.send_replace(Some(document));
        }
    }

    /// The server browser's own knobs: `[browser]`'s encoding rate and
    /// quality, and its idle release's two bounds. Absent section keeps the
    /// defaults the struct carries.
    pub fn browser_settings(&self) -> crate::BrowserSettings {
        self.config_arc().browser
    }

    /// The profile names `forge.toml` resolved: each org's, and each
    /// project's override keyed by `(org, project)`. **Project names are
    /// unique inside an org**, so the pair is the key the fleet resolves a
    /// seat against.
    pub fn browser_profile_config(
        &self,
    ) -> (
        std::collections::HashMap<String, String>,
        std::collections::HashMap<(String, String), String>,
    ) {
        let config = self.config_arc();
        let orgs = config.org_browser_profiles.clone();
        let projects = config
            .projects
            .iter()
            .map(|project| {
                (
                    (project.org.clone(), project.name.clone()),
                    project.browser_profile.name().to_owned(),
                )
            })
            .collect();
        (orgs, projects)
    }

    /// The ceiling on one handed document, in bytes: `[documents]
    /// max_size_mib` over the crate's own default. Read by the document
    /// read, which refuses a document over it.
    pub fn document_max_bytes(&self) -> u64 {
        self.config_arc().document_max_bytes
    }

    /// Note a client connection attached, and give it back when it goes.
    /// The transport's per-connection guard calls these.
    pub fn note_client_attached(&self) {
        self.attached_clients.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    }

    /// The counterpart of [`Self::note_client_attached`].
    pub fn note_client_detached(&self) {
        self.attached_clients.fetch_sub(1, std::sync::atomic::Ordering::Relaxed);
    }

    /// Whether any client connection is attached. Only a client that draws a
    /// document viewer counts: a hand-off's ask needs one that does.
    pub(crate) fn client_attached(&self) -> bool {
        self.attached_clients.load(std::sync::atomic::Ordering::Relaxed) > 0
    }

    /// Install the server's browser fleet. **Boot-time and once**: the fleet
    /// outlives every session, and a second install would be two browsers
    /// answering one tool surface.
    pub fn install_browser_host(&self, host: Arc<dyn crate::browser::BrowserHost>) {
        let _ = self.browser_host.set(host);
    }

    /// The browser fleet, when this workspace has one.
    pub fn browser_host(&self) -> Option<Arc<dyn crate::browser::BrowserHost>> {
        self.browser_host.get().cloned()
    }

    /// The push-to-talk key from forge.toml `[dictate] bind`. The value
    /// rides the seat record a client last read, so a reload reaches the
    /// key handler on the next seat read rather than the next event.
    pub fn dictate_bind(&self) -> crate::dictate::DictateBind {
        self.config_arc().dictate.bind
    }

    /// How press/release maps onto starting and stopping a take, from
    /// forge.toml `[dictate] mode`. It rides the seat record like `bind`,
    /// so a reload reaches the key handler on the next seat read.
    pub fn dictate_mode(&self) -> crate::dictate::DictateMode {
        self.config_arc().dictate.mode
    }

    /// Whether dictation is on at all. The key handler reads this so a
    /// press with `[dictate]` disabled is dead rather than a refusal:
    /// the box doc's S0 is "nothing at all", and with the section
    /// absent every Cmd chord would otherwise pop an error.
    pub fn dictate_enabled(&self) -> bool {
        self.config_arc().dictate.enabled
    }

    /// The `[plugins]` auto-update policy from forge.toml. Read by the
    /// plugins pane for the boot auto-update gate and the pane's
    /// auto-update state display.
    pub fn plugin_settings(&self) -> crate::config::PluginSettings {
        self.config_arc().plugins.clone()
    }

    /// Remember plugin updates applied by a pane run or by boot
    /// auto-update: the visible record of what moved, from where, and
    /// the ref a rollback restores. One transaction for the whole
    /// batch. A no-op with a warn when the store is closed.
    pub fn record_plugin_updates(&self, records: &[forge_primitives::plugins::PluginUpdateRecord]) {
        if let Some(db) = self.db.lock().as_ref()
            && let Err(error) = crate::store::plugins::record_updates(db, records)
        {
            tracing::warn!(
                target: "forge_workspace::workspace",
                count = records.len(),
                error = %error,
                "failed to persist the plugin update records",
            );
        }
    }

    /// Every remembered plugin update, latest write per installed
    /// entry. Empty when the store is closed or unreadable.
    pub fn plugin_update_records(&self) -> Vec<forge_primitives::plugins::PluginUpdateRecord> {
        self.db
            .lock()
            .as_ref()
            .and_then(|db| crate::store::plugins::update_records(db).ok())
            .map(|records| records.into_values().collect())
            .unwrap_or_default()
    }

    /// Forget the record for one installed entry after its rollback
    /// ran: the previous version it named is now current.
    pub fn clear_plugin_update_record(&self, plugin_id: &str, scope: &str) {
        if let Some(db) = self.db.lock().as_ref()
            && let Err(error) = crate::store::plugins::clear_update_record(db, plugin_id, scope)
        {
            tracing::warn!(
                target: "forge_workspace::workspace",
                plugin = %plugin_id,
                error = %error,
                "failed to clear a plugin update record",
            );
        }
    }

    /// The projects a boot opens, in forge.toml order.
    ///
    /// With no project named, that is every configured project whose lead
    /// row is open (`idle` or `in_turn`) - the seats the user last had
    /// open. A closed lead is left shut, and a project whose lead never
    /// spawned has no row to open. A seat whose turn was cut off carries
    /// the restart note; a parked one is resumed with nothing.
    ///
    /// `only` names one project explicitly, which opens whether its row is
    /// open or closed: naming it is the user's own act, and closing is not
    /// forgetting. A name no project declares is returned as itself so the
    /// spawn handler reports it like any other unknown project.
    ///
    /// A project renamed in `forge.toml` starts with no row, because the
    /// row is keyed by its org and name: the rename is the same act that
    /// loses the stored session id, and there is nothing stable underneath
    /// to key by instead.
    pub fn boot_wave_targets(&self, only: Option<&str>) -> Vec<BootWaveTarget> {
        let config = self.config_arc();
        let mut targets = Vec::new();
        for project in &config.projects {
            if only.is_some_and(|name| project.name != name) {
                continue;
            }
            let slot = SessionSlot::lead(&project.org, &project.name);
            // The migration seeds a row written before the field `idle`,
            // so an absent state after it means the row itself is absent:
            // this lead has never spawned. A seat left open reopens; a
            // closed one does so only when named, and neither has an
            // interrupted turn to report unless the row says `in_turn`.
            let state = self.stored_seat_state(&slot);
            if only.is_some() || state.is_some_and(crate::store::sessions::SeatState::is_open) {
                let resume_kick = match state {
                    Some(crate::store::sessions::SeatState::InTurn) => {
                        Some(LEAD_RESTART_NOTE.to_owned())
                    }
                    _ => None,
                };
                targets.push(BootWaveTarget { project_name: project.name.clone(), resume_kick });
            }
        }
        if let (Some(name), true) = (only, targets.is_empty()) {
            // No configured project carries the name. Return it so the
            // spawn handler answers with the same unknown-project refusal a
            // named launch has always given.
            targets.push(BootWaveTarget { project_name: name.to_owned(), resume_kick: None });
        }
        targets
    }

    /// Every project listed in `forge.toml`, each carrying its catalog
    /// sessions sorted by last-activity descending - `sessions[0]` is
    /// the lead. Empty `sessions` means the project has nothing on
    /// disk yet; the project still surfaces in the returned Vec.
    pub fn list_projects(&self) -> Vec<ProjectView> {
        // A catalog row is a transcript file, named by the id the CLI
        // wrote it under, so openness is answered by the ids forge
        // currently holds rather than by the row's slot.
        let open_sessions: std::collections::HashSet<String> =
            self.pool.lock().values().map(|entry| entry.session_id.clone()).collect();

        // One catalog acquire for the whole walk - the loop body is
        // a HashMap lookup + bounded cloning over owned session info
        // and never re-enters the catalog, so holding the lock for
        // the duration is cheap. The prior per-iteration
        // acquire/drop showed up as the dominant hot spot in
        // `ui::render` under projects with ~14 entries.
        let catalog = self.catalog.lock();
        // Iterate config.projects, with the test-only overlay appended
        // so unit tests can seed projects via `seed_test_project`
        // and exercise paths that read `list_projects` (matches the
        // `project_root_for_key` / `find_project_view_by_name` overlay
        // pattern).
        #[cfg(any(test, feature = "testing"))]
        let extra = self.test_extra_projects.lock();
        let config = self.config_arc();
        let project_iter: Box<dyn Iterator<Item = &LoadedProject>> = {
            #[cfg(any(test, feature = "testing"))]
            {
                Box::new(config.projects.iter().chain(extra.iter()))
            }
            #[cfg(not(any(test, feature = "testing")))]
            {
                Box::new(config.projects.iter())
            }
        };
        let mut views = Vec::with_capacity(config.projects.len());
        for project in project_iter {
            let key =
                ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(
                    Some(&project.path.to_string_lossy()),
                ));

            let sessions: Vec<SessionView> = catalog
                .get(&key)
                .map(|entries| {
                    entries
                        .iter()
                        .map(|info| SessionView {
                            session: forge_primitives::SessionId::new(info.session_id.clone()),
                            label: info.summary.clone(),
                            is_open: open_sessions.contains(&info.session_id),
                            last_activity: Some(
                                UNIX_EPOCH + Duration::from_millis(info.last_modified),
                            ),
                        })
                        .collect()
                })
                .unwrap_or_default();

            views.push(ProjectView {
                key,
                name: project.name.clone(),
                org: project.org.clone(),
                path: project.path.clone(),
                display_path: project.display_path.clone(),
                accounts: project.accounts.clone(),
                fallback_accounts: project.fallback_accounts.clone(),
                has_model: project.model.is_some(),
                sessions,
            });
        }
        views
    }

    /// The handoff trigger this seat runs under: the project's table over the
    /// top-level one, with the defaults under both.
    pub(crate) fn handoff_policy_for(&self, slot: &SessionSlot) -> crate::config::HandoffPolicy {
        let project = self.project_for_slot(slot).and_then(|project| project.handoff);
        let config = self.config_arc();
        crate::config::HandoffPolicy::resolve(&config.handoff, project.as_ref())
    }

    /// Validate that `name` matches a project in `forge.toml`. Used
    /// by callers (e.g. the server's boot) to fail fast on an unknown
    /// CLI positional arg before setup, rather than surface the
    /// same error later via [`Self::get_agent_handle`].
    pub fn validate_project_name(&self, name: &str) -> Result<(), WorkspaceError> {
        self.find_project_by_name(name).map(|_| ())
    }

    /// Stamp [`LEAD_DELEGATION_PREAMBLE`] onto a Lead session's launch
    /// settings. No-op for a worker.
    fn apply_lead_delegation(settings: &mut SessionLaunchSettings, kind: crate::mcp::SessionKind) {
        if matches!(kind, crate::mcp::SessionKind::Lead) {
            settings.delegation_preamble = Some(LEAD_DELEGATION_PREAMBLE.to_owned());
        }
    }

    /// The slot a spawn fills, from the role its caller stated. The label
    /// is used as given: a worker must never be resolved through the
    /// registry, which answers with the lead's slot once its entry is
    /// gone, and nothing recovers either answer from the key's shape - a
    /// key that looks like a worker is not evidence, and a project named
    /// `worker_foo` once classified as a worker for exactly that reason.
    /// The slot a spawn's role states under `project`. The one source
    /// for both a session's tool surface and its address, so the two
    /// cannot disagree.
    fn slot_for_spawn(
        role: &crate::protocol::SpawnRole,
        project: &LoadedProject,
    ) -> crate::SessionSlot {
        match role {
            crate::protocol::SpawnRole::Lead => {
                crate::SessionSlot::lead(&project.org, &project.name)
            }
            crate::protocol::SpawnRole::Worker { label, .. } => {
                crate::SessionSlot::worker(&project.org, &project.name, label)
            }
        }
    }

    /// Hands out the `Arc<AgentHandle>` for the requested session,
    /// spawning the underlying Agent lazily if it isn't already pooled.
    /// Idempotent - repeated calls for the same target return the same
    /// handle (no second subprocess). `settings` only apply to the
    /// spawn; subsequent calls reuse the existing Agent and ignore the
    /// parameter.
    ///
    /// Each fresh spawn runs the gateway's account selection and
    /// stamps the chosen account's env onto the spawned `claude`
    /// subprocess, so it talks to the gateway listener rather than
    /// upstream. Selection state lives in the in-memory usage cache;
    /// nothing about account choice is persisted across forge
    /// launches.
    ///
    /// Workspace does not track which handle the caller is "using" -
    /// that's the caller's concern.
    /// `role` is what the caller states this session to be. There is no
    /// keyless form: a role forge cannot state is one it would have to
    /// guess from the live-worker registry, which answers with the lead's
    /// slot for a worker whose entry is gone.
    pub fn get_agent_handle(
        self: &Arc<Self>,
        target: SessionTarget,
        settings: SessionLaunchSettings,
        role: &crate::protocol::SpawnRole,
    ) -> Result<Arc<AgentHandle>> {
        self.get_agent_handle_at_key(target, settings, None, role, true)
    }

    /// Like [`Self::get_agent_handle`] but takes the key the caller
    /// already resolved, so the pool entry lands under the same key the
    /// caller announced. `None` for callers that have not resolved one.
    ///
    /// `role` is what the caller states this spawn to be. It is the one
    /// source for both the tool surface and the slot's label, so a worker
    /// cannot be handed a lead's tool surface or a lead's address.
    ///
    /// `reopen` is the opening door's word: a user's click, the boot wave
    /// and a cron wake open the seat they name, while the heal's recovery
    /// of a death must leave a seat the reader closed shut.
    pub(crate) fn get_agent_handle_at_key(
        self: &Arc<Self>,
        target: SessionTarget,
        mut settings: SessionLaunchSettings,
        resolved_key: Option<SessionSlot>,
        role: &crate::protocol::SpawnRole,
        reopen: bool,
    ) -> Result<Arc<AgentHandle>> {
        // Every session forge launches passes through here, so the tools
        // forge has replaced are denied at this one point rather than at
        // each spawn entry - a fourth entry cannot forget them. The role
        // states the kind, and the slot it is checked against below cannot
        // disagree with it.
        let spawn_kind = match role {
            crate::protocol::SpawnRole::Lead => crate::mcp::SessionKind::Lead,
            crate::protocol::SpawnRole::Worker { .. } => crate::mcp::SessionKind::Worker,
        };
        // `interactive` is passed as `true` because this point cannot know
        // it, and the question denial must not be decided wrongly here: a
        // worker's own spawn writes that name when the flag calls for it,
        // and the merge below leaves it in place.
        crate::spawn::apply_blocked_tools(&mut settings, spawn_kind, true);
        // A shutdown is tearing sessions down and starts none: a session
        // that began behind its drain would sit outside the set the exit
        // waits on, and its tree would outlive forge.
        if self.is_shutting_down() {
            return Err(forge_sdk::Error::Connection {
                reason: "forge is shutting down; no new session can start".to_owned(),
            }
            .into());
        }
        // The boot gate is a spawn precondition, not just a launchpad
        // decoration: a child stamped before the listener is bound
        // points at a base URL nothing answers.
        if !self.gateway_ready.load(std::sync::atomic::Ordering::Acquire) {
            return Err(forge_sdk::Error::Connection {
                reason: format!(
                    "the gateway listener on port {} is not ready; the boot gate is shut, so \
                     the session would be stamped at a base URL nothing serves",
                    self.gateway_port
                ),
            }
            .into());
        }
        // The caller may already have resolved the slot - the spawn
        // handlers do, because the bucket they announce under
        // `Spawning` has to be the one the child connects under.
        let session_slot = match resolved_key {
            Some(slot) => slot,
            None => self.resolve_slot(&target)?,
        };
        // The id the child runs under. `--session-id` and `--resume` are
        // the CLI's own arguments and stay ids; the store row records it
        // under the slot before the child starts, so a restart resolves
        // the same occupant from the same slot.
        let stored = self.stored_resume_id(&session_slot, settings.force_new)?;
        let resuming = stored.is_some();
        // One shared config dir: every account's child reads the same
        // MCP servers, plugins and settings, so the per-account dir is
        // gone along with the field that carried it.
        let account_dir = self.config_dir.clone();

        // Fast path: cache hit, but only while a session task still
        // consumes the slot. A pooled handle a task has left behind
        // answers nothing - the seat takes no prompt and no child starts -
        // and handing it back made every later spawn fast-path a seat that
        // could never start again (#2683).
        let pooled = {
            let pool = self.pool.lock();
            pool.get(&session_slot)
                .map(|existing| (Arc::clone(&existing.handle), existing.session_id.clone()))
        };
        if let Some((existing, session_id)) = pooled {
            if self.pooled_handle_has_task(&session_slot) {
                return Ok(existing);
            }
            tracing::info!(
                target: "forge_workspace::workspace",
                event_name = "pooled_handle_without_task",
                slot = %session_slot.display(),
                occupant = %session_id,
                "a pooled handle has no session task behind it; rebuilding the session",
            );
            self.release_session_if_current(&session_slot, &existing);
        }

        // Resolve which account this spawn lands under: the walk over
        // the accounts declaring the project's model, which is the same
        // walk the gateway runs on a session's first request. Both the
        // project and its model are required - without a project there
        // is no org, no pin and no model for the walk to run over, and
        // an unregistered spawn would hand the child the account's real
        // credential and a direct base URL.
        // Resolving a project and selecting its account reads two different
        // snapshots (the config and the pool). A reload between them would
        // pair an old pin with the new pool, so the generation is read
        // before and re-checked after; a straddled resolution retries.
        let (project, account_key) = loop {
            let generation = self.reload_generation.load(std::sync::atomic::Ordering::Acquire);
            if !generation.is_multiple_of(2) {
                // The swap holds `reload_gate` from odd to even, so taking it
                // is waiting for the generation to settle - no spin.
                drop(self.reload_gate.lock().unwrap_or_else(std::sync::PoisonError::into_inner));
                continue;
            }
            let Some(project) = self.project_for_target(&target) else {
                return Err(WorkspaceError::SpawnResolvesToNoProject {
                    slot: session_slot.display(),
                }
                .into());
            };
            // The role and the slot are two statements of the same thing -
            // the tool surface comes from the first and the address from
            // the second - so a caller that states them differently is
            // refused rather than handed a worker's address with a lead's
            // tools.
            if Self::slot_for_spawn(role, &project) != session_slot {
                return Err(WorkspaceError::SpawnRoleSlotDisagree {
                    role: role.clone(),
                    slot: session_slot.display(),
                }
                .into());
            }
            // The gateway's walk is the one place a session's account is
            // decided: it looks the org's pin up, filters cooling accounts
            // and walks the accounts declaring the model. The spawn only
            // registers the answer, and that registration is what binds.
            let Some(model) = project.model.as_deref() else {
                return Err(WorkspaceError::ProjectModelMissing {
                    project: project.name.clone(),
                    org: project.org.clone(),
                }
                .into());
            };
            let account_key = self.select_account_for_project(&project, model)?;
            let settled = self.reload_generation.load(std::sync::atomic::Ordering::Acquire);
            if Self::resolution_held(generation, settled) {
                break (project, account_key);
            }
        };
        // The account and model checks have passed, so this spawn is
        // committed: record the id its lead will run under, either the
        // one the store held or the one minted in
        // `lead_session_key_for`. Nothing is written before this point -
        // a refusal ahead of it would pin an id no child ever adopts,
        // and the next boot would resume onto it.
        // **One rollback for everything between the id record and the pool
        // insert.** Any refusal in between - the loader, a missing project,
        // the bind - would otherwise leave a live-looking domain handle and
        // an id no child ever adopted.
        let mut rollback = SpawnRollback {
            workspace: Arc::clone(self),
            slot: session_slot.clone(),
            stored: stored.clone(),
            // Read before the spawn's own `idle` write, so a refusal puts
            // back the state the row held rather than the one the spawn set.
            prior_seat_state: self.stored_seat_state(&session_slot),
            domain_created: false,
            armed: true,
        };
        // **The opening door is the caller's word.** Naming a closed
        // project, or a wake that names it, runs this path with `reopen`
        // set and the seat it starts is open; every other seat-state write,
        // the heal's included, leaves a closed row closed.
        let session_id = self.record_spawn_id(&session_slot, stored.clone(), reopen);
        tracing::info!(
            target: "forge_workspace::account",
            slot = %session_slot.display(),
            session_id = %session_id,
            account = %account_key.0,
            "spawn bound to account",
        );

        // Slow path: spawn a fresh Agent bound to the workspace's
        // shared config_dir. The Agent stores it as a typed field;
        // every in-process accessor (oauth, settings, catalog scans)
        // reads it from there, and the spawned `claude` subprocess
        // inherits it as `CLAUDE_CONFIG_DIR` so each session reads/
        // writes the right account's user-data tree.
        let account_env = self.accounts.env(&account_key).unwrap_or_default();
        apply_project_permission_mode(Some(&project), &mut settings);
        let project_permission_mode = Some(project.permission_mode);
        // The project env merges BEFORE the gateway registers: the
        // stamp must land last, or a project env carrying a
        // base-url key would point the child away from the listener
        // while it still holds the dummy credential - the silent bypass
        // the stamp exists to close, reopened one layer up.
        let merged_env = session_env_for(&project, &account_env);
        // Register the session and let the gateway stamp the child's
        // env: the base URL names this listener, the credential the
        // child holds is a dummy, and the real one stays in the
        // gateway.
        let registration = self.accounts.provider(&account_key).map(|provider| {
            forge_gateway::binding::Registration {
                org: project.org.clone(),
                project: project.name.clone(),
                session: session_id.clone(),
                account: account_key.clone(),
                provider,
            }
        });
        let mut session_env = match &registration {
            Some(registration) => self
                .gateway
                .bindings
                .register(registration, &self.gateway_listener_url(), &merged_env)
                .into_map(),
            None => merged_env,
        };
        // The project's model fills the CLI's model slots: one model
        // for everything the CLI does - main, subagents, background
        // slots. A /model change re-seats the primary immediately; the
        // slots follow on the next respawn.
        if let Some(model) = project.model.as_ref() {
            for var in MODEL_SLOT_VARIABLES {
                session_env.insert((*var).to_owned(), model.clone());
            }
            // And the parameters the model's `[models]` table carries,
            // for the same reason the slots do: they describe this model,
            // so they follow the project's pin. An env layer that already
            // names the key is the user's own word on it and wins.
            let config = self.config_arc();
            if let Some(window) =
                config.models.get(model).and_then(|parameters| parameters.auto_compact_window)
                && !session_env.contains_key(AUTO_COMPACT_WINDOW_ENV)
            {
                session_env.insert(AUTO_COMPACT_WINDOW_ENV.to_owned(), window.to_string());
            }
        }
        // Telling the CLI the project's model is what stops the
        // caller's pin - forge defaults it to the literal "opus" - from
        // resolving through an account's alias mapping into a model the
        // project never declared.
        apply_project_model(Some(&project), &mut settings);

        // Hoist DomainSession creation to BEFORE Agent::spawn. A caller
        // may have registered one at `session_key` already (the cron
        // and gotify delivery paths register a worker's domain before
        // its spawn); reuse it when present so the registrant keeps its
        // handle reference. Otherwise create
        // fresh with conn = None and update post-Agent::spawn at line
        // ~470.
        let (domain_arc, domain_created) = {
            let mut handles = self.domain_handles.lock();
            // A DomainSession is often already registered at
            // `session_key` (the cron and gotify delivery paths register
            // a worker's domain before dispatching its spawn). Reuse it,
            // so whoever registered it keeps the handle reference it was
            // given; otherwise create fresh with conn = None and fill
            // the handle in after `Agent::spawn`. A handle this spawn
            // created is removed again if the bind refuses.
            if let Some(existing) = handles.get(&session_slot).cloned() {
                (existing, false)
            } else {
                let fresh = Arc::new(Mutex::new(DomainSession::new(session_slot.clone(), None)));
                handles.insert(session_slot.clone(), Arc::clone(&fresh));
                (fresh, true)
            }
        };
        rollback.domain_created = domain_created;
        // Carry `--new` onto the domain so a project lead's
        // Connected-time respawn skips the store lookup and brings its
        // workers up fresh alongside the fresh lead.
        domain_arc.lock().spawned_force_new = settings.force_new;
        // The boot wave's restart note belongs to this spawn only when it
        // actually resumed; a fresh spawn (`--new` included) clears what a
        // previous spawn left.
        domain_arc.lock().pending_lead_resume_note =
            resume_kick_for(resuming, settings.resume_kick.take());
        // The effort this spawn asked for, so a session whose hook has
        // not reported one yet still answers with the level it runs at.
        domain_arc.lock().configured_effort =
            crate::domain_session::configured_effort_from_settings(&settings);
        // The mode, the same way: forge stamps its effective default into
        // the launch settings, so this is the mode the session was spawned
        // in rather than a guess.
        domain_arc.lock().configured_permission_mode =
            crate::domain_session::configured_permission_mode_from_settings(&settings);
        // Carry the row's provenance the same way: the tag-write
        // rollback runs long after this spawn returned and needs to know
        // whether the row it would delete is this spawn's to take.
        domain_arc.lock().spawn_wrote_row =
            matches!(role, crate::protocol::SpawnRole::Worker { wrote_row: true, .. });

        // Build the per-session `forge` MCP server. ONE server name;
        // tool surface depends on whether this spawn is for a project
        // lead or a worker. Both kinds reach any other session by its
        // slot; a lead additionally gets the four verbs that act on its
        // own project (spawn / despawn / update / capacity). See
        // `crate::mcp::SessionKind` for the rationale.
        // One source for both answers: the slot's label decides the kind,
        // so a worker's tool surface and a worker's address cannot
        // disagree.
        let session_kind = if session_slot.is_lead() {
            crate::mcp::SessionKind::Lead
        } else {
            crate::mcp::SessionKind::Worker
        };
        let forge_server = {
            let workspace_facade = crate::mcp::peers::facade::ProdWorkspaceFacade::from_arc(self);
            let worker_facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(self);
            let browser_facade =
                crate::mcp::browser::facade::ProdBrowserFacade::from_workspace(self);
            let terminal_facade =
                crate::mcp::terminal::facade::ProdTerminalFacade::from_workspace(self);
            let documents_facade =
                crate::mcp::documents::facade::ProdDocumentFacade::from_workspace(self);
            let review_facade = crate::mcp::review::facade::ProdReviewFacade::from_arc(self);
            let cron_facade = crate::mcp::cron::facade::ProdCronFacade::from_arc(self);
            let gotify_facade = crate::mcp::gotify::facade::ProdGotifyFacade::from_arc(self);
            let slack_facade = crate::mcp::slack::facade::ProdSlackFacade::from_arc(self);
            let settings_facade = crate::mcp::settings::facade::ProdSettingsFacade::from_arc(self);
            let tasks_facade = crate::mcp::tasks::facade::ProdTasksFacade::from_arc(self);
            let systemone_facade = self.systemone.read().as_ref().map(|client| {
                crate::mcp::systemone::facade::ProdSystemOneFacade::new(Arc::clone(client))
                    .into_arc()
            });
            let families = match role {
                crate::protocol::SpawnRole::Lead => crate::mcp::McpFamily::all(),
                crate::protocol::SpawnRole::Worker { mcp_families, .. } => {
                    crate::mcp::resolve_mcp_families(mcp_families.as_deref())
                }
            };
            crate::mcp::build_forge_server(
                crate::mcp::ForgeServerFacades {
                    workspace: workspace_facade,
                    worker: worker_facade,
                    browser: browser_facade,
                    terminal: terminal_facade,
                    documents: documents_facade,
                    review: review_facade,
                    cron: cron_facade,
                    gotify: gotify_facade,
                    slack: slack_facade,
                    settings: settings_facade,
                    tasks: tasks_facade,
                    systemone: systemone_facade,
                    voice: self.voice_service(),
                    vault: self.vault.read().as_ref().map(|_| {
                        crate::mcp::vault::facade::ProdVaultFacade::from_arc(self).into_arc()
                    }),
                },
                &families,
                &session_slot,
                session_kind,
            )
        };
        record_session_tool_surface(
            &session_slot,
            session_slot.is_lead(),
            &forge_server.tool_names(),
        );

        #[cfg(any(test, feature = "testing"))]
        {
            // The stand-in below replaces the call the server would have been
            // handed to, so this is the only way a test sees the one the spawn
            // composed.
            *self.test_spawn_server.lock() = Some(forge_server.clone());
        }
        let spawn_agent = || {
            forge_agent::Agent::spawn(
                account_dir.clone(),
                Some(account_key.0.clone()),
                vec![("forge".to_owned(), forge_server)],
                session_env,
            )
        };
        // A test that installed a stand-in reads the settings this spawn
        // hands its child, which nothing else can observe.
        #[cfg(any(test, feature = "testing"))]
        let handle = self.take_test_spawn_handle().unwrap_or_else(spawn_agent);
        #[cfg(not(any(test, feature = "testing")))]
        let handle = spawn_agent();
        // Project-rooted targets (`Default` / `Named`) resume the
        // project's lead session when the on-disk catalog has one,
        // and fall back to a fresh session in that project's cwd
        // otherwise. Pool key = lead's session id from the catalog
        // so it stays consistent with the running session id.
        // A project-rooted target (`Default` / `Named`) resumes the
        // project's lead session when its row holds an id, and starts a
        // fresh session under a minted one otherwise. The id is the
        // CLI's argument, so it is named here rather than derived.
        match target {
            SessionTarget::Default | SessionTarget::Named(_) => {
                let project = self.project_for_target(&target).ok_or_else(|| {
                    WorkspaceError::ProjectNotFound {
                        name: session_slot.project().to_owned(),
                        path: crate::config::forge_data_dir(&self.config_dir).join("forge.toml"),
                    }
                })?;
                Self::apply_lead_delegation(&mut settings, session_kind);
                let cwd = project.path.to_string_lossy().to_string();
                if resuming {
                    handle.resume_or_new_session(session_id.clone(), cwd, settings)?;
                } else {
                    handle.new_session(Some(session_id.clone()), cwd, settings)?;
                }
            }
            SessionTarget::Session(slot) => {
                let cwd = self.resume_cwd_for_slot(&slot);
                handle.resume_session(session_id.clone(), cwd, settings)?;
            }
            SessionTarget::FreshInProject { cwd, .. } => {
                // Worker spawn: a fresh session in the tree the spawn
                // resolved - its own `cwd` when it stated one, else the
                // project's. Skip the lead-resume path so each worker
                // runs under the id its caller already minted and
                // recorded.
                let cwd = cwd.as_ref().map_or_else(
                    || project.path.to_string_lossy().to_string(),
                    |cwd| cwd.to_string_lossy().into_owned(),
                );
                handle.new_session(Some(session_id.clone()), cwd, settings)?;
            }
        }
        // The session is up; whatever is buffered on it belongs to the live
        // SessionTask to drain on Connected.
        let arc = Arc::new(handle);

        // Insert: a concurrent caller's live session wins the slot and hands
        // its handle back (ours drops at end-of-scope); an entry whose task
        // is gone is stale and this spawn replaces it. Single-user scope
        // makes the race effectively impossible, so the check is about the
        // stale entry a crashed task left, not about two live spawns.
        //
        // **A session may not bind to a project the config no longer
        // holds.** A save's identity diff and this bind are serialized on
        // the settings write lock: either the save lands first (this
        // refuses, and the child drops at end of scope) or the session is
        // pooled first (the save's guard sees it and refuses). Without
        // that, a spawn resolving mid-save leaves a session running but
        // off every roster.
        let (cmd_rx, teardown_done, replaced_sender) = {
            let _settings = self.settings_write.lock();
            let held = self.config_arc();
            // **A save that has landed but that the watcher has not reloaded
            // yet is not in `held`.** The file's own fingerprint says the
            // config moved; the file's projects are then the set a bind must
            // check, or a spawn in the reload window binds to a project the
            // reload is about to remove.
            let path = self.config_path();
            let text = std::fs::read_to_string(&path).ok();
            let current = match text
                .as_ref()
                .filter(|text| crate::config::fingerprint_of(text) != held.raw_fingerprint)
            {
                Some(text) => Some(crate::config::load_from_text(path, text)?),
                None => None,
            };
            let present = match current.as_ref() {
                Some(config) => config.projects.iter().any(|project| {
                    project.org == session_slot.org() && project.name == session_slot.project()
                }),
                None => held.projects.iter().any(|project| {
                    project.org == session_slot.org() && project.name == session_slot.project()
                }),
            };
            if !present {
                // The guard rolls this spawn's side effects back on the way
                // out, or the project reads live for ever and a boot resumes
                // onto a transcript that never existed.
                return Err(WorkspaceError::SpawnResolvesToNoProject {
                    slot: session_slot.display(),
                }
                .into());
            }
            let mut pool = self.pool.lock();
            // **A non-opening spawn stops at a close that landed after its
            // own start.** The heal's `fire` reads `Closed` before it
            // calls in, and the close can still land while the spawn
            // resolves its account. Checked here, in the block that
            // inserts the pool entry under the same lock the close's
            // release takes: the close either writes `Closed` before this
            // read (refused now) or removes the entry this spawn inserts.
            if !reopen
                && matches!(
                    self.stored_seat_state(&session_slot),
                    Some(crate::store::sessions::SeatState::Closed)
                )
            {
                arc.kill_process_group();
                return Err(
                    WorkspaceError::SeatClosedDuringSpawn { slot: session_slot.display() }.into()
                );
            }
            if let Some(existing) = pool.get(&session_slot) {
                // A concurrent spawn won the slot: its handle is the one to
                // hand back, but only while a task consumes it. A handle
                // whose task is gone is this spawn's to replace, the same
                // stale entry the fast path refuses above. **Race-only**: the
                // fast path reads the same state, so no single-threaded test
                // can reach this branch without a seam; it exists for the
                // entry another spawn inserted while this one built a handle.
                if self.pooled_handle_has_task(&session_slot) {
                    rollback.armed = false;
                    return Ok(Arc::clone(&existing.handle));
                }
            }
            // **Registered before the entry is visible, so a pooled handle
            // never exists without a task behind it.** The teardown signal
            // and the command sender are what a later spawn reads as "a task
            // consumes this slot"; inserting the pool entry first left a
            // window where a concurrent spawn released the winner and both
            // tasks ran (#2683). The order is the invariant and no test can
            // observe its violation: the entry goes in last, under the lock
            // the readers take. A shutdown here starts no session, and the
            // child this spawn already started goes with it.
            let Some(teardown_done) = self.mint_session_teardown(&session_slot) else {
                arc.kill_process_group();
                return Err(forge_sdk::Error::Connection {
                    reason: "forge is shutting down; the session was not started".to_owned(),
                }
                .into());
            };
            let (cmd_tx, cmd_rx) = mpsc::unbounded_channel::<Command>();
            let replaced_sender =
                self.command_senders.lock().insert(session_slot.clone(), cmd_tx).is_some();
            pool.insert(
                session_slot.clone(),
                PooledAgent {
                    handle: Arc::clone(&arc),
                    account: account_key.clone(),
                    permission_mode: project_permission_mode,
                    registration: registration.clone(),
                    session_id: session_id.clone(),
                },
            );
            // The session is pooled: its id and domain are its own now.
            rollback.armed = false;
            (cmd_rx, teardown_done, replaced_sender)
        };
        if replaced_sender {
            tracing::info!(
                target: "forge_workspace::workspace",
                event_name = "orphaned_command_sender_replaced",
                slot = %session_slot.display(),
                "a command sender had no live task behind it; the rebuilt session takes the slot",
            );
        }
        {
            // `domain_arc` was hoisted above the spawn. Stamp the live
            // `Arc<AgentHandle>` onto its `conn` slot
            // now that the handle exists. Whoever holds the
            // `Arc<Mutex<...>>` from before the spawn keeps reading
            // from the same one - no second `domain_session_for`
            // round-trip after the spawn lands.
            domain_arc.lock().conn = Some(Arc::clone(&arc));
            let domain = Arc::clone(&domain_arc);
            let task = SessionTask {
                key: session_slot,
                handle: Arc::clone(&arc),
                command_rx: cmd_rx,
                domain,
                update_tx: self.update_tx.clone(),
                // Every spawn now emits Connected on its first connect:
                // nothing replaces a live session's agent in-process any
                // more, so there is no SessionReplaced case to seed.
                connected_once: false,
                workspace: Arc::downgrade(self),
                // Filled by the first `Connected`, which is where this task
                // is handed the history it can later replay.
                compaction_count: 0,
                successor: None,
                teardown_done: Some(teardown_done),
            };
            let span = tracing::info_span!(
                "session_task",
                slot = %task.key.display(),
            );
            tokio::spawn(task.run().instrument(span));
        }

        Ok(arc)
    }

    /// Crate-internal accessor for the boot-time loading task to
    /// drive `LoadingState` transitions on the workspace's account
    /// map. Not exposed beyond the crate - the field stays private
    /// so only intentional callers reach in.
    pub(crate) fn account_pool(&self) -> &forge_gateway::AccountPool {
        &self.accounts
    }

    /// The gateway's bind failure, if the listener could not start.
    /// The launchpad surfaces this instead of "loading accounts" so a
    /// dead bind does not read as an endless wait.
    pub fn gateway_bind_error(&self) -> Option<String> {
        self.gateway_bind_error.lock().clone()
    }

    /// Whether the gateway listener has bound its port. The preflight
    /// screen's gateway row renders this.
    pub fn gateway_ready(&self) -> bool {
        self.gateway_ready.load(std::sync::atomic::Ordering::Acquire)
    }

    /// The port the gateway's listener binds.
    pub fn gateway_port(&self) -> u16 {
        self.gateway_port
    }

    /// The base URL children are stamped with: the listener's BOUND
    /// address, not the config-derived one - the config names the port
    /// that was asked for, the listener names the port that was bound,
    /// and the stamp must carry the one that answers.
    fn gateway_listener_url(&self) -> String {
        match self.gateway_url.lock().clone() {
            Some(url) => url,
            // Unreachable behind the boot gate: the gate is open only
            // after the listener stored its bound address.
            None => format!("http://127.0.0.1:{}", self.gateway_port),
        }
    }

    /// `true` when every `[[accounts]]` entry has reached a terminal
    /// `LoadingState` AND the gateway's listener is bound. The boot wave
    /// and the cron spawn path gate on this - spawning while an account
    /// is still resolving means the walk runs over a partial map, and
    /// spawning before the listener is bound stamps a base URL nothing
    /// answers - and a view reads it for its accounts card. Public so a
    /// view can read the pool's settledness without reaching into the
    /// crate-private account map.
    pub fn all_accounts_loaded(&self) -> bool {
        self.accounts.all_loaded() && self.gateway_ready.load(std::sync::atomic::Ordering::Acquire)
    }

    /// Whether a spawn in `project_key` would find an account: the
    /// gateway's walk over the project's declared model, which is what a
    /// spawn runs and what a project row's refusal reads. `false` for a
    /// project without a model, or one whose org serves nothing it
    /// declares, which is the refusal a row draws.
    pub fn project_would_bind(&self, project_key: &ProjectKey) -> bool {
        let Some(project) = self.project_for_key(project_key) else {
            return false;
        };
        let Some(model) = project.model.as_deref() else {
            return false;
        };
        self.gateway.select_for(&project.org, model).is_ok()
    }

    /// The cooling that would refuse a spawn in `project_key`, or `None`
    /// when a spawn would find an account.
    ///
    /// Matches the walk's budget failure alone, rather than taking any
    /// error, because that failure is the one carrying a reset to wait
    /// for - and only a refusal that clears on its own is owed a
    /// deferral. The walk's other failure is the config-level one, and
    /// `forge.toml` refuses a project whose model no account in its org
    /// serves (`ProjectModelUndeclared`), so it is not reachable from a
    /// loaded config today. Keep the match narrow anyway: an empty walk
    /// with nothing to wait for must fail as before rather than retry
    /// forever, and this is the line that says so.
    pub(crate) fn project_walk_cooling(&self, project_key: &ProjectKey) -> Option<ProjectCooling> {
        let project = self.project_for_key(project_key)?;
        let model = project.model.as_deref()?;
        match self.gateway.select_for(&project.org, model) {
            Err(forge_gateway::SelectFailure::BudgetExhausted { tried, org, model, reset_in }) => {
                Some(ProjectCooling { org, model, tried, reset_in })
            }
            _ => None,
        }
    }

    /// Snapshot of `(AccountKey display name, LoadingState)` pairs in
    /// declaration order, read by the accounts surface. The order
    /// matches `forge.toml`'s `[[accounts]]` declarations so the rows
    /// sit next to the user's mental model of which-account-is-which.
    pub fn account_loading_snapshot(&self) -> Vec<AccountLoadingRow> {
        self.accounts
            .account_names()
            .into_iter()
            .map(|display_name| {
                let key = AccountKey(display_name.clone());
                let last_error = self.accounts.usage_error(&display_name);
                let retry_after = self.accounts.next_probe_after(&key);
                let auth = self.accounts.auth(&display_name);
                AccountLoadingRow {
                    display_name,
                    state: self.accounts.loading_state(&key),
                    last_error,
                    retry_after,
                    auth: auth.unwrap_or(crate::views::AccountAuth::Token),
                    at_cap: self.accounts.is_saturated(&key),
                    cooling: self.gateway.is_cooling(&key),
                }
            })
            .collect()
    }

    /// The account pool as a view draws it: the rows the home snapshot
    /// carries, and the payload [`SessionUpdate::AccountsChanged`] pushes.
    ///
    /// **One builder for both paths**, so a client folding the frame and a
    /// client reading the snapshot draw the same pool.
    pub fn account_pool_view(&self) -> crate::views::AccountPoolView {
        let loading = self.account_loading_snapshot();
        let usage = loading
            .iter()
            .map(|row| crate::views::AccountUsageView {
                display_name: row.display_name.clone(),
                snapshot: self.usage_for(&row.display_name),
            })
            .collect();
        crate::views::AccountPoolView {
            loading,
            all_loaded: self.all_accounts_loaded(),
            gateway: crate::views::AccountGatewayView {
                ready: self.gateway_ready(),
                port: self.gateway_port(),
                bind_error: self.gateway_bind_error(),
            },
            usage,
        }
    }

    /// How the account called `display_name` authenticates - the input
    /// the auth-repair hints branch on. `None` when the name isn't a
    /// configured account.
    pub fn account_auth_for(&self, display_name: &str) -> Option<crate::views::AccountAuth> {
        self.accounts.auth(display_name)
    }

    /// The account name back, when that account is saturated or bailed:
    /// the walk takes one of those only when nothing else in the pin
    /// declares the project's model, so a spawn landing there is worth
    /// saying out loud. `None` when it has room, and for an unknown name.
    pub(crate) fn degraded_account_name(&self, account: &str) -> Option<String> {
        let key = AccountKey(account.to_owned());
        let degraded = self.accounts.is_saturated(&key)
            || self.accounts.loading_state(&key) == forge_gateway::LoadingState::Bailed;
        degraded.then(|| account.to_owned())
    }

    /// The `forge.toml` this workspace loaded. Preflight names it as
    /// one of the two ways past an account that will not authenticate;
    /// an edit applies to new work as the file changes. The other is
    /// repairing the account's own credentials, which a poller picks up
    /// in place without one.
    pub fn config_path(&self) -> PathBuf {
        crate::config::forge_data_dir(&self.config_dir).join("forge.toml")
    }

    /// The config dir this workspace owns: `forge.toml`'s parent dir, and
    /// the dir every session's child runs under, so a session's transcript
    /// lives in its `projects/` tree.
    pub fn config_dir(&self) -> &Path {
        &self.config_dir
    }

    /// Per-model dictation progress for the preflight screen. Empty
    /// `models` means `[dictate] enabled` is false and preflight has no
    /// Dictation section to draw.
    pub fn dictate_snapshot(&self) -> crate::dictate::DictateSnapshot {
        self.dictate.snapshot.lock().clone()
    }

    /// Where the dictation models land. `None` when the platform has no
    /// usable cache directory and none was configured.
    pub fn dictate_models_dir(&self) -> Option<PathBuf> {
        self.config_arc().dictate.models_dir()
    }

    /// The connection that was streaming a take for `key` has gone: the
    /// take is DROPPED, not submitted - its reader is gone, so nothing it
    /// produced would land anywhere, and stopping it now spends nothing
    /// further on it.
    ///
    /// Only a take by THIS connection is closed: an entry with no sink
    /// is not a connection's to close, and a take that ended with
    /// another one started since is not this connection's to close. The
    /// seat is free the moment this returns, so a client that reconnects
    /// and starts again is not refused by the take it left behind.
    /// Answers whether there was one to close.
    pub fn dictate_close(&self, key: &SessionSlot, initiator: u64) -> bool {
        let mut runtime = self.dictate_runtime.lock();
        let live = runtime
            .recordings
            .get(key)
            .is_some_and(|live| live.sink.is_some() && live.initiator == Some(initiator));
        if live {
            let Some(take) = runtime.recordings.remove(key) else {
                return false;
            };
            // `false` is the abandon the runner already honours for Esc:
            // the capture is released and its audio is transcribed no
            // further. A channel nobody is reading yet still takes the
            // value.
            let _ = take.stop.try_send(false);
            return true;
        }
        // A take already submitted is still this connection's to cancel:
        // its transcript would have no reader left either.
        if let Some(take) = runtime
            .finishing
            .iter()
            .find(|take| &take.key == key && take.initiator == Some(initiator))
        {
            let _ = take.stop.try_send(false);
            return true;
        }
        false
    }

    /// The dictate axes in force: `forge.toml` over the crate's own
    /// defaults. What a capturing client starts on and resets to.
    pub fn dictate_axes(&self) -> crate::dictate::DictateAxes {
        self.config_arc().dictate.axes()
    }

    /// Push one frame of client-captured audio into the seat's live take,
    /// answering whether the samples were kept.
    ///
    /// **The take must be `initiator`'s own.** A frame carries no seat, and
    /// a seat's live take can be another connection's - decision 3's own
    /// scenario, where a client whose start was refused still has its
    /// microphone open for the frames already on the wire - so a push from
    /// any other connection is dropped rather than landing in someone
    /// else's dictation. `false` also means the seat has no live take
    /// (never started, refused, or already resolved) or the take has
    /// stopped (the cap, or the speaker let go). A caller drops the frame
    /// rather than holding it, because the take's own answer is what a
    /// reader sees either way.
    pub fn dictate_push(&self, key: &SessionSlot, samples: &[f32], initiator: Option<u64>) -> bool {
        let runtime = self.dictate_runtime.lock();
        runtime.frame_sink_for(key, initiator).is_some_and(|sink| sink.push_mono(samples))
    }

    /// Stop the in-flight model fetch. Whatever reached the disk stays
    /// there as a `.part`, so the next run resumes; the snapshot then
    /// carries [`crate::DictateFailure::Cancelled`] and forge quits,
    /// because there is no dictation-less runtime to fall back to.
    pub fn cancel_dictate_preflight(&self) {
        self.dictate.cancelled.store(true, std::sync::atomic::Ordering::Relaxed);
    }

    /// Fetch, verify and load the dictation models. One task per forge
    /// run, started beside the account loaders; a no-op when dictation
    /// is switched off.
    ///
    /// **This is the prewarm the run keeps resident**: the engine it parks
    /// in the state serves every take, so a press pays no model load, and
    /// the task it runs on is spawned rather than awaited, so none of the
    /// fetch, the verify or the load is on the boot path. The one event it
    /// writes says which of the two ended it.
    ///
    /// The active models are resolved first - the config key, the runtime
    /// pick, or the compiled pin, per role - and the resolution's failure
    /// is the same stop a failed fetch is, naming the config key that
    /// could not be answered.
    pub fn start_dictate_preflight(self: &Arc<Self>) {
        // Before the gate below, so the flag reads "the wave asked for the
        // prewarm" and a second call cannot start a second one.
        if self.dictate_preflight_started.swap(true, std::sync::atomic::Ordering::AcqRel) {
            return;
        }
        let settings = self.config_arc().dictate.clone();
        if !settings.enabled {
            return;
        }
        let state = Arc::clone(&self.dictate);
        let this = Arc::clone(self);
        let updates = self.update_sender();
        let span = tracing::info_span!("dictate_preflight");
        tokio::spawn(
            async move {
                let started = std::time::Instant::now();
                let resolved = match this.resolve_active(&settings).await {
                    Ok(resolved) => resolved,
                    Err(message) => {
                        tracing::warn!(
                            event_name = "dictate_prewarm_failed",
                            failure = %message,
                            "no dictation model is resident; a take will be refused"
                        );
                        state.fail(crate::dictate::DictateFailure::Other { message }, None);
                        let models = this.dictate_models();
                        let _ = updates.send(SessionUpdate::DictateModelsChanged { models });
                        return;
                    }
                };
                state.set_active(&resolved);
                // The page's rows move with the resolution: a role the
                // config or a runtime pick names is not the pin it read a
                // moment ago.
                let models = this.dictate_models();
                let _ = updates.send(SessionUpdate::DictateModelsChanged { models });

                let cfg = crate::dictate::preflight_config(&settings, &resolved);
                crate::dictate::run_dictate_preflight(cfg, Arc::clone(&state)).await;
                // `run_dictate_preflight` parks the engine in the state
                // only on success, and every failure path ends the run,
                // so a held engine is the whole availability signal.
                if state.engine.lock().is_some() {
                    let files: Vec<&str> =
                        resolved.iter().map(|(_, model)| model.spec.file.as_str()).collect();
                    tracing::info!(
                        event_name = "dictate_prewarm_ready",
                        elapsed_ms = started.elapsed().as_millis(),
                        models = ?files,
                        "the dictation models are resident; a take pays no load"
                    );
                    // A variant the config resolved from the feed is on
                    // disk now: record it so the page and the bench see it.
                    this.record_resolved_installs(&resolved);
                    let _ = updates.send(SessionUpdate::DictateAvailability);
                } else if let Some(failure) = &state.snapshot.lock().failure {
                    // The screen carries this for a view; the log is where a
                    // headless run reads it.
                    if failure.is_cancelled() {
                        tracing::debug!(
                            event_name = "dictate_prewarm_cancelled",
                            "the prewarm was stopped before it finished"
                        );
                    } else {
                        tracing::warn!(
                            event_name = "dictate_prewarm_failed",
                            failure = ?failure,
                            "no dictation model is resident; a take will be refused"
                        );
                    }
                }
            }
            .instrument(span),
        );
    }

    /// Resolve `project_key` to the per-session chip the Projects pane
    /// renders next to each row: the account a spawn in it would land
    /// on, and that account's current visual-state category. Returns
    /// `None` when the project is unknown, declares no model, or its
    /// org serves nothing it declares.
    ///
    /// The walk is per org and model, so every row in a project shows
    /// the same account - which is what a spawn does.
    ///
    /// State derivation:
    /// - `LoadingState::Bailed` splits by the recorded failure class,
    ///   the same split the account rows render: auth failures
    ///   (`Unauthorized` / `Expired`) -> `SessionChipState::Bailed`
    ///   (red with a `⚠ ` prefix); transient classes and an unrecorded
    ///   bail -> `Degraded` (warning yellow, the pollers heal it).
    /// - `Ready` + any usage window at the cap (the same
    ///   `is_saturated` signal the walk demotes an account for) ->
    ///   `AtCap` (yellow; the session still spawns but will throttle).
    /// - Every account serving the model inside a rotation cooldown ->
    ///   `RateLimited`, naming the account whose cooldown lifts first:
    ///   the one the first spawn after the thaw lands on. The walk still
    ///   refuses a spawn; only this read looks past the cooldown.
    /// - Otherwise -> `Normal` (DIM; default chip).
    pub fn session_chip_for(&self, project_key: &ProjectKey) -> Option<SessionChipInfo> {
        let project = self.project_for_key(project_key)?;
        let model = project.model.as_deref()?;
        let account_key = match self.gateway.select_for(&project.org, model) {
            Ok(key) => key,
            Err(forge_gateway::SelectFailure::BudgetExhausted { .. }) => {
                let key = self.gateway.cooling_account_serving(&project.org, model)?;
                return Some(SessionChipInfo {
                    account_name: key.0,
                    state: SessionChipState::RateLimited,
                });
            }
            Err(_) => return None,
        };

        let loading = self.accounts.loading_state(&account_key);
        let saturated = self.accounts.is_saturated(&account_key);
        let last_error = self.accounts.usage_error(&account_key.0);

        let state = match loading {
            forge_gateway::LoadingState::Bailed => match last_error {
                Some(
                    forge_gateway::UsageFetchStatus::Unauthorized
                    | forge_gateway::UsageFetchStatus::Expired,
                ) => SessionChipState::Bailed,
                _ => SessionChipState::Degraded,
            },
            forge_gateway::LoadingState::Ready if saturated => SessionChipState::AtCap,
            _ => SessionChipState::Normal,
        };

        Some(SessionChipInfo { account_name: account_key.0, state })
    }

    /// The account the gateway walks for a project's declared model,
    /// with the walk's failures turned into the vocabulary a spawn
    /// reports.
    fn select_account_for_project(
        &self,
        project: &LoadedProject,
        model: &str,
    ) -> Result<AccountKey, anyhow::Error> {
        use forge_gateway::SelectFailure;
        self.gateway.select_for(&project.org, model).map_err(|failure| match failure {
            SelectFailure::NoEligibleAccount { org, model } => {
                WorkspaceError::NoAccountServesProjectModel {
                    project: project.name.clone(),
                    org,
                    model,
                    accounts: project
                        .accounts
                        .iter()
                        .chain(project.fallback_accounts.iter())
                        .cloned()
                        .collect::<Vec<String>>()
                        .join(", "),
                }
                .into()
            }
            SelectFailure::BudgetExhausted { org, model, reset_in, .. } => {
                WorkspaceError::AllAccountsCooling {
                    project: project.name.clone(),
                    org,
                    model,
                    seconds: reset_in.as_secs(),
                }
                .into()
            }
            SelectFailure::UnknownOrg { org } => anyhow::anyhow!(
                "project '{}' names org '{org}', which the gateway holds no pin for",
                project.name
            ),
        })
    }

    /// Spawn one boot-time loading task per `[[accounts]]` entry in
    /// `forge.toml`. Each task runs the per-account loading state
    /// machine (in the crate-private `account_loader` module) until
    /// the account reaches a terminal `LoadingState` (`Ready` or
    /// `Bailed`). Called once at startup, replacing the older
    /// "single-probe-then-poll" boot model with the explicit loading
    /// gate that the launchpad now consults via
    /// `AccountStateMap::all_loaded()`.
    pub fn start_account_loading_tasks(self: &Arc<Self>) {
        for key in self.accounts.ordered_account_keys() {
            let span = tracing::info_span!("account_loading", account = %key.0);
            let weak = Arc::downgrade(self);
            tokio::spawn(
                async move {
                    crate::account_loader::run_account_loading(key, weak).await;
                }
                .instrument(span),
            );
        }
    }

    /// Enqueue a worker kick on the dispatcher channel (#259). The
    /// drainer task fires one `Command::Prompt` per
    /// `KICK_DISPATCH_INTERVAL`, so simultaneous boot-time kicks
    /// across a team of N workers spread out as N × INTERVAL instead
    /// of all hitting Anthropic's per-IP burst limit in the same tick.
    ///
    /// Send errors (channel closed - workspace has shut down) are
    /// logged at `error` because they signal a kick was dropped after
    /// `maybe_kick_worker_on_connected` already decided to send. The
    /// worker stays idle in that case; this is rare in practice
    /// (workspace shutdown drains all sessions before the kick path
    /// could fire), but the log line preserves diagnosability.
    pub(crate) fn enqueue_kick(&self, request: KickRequest) {
        if let Err(err) = self.kick_dispatcher_tx.send(request) {
            tracing::error!(
                target: "forge_workspace::workspace",
                error = %err,
                "enqueue_kick: channel closed (workspace shutting down?); kick dropped",
            );
        }
    }

    /// Spawn the worker-kick drainer task (#259). Takes the receiver
    /// out of `kick_dispatcher_rx_slot` and starts a tokio task that
    /// loops on `recv()`, calls
    /// [`Self::dispatch_forged_prompt`] for each request, then sleeps
    /// `KICK_DISPATCH_INTERVAL` before the next pull.
    ///
    /// Call once at construction, AFTER `Workspace::new` returns and
    /// the result is Arc-wrapped (mirrors `start_account_loading_tasks`
    /// / `start_usage_poller` shape). Subsequent calls find the slot
    /// empty and no-op, so a caller's programming error can't
    /// duplicate the drainer.
    ///
    /// The drainer holds an `Arc::downgrade(self)` so the task exits
    /// cleanly when the workspace is dropped: each `upgrade()` returns
    /// `None` and the loop breaks. No explicit shutdown signal needed.
    pub fn start_kick_dispatcher(self: &Arc<Self>) {
        let Some(mut rx) = self.kick_dispatcher_rx_slot.lock().take() else {
            tracing::debug!(
                target: "forge_workspace::workspace",
                "start_kick_dispatcher called more than once; ignoring",
            );
            return;
        };
        let weak = Arc::downgrade(self);
        let span = tracing::info_span!("kick_dispatcher");
        tokio::spawn(
            async move {
                while let Some(req) = rx.recv().await {
                    let Some(workspace) = weak.upgrade() else {
                        return; // Workspace dropped; exit cleanly.
                    };
                    let session_key = req.slot.clone();
                    if let Err(err) =
                        workspace.dispatch_forged_prompt(&session_key, req.prompt_body)
                    {
                        tracing::error!(
                            target: "forge_workspace::workspace",
                            slot = %session_key.display(),
                            error = ?err,
                            "kick dispatcher: dispatch failed; kick dropped",
                        );
                    }
                    // Drop the Arc before sleeping so the workspace
                    // isn't held alive across the interval.
                    drop(workspace);
                    tokio::time::sleep(KICK_DISPATCH_INTERVAL).await;
                }
            }
            .instrument(span),
        );
    }

    /// Bind the gateway's inference listener and open the boot gate
    /// once the port is ours. Called once at boot, from the server's
    /// startup. On success the launchpad's gate opens; on failure
    /// the gate STAYS SHUT and every spawn attempt
    /// are refused at the spawn entries with the reason attached - the
    /// refusal is the protection, not the log line.
    pub fn start_gateway_listener(self: &Arc<Self>) {
        let port = self.gateway_port;
        let weak = Arc::downgrade(self);
        self.supervisor.spawn("gateway_listener", forge_supervise::Policy::Never, move || {
            let weak = weak.clone();
            async move {
                let Some(workspace) = weak.upgrade() else { return };
                match forge_gateway::listener::GatewayListener::bind(port).await {
                    Ok(listener) => {
                        *workspace.gateway_url.lock() = Some(listener.local_url());
                        workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
                        workspace.announce_accounts_changed();
                        tracing::info!(
                            target: "forge_workspace::workspace",
                            port,
                            "gateway listener bound",
                        );
                        let handler: Arc<dyn forge_gateway::listener::RouteHandler> =
                            workspace.gateway.clone();
                        listener.run(handler).await;
                    }
                    Err(error) => {
                        *workspace.gateway_bind_error.lock() = Some(error.to_string());
                        workspace.announce_accounts_changed();
                        tracing::error!(
                            target: "forge_workspace::workspace",
                            error = %error,
                            "the gateway listener could not start; the boot gate stays shut and \
                             spawn attempts are refused until forge restarts",
                        );
                    }
                }
            }
        });
    }

    /// Whether this is the only live forge on the machine: no other config
    /// dir's lock is held.
    ///
    /// **A boot may change shared app-support state only when this is true.**
    /// The test beside the store tests pins the peer case.
    ///
    /// **The app-support tree is machine-wide**, so a boot that changes
    /// something shared in it - the browser host's per-version prune - has
    /// to establish this first, or it deletes a peer's state.
    pub fn sole_instance(&self) -> bool {
        match self.app_support.as_deref() {
            Some(base) => !crate::single_instance::another_instance_running(&self.config_dir, base),
            None => false,
        }
    }

    /// Announce the roster on every rotation change: a cooldown a live 429
    /// starts (a write the gateway publishes) and the clock-driven thaw
    /// after it (which no write announces, so this task sleeps to it).
    ///
    /// **A project row's `would_bind` is derived from the selection walk**,
    /// so both moments change what the home draws with nothing else to hang
    /// an update on. Started once at boot; the registry makes a second call
    /// a no-op, since a second watcher would double every frame.
    pub fn start_rotation_announcer(self: &Arc<Self>) {
        let weak = Arc::downgrade(self);
        // **The subscribe happens before the member starts**, so a cooldown
        // written between this call and the driver's first poll is seen.
        let rotation = self.gateway.rotation_watch();
        self.supervisor.spawn(
            "rotation_announcer",
            forge_supervise::Policy::backoff(),
            move || {
                let weak = weak.clone();
                let mut rotation = rotation.clone();
                async move {
                    let Some(workspace) = weak.upgrade() else { return };
                    drop(workspace);
                    loop {
                        let Some(workspace) = weak.upgrade() else { return };
                        let thaw =
                            workspace.gateway.soonest_cooldown_end(std::time::SystemTime::now());
                        drop(workspace);
                        match thaw {
                            None => {
                                // Nothing is cooling: the next wake is a write.
                                if rotation.changed().await.is_err() {
                                    return;
                                }
                            }
                            Some(end) => {
                                let wait = end
                                    .duration_since(std::time::SystemTime::now())
                                    .unwrap_or(std::time::Duration::ZERO);
                                // A cooldown that started or was replaced restarts
                                // the sleep; the thaw itself ends it.
                                tokio::select! {
                                    () = tokio::time::sleep(wait) => {}
                                    changed = rotation.changed() => {
                                        if changed.is_err() {
                                            return;
                                        }
                                    }
                                }
                            }
                        }
                        let Some(workspace) = weak.upgrade() else { return };
                        workspace.announce_accounts_changed();
                    }
                }
            },
        );
    }

    /// Spawn the background account-usage poller on the interval
    /// `[usage] poll_seconds` resolves to (60 s by default). Fetches
    /// OAuth usage for every `[[accounts]]` entry via the per-
    /// account config-dir's credentials file (no Agent spawn
    /// required), writes each result into `AccountStateMap.by_key`.
    /// The session page draws its 5h/7d utilization from that cache,
    /// and the gateway's account selection reads it too.
    ///
    /// Called once at boot, AFTER `start_account_loading_tasks`
    /// (which subsumed the old `spawn_initial_account_probe` in #246).
    /// The supervisor's registry is the idempotency: a second call while
    /// the poller is running is a no-op, so a caller's programming error
    /// can't multiply the poll rate.
    pub fn start_usage_poller(self: &Arc<Self>) {
        let weak = Arc::downgrade(self);
        let poll_interval = self.config_arc().usage_poll_interval;
        let span = tracing::info_span!("usage_poller");
        self.supervisor.spawn("usage_poller", forge_supervise::Policy::backoff(), move || {
            let weak = weak.clone();
            let span = span.clone();
            async move {
                // Skip the immediate-fire tick: the boot-time loading
                // tasks (`start_account_loading_tasks`, #246) already
                // drove the live probes. Firing again right away would
                // burn another round of Anthropic-side per-IP rate-
                // limiter capacity for no gain. First tick of this
                // interval lands one poll interval after boot.
                let mut interval = tokio::time::interval_at(
                    tokio::time::Instant::now() + poll_interval,
                    poll_interval,
                );
                interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
                loop {
                    interval.tick().await;
                    let Some(workspace) = weak.upgrade() else {
                        return; // Workspace dropped; exit cleanly.
                    };
                    // A reload's `[usage] poll_seconds` lands on the tick
                    // after it, so the loop never holds a stale interval.
                    let configured = workspace.config_arc().usage_poll_interval;
                    if configured != interval.period() {
                        interval = tokio::time::interval_at(
                            tokio::time::Instant::now() + configured,
                            configured,
                        );
                        interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
                    }
                    workspace.refresh_account_usage_once().await;
                }
            }
            .instrument(span)
        });
    }

    /// One pass of the usage poller: fetch OAuth usage for every
    /// configured account in parallel, write each result back to
    /// `AccountStateMap`. Per-account fetch errors are logged at
    /// `warn` so persistent auth failures (revoked token, expired
    /// refresh, missing credentials file) surface in default log
    /// output. Snapshot-mapping errors stay at `debug` because they
    /// indicate a response-shape drift rather than something the
    /// user needs to act on. Public so tests can drive a
    /// deterministic refresh without waiting for the poll tick.
    pub async fn refresh_account_usage_once(self: &Arc<Self>) {
        // Skip accounts inside an active backoff window - a recent
        // probe failed and re-probing now would just re-trip the same
        // rate limit. `scheduler_should_probe` ORs the backoff gate
        // (`should_probe_now`) with the one-shot reset-clear override
        // hook (`has_just_cleared_cap_window`): cold-cache accounts
        // probe immediately, and a snapshot whose resets_at moment has
        // passed gets a fresh probe via the override even if the
        // backoff timer is still active.
        let entries = self.accounts.probe_entries();

        // Disarm any account where the override hook was the deciding
        // factor (should_probe_now was false but the hook said yes).
        // One-shot semantics: each successful probe arms the hook once
        // via set_usage; the override fires once, and subsequent
        // stale-reset state respects the backoff schedule until a
        // fresh snapshot lands.
        let due: Vec<AccountKey> = entries.iter().map(|(key, _, _)| key.clone()).collect();
        self.accounts.disarm_backoff_overrides(&due);
        // Sequential probes. Anthropic's `/api/oauth/usage` endpoint
        // has a per-IP burst limit; parallel spawns trip the limit
        // and produce HTTP 429s even well under the user's own quota.
        // Serial execution staggers requests by per-probe latency
        // (~hundreds of ms), within the configured poll interval (60 s
        // by default).
        let mut any_success = false;
        for (key, provider, env) in entries {
            // The backend owns the probe; an auth failure surfaces and
            // the account stays bailed until the credential heals.
            let fetch_result = crate::provider_probe::probe_via_backend(provider, &env).await;
            match fetch_result {
                Ok(snapshot) => {
                    self.record_usage_success(&key, snapshot);
                    any_success = true;
                }
                Err(forge_gateway::ProbeError::Unmappable(message)) => {
                    self.accounts.set_last_error(
                        &key,
                        forge_gateway::UsageFetchStatus::Other,
                        None,
                    );
                    // This arm writes the pool too: `set_last_error` moves
                    // `last_error` and the re-probe instant, both of which
                    // cross on the account row. A pass whose only write is
                    // this one would otherwise announce nothing.
                    self.announce_accounts_changed();
                    tracing::debug!(
                        target: "forge_workspace::account",
                        account = %key.0,
                        error = %message,
                        "usage_poll snapshot mapping failed",
                    );
                }
                Err(err) => {
                    let status = classify_oauth_usage_error(&err);
                    // Pull the server-provided Retry-After out of the
                    // 429 variant so the next probe schedules against
                    // Anthropic's actual reset time rather than our
                    // local guess.
                    let retry_after = match &err {
                        forge_gateway::ProbeError::Fetch(
                            forge_primitives::usage::oauth::OauthUsageError::RateLimited {
                                retry_after,
                                ..
                            },
                        ) => *retry_after,
                        _ => None,
                    };
                    self.accounts.set_last_error(&key, status, retry_after);
                    // A 429 is a reading even though it heals nothing: keep
                    // its windows so the rail can say which one is spent.
                    if let Some(snapshot) = err.rate_limited_snapshot() {
                        self.accounts.set_limit_reading(&key, snapshot.clone());
                    }
                    self.announce_accounts_changed();
                    // Branch the log message by error class so anyone
                    // reading triage logs gets the right framing.
                    // The previous shape said "persistent failures
                    // usually mean stale OAuth credentials" for every
                    // error variant - which misclassified 429
                    // rate-limits (a transient Anthropic throttle) as
                    // an auth/credentials issue and sent users hunting
                    // for /login problems that didn't exist.
                    let message: &str = match status {
                        forge_gateway::UsageFetchStatus::RateLimited => {
                            "usage_poll fetch rate-limited by Anthropic; sub-second Retry-After is treated as 'no hint' and we back off exponentially"
                        }
                        forge_gateway::UsageFetchStatus::Expired
                        | forge_gateway::UsageFetchStatus::Unauthorized => {
                            auth_repair_hint(provider)
                        }
                        forge_gateway::UsageFetchStatus::NetworkFailed => {
                            "usage_poll fetch failed with network error; will retry on next tick"
                        }
                        forge_gateway::UsageFetchStatus::Other => {
                            "usage_poll fetch failed with unhandled error class; see error field for details"
                        }
                    };
                    // A 429 is a healthy poller meeting its rate limit,
                    // which the backoff above already handles; the other
                    // classes mean the account's figures are missing for
                    // a reason someone may need to fix.
                    if matches!(status, forge_gateway::UsageFetchStatus::RateLimited) {
                        tracing::debug!(
                            target: "forge_workspace::account",
                            account = %key.0,
                            error = %err,
                            retry_after_secs = ?retry_after.map(|d| d.as_secs()),
                            status = ?status,
                            "{message}",
                        );
                    } else {
                        tracing::warn!(
                            target: "forge_workspace::account",
                            account = %key.0,
                            error = %err,
                            retry_after_secs = ?retry_after.map(|d| d.as_secs()),
                            status = ?status,
                            "{message}",
                        );
                    }
                }
            }
        }

        // Persist the snapshot to disk so the next forge launch's usage
        // reads have seed data even if Anthropic 429s the first probe.
        // Skipped when no probe succeeded this round -
        // no point rewriting the file with the same contents.
        if any_success {
            let snapshots = self.accounts.snapshots_for_cache();
            let account_count = snapshots.len();
            // A redb write is a small mmap'd transaction, not the old
            // load-merge-write of a TOML file, so it runs inline on the
            // held store handle like the cron + gotify writes do.
            if let Some(db) = self.db.lock().as_ref() {
                crate::account_cache::store(db, &snapshots);
            }
            tracing::info!(
                target: "forge_workspace::account_cache",
                event_name = "account_cache_written",
                accounts = account_count,
                "usage cache updated in the store after a successful poll round",
            );
        }
    }

    /// Write one successful poll result. A healed account is
    /// immediately eligible for new spawns: the walk reads the state
    /// map directly, so there is nothing to recompute. Existing
    /// sessions keep the account they bound to.
    pub(crate) fn record_usage_success(
        &self,
        key: &AccountKey,
        snapshot: forge_primitives::usage::UsageSnapshot,
    ) {
        use forge_gateway::LoadingState;
        let previous = self.accounts.usage(&key.0);
        let was_loading = self.accounts.loading_state(key);
        let was_error = self.accounts.usage_error(&key.0);
        let healed = was_loading == LoadingState::Bailed;
        // A window at the cap with a reset ahead is proven exhaustion:
        // the gateway cools the account until that reset and every
        // bound session re-selects. Read off the incoming snapshot -
        // the pre-write pool state is the stale one.
        let probe_reset_at = snapshot
            .binding_reset_at()
            .and_then(|reset| reset.duration_since(std::time::SystemTime::UNIX_EPOCH).ok())
            .map(|duration| duration.as_secs());
        self.accounts.set_usage(key, snapshot);
        if let Some(reset_at) = probe_reset_at {
            self.gateway.report_probe_limit(key, Some(reset_at));
        }
        if healed {
            tracing::info!(
                target: "forge_workspace::account",
                event_name = "account_healed",
                account = %key.0,
                outcome = "ready",
                "Bailed -> Ready on a clean usage poll; the walk serves it for new sessions",
            );
        }
        // A poll that found the figures already held is no news, and
        // announcing it costs every home subscriber a full read for an
        // answer that cannot differ. Everything the wire carries is
        // compared: the loading state, the last probe failure (a success
        // after a transient failure clears it, and the figures can be
        // identical; its hold-down instant is cleared with it, so the error
        // is the whole of that change), and the usage's own fields.
        // `fetched_at` is the one exclusion - it records when the reading
        // was taken rather than what it says, and it moves on every probe.
        let moved = was_loading != self.accounts.loading_state(key)
            || was_error != self.accounts.usage_error(&key.0)
            || match (&previous, &self.accounts.usage(&key.0)) {
                (Some(before), Some(after)) => !before.same_usage(after),
                (None, None) => false,
                _ => true,
            };
        if moved {
            self.announce_accounts_changed();
        }
    }

    /// The newest usage reading the pool holds for an account, by display
    /// name: a rate-limited response's windows when one landed after the
    /// last successful probe, else that probe's snapshot. `None` while the
    /// account has reported nothing. A view renders the 5h / 7d bars from
    /// this reading.
    pub fn usage_for(&self, display_name: &str) -> Option<forge_primitives::usage::UsageSnapshot> {
        self.accounts.latest_reading(display_name)
    }

    /// The account the gateway is serving `key`'s session with right
    /// now, which a re-selection may have moved off the spawn-time
    /// pick. The lookup goes through the pooled registration: bindings
    /// are keyed by the segment the child's base URL was stamped with,
    /// which is the id the occupant runs under.
    pub fn bound_account_for(&self, key: &SessionSlot) -> Option<AccountKey> {
        let (org, project, session) = {
            let pool = self.pool.lock();
            let registration = pool.get(key).and_then(|entry| entry.registration.as_ref())?;
            (registration.org.clone(), registration.project.clone(), registration.session.clone())
        };
        self.gateway.bindings.binding_for(&org, &project, &session)
    }

    /// Stamp a respawn's gateway registration for a child that runs
    /// under `session_id`: the four gateway-owned keys ride
    /// `launch_settings` as overrides, the binding moves to that
    /// segment, and the one it replaces is dropped. The pool entry
    /// records the same id, so `bound_account_for` reads the binding the
    /// child actually answers to. The gateway half is a no-op when the
    /// slot is not pooled or carries no registration: the launch then
    /// keeps the account env the original spawn laid down.
    ///
    /// The tools forge has replaced are denied unconditionally, because a
    /// respawn's settings are built by a view and carry no spawn-time
    /// flags - so `/new` and `/resume` are exactly where those denials
    /// would otherwise come back. A worker's own denials come back with
    /// them: the kind decides the worktree pins, and the row's own
    /// `interactive` flag decides the question.
    pub(crate) fn stamp_respawn_overrides(
        &self,
        slot: &SessionSlot,
        session_id: &str,
        launch_settings: &mut SessionLaunchSettings,
    ) {
        let kind = if slot.is_lead() {
            crate::mcp::SessionKind::Lead
        } else {
            crate::mcp::SessionKind::Worker
        };
        // A lead is the session whose row the user is looking at, so the
        // question is never denied to it. A worker's row answers for it,
        // and a row that never carried the flag was spawned under the
        // non-interactive default.
        let interactive = match kind {
            crate::mcp::SessionKind::Lead => true,
            crate::mcp::SessionKind::Worker => self.stored_interactive_for(slot).unwrap_or(false),
        };
        crate::spawn::apply_blocked_tools(launch_settings, kind, interactive);
        // **A respawn rebuilds both of a lead's blocks.** A worker's charter
        // is re-delivered from the store by the caller, and a lead has no
        // stored row to read one from - its two blocks are stamped at spawn
        // and were lost here, so a `/new`, a `/resume` or a handoff handed
        // back a lead with neither its mission nor its delegation rules.
        if matches!(kind, crate::mcp::SessionKind::Lead) {
            crate::spawn::apply_lead_charter(launch_settings);
            Self::apply_lead_delegation(launch_settings, kind);
        }
        let (registration, replaced) = {
            let mut pool = self.pool.lock();
            let Some(entry) = pool.get_mut(slot) else { return };
            let Some(registration) = entry.registration.as_mut() else { return };
            let replaced = std::mem::replace(&mut registration.session, session_id.to_owned());
            let owned = registration.clone();
            session_id.clone_into(&mut entry.session_id);
            (owned, replaced)
        };
        launch_settings.env_overrides = self.gateway.bindings.respawn_env_overrides(
            &registration,
            &replaced,
            &self.gateway_listener_url(),
        );
    }

    /// Read the last poll-attempt failure for an account, if any.
    /// `None` when the most recent poll succeeded (or no attempt
    /// has been made yet). The class is what tells an empty bar apart
    /// from an upstream failure (the HTTP 429 case is especially common
    /// when multiple forge instances poll the same Anthropic account).
    pub fn usage_error_for(&self, display_name: &str) -> Option<forge_gateway::UsageFetchStatus> {
        self.accounts.usage_error(display_name)
    }

    /// Resolves a `SessionTarget` to the slot it names. A
    /// project-rooted target resolves to that project's lead slot; a
    /// specific session names its own. For `Named` with no matching
    /// project, returns [`WorkspaceError::ProjectNotFound`].
    pub(crate) fn resolve_slot(
        &self,
        target: &SessionTarget,
    ) -> Result<SessionSlot, WorkspaceError> {
        match target {
            SessionTarget::Default => {
                let config = self.config_arc();
                let project = config.default_project();
                Ok(SessionSlot::lead(&project.org, &project.name))
            }
            SessionTarget::Named(name) => {
                let project = self.find_project_by_name(name)?;
                Ok(SessionSlot::lead(&project.org, &project.name))
            }
            SessionTarget::Session(slot) | SessionTarget::FreshInProject { slot, .. } => {
                Ok(slot.clone())
            }
        }
    }

    /// The project a spawn under `target` belongs to. A project-rooted
    /// target names it directly; a specific session slot names it by
    /// org and name.
    fn project_for_target(&self, target: &SessionTarget) -> Option<LoadedProject> {
        match target {
            SessionTarget::Default => {
                let config = self.config_arc();
                Some(config.default_project().clone())
            }
            SessionTarget::Named(name) => self.find_project_view_by_name(name),
            SessionTarget::Session(slot) | SessionTarget::FreshInProject { slot, .. } => self
                .config_arc()
                .projects
                .iter()
                .find(|project| project.org == slot.org() && project.name == slot.project())
                .cloned(),
        }
    }

    /// The project `slot` names, if `forge.toml` still declares it.
    pub(crate) fn project_for_slot(&self, slot: &SessionSlot) -> Option<LoadedProject> {
        let config = self.config_arc();
        let find =
            |project: &LoadedProject| project.org == slot.org() && project.name == slot.project();
        if let Some(project) = config.projects.iter().find(|project| find(project)) {
            return Some(project.clone());
        }
        #[cfg(any(test, feature = "testing"))]
        if let Some(project) = self.test_extra_projects.lock().iter().find(|project| find(project))
        {
            return Some(project.clone());
        }
        None
    }

    /// The Slack workspace bound to `slot`'s project: the project's own
    /// binding, else its org's. `None` when the slot names no configured
    /// project or nothing binds one - both leave the Slack tools refusing
    /// with the key to add.
    pub(crate) fn slack_workspace_for_slot(&self, slot: &SessionSlot) -> Option<String> {
        self.project_for_slot(slot).and_then(|project| project.slack_workspace)
    }

    /// Look up a project by `name` from `forge.toml`. Returns
    /// [`WorkspaceError::ProjectNotFound`] when no project carries
    /// that name.
    fn find_project_by_name(&self, name: &str) -> Result<LoadedProject, WorkspaceError> {
        self.config_arc().projects.iter().find(|project| project.name == name).cloned().ok_or_else(
            || WorkspaceError::ProjectNotFound {
                name: name.to_owned(),
                path: crate::config::forge_data_dir(&self.config_dir).join("forge.toml"),
            },
        )
    }

    /// The charter the store holds for `slot`, if any. A worker's mission
    /// lives in its conversation, so a `/new` that emptied it has to
    /// re-deliver this or the worker comes back with no idea what it is
    /// for. Only a worker has one, and a lead's absence is the ordinary
    /// answer here.
    pub(crate) fn stored_charter_for(&self, slot: &SessionSlot) -> Option<String> {
        let db = self.db.lock();
        let db = db.as_ref()?;
        crate::store::sessions::get(db, slot.org(), slot.project(), slot.label())
            .ok()
            .flatten()
            .and_then(|row| row.charter)
    }

    /// Whether the store's row for `slot` says its session may ask its user
    /// a question. `None` when the store holds no row: a lead has none, and
    /// a worker without one was never spawned.
    pub(crate) fn stored_interactive_for(&self, slot: &SessionSlot) -> Option<bool> {
        let db = self.db.lock();
        let db = db.as_ref()?;
        crate::store::sessions::get(db, slot.org(), slot.project(), slot.label())
            .ok()
            .flatten()
            .and_then(|row| row.interactive)
    }

    /// The id the store holds for `slot`, unless `--new` (`force_new`)
    /// forces a fresh session. `Ok(Some(id))` => resume that id;
    /// `Ok(None)` => start fresh under a minted one. `force_new`
    /// overrides a stored id - that is what makes the boot wave's leads
    /// come up fresh under `--new`, while every non-boot spawn leaves
    /// `force_new` false and resumes.
    ///
    /// The store is the only source. A row with no id is a session that
    /// has never run, so the caller mints rather than re-deriving one
    /// from the transcripts. A store that cannot be read is an error
    /// rather than a mint: the session it names would be forked, and the
    /// new id written over the row that could not be read.
    fn stored_resume_id(
        &self,
        slot: &SessionSlot,
        force_new: bool,
    ) -> Result<Option<String>, WorkspaceError> {
        if force_new {
            return Ok(None);
        }
        match self.stored_session_id(slot.org(), slot.project(), slot.label()) {
            Ok(id) => Ok(id),
            Err(source) => {
                tracing::error!(
                    target: "forge_workspace::sessions",
                    org = slot.org(),
                    project = slot.project(),
                    label = slot.label(),
                    %source,
                    "reading the session row failed; refusing the spawn rather than minting over it",
                );
                Err(WorkspaceError::SessionStoreUnreadable {
                    org: slot.org().to_owned(),
                    project: slot.project().to_owned(),
                    label: slot.label().to_owned(),
                })
            }
        }
    }

    /// Record `id` as the session for `slot`, minting a fresh one when
    /// the caller has none to hand in. A spawn leaves the seat open with
    /// no turn in flight; the boot wave read its pre-spawn state already,
    /// and the turn its note starts flips it back.
    fn record_spawn_id(&self, slot: &SessionSlot, id: Option<String>, reopen: bool) -> String {
        let id = id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
        self.record_session_id(slot.org(), slot.project(), slot.label(), &id);
        self.write_seat_state(slot, SPAWNED_SEAT_STATE, reopen);
        id
    }

    /// Move `slot`'s row to `state`. A write that cannot land is warned and
    /// not retried: the row is what the next boot derives from, and a
    /// missing write reads as the state it held before. A closed row is
    /// left closed; only the spawn path reopens it.
    pub(crate) fn record_seat_state(
        &self,
        slot: &SessionSlot,
        state: crate::store::sessions::SeatState,
    ) {
        self.write_seat_state(slot, state, false);
    }

    /// The one write behind [`Self::record_seat_state`] and the spawn's
    /// reopen. `reopen` is the opening door's word, not a turn's: a spawn
    /// the user or the boot wave asked for may open a closed seat, while a
    /// settle or a swap landing late must not.
    fn write_seat_state(
        &self,
        slot: &SessionSlot,
        state: crate::store::sessions::SeatState,
        reopen: bool,
    ) {
        let db = self.db.lock();
        let Some(db) = db.as_ref() else { return };
        if let Err(error) = crate::store::sessions::set_seat_state(
            db,
            slot.org(),
            slot.project(),
            slot.label(),
            state,
            reopen,
        ) {
            tracing::warn!(
                target: "forge_workspace::sessions",
                event_name = "seat_state_write_failed",
                slot = %slot.display(),
                state = ?state,
                %error,
                "recording the seat's state failed; the next boot reads the state it held before",
            );
        }
    }

    /// Put `slot`'s row back to the state it held before a refused spawn.
    /// Not a transition: the value is written verbatim, `None` included.
    fn restore_seat_state(
        &self,
        slot: &SessionSlot,
        state: Option<crate::store::sessions::SeatState>,
        expected: crate::store::sessions::SeatState,
    ) {
        let db = self.db.lock();
        let Some(db) = db.as_ref() else { return };
        if let Err(error) = crate::store::sessions::restore_seat_state(
            db,
            slot.org(),
            slot.project(),
            slot.label(),
            state,
            expected,
        ) {
            tracing::warn!(
                target: "forge_workspace::sessions",
                event_name = "seat_state_restore_failed",
                slot = %slot.display(),
                state = ?state,
                %error,
                "restoring the seat's state after a refused spawn failed; the next boot reads what the spawn wrote",
            );
        }
    }

    /// The state `slot`'s row holds, or `None` when the row is absent, was
    /// written before the field existed, or could not be read.
    pub(crate) fn stored_seat_state(
        &self,
        slot: &SessionSlot,
    ) -> Option<crate::store::sessions::SeatState> {
        let db = self.db.lock();
        let db = db.as_ref()?;
        match crate::store::sessions::seat_state(db, slot.org(), slot.project(), slot.label()) {
            Ok(state) => state,
            Err(error) => {
                tracing::warn!(
                    target: "forge_workspace::sessions",
                    event_name = "seat_state_read_failed",
                    slot = %slot.display(),
                    %error,
                    "reading the seat's state failed; the boot opens nothing for this seat and \
                     a resumed worker carries no kick",
                );
                None
            }
        }
    }

    /// Undo a spawn's recorded id after a bind refuses: the store keeps the
    /// id it held before, or none at all, so a boot never resumes onto a
    /// transcript that never existed.
    fn forget_spawn_id(&self, slot: &SessionSlot, previous: Option<&str>) {
        if let Some(previous) = previous {
            self.record_session_id(slot.org(), slot.project(), slot.label(), previous);
            return;
        }
        let db = self.db.lock();
        let Some(db) = db.as_ref() else { return };
        if let Err(error) =
            crate::store::sessions::clear_session_id(db, slot.org(), slot.project(), slot.label())
        {
            tracing::warn!(
                target: "forge_workspace::sessions",
                org = slot.org(),
                project = slot.project(),
                label = slot.label(),
                %error,
                "clearing a refused spawn's session id failed",
            );
        }
    }

    /// Record the id the CLI adopted for a live session, so the store
    /// stops disagreeing with what is running. An in-session `/resume`, a
    /// `/clear`, a login or a logout can move a session's id without
    /// forge choosing it, and a boot resolves a session from this row.
    ///
    /// `slot` is the one the task is registered under, so the row is
    /// named rather than derived: a session's role is what its spawn
    /// stated and nothing re-derives it from the live-worker registry.
    pub(crate) fn note_running_session_id(&self, slot: &SessionSlot, session_id: &str) {
        self.note_worker_session_id(slot, session_id);
        let stored = match self.stored_session_id(slot.org(), slot.project(), slot.label()) {
            Ok(stored) => stored,
            Err(error) => {
                tracing::error!(
                    target: "forge_workspace::sessions",
                    org = slot.org(),
                    project = slot.project(),
                    label = slot.label(),
                    %error,
                    "reading the session row failed; not recording the adopted id over it",
                );
                return;
            }
        };
        if stored.as_deref() == Some(session_id) {
            return;
        }
        tracing::info!(
            target: "forge_workspace::sessions",
            org = slot.org(),
            project = slot.project(),
            label = slot.label(),
            session_id,
            "recording the id the CLI adopted, which is not the one the store held",
        );
        self.record_session_id(slot.org(), slot.project(), slot.label(), session_id);
    }

    /// Mirror the id a live worker adopted onto its registry entry, so
    /// the status echo and `agents__list` name the occupant that is
    /// running rather than the one it was spawned under.
    fn note_worker_session_id(&self, slot: &SessionSlot, session_id: &str) {
        if let Some(entry) = self.pool.lock().get_mut(slot) {
            session_id.clone_into(&mut entry.session_id);
        }
        for entry in self.live_workers.lock().values_mut().flatten() {
            if entry.slot == *slot {
                entry.session_id = Some(forge_primitives::SessionId::new(session_id));
            }
        }
    }

    /// The id the session at `slot` runs under, when this process holds
    /// it live. `None` for a slot with no pooled session. This is the
    /// slot's occupant rather than a snapshot of when a caller last
    /// heard about it, so a read that has to name the id now - a
    /// transcript path, a CLI argument - asks here.
    pub fn running_session_id_for(&self, slot: &SessionSlot) -> Option<String> {
        self.pool.lock().get(slot).map(|entry| entry.session_id.clone())
    }

    /// The id a transcript read for `slot` is looked up under: the live
    /// occupant's when this process holds one, and the store's own row -
    /// the session a wake resumes - otherwise.
    ///
    /// **A sleeping seat still has a session.** The store records the id under
    /// the slot before the child starts and the CLI writes its transcript
    /// under it, so a sleeping seat's history is readable without a spawn; a
    /// read that named only pooled sessions drew one empty. `None` for a
    /// slot with no session at all: nothing live, and no stored id.
    pub fn transcript_session_id_for(&self, slot: &SessionSlot) -> Option<String> {
        if let Some(live) = self.running_session_id_for(slot) {
            return Some(live);
        }
        match self.stored_session_id(slot.org(), slot.project(), slot.label()) {
            Ok(id) => id,
            Err(source) => {
                tracing::warn!(
                    target: "forge_workspace::sessions",
                    org = slot.org(),
                    project = slot.project(),
                    label = slot.label(),
                    %source,
                    "reading the session row failed; the seat reads as one with no history",
                );
                None
            }
        }
    }

    /// Whether an agent is currently pooled for `slot`.
    pub(crate) fn session_is_pooled(&self, slot: &SessionSlot) -> bool {
        self.pool.lock().contains_key(slot)
    }

    /// Whether the slot's pooled handle still has a session task consuming
    /// its commands. The teardown signal is the task's own record of itself:
    /// unanswered while it runs, answered as it drops. A pooled handle with
    /// no such task is one no spawn may hand back (#2683).
    fn pooled_handle_has_task(&self, slot: &SessionSlot) -> bool {
        self.session_teardown(slot).is_some()
    }

    /// When the transcript of the session at `slot` was last written,
    /// read from the catalog row naming the id it currently runs under.
    /// `None` for a slot with no live session, or one whose transcript
    /// is not on disk yet.
    pub fn session_last_activity(&self, slot: &SessionSlot) -> Option<std::time::SystemTime> {
        let id = self.running_session_id_for(slot)?;
        self.catalog
            .lock()
            .values()
            .flatten()
            .find(|info| info.session_id == id)
            .map(|info| UNIX_EPOCH + Duration::from_millis(info.last_modified))
    }

    /// The sessions the seat at `slot` can jump back to with `/resume`,
    /// newest first, and never the one it is already on.
    ///
    /// **The set is what `claude --resume` can find from the directory the
    /// seat's own resume runs in** ([`Self::cwd_for_session`], which is what
    /// `--resume` is handed): a lead's project root, a worker's worktree, or
    /// the project root for a worker with none. A lead gets its project's own
    /// sessions and never its workers' - `Workers::Hidden`, which is what
    /// keeps a lead's turns out of a transcript tagged for a worker - while a
    /// worker gets only the transcripts carrying its own label.
    ///
    /// **A lead is answered from the boot catalog's group for its project**,
    /// which the boot scan already read from disk and holds in memory, with
    /// each row kept only if its transcript is still there: the catalog also
    /// mirrors every Connected, including a session that never wrote a turn,
    /// and `--resume` cannot find that one. A worker's runs are not in the
    /// catalog, so its own directory is scanned - its worktree for a git
    /// worker, the project root otherwise. A seat whose project forge has not
    /// loaded has no directory to resume from, and answers empty.
    pub async fn resumable_sessions(&self, slot: &SessionSlot) -> Vec<SDKSessionInfo> {
        let Some(cwd) = self.cwd_for_session(slot) else {
            return Vec::new();
        };
        let workers = if slot.is_lead() {
            forge_agent::userdata::catalog::scan::Workers::Hidden
        } else {
            forge_agent::userdata::catalog::scan::Workers::Only(slot.label().to_owned())
        };
        // A worker's runs are not in the catalog at all - the boot scan hides
        // them and nothing mirrors them - so only a lead takes this source.
        let from_catalog = if slot.is_lead() { self.catalog_sessions_for(&cwd) } else { None };
        let mut entries = match from_catalog {
            Some(mut held) => {
                let dir = self.transcript_dir_for(&cwd);
                held.retain(|info| dir.join(format!("{}.jsonl", info.session_id)).is_file());
                held
            }
            None => self.scan_sessions(&cwd, workers).await,
        };
        let occupant = self.transcript_session_id_for(slot);
        entries.retain(|info| Some(&info.session_id) != occupant.as_ref());
        // A row the catalog mirrored at Connected states a placeholder title
        // until the next scan reads the transcript. The transcript is there
        // now and the row is a real jump, so read the one file: the occupant
        // has already gone, so this is a session the seat left, not the one it
        // is writing.
        let dir = self.transcript_dir_for(&cwd);
        for info in &mut entries {
            if info.file_size.is_none() {
                let path = dir.join(format!("{}.jsonl", info.session_id));
                if let Some(read) =
                    forge_agent::userdata::catalog::scan::read_session_info_at(&path)
                {
                    *info = read;
                }
            }
        }
        entries.sort_by_key(|info| std::cmp::Reverse(info.last_modified));
        entries.truncate(Self::RESUME_CANDIDATES);
        entries
    }

    /// The newest sessions a `/resume` picker offers: a reader picks from the
    /// top, and the record is re-encoded on every seat open and reread, so the
    /// answer cannot grow with the project's history.
    const RESUME_CANDIDATES: usize = 50;

    /// The boot catalog's group for the project at `cwd`, or `None` while the
    /// boot scan has not landed: a group missing because nothing has scanned
    /// is not a project with no sessions.
    fn catalog_sessions_for(&self, cwd: &str) -> Option<Vec<SDKSessionInfo>> {
        if !self.catalog_ready() {
            return None;
        }
        let key = ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(
            Some(cwd),
        ));
        let catalog = self.catalog.lock();
        Some(catalog.get(&key).cloned().unwrap_or_default())
    }

    /// The directory claude writes `cwd`'s transcripts in, under this
    /// workspace's config dir.
    fn transcript_dir_for(&self, cwd: &str) -> std::path::PathBuf {
        forge_sdk::projects_dir_for(&self.session_scan_root())
            .join(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(cwd)))
    }

    /// Where this workspace's `projects/` tree resolves, with the boot scan's
    /// own fallbacks.
    fn session_scan_root(&self) -> std::path::PathBuf {
        catalog_scan_root(&self.config_dir).unwrap_or_else(|| {
            std::fs::canonicalize(&self.config_dir).unwrap_or_else(|_| self.config_dir.clone())
        })
    }

    /// One directory scanned for the sessions a seat may resume - a worker's
    /// own runs, and a lead's before the boot catalog has landed - through the
    /// store's tag cache like the boot scan: an unchanged transcript is not
    /// re-read end to end for a list a reader opens for a moment.
    ///
    /// The cap bounds the reads as well as the answer: the scan reads the
    /// newest transcripts first and stops once the rows it serves are in
    /// hand, filling from the next batch when one comes back short - and a
    /// transcript a worker's cached tag rules out is not read at all
    /// (#2567), so a non-git worker sharing the project root no longer pays
    /// the project's whole scan. A lead takes the catalog above for a list
    /// that costs no read at all.
    async fn scan_sessions(
        &self,
        cwd: &str,
        workers: forge_agent::userdata::catalog::scan::Workers,
    ) -> Vec<SDKSessionInfo> {
        // Loaded but NOT persisted: the boot scan owns this table, and a redb
        // commit on the open path is a cost nothing here needs.
        let tag_cache = std::sync::Arc::new(load_session_tag_cache(self.db.lock().as_ref()));
        forge_agent::userdata::catalog::scan::list_sessions(
            &self.session_scan_root(),
            Some(cwd),
            Some(Self::RESUME_CANDIDATES),
            0,
            workers,
            Some(&tag_cache),
        )
        .await
    }

    /// A fresh id for a session starting now, recorded against `slot`'s
    /// row.
    pub(crate) fn fresh_session_id_for(&self, slot: &SessionSlot) -> String {
        // A swap is not an opening door: a `/new` a dying task drains after
        // the close must not reopen the row.
        self.record_spawn_id(slot, None, false)
    }

    /// The session id the store holds for `(org, project, label)`.
    ///
    /// `Ok(None)` means no id: the row is absent, or it carries none.
    /// That is a session which has never run, and a caller may mint for
    /// it. `Err` means the row could not be read, which is a different
    /// answer and must never be treated as absence: a caller that minted
    /// there would fork the session and write the new id over the row it
    /// failed to read.
    fn stored_session_id(
        &self,
        org: &str,
        project: &str,
        label: &str,
    ) -> Result<Option<String>, anyhow::Error> {
        let db = self.db.lock();
        let Some(db) = db.as_ref() else {
            // No store at all, so there is no row to read and none a mint
            // could overwrite.
            return Ok(None);
        };
        Ok(crate::store::sessions::get(db, org, project, label)?.and_then(|row| row.session_id))
    }

    /// Record `id` as the session for `(org, project, label)`, keeping the
    /// fields a worker's row already carries. A write that cannot land is
    /// warned and not retried: the session still runs under `id`, and the
    /// next boot reads whatever the row held.
    pub(crate) fn record_session_id(&self, org: &str, project: &str, label: &str, id: &str) {
        let db = self.db.lock();
        let Some(db) = db.as_ref() else { return };
        let existing = crate::store::sessions::get(db, org, project, label).ok().flatten();
        let row = crate::store::sessions::SessionRecord {
            org: org.to_owned(),
            project: project.to_owned(),
            label: label.to_owned(),
            session_id: Some(id.to_owned()),
            charter: existing.as_ref().and_then(|row| row.charter.clone()),
            kick: existing.as_ref().and_then(|row| row.kick.clone()),
            resume_kick: existing.as_ref().and_then(|row| row.resume_kick.clone()),
            interactive: existing.as_ref().and_then(|row| row.interactive),
            seat_state: existing.as_ref().and_then(|row| row.seat_state),
            is_git_repo: existing.as_ref().and_then(|row| row.is_git_repo),
            mcp_families: existing.as_ref().and_then(|row| row.mcp_families.clone()),
            cwd: existing.and_then(|row| row.cwd),
        };
        if let Err(error) = crate::store::sessions::put(db, &row) {
            tracing::warn!(
                target: "forge_workspace::sessions",
                org, project, label, session_id = %id, %error,
                "recording the session id failed; it will not survive a restart",
            );
        }
    }

    /// Locate a `ProjectView`-like (`LoadedProject`) by `name` from
    /// `forge.toml`. Returns `None` when no project carries that name.
    /// Used by the spawn handlers to resolve the project's path / cwd
    /// before emitting `SessionUpdate::Spawning`.
    pub(crate) fn find_project_view_by_name(&self, name: &str) -> Option<LoadedProject> {
        #[cfg(any(test, feature = "testing"))]
        if let Some(found) =
            self.test_extra_projects.lock().iter().find(|p| p.name == name).cloned()
        {
            return Some(found);
        }
        self.config_arc().projects.iter().find(|p| p.name == name).cloned()
    }

    /// The seat a project-scoped section update routes on: the project's
    /// lead, which exists for every declared project. `None` for a name no
    /// project carries, the shape a project that left forge.toml leaves.
    pub(crate) fn lead_slot_for_project(&self, project_name: &str) -> Option<SessionSlot> {
        self.find_project_view_by_name(project_name)
            .map(|project| SessionSlot::lead(project.org, project.name))
    }

    /// Internal accessor for the SessionUpdate fan-out sender. Used
    /// by `spawn.rs` to emit `Spawning` / `ConnectionFailed` /
    /// `FatalError` from the App-level handlers.
    pub(crate) fn update_tx(&self) -> &UpdateFanout {
        &self.update_tx
    }

    /// Tell every view the account pool moved.
    ///
    /// Called from the writes that move it - a boot probe settling, the usage
    /// poller landing or failing, and the listener binding - because none of
    /// them belongs to a seat. The frame carries the pool's drawn state, built
    /// by [`Self::account_pool_view`], so a subscriber applies a usage-only
    /// move without a home re-read; a move in what a project row binds on
    /// still asks for the snapshot that refreshes it.
    pub(crate) fn announce_accounts_changed(&self) {
        let _ = self
            .update_tx
            .send(SessionUpdate::AccountsChanged { accounts: self.account_pool_view() });
    }

    /// The cwd a project lead's slot runs in: its project's path.
    /// `claude --resume` indexes by the project key derived from the
    /// subprocess's working directory, so every explicit-resume code
    /// path must spawn the subprocess in the session's original cwd or
    /// the resume hits "No conversation found with session ID ..." even
    /// when the `.jsonl` exists.
    ///
    /// Read from the slot rather than from the catalog: a catalog row is
    /// keyed by the id the CLI adopted, which `/new` replaces, so the
    /// lookup answered nothing for the session that had just started and
    /// resume was handed an empty working directory.
    ///
    /// A WORKER answers nothing here, deliberately. Its cwd is its
    /// worktree, which only the live-worker registry can compose; the
    /// project root is a plausible-looking wrong answer that would shadow
    /// the registry arm in [`Self::cwd_for_session`] and send a git
    /// worker's resume to the wrong directory.
    fn session_cwd_for(&self, slot: &SessionSlot) -> Option<String> {
        if !slot.is_lead() {
            return None;
        }
        Some(self.project_for_slot(slot)?.path.to_string_lossy().into_owned())
    }

    /// Insert (or update) a session entry under the project that
    /// owns `cwd`. Called after every `Connected` migration so newly
    /// spawned sessions surface in the
    /// Projects-pane drilldown immediately, without forcing a full
    /// disk re-scan. The entry is placed at the head of the
    /// project's session list to match the most-recent-first ordering
    /// the scan produces.
    pub fn record_connected_session(&self, cwd: &str, session_id: &str, summary: Option<String>) {
        let storage_key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(cwd));
        let key = ProjectKey::new(storage_key.clone());
        let now_ms = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map_or(0, |d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX));
        let entry = SDKSessionInfo {
            session_id: session_id.to_owned(),
            summary: summary.unwrap_or_else(|| "new session".to_owned()),
            last_modified: now_ms,
            file_size: None,
            custom_title: None,
            first_prompt: None,
            git_branch: None,
            cwd: Some(cwd.to_owned()),
            storage_key,
            tag: None,
            created_at: None,
        };
        let mut catalog = self.catalog.lock();
        let entries = catalog.entry(key).or_default();
        entries.retain(|e| e.session_id != session_id);
        entries.insert(0, entry);
    }

    /// Subscribe without answering the workspace's prompts: a logger, a
    /// mirror, anything that reads the stream but renders no prompt.
    ///
    /// Every caller gets its own stream, so a second view attaches beside
    /// the first rather than being refused, and the workspace drops the
    /// matching subscription once its receiver goes. A stream carries what
    /// is emitted after this call; a subscriber reads what it missed from
    /// the subject's snapshot instead.
    ///
    /// The distinction from [`Self::subscribe_answerer`] is load-bearing
    /// rather than descriptive. A permission, question or Slack-draft
    /// request is parked on a reply, and the paths that raise one resolve it
    /// `Cancelled` instead when no subscriber can answer, so that a request
    /// nobody will reply to fails the turn rather than hanging it. A
    /// subscriber that declares itself an observer is not counted as an
    /// answer.
    ///
    /// **A browser hand-off fails closed differently**: nothing parks a
    /// decision for it to cancel, so its registration hands the blocked call
    /// a dead receiver instead and the tool answers the reason - no attached
    /// client can show the hand-off - rather than holding a session on a
    /// prompt no view can draw.
    ///
    /// Every frame arrives as a [`SeatUpdate`], carrying the number its
    /// seat minted for it.
    pub fn subscribe_mirror(&self) -> mpsc::UnboundedReceiver<SeatUpdate> {
        self.update_tx.subscribe(SubscriberRole::Observing)
    }

    /// Subscribe as an answerer: the same stream, for a client that renders
    /// prompts and can answer them.
    ///
    /// The answering half of [`Self::subscribe_mirror`]. The role decides one
    /// thing: whether the core may park a prompt on this subscriber's reply.
    pub fn subscribe_answerer(&self) -> mpsc::UnboundedReceiver<SeatUpdate> {
        self.update_tx.subscribe(SubscriberRole::Answering)
    }

    /// Clone the workspace's [`SessionUpdate`] sender. Internal to this
    /// crate: a view's own async work belongs on a channel of its own,
    /// so that the subscription methods above are the whole of what the core
    /// owes a frontend.
    pub(crate) fn update_sender(&self) -> UpdateFanout {
        self.update_tx.clone()
    }

    /// The number `key`'s next frame will be minted under: what a client
    /// reading the seat expects next, beside the occupant that names the
    /// epoch it belongs to.
    pub fn seat_next_seq(&self, key: &SessionSlot) -> u64 {
        self.update_tx.next_seq(key)
    }

    /// The frames `key`'s stream emitted under the numbers in `from..=to`,
    /// oldest first: the answer to a client's range ask while the seat's own
    /// window holds them.
    pub fn seat_frames_between(&self, key: &SessionSlot, from: u64, to: u64) -> Vec<SeatUpdate> {
        self.update_tx.frames_between(key, from, to)
    }

    /// The oldest number `key`'s window still holds, `None` for a seat that
    /// has emitted nothing: what tells a range answered from memory from one
    /// that has to be read off the transcript.
    pub fn seat_oldest_kept_seq(&self, key: &SessionSlot) -> Option<u64> {
        self.update_tx.oldest_kept(key)
    }

    /// How many of the numbers in `from..=to` on `key`'s stream no window
    /// holds: the frames that close an epoch are numbered but kept out of the
    /// ring, so a reader measuring whether a copy covers a stretch leaves them
    /// out of what it must account for.
    pub fn seat_unringed_between(&self, key: &SessionSlot, from: u64, to: u64) -> u64 {
        self.update_tx.unringed_between(key, from, to)
    }

    /// Whether `key`'s latest epoch-opening seal carried rows, which no ring
    /// holds: what tells a copy filled from the window that it cannot reach
    /// the rows the epoch began with.
    pub fn seat_epoch_opened_with_rows(&self, key: &SessionSlot) -> bool {
        self.update_tx.epoch_opened_with_rows(key)
    }

    /// Borrow the workspace-side [`DomainSession`] for `key`.
    ///
    /// Returns the [`Arc`]-cloned mutex protecting the domain bucket.
    /// Callers `.lock()` to read or mutate. `None` when no
    /// `SessionTask` is registered for `key` (e.g., the session was
    /// closed or hasn't been spawned yet).
    ///
    /// Callers should hold the lock for the shortest scope possible;
    /// concurrent reducers and the per-session `SessionTask` share
    /// this mutex.
    pub fn domain_session_for(&self, key: &SessionSlot) -> Option<Arc<Mutex<DomainSession>>> {
        self.domain_handles.lock().get(key).cloned()
    }

    /// The slash commands the CLI last advertised for the session at
    /// `slot`. Empty for a slot whose session has not connected yet, or
    /// whose CLI advertised none.
    pub fn available_commands_for(&self, slot: &SessionSlot) -> Vec<AvailableCommand> {
        self.domain_session_for(slot)
            .map(|domain| domain.lock().available_commands.clone())
            .unwrap_or_default()
    }

    /// The subagents the CLI last advertised for the session at `slot`.
    /// Empty in the same two cases as [`Self::available_commands_for`].
    pub fn available_agents_for(&self, slot: &SessionSlot) -> Vec<AvailableAgent> {
        self.domain_session_for(slot)
            .map(|domain| domain.lock().available_agents.clone())
            .unwrap_or_default()
    }

    /// The sub-agent instances the session at `slot` has folded, as the list
    /// the session task pushes when it moves.
    ///
    /// **A record reads this rather than folding the conversation itself.**
    /// The task folds a card per frame and announces the list moving, so a
    /// second fold over the held conversation would be a second answer to a
    /// question one fold already answers - and one that disagrees with the
    /// frames as soon as the conversation a record can see is shorter than the
    /// one the session has run.
    pub fn subagent_cards_for(
        &self,
        slot: &SessionSlot,
    ) -> Vec<forge_primitives::runtime::SubagentCard> {
        self.domain_session_for(slot)
            .map(|domain| domain.lock().cards_snapshot.clone())
            .unwrap_or_default()
    }

    /// Whether the session at `key` currently has a live agent
    /// handle stamped onto its [`DomainSession`]. Encapsulates the
    /// presence check so callers don't need to peek at
    /// `DomainSession.conn` directly - the field layout is a
    /// workspace internal.
    pub fn has_agent_for(&self, key: &SessionSlot) -> bool {
        self.domain_session_for(key).is_some_and(|d| d.lock().conn.is_some())
    }

    /// Apply a `/dictate` override edit to the session's `DomainSession`
    /// and echo the full set back. An unknown session is refused the same
    /// way the per-session commands are: there is nothing to edit.
    ///
    /// # Errors
    ///
    /// Returns [`DispatchError::UnknownSession`] when no `DomainSession`
    /// is registered for the key.
    fn apply_dictate_override(
        self: &Arc<Self>,
        key: &SessionSlot,
        update: crate::dictate::DictateOverrideUpdate,
    ) -> Result<(), DispatchError> {
        let Some(domain) = self.domain_session_for(key) else {
            return Err(DispatchError::UnknownSession(key.clone()));
        };
        match update {
            crate::dictate::DictateOverrideUpdate::Styling(v) => {
                domain.lock().dictate_overrides.styling = Some(v);
            }
            crate::dictate::DictateOverrideUpdate::Structure(v) => {
                domain.lock().dictate_overrides.structure = Some(v);
            }
            crate::dictate::DictateOverrideUpdate::Context(v) => {
                domain.lock().dictate_overrides.context = Some(v);
            }
            crate::dictate::DictateOverrideUpdate::Reset => {
                domain.lock().dictate_overrides = crate::dictate::DictateOverrides::default();
            }
        }
        let overrides = domain.lock().dictate_overrides;
        let _ = self
            .update_sender()
            .send(SessionUpdate::DictateOverrides { key: key.clone(), overrides });
        Ok(())
    }

    /// Dispatch a workspace-originated plain prompt (cron fire, peer,
    /// gotify or slack delivery, kick, notices).
    ///
    /// **A delivery drawn in a view needs an update here, paired with an arm
    /// in `forge-server`'s `delivery_turn`.** This path emits no frame of its
    /// own - the forge for one is `delivery_turn`, downstream, and it ends in
    /// `_ => return None`. So a prompt sent from here whose typed update has
    /// no arm there draws nothing in any view, silently: a prompt with no
    /// envelope of its own takes [`Self::dispatch_forged_prompt`] instead,
    /// which forges the frame here.
    pub fn dispatch_workspace_prompt(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
    ) -> Result<(), DispatchError> {
        self.dispatch_workspace_prompt_from(key, text, PromptSource::Forge)
    }

    /// [`Self::dispatch_workspace_prompt`], with the row's source label named
    /// by the caller: a delivery knows what it is (a cron fire, a Gotify
    /// notification, a peer comm) and the queued row has to say so.
    pub fn dispatch_workspace_prompt_from(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
        source: PromptSource,
    ) -> Result<(), DispatchError> {
        self.dispatch_workspace_prompt_under(
            key,
            text,
            source,
            match source {
                PromptSource::Forge => forge_sdk::request_id::next_forged_prompt_id(),
                _ => forge_sdk::request_id::next_prompt_id(),
            },
        )
    }

    /// [`Self::dispatch_workspace_prompt_from`] with the id supplied by the
    /// caller, for a site that already minted one: a delivery that draws its
    /// own envelope row passes the same id to both, so the row a view holds
    /// while the prompt queues and the prompt's lifecycle frames are one thing
    /// by id.
    pub fn dispatch_workspace_prompt_under(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
        source: PromptSource,
        uuid: String,
    ) -> Result<(), DispatchError> {
        // A prompt arriving while the seat swaps its occupant waits for the
        // successor: the session on its way out must not start a turn the new
        // one would never carry. Every machinery delivery - peer, cron,
        // Gotify, Slack - comes through here, so one gate holds them all.
        if self.hold_prompt(
            key,
            crate::handoff::HeldPrompt {
                text: text.clone(),
                attachments: Vec::new(),
                source,
                uuid: uuid.clone(),
                sender: None,
            },
        ) {
            return Ok(());
        }
        // `route` rather than `dispatch`: the delivery's frame is the
        // envelope one its own update forges, not a bare user turn.
        self.route(Command::PromptUnder {
            key: key.clone(),
            text,
            attachments: Vec::new(),
            uuid,
            source,
            dispatch_id: None,
        })
    }

    /// Fire the continuation for a seat whose turn just failed: one prompt
    /// of forge's own, the moment the failure lands (#2146).
    ///
    /// Every non-cancelled failed turn is this one's to answer, whatever its
    /// class - a transient server error included, which nobody's retry
    /// ladder throws back at the CLI once the turn has died. The decision is
    /// taken under the lock; the dispatch is not.
    pub(crate) fn fire_auto_continue(self: &Arc<Self>, key: &SessionSlot) {
        let Some(domain) = self.domain_session_for(key) else {
            return;
        };
        let (reason, uuid) = {
            let mut guard = domain.lock();
            // Spent either way: the decision for this failure is made here,
            // so nothing can send the same nudge twice.
            let Some(pending) = guard.auto_continue.take() else {
                return;
            };
            guard.auto_continue_spent = true;
            // The prompt is keyed to the occupant the failure belonged to -
            // the same tick's fold cannot have moved it - so a replacement
            // drained ahead of it is not handed words about a history it
            // does not have; the check is where the queued prompt runs.
            let uuid = forge_sdk::request_id::next_forged_prompt_id();
            guard.auto_continue_queued = Some((uuid.clone(), guard.session_id.clone()));
            (pending.reason, uuid)
        };
        let text = auto_continue_prompt(&reason);
        if let Err(error) = self.dispatch_forged_prompt_under(key, text, uuid) {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "auto_continue_dispatch_failed",
                slot = %key.display(),
                %error,
                "the continuation prompt for a failed turn could not be dispatched",
            );
            return;
        }
        tracing::info!(
            target: "forge_workspace::workspace",
            event_name = "auto_continued_failed_turn",
            slot = %key.display(),
            "continued a failed turn",
        );
    }

    /// Dispatch a workspace-originated prompt whose words no view has drawn:
    /// a worker kick, an auto-continue. [`Self::dispatch_workspace_prompt`]
    /// exactly, plus the frame - nothing else carries these words, where a
    /// delivery's own envelope update is what draws a delivery, and routing
    /// one of those through here would draw its words twice.
    pub fn dispatch_forged_prompt(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
    ) -> Result<(), DispatchError> {
        self.dispatch_forged_prompt_under(key, text, forge_sdk::request_id::next_forged_prompt_id())
    }

    /// [`Self::dispatch_forged_prompt`] with the id supplied by the caller,
    /// for a forged prompt an association has to outlive the dispatch: the
    /// auto-continue records the id it sent under, so the prompt can be
    /// matched where it runs. The frame and the prompt carry one id either
    /// way - the row a view draws and the turn the model receives are one
    /// thing by id.
    pub(crate) fn dispatch_forged_prompt_under(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
        uuid: String,
    ) -> Result<(), DispatchError> {
        self.dispatch_forged_prompt_held(key, text, uuid, true)
    }

    /// The brief a handoff's successor runs as its first turn.
    ///
    /// **Its own row, forged like the machinery's other prompts.** The
    /// successor's transcript opens with this prompt and the client draws it
    /// as the handoff procedure; the CLI never echoes a stdin prompt, so this
    /// frame is the page's only carrier of it.
    pub(crate) fn dispatch_handoff_brief(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
        uuid: String,
    ) -> Result<(), DispatchError> {
        self.dispatch_forged_prompt_held(key, text, uuid, true)
    }

    /// The handoff's own judgment prompt.
    ///
    /// **The one prompt a swap's gate lets through.** The gate opens when
    /// the handoff begins, and this is the prompt the handoff is built on:
    /// held like any other, it would wait for a successor that is waiting
    /// for it.
    pub(crate) fn dispatch_handoff_prompt(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
        uuid: String,
    ) -> Result<(), DispatchError> {
        self.dispatch_forged_prompt_held(key, text, uuid, false)
    }

    fn dispatch_forged_prompt_held(
        self: &Arc<Self>,
        key: &SessionSlot,
        text: String,
        uuid: String,
        holdable: bool,
    ) -> Result<(), DispatchError> {
        // Stamped at the forge: the CLI never echoes a prompt, so this row
        // opens every turn the machinery starts - and a page attaching
        // mid-turn anchors its running clock on the first row that carries a
        // stamp.
        let mut frame = Message::display_only_user(text.clone(), uuid.clone());
        frame.stamp_if_absent(&crate::install::rfc3339_now());
        // One source for both the dispatch and the frame the dispatch forges:
        // the row a view labels and the frame a reader's follow reads arm
        // alike only while they are one fact (#2198).
        let source = crate::protocol::PromptSource::Forge;
        let result = if holdable {
            self.dispatch_workspace_prompt_under(key, text, source, uuid)
        } else {
            self.route(Command::PromptUnder {
                key: key.clone(),
                text,
                attachments: Vec::new(),
                uuid,
                source,
                dispatch_id: None,
            })
        };
        if result.is_ok() {
            let _ = self.update_sender().send(SessionUpdate::ChatAppended {
                key: key.clone(),
                msg: frame,
                source: Some(source),
            });
        }
        result
    }

    /// Tell a row's live owner what the user just did to it, one line.
    ///
    /// **Forged, not plain.** The board's edits carry no envelope update of
    /// their own, so a prompt routed the plain way queues invisibly in a
    /// view - the forged frame is what draws the line the moment it lands.
    /// Silent for an ownerless row and a sleeping seat: the board is where
    /// that edit shows, and a prompt is a real turn.
    fn tell_row_owner(self: &Arc<Self>, task: &forge_primitives::tasks::Task, text: String) {
        if let Some(owner) = &task.owner
            && self.seat_is_live(owner)
        {
            let _ = self.dispatch_forged_prompt(owner, text);
        }
    }

    /// What a board notice calls the lane a move landed in: the board's own
    /// names, so `Pending` reads `backlog` as its lane does.
    fn lane_words(to: forge_primitives::tasks::TaskStatus) -> &'static str {
        use forge_primitives::tasks::TaskStatus;
        match to {
            TaskStatus::Pending => "backlog",
            TaskStatus::InProgress => "in progress",
            TaskStatus::Waiting => "waiting",
            TaskStatus::Completed => "completed",
            TaskStatus::Failed => "failed",
            TaskStatus::Canceled => "canceled",
        }
    }

    /// Route a [`Command`]. Per-session commands (`cmd.key() ==
    /// Some(key)`) fan out to the matching `SessionTask`. App-level
    /// commands (`cmd.key() == None` - `SpawnProject`) route to the
    /// workspace's own handler.
    ///
    /// Test fallback: when no `SessionTask` is registered for `key`
    /// but a `DomainSession` carries a stub `AgentHandle` (e.g., the
    /// `Workspace::testing_stub` path), the command runs
    /// synchronously against that handle. This keeps `#[test]`-flavor
    /// unit tests (no tokio runtime) able to observe the
    /// `forge_primitives::AgentCommand` emitted on the stub's channel
    /// without spinning up an async actor.
    ///
    /// # Errors
    ///
    /// Returns [`DispatchError::UnknownSession`] when no `SessionTask`
    /// is registered for the requested key (e.g., the session was just
    /// closed), with one exception: a `ResumeSession` starts the seat on the
    /// id it names, which is the recovery a failed start leaves. Returns
    /// [`DispatchError::SessionClosed`] when the task's command receiver has
    /// been dropped.
    pub fn dispatch(self: &Arc<Self>, cmd: Command) -> Result<(), DispatchError> {
        self.dispatch_answered(cmd)
    }

    /// Dispatch one command a view sent over the socket.
    ///
    /// The same dispatch as [`Self::dispatch`]: the frame a prompt draws is
    /// the session task's, emitted when the CLI starts it, so no entry needs
    /// to say which door the words came through.
    ///
    /// # Errors
    ///
    /// As [`Self::dispatch`].
    pub fn dispatch_from_view(self: &Arc<Self>, cmd: Command) -> Result<(), DispatchError> {
        self.dispatch_answered(cmd)
    }

    /// Route a command, answering the prompts forge handles itself.
    ///
    /// **A prompt draws its turn in the session task, never here** (#2816):
    /// the queue carries its words from dispatch and the page takes the row
    /// when the CLI starts it. Only the answer a forge command, a misuse or an
    /// unrunnable slash name owes is emitted from this path, because the task
    /// never sees those prompts.
    ///
    /// NOT from `dispatch_workspace_prompt`, which is the delivery path: a
    /// delivery already draws as an envelope turn of its own.
    fn dispatch_answered(self: &Arc<Self>, cmd: Command) -> Result<(), DispatchError> {
        // The id is minted HERE, before the prose is taken, so the prompt and
        // its lifecycle frames carry one thing by id: a plain `Prompt` becomes
        // the `PromptUnder` the rest of the tree already treats identically,
        // keeping the mint on one path instead of two.
        let cmd = match cmd {
            Command::Prompt { key, text, attachments } => Command::PromptUnder {
                key,
                text,
                attachments,
                uuid: forge_sdk::request_id::next_prompt_id(),
                source: crate::protocol::PromptSource::You,
                dispatch_id: None,
            },
            Command::PromptUnder { key, text, attachments, uuid, source, dispatch_id, .. } => {
                Command::PromptUnder { key, text, attachments, uuid, source, dispatch_id }
            }
            other => other,
        };
        let key = match &cmd {
            Command::PromptUnder { key, .. } => Some(key.clone()),
            _ => None,
        };
        // A composer's text that names a forge command is FORGE'S, not the
        // CLI's. Decided here rather than in a view, because this is where
        // both entries dispatch: the UI's own entry and the socket's reach
        // the same commands only by taking the same path, and some of these
        // names the CLI answers differently or not at all - `/new` is its own
        // `/clear`, which rotates a conversation forge never records.
        //
        // A forge command's answer comes back with the outcome rather than
        // being emitted where it is decided, so it lands after the command has
        // run and never before a refusal that wrote nothing.
        let (outcome, answer, answered_here) = match &cmd {
            Command::PromptUnder { key, text, .. } => match crate::prompt::forge_invocation(text) {
                Some(crate::prompt::Invocation::Command(prompt)) => {
                    let (outcome, answer) = self.run_forge_prompt(key, &prompt);
                    (outcome, answer, true)
                }
                Some(crate::prompt::Invocation::Misuse(usage)) => {
                    (Ok(()), Some(forge_misuse(usage)), true)
                }
                None => {
                    if let Some(refusal) = self.unrunnable_slash_name(key, text) {
                        (Ok(()), Some(forge_misuse(&refusal)), true)
                    } else {
                        (self.route(cmd), None, false)
                    }
                }
            },
            _ => (self.route(cmd), None, false),
        };
        // A refused prompt never reached a model, so the refusal is written to
        // the asking socket alone. The task draws the prompt's row once it has
        // it, so a route refusal never draws one.
        if answered_here
            && outcome.is_ok()
            && let Some(key) = key
            && let Some((severity, answer)) = answer
        {
            self.notice(&key, severity, &answer);
        }
        outcome
    }

    /// Run one of forge's own commands against `key`'s seat.
    ///
    /// The launch settings are built here rather than taken from the caller:
    /// a view that supplied its own would spawn a session with what its own
    /// snapshot happened to hold, and a client has no snapshot to supply.
    ///
    /// The answer is returned rather than emitted, so the dispatcher can land
    /// it after the command has run.
    fn run_forge_prompt(
        self: &Arc<Self>,
        key: &SessionSlot,
        prompt: &crate::prompt::ForgePrompt,
    ) -> (Result<(), DispatchError>, Option<ForgeAnswer>) {
        use crate::prompt::ForgePrompt;
        // A mode the CLI has no name for is answered rather than sent: the
        // command carries the enum, so an unparsed one cannot be dispatched
        // at all.
        let command = match prompt {
            ForgePrompt::NewSession => {
                let (cwd, launch_settings) = self.spawn_inputs(key);
                // **A replacement is not a sweep**: the slot stays and the
                // previous occupant's tabs close before the new one starts.
                self.replace_browser_seat(key);
                Command::NewSession { key: key.clone(), cwd, launch_settings, session_id: None }
            }
            // The brief is asked of the session: the same process the
            // automatic trigger runs, with the trigger being the person.
            ForgePrompt::Handoff => Command::Handoff { key: key.clone(), brief: None },
            ForgePrompt::ResumeSession { session_id } => {
                let (cwd, launch_settings) = self.spawn_inputs(key);
                self.replace_browser_seat(key);
                Command::ResumeSession {
                    key: key.clone(),
                    session_id: session_id.clone(),
                    cwd,
                    launch_settings,
                }
            }
            ForgePrompt::ShowMode => return self.show_mode(key),
            ForgePrompt::SetMode { mode } => {
                let Some(mode) = forge_primitives::permission::PermissionMode::from_wire(mode)
                else {
                    return (Ok(()), Some(forge_misuse(&format!("Unknown mode: {mode}"))));
                };
                Command::SetMode { key: key.clone(), mode }
            }
            ForgePrompt::SetModel { model } => {
                Command::SetModel { key: key.clone(), model: model.clone() }
            }
            ForgePrompt::ShowEffort => return self.show_effort(key),
            ForgePrompt::SetEffort { level } => return self.set_effort(key, level),
        };
        (self.route(command), None)
    }

    /// **A bare `/mode` answers what the session is on**, not what the
    /// command's usage is (#1626). The hook's observation outranks the
    /// launch's own setting - the precedence the inspector draws - because
    /// the CLI can change mode without re-emitting status. A session that
    /// has reported neither is answered with the usage line it answered
    /// before.
    fn show_mode(&self, key: &SessionSlot) -> (Result<(), DispatchError>, Option<ForgeAnswer>) {
        let mode = self.domain_session_for(key).and_then(|domain| {
            let domain = domain.lock();
            domain.observed_permission_mode.or(domain.configured_permission_mode)
        });
        (
            Ok(()),
            Some(match mode {
                Some(mode) => (NoticeSeverity::Info, format!("Mode: {}", mode.as_wire())),
                None => forge_misuse("Usage: /mode <id>"),
            }),
        )
    }

    /// **A bare `/effort` answers the level in force**, on `show_mode`'s
    /// terms: the observed level, else the one the launch asked for (#1626).
    fn show_effort(&self, key: &SessionSlot) -> (Result<(), DispatchError>, Option<ForgeAnswer>) {
        let level = self.domain_session_for(key).map(|domain| {
            let domain = domain.lock();
            domain.observed_effort.unwrap_or(domain.configured_effort)
        });
        (
            Ok(()),
            Some(match level {
                Some(level) => (NoticeSeverity::Info, format!("Effort: {}", level.as_stored())),
                None => forge_misuse("Usage: /effort <level>"),
            }),
        )
    }

    /// Tell the fleet a `/new` or `/resume` kept the slot and swapped the
    /// occupant, so the previous occupant's tabs close. **Best-effort**, like
    /// the spawn's own warm: a workspace with no fleet has no tabs to replace.
    pub(crate) fn replace_browser_seat(&self, seat: &SessionSlot) {
        let (Some(host), Ok(runtime)) =
            (self.browser_host(), tokio::runtime::Handle::try_current())
        else {
            return;
        };
        let seat = seat.clone();
        runtime.spawn(async move { host.replace_seat(&seat).await });
    }

    /// **A session ended**, told to the fleet as a fact rather than left to
    /// the next sweep: a sweep rebuilds its set from configuration, so a
    /// closed lead is still in it. The tombstone is synchronous, so it lands
    /// before the release work; the tab close is the fleet's own async work.
    fn release_browser_seat(&self, seat: &SessionSlot) {
        let Some(host) = self.browser_host() else { return };
        host.session_ended(seat);
        let Ok(runtime) = tokio::runtime::Handle::try_current() else {
            // **The tombstone landed; the tab close did not.** A close
            // called off a runtime thread leaves the seat's tabs to the next
            // sweep, and says so rather than returning silently.
            tracing::warn!(
                target: "forge_workspace::workspace",
                seat = %seat.display(),
                "a seat ended but its browser tab replacement could not be spawned \
                 (event_name browser_seat_end_without_replacement)"
            );
            return;
        };
        let seat = seat.clone();
        runtime.spawn(async move { host.replace_seat(&seat).await });
    }

    /// The cwd and settings a re-spawn on `key` carries.
    fn spawn_inputs(&self, key: &SessionSlot) -> (String, SessionLaunchSettings) {
        let cwd = self.cwd_for_session(key).unwrap_or_default();
        let launch_settings = self.launch_settings_for(key, &cwd);
        (cwd, launch_settings)
    }

    /// Start a seat on an id when no task is running for it: the `/resume
    /// <old-id>` recovery a failed handoff names.
    ///
    /// A lead goes through the project wake, so a failed start surfaces the
    /// same `ConnectionFailed` and the same fallback a wake has. The id named
    /// is recorded first because that path resumes the slot's stored id; it
    /// names a transcript that already exists, so a failed start leaves a real
    /// id rather than an unrun one. A worker goes through the spawn its boot
    /// re-spawn uses, with the row's own charter, tree and family selection.
    fn resume_without_task(
        self: &Arc<Self>,
        key: &SessionSlot,
        session_id: &str,
        launch_settings: SessionLaunchSettings,
    ) -> Result<(), DispatchError> {
        if key.is_lead() {
            self.note_running_session_id(key, session_id);
            // The failure is surfaced by the frame the handler emits; this
            // recovery path has no caller to answer with it.
            let _ = crate::spawn::handle_spawn_project(self, key.project(), launch_settings);
            return Ok(());
        }
        let Some(view) = self
            .list_projects()
            .into_iter()
            .find(|view| view.org == key.org() && view.name == key.project())
        else {
            return Err(DispatchError::UnknownSession(key.clone()));
        };
        let row = match self.stored_worker_row(&view.key, key.label()) {
            Ok(Some(row)) => row,
            Ok(None) => return Err(DispatchError::UnknownSession(key.clone())),
            Err(error) => {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    event_name = "resume_worker_row_unreadable",
                    slot = %key.display(),
                    %error,
                    "the worker's row could not be read; a task-less resume needs it for the charter and tree",
                );
                return Err(DispatchError::UnknownSession(key.clone()));
            }
        };
        // **The failure this resume replaces goes first.** A failed spawn
        // leaves its entry for a worker with no worktree; it is not live, so
        // the insert below would append a second entry for the slot and the
        // by-slot reads would move the tombstone instead of the new entry.
        self.clear_failed_worker(&view.key, key.label());
        let (return_to, mut reply) = tokio::sync::oneshot::channel();
        let outcome = self.dispatch(Command::SpawnWorker {
            project_key: view.key,
            label: key.label().to_owned(),
            charter: row.charter.unwrap_or_default(),
            spawned_by: SessionSlot::lead(key.org(), key.project()),
            resume_existing: Some(session_id.to_owned()),
            // **An explicit `/resume` is the reader's own act**, so it
            // delivers the re-orient kick whatever the row says: unlike a
            // boot re-spawn or a heal, the person is asking this seat to
            // carry on.
            kick: row.resume_kick.or_else(|| Some(DYNAMIC_WORKER_RESTART_NOTE.to_owned())),
            resume_kick: None,
            interactive: row.interactive.unwrap_or(false),
            mcp_families: row.mcp_families,
            cwd: row.cwd,
            // **A user-driven restore is the row restore a boot re-spawn
            // does.** The row already holds the worker's cap slot and tree,
            // so the restore semantics fit: no cap check, and a failure kept
            // as the visible tombstone. The refusal the handler does answer
            // is surfaced below rather than dropped.
            from_boot_respawn: true,
            return_to: Some(return_to),
        });
        // The handler answers before it returns, so a restore that was
        // refused says why instead of echoing as accepted.
        if let Ok(Err(reason)) = reply.try_recv() {
            self.notice(key, NoticeSeverity::Error, &format!("the resume was refused: {reason}"));
        }
        outcome
    }

    /// Fill in the launch settings a caller did not build.
    ///
    /// A caller with its own snapshot of the documents builds them and
    /// hands them over; a client has no config to read, so a spawn it asks
    /// for arrives with none, and a spawn that ran on those alone would carry
    /// no language, no model and the CLI's own defaults for permissions,
    /// effort and output style - a session launched differently from one
    /// started with the documents in hand.
    ///
    /// Read from the workspace's own config dir, which is what a session with
    /// no account-scoped dir of its own runs under. A caller bound to an
    /// account builds its own from that account, so the two can differ where
    /// an account names a dir of its own - and where they do, the caller that
    /// supplied settings keeps them.
    fn fill_launch_settings(&self, launch_settings: &mut SessionLaunchSettings, cwd: Option<&str>) {
        if launch_settings.settings.is_some() {
            return;
        }
        let empty = || serde_json::Value::Object(serde_json::Map::new());
        let documents_cwd = cwd.filter(|cwd| !cwd.is_empty()).map(std::path::Path::new);
        let documents =
            forge_agent::userdata::settings::settings_documents(self.config_dir(), documents_cwd);
        let user = documents.user.unwrap_or_else(empty);
        let local = documents.project_local.unwrap_or_else(empty);
        let preferences = self.user_preferences().unwrap_or_else(empty);
        let built = crate::launch_settings::session_launch_settings(
            &crate::launch_settings::LaunchSettingsDocuments {
                user: &user,
                local: &local,
                preferences: &preferences,
            },
        );
        launch_settings.language = built.language;
        launch_settings.settings = built.settings;
        launch_settings.agent_progress_summaries = built.agent_progress_summaries;
    }

    /// `/effort <level>`: write the level the next launch reads.
    ///
    /// A settings write rather than a session command - the CLI carries no
    /// control request for effort - so it lands in the same document the
    /// launch builder reads and takes effect when the session next starts.
    fn set_effort(
        self: &Arc<Self>,
        key: &SessionSlot,
        level: &str,
    ) -> (Result<(), DispatchError>, Option<ForgeAnswer>) {
        let Some(level) = forge_primitives::EffortLevel::from_stored(level) else {
            return (Ok(()), Some(forge_misuse(&format!("Unknown effort level: {level}"))));
        };
        // The seat's own config dir where there is one, and the one forge runs
        // under otherwise: effort is a user-level setting, so it does not
        // depend on a session being live.
        let config_dir =
            self.config_dir_for(key).unwrap_or_else(|| self.config_dir().to_path_buf());
        let path = config_dir.join("settings.json");
        let held = forge_agent::userdata::settings::settings_documents(&config_dir, None)
            .user
            .unwrap_or_else(|| serde_json::Value::Object(serde_json::Map::new()));
        // A settings file holding something other than an object is one this
        // cannot add a key to. Writing the key alone is better than reporting
        // a success over a document nothing was added to.
        let mut document =
            if held.is_object() { held } else { serde_json::Value::Object(serde_json::Map::new()) };
        document["effortLevel"] = serde_json::Value::String(level.as_stored().to_owned());
        match forge_agent::userdata::settings::save_document(&path, &document) {
            Ok(()) => (
                Ok(()),
                Some((
                    NoticeSeverity::Info,
                    format!("Effort: {} (takes effect next session)", level.label()),
                )),
            ),
            Err(err) => (Ok(()), Some(forge_misuse(&format!("Failed to save effort: {err}")))),
        }
    }

    /// The line to answer a slash name this session cannot run, or `None`
    /// when the text is the CLI's to read.
    ///
    /// What a session can run is what its CLI advertised, or one of the names
    /// the CLI resolves without advertising ([`crate::prompt::FORWARDED`]).
    /// A session that has advertised nothing refuses nothing: an empty
    /// catalogue is not knowing, and refusing on ignorance would drop names
    /// the CLI has.
    fn unrunnable_slash_name(&self, key: &SessionSlot, text: &str) -> Option<String> {
        let name = text.split_whitespace().next()?;
        if !name.starts_with('/') {
            return None;
        }
        let advertised = self.available_commands_for(key);
        if advertised.is_empty()
            || advertised
                .iter()
                .any(|command| forge_agent::translate::commands::slash_name(&command.name) == name)
            || crate::prompt::is_forwarded_name(name)
        {
            return None;
        }
        Some(format!("{name} is not yet supported"))
    }

    /// Emit one line the core has for a view about `key`.
    pub(crate) fn notice(&self, key: &SessionSlot, severity: NoticeSeverity, text: &str) {
        let _ = self.update_sender().send(SessionUpdate::Notice {
            key: key.clone(),
            severity,
            text: text.to_owned(),
        });
    }

    /// The settings a launch on `key` carries, read from the same documents
    /// the CLI reads.
    pub(crate) fn launch_settings_for(
        &self,
        key: &SessionSlot,
        cwd: &str,
    ) -> SessionLaunchSettings {
        let empty = || serde_json::Value::Object(serde_json::Map::new());
        // An empty cwd is no cwd: joining `.claude/settings.local.json` onto
        // one would read it against the process working directory.
        let documents_cwd = (!cwd.is_empty()).then(|| std::path::Path::new(cwd));
        let documents = self.settings_documents(key, documents_cwd);
        let user =
            documents.as_ref().and_then(|documents| documents.user.clone()).unwrap_or_else(empty);
        let local = documents
            .as_ref()
            .and_then(|documents| documents.project_local.clone())
            .unwrap_or_else(empty);
        let preferences = self.user_preferences().unwrap_or_else(empty);
        crate::launch_settings::session_launch_settings(
            &crate::launch_settings::LaunchSettingsDocuments {
                user: &user,
                local: &local,
                preferences: &preferences,
            },
        )
    }

    /// Route a command that carries no frame of its own.
    pub(crate) fn route(self: &Arc<Self>, mut cmd: Command) -> Result<(), DispatchError> {
        // A spawn a caller could not complete is completed here, ahead of
        // routing: a client has no config to read, so what it sends carries no
        // settings, and a spawn that ran on those alone would carry no
        // language and the CLI's own defaults for permissions, effort and
        // output style. Ahead of the intercept below because a command is
        // finished before it is dispatched, and what a test reads there is
        // what the handler will receive.
        if let Command::SpawnProject { project_name, launch_settings } = &mut cmd {
            let cwd = self
                .find_project_view_by_name(project_name)
                .map(|project| project.path.to_string_lossy().into_owned())
                .unwrap_or_default();
            self.fill_launch_settings(launch_settings, Some(&cwd));
        }
        // Test intercept (when armed): capture EVERY Command - both
        // app-level and per-session - before any routing. Tests use
        // this to assert what would have been dispatched without
        // spinning up real subprocesses or stub SessionTasks. Always
        // a no-op in production builds without the testing feature.
        #[cfg(any(test, feature = "testing"))]
        {
            let mut intercept = self.command_intercept.lock();
            if let Some(buffer) = intercept.as_mut() {
                buffer.push(cmd);
                return Ok(());
            }
        }
        // A prompt already answered, or one that asked something else, is a
        // dock that is gone: the reader's click did nothing. The session task
        // itself just logs that, and by the time it sees the answer the caller
        // is long gone - so it is refused here, the last layer that can still
        // tell one.
        match &cmd {
            Command::RespondPermission { key, tool_id, .. } => {
                let waiting = self
                    .domain_session_for(key)
                    .is_some_and(|domain| domain.lock().awaits_permission(tool_id));
                if !waiting {
                    return Err(DispatchError::NoPromptWaiting {
                        key: key.clone(),
                        tool_id: tool_id.clone(),
                    });
                }
            }
            Command::RespondQuestion { key, tool_id, .. } => {
                let waiting = self
                    .domain_session_for(key)
                    .is_some_and(|domain| domain.lock().awaits_question(tool_id));
                if !waiting {
                    return Err(DispatchError::NoPromptWaiting {
                        key: key.clone(),
                        tool_id: tool_id.clone(),
                    });
                }
            }
            Command::RespondSlackPost { key, id, .. } => {
                let waiting = self.slack_draft_waiting(*id, key);
                if !waiting {
                    return Err(DispatchError::NoDraftWaiting { key: key.clone(), id: *id });
                }
            }
            Command::RespondBrowserHandOff { key, id, .. } => {
                let waiting = self.browser_handoff_waiting(*id, key);
                if !waiting {
                    return Err(DispatchError::NoBrowserHandOffWaiting {
                        key: key.clone(),
                        id: *id,
                    });
                }
            }
            Command::RespondTerminalHandOff { key, id, .. } => {
                let waiting = self.terminal_handoff_waiting(*id, key);
                if !waiting {
                    return Err(DispatchError::NoTerminalHandOffWaiting {
                        key: key.clone(),
                        id: *id,
                    });
                }
            }
            Command::AnswerDocumentHandOff { key, id, .. } => {
                let waiting = self.document_handoff_waiting(*id, key);
                if !waiting {
                    return Err(DispatchError::NoDocumentHandOffWaiting {
                        key: key.clone(),
                        id: *id,
                    });
                }
            }
            Command::RespondSettingsWrite { key, id, .. } => {
                let waiting = self.settings_write_waiting(*id, key);
                if !waiting {
                    return Err(DispatchError::NoSettingsWriteWaiting {
                        key: key.clone(),
                        id: *id,
                    });
                }
            }
            Command::RespondVaultAsk { key, id, .. } => {
                let waiting = self.vault_ask_waiting(*id, key);
                if !waiting {
                    return Err(DispatchError::NoVaultAskWaiting { key: key.clone(), id: *id });
                }
            }
            _ => {}
        }
        if let Some(key) = cmd.key() {
            // The /dictate override edits are workspace state on the
            // DomainSession, never agent traffic: apply inline and
            // echo, ahead of the SessionTask routing below.
            match cmd {
                Command::SetDictateOverride { key, update } => {
                    return self.apply_dictate_override(&key, update);
                }
                Command::ResetDictateOverrides { key } => {
                    return self.apply_dictate_override(
                        &key,
                        crate::dictate::DictateOverrideUpdate::Reset,
                    );
                }
                // The seat's voice state: workspace state, never agent
                // traffic, so it does not ride the session task.
                Command::VoiceMode { key, on, explicit, initiator } => {
                    let client = initiator.unwrap_or(0);
                    let voice = self.voice_service();
                    if voice.enabled() {
                        voice.set_listening(&key, client, on, explicit);
                    }
                    let listeners = u32::try_from(voice.listeners(&key)).unwrap_or(u32::MAX);
                    let _ =
                        self.update_sender().send(SessionUpdate::VoiceModeState { key, listeners });
                    return Ok(());
                }
                // The refusals a page acts on are answered here, and the
                // render itself rides the seat's queue rather than holding
                // this dispatch for a model load.
                Command::VoicePreview { key, voice } => {
                    let service = self.voice_service();
                    if !service.enabled() {
                        return Err(crate::DispatchError::VoiceOff {
                            reason: "[tts] enabled is false".to_owned(),
                        });
                    }
                    if service.listeners(&key) == 0 {
                        return Err(crate::DispatchError::VoiceOff {
                            reason: "that seat's speaker switch is off".to_owned(),
                        });
                    }
                    let Some(files) = self.speaking_files() else {
                        return Err(crate::DispatchError::VoiceOff {
                            reason: "the speaking model is not installed".to_owned(),
                        });
                    };
                    let installed = files.installed_voices().map_err(|error| {
                        crate::DispatchError::VoiceOff { reason: error.to_string() }
                    })?;
                    forge_tts::select_voice(Some(&voice), &installed).map_err(|error| {
                        crate::DispatchError::VoiceOff { reason: error.to_string() }
                    })?;
                    // A failure the client is still drawing is cleared here, and
                    // the read pushed: an accepted press is the promise the old
                    // error no longer stands, whatever this render does.
                    if self.voice_preview_error.lock().is_ok_and(|mut slot| slot.take().is_some()) {
                        self.push_models();
                    }
                    let this = Arc::clone(self);
                    tokio::spawn(async move {
                        if let Err(error) = service.preview(&key, voice).await {
                            tracing::warn!(
                                event_name = "voice_preview_failed",
                                slot = %key.display(),
                                %error,
                                "the voice preview did not render"
                            );
                            if let Ok(mut slot) = this.voice_preview_error.lock() {
                                *slot = Some(error.to_string());
                            }
                            this.push_models();
                        }
                    });
                    return Ok(());
                }
                _ => {}
            }
            let key = key.clone();
            // **A hand-off parked by the outgoing occupant cannot outlive
            // it.** `/new` and `/resume` replace the session that is waiting,
            // and a park left behind would blind the new occupant's first
            // terminal call with an ask nobody owns.
            if matches!(&cmd, Command::NewSession { .. } | Command::ResumeSession { .. }) {
                self.abandon_terminal_hand_offs(&key);
            }
            // /new and /resume re-spawn on the already-pooled handle, where
            // get_agent_handle_at_key's stamp never runs.
            let resuming = matches!(&cmd, Command::ResumeSession { .. });
            if let Command::NewSession { launch_settings, .. }
            | Command::ResumeSession { launch_settings, .. } = &mut cmd
            {
                let pooled = self
                    .pool
                    .lock()
                    .get(&key)
                    .map(|p| (p.permission_mode, p.registration.clone(), p.account.clone()));
                match pooled {
                    // A resume on a seat whose task has gone has no pooled
                    // handle by design; the wake's own spawn stamps it. The
                    // warning is for a live seat caught between teardown and
                    // release.
                    None if resuming => tracing::debug!(
                        target: "forge_workspace::workspace",
                        event_name = "resume_without_pool_entry",
                        slot = %key.display(),
                        "a task-less resume has no pooled handle to stamp; the wake's spawn stamps itself",
                    ),
                    None => tracing::warn!(
                        target: "forge_workspace::workspace",
                        slot = %key.display(),
                        "permission_mode stamp skipped: respawn routed but no pool entry \
                         (release_session teardown window)",
                    ),
                    Some((mode, registration, account)) => {
                        // The respawned CLI runs the project's model too:
                        // this path bypasses the spawn-time stamp.
                        let config = self.config_arc();
                        let project = registration.as_ref().and_then(|registration| {
                            config
                                .projects
                                .iter()
                                .find(|project| project.name == registration.project)
                        });
                        apply_project_model(project, launch_settings);
                        if let Some(mode) = mode {
                            spawn::stamp_permission_mode(launch_settings, mode);
                        } else {
                            tracing::debug!(
                                target: "forge_workspace::workspace",
                                slot = %key.display(),
                                account = %account.0,
                                "respawn keeps the launcher default: no project resolved for \
                                 this session, so there is no permission mode to stamp",
                            );
                        }
                    }
                }
            }
            let senders = self.command_senders.lock();
            if let Some(sender) = senders.get(&key) {
                // Stamp turn_pending only on the routed path (set + route
                // together) so the in-flight guards can't race a Prompt
                // whose wire-lagged `Running` echo hasn't landed yet. The
                // committed turn also spends the previous turn's failure
                // mark: the newest turn is this one now.
                let mut committed = false;
                if matches!(cmd, Command::Prompt { .. } | Command::PromptUnder { .. })
                    && let Some(domain) = self.domain_session_for(&key)
                {
                    let mut guard = domain.lock();
                    // A prompt committed with no turn in flight starts a new
                    // one, and a cancel stamp the last turn left armed expires
                    // here: nothing would spend it, and left standing it would
                    // exempt this turn's genuine failure. A prompt that only
                    // queues behind a busy turn keeps the stamp - that turn
                    // is still the one it was armed for, and its error Result
                    // still has to read as the reader's own cancel.
                    //
                    // The nudge is the running turn's for the same reason:
                    // a queued prompt is not the turn that will fail next.
                    //
                    // The failure mark is the run's too. A committed prompt
                    // spends it because the newest turn is then this one; a
                    // prompt that only queues has committed nothing, and
                    // clearing the mark there leaves a failure nobody has
                    // seen drawing no rail mark.
                    if !guard.turn_in_flight() {
                        guard.pending_cancel = false;
                        guard.auto_continue = None;
                        guard.failed_turn_at = None;
                    }
                    committed = guard.commit_turn();
                }
                // **The turn starts here, before the CLI hears of it.** A
                // boot that finds the row mid-turn hands the seat the
                // restart note, so the write is the spawn's turn marker and
                // not the CLI's echo: a crash between this send and the
                // Result leaves the interrupted turn on the row.
                if committed {
                    self.record_seat_state(&key, crate::store::sessions::SeatState::InTurn);
                }
                // A prompt the reader's own hands sent moves the seat on: a
                // death trace still standing is taken with it, whether the
                // prompt commits a turn or queues behind one - it is the
                // reader looking, not the turn. A cron's, a peer's or
                // forge's own prompt is not, so none of those spends it.
                if let Command::PromptUnder { source: crate::protocol::PromptSource::You, .. } =
                    &cmd
                {
                    self.spend_death(&key);
                }
                // Arm the cancel stamp on the routed path, so the turn's
                // own failed `Result` can tell a reader's interrupt from a
                // genuine error. An idle Cancel arms nothing.
                if matches!(cmd, Command::Cancel { .. })
                    && let Some(domain) = self.domain_session_for(&key)
                {
                    let mut guard = domain.lock();
                    if guard.turn_in_flight() {
                        guard.pending_cancel = true;
                    }
                }
                // **A send that never reached the task spends the turn it
                // just committed.** No Result is coming for a prompt the task
                // never saw, so leaving `turn_pending` set draws a turn in
                // flight on the header that nothing can close.
                if let Err(unsent) = sender.send(cmd) {
                    let _ = unsent;
                    if committed {
                        if let Some(domain) = self.domain_session_for(&key) {
                            domain.lock().uncommit_turn();
                        }
                        // No turn is running for a prompt the task never
                        // saw, so the row must not say one is.
                        self.record_seat_state(&key, crate::store::sessions::SeatState::Idle);
                    }
                    return Err(DispatchError::SessionClosed(key));
                }
                return Ok(());
            }
            drop(senders);
            // **`/resume` on a seat whose task has exited is the recovery
            // the handoff promises.** The task leaves with its child, so the
            // command lands here with no sender; start the seat on the id it
            // names rather than answering `UnknownSession`. A failed start
            // still surfaces as `ConnectionFailed`, and the project wake
            // remains the fallback beside it.
            // A test that wired a stub handle expects the synchronous fallback
            // below to take the command; only a genuinely ownerless seat goes
            // through the wake.
            let stub_fallback_can_take_it =
                cfg!(any(test, feature = "testing")) && self.agent_handle_for(&key).is_some();
            if !stub_fallback_can_take_it
                && let Command::ResumeSession { key, session_id, launch_settings, .. } = &cmd
            {
                return self.resume_without_task(key, session_id, launch_settings.clone());
            }
            // In production this branch returns `UnknownSession`: a
            // per-session `Command` arrives before a `SessionTask`
            // exists, which is the contract violation the error
            // signals. Under `cfg(any(test, feature = "testing"))`,
            // tests that wire a stub `AgentHandle` directly onto a
            // `DomainSession` (without a running tokio runtime to host
            // a real `SessionTask`) get a synchronous fallback so the
            // command still reaches the stub. Gating this here means
            // the fallback is structurally unreachable in production -
            // a future refactor can't open the race window silently.
            #[cfg(any(test, feature = "testing"))]
            {
                let Some(handle) = self.agent_handle_for(&key) else {
                    return Err(DispatchError::UnknownSession(key));
                };
                let sid = self.domain_handles.lock().get(&key).and_then(|d| {
                    d.lock().session_id.as_ref().map(std::string::ToString::to_string)
                });
                let fresh = match &cmd {
                    Command::NewSession { session_id: Some(id), .. } => Some(id.clone()),
                    Command::NewSession { session_id: None, .. } => {
                        Some(self.fresh_session_id_for(&key))
                    }
                    _ => None,
                };
                // A respawn moves the id the child runs under, so its
                // gateway binding moves with it. The routed path stamps
                // in the `SessionTask`, where `/new`'s id is minted;
                // this fallback holds the same id here, so it stamps the
                // same way rather than leaving the child on the previous
                // occupant's segment.
                let respawn_id = match &cmd {
                    Command::NewSession { .. } => fresh.clone(),
                    Command::ResumeSession { session_id, .. } => Some(session_id.clone()),
                    _ => None,
                };
                if let Some(respawn_id) = respawn_id.as_deref()
                    && let Command::NewSession { launch_settings, .. }
                    | Command::ResumeSession { launch_settings, .. } = &mut cmd
                {
                    self.stamp_respawn_overrides(&key, respawn_id, launch_settings);
                }
                crate::session_task::execute_command_via_handle(
                    &handle,
                    &key,
                    sid.as_deref(),
                    fresh,
                    cmd,
                )
                .map_err(|_| DispatchError::SessionClosed(key))
            }
            #[cfg(not(any(test, feature = "testing")))]
            {
                let _ = cmd;
                Err(DispatchError::UnknownSession(key))
            }
        } else {
            // App-level commands. The `spawn::*` handlers are sync -
            // they emit one event, kick off `get_agent_handle_at_key`
            // (which internally tokio::spawns the agent), and return.
            // Run them inline under the span; no detach needed.
            match cmd {
                Command::SpawnProject { project_name, launch_settings } => {
                    let span = tracing::info_span!(
                        "spawn_project",
                        project = %project_name,
                    );
                    let _enter = span.enter();
                    // A command has no caller to answer: the failure reaches
                    // the views through the frame the handler emits.
                    let _ = spawn::handle_spawn_project(self, &project_name, launch_settings);
                }
                Command::DeliverPeerPrompt { caller, target_project, wrapped, respond } => {
                    let span = tracing::info_span!(
                        "deliver_peer_prompt",
                        target = %target_project,
                        message_id = %wrapped.id,
                    );
                    let _enter = span.enter();
                    let outcome =
                        spawn::handle_deliver_peer_prompt(self, &caller, target_project, wrapped);
                    // The answer is the handler's own, handed back to
                    // whoever awaited the dispatch: a caller that got no
                    // answer must not read one into the silence.
                    if let Some(respond) = respond {
                        let _ = respond.send(outcome);
                    }
                }
                Command::SpawnWorker {
                    project_key,
                    label,
                    charter,
                    spawned_by,
                    resume_existing,
                    kick,
                    resume_kick,
                    interactive,
                    mcp_families,
                    cwd,
                    from_boot_respawn,
                    return_to,
                } => {
                    let span = tracing::info_span!(
                        "spawn_worker",
                        project = %project_key.as_str(),
                        label = %label,
                        resume = resume_existing.is_some(),
                        interactive,
                    );
                    let _enter = span.enter();
                    spawn::handle_spawn_worker(
                        self,
                        project_key,
                        spawn::WorkerSpawnArgs {
                            label,
                            charter,
                            kick,
                            resume_kick,
                            interactive,
                            mcp_families,
                            cwd,
                        },
                        spawned_by,
                        resume_existing.as_deref(),
                        from_boot_respawn,
                        return_to.unwrap_or_else(crate::protocol::unanswerable),
                    );
                }
                Command::CloseWorker { project_key, label } => {
                    let span = tracing::info_span!(
                        "close_worker",
                        project = %project_key.as_str(),
                        label = %label,
                    );
                    let _enter = span.enter();
                    spawn::handle_close_worker(self, &project_key, &label);
                }
                Command::DespawnWorker { project_key, label, force, respond } => {
                    let span = tracing::info_span!(
                        "despawn_worker",
                        project = %project_key.as_str(),
                        label = %label,
                        force,
                    );
                    let _enter = span.enter();
                    spawn::handle_despawn_worker(
                        self,
                        &project_key,
                        &label,
                        force,
                        respond.unwrap_or_else(crate::protocol::unanswerable),
                    );
                }
                Command::DeliverWorkerPrompt {
                    caller,
                    project_key,
                    target_label,
                    wrapped,
                    respond,
                } => {
                    let span = tracing::info_span!(
                        "deliver_worker_prompt",
                        project = %project_key.as_str(),
                        label = %target_label,
                        message_id = %wrapped.id,
                    );
                    let _enter = span.enter();
                    spawn::handle_deliver_worker_prompt(
                        self,
                        &caller,
                        &project_key,
                        &target_label,
                        wrapped,
                        respond,
                    );
                }
                Command::DeliverWorkerPromptToLead {
                    caller,
                    target_lead_key,
                    wrapped,
                    respond,
                } => {
                    let span = tracing::info_span!(
                        "deliver_worker_prompt_to_lead",
                        slot = %target_lead_key.display(),
                        message_id = %wrapped.id,
                    );
                    let _enter = span.enter();
                    spawn::handle_deliver_worker_prompt_to_lead(
                        self,
                        &caller,
                        &target_lead_key,
                        wrapped,
                        respond,
                    );
                }
                Command::DeliverGotifyMessage { project, team_role, notification } => {
                    let span = tracing::info_span!(
                        "deliver_gotify_message",
                        project = %project,
                        app = %notification.app,
                        priority = notification.priority,
                    );
                    let _enter = span.enter();
                    spawn::deliver_gotify_message(
                        self,
                        &project,
                        team_role.as_deref(),
                        notification,
                    );
                }
                Command::RespondSlackPost { key, id, answer } => {
                    // A send-back with no words is not an answer: it would
                    // drop the reader's card and hand the agent nothing. The
                    // draft stays waiting so the field can be sent again.
                    if let forge_primitives::slack::SlackDraftAnswer::SendBack { note } = &answer
                        && note.trim().is_empty()
                    {
                        return Err(DispatchError::EmptySlackFeedback { key: key.clone(), id });
                    }
                    // The guard above already refused a draft this one is not
                    // waiting for, so a `false` here is a resolve that landed
                    // between the two: the same refusal, not a silent drop.
                    let answered = self.resolve_slack_draft(
                        id,
                        &key,
                        crate::slack::DraftResolution::Answered(answer),
                    );
                    if !answered {
                        return Err(DispatchError::NoDraftWaiting { key: key.clone(), id });
                    }
                }
                Command::RespondBrowserHandOff { key, id, answer } => {
                    // Same shape as the Slack arm above: the guard already
                    // refused one that is not waiting, so a `false` here is a
                    // resolve that landed between the two.
                    // **The answer names its own hand**: the ending, the door
                    // that sent it and the connection it came over, so a
                    // hand-off never resolves with nothing attributable
                    // behind it (2026-10-07, 2026-10-26).
                    tracing::debug!(
                        event_name = "browser_hand_off_answered",
                        key = ?key,
                        id = %id,
                        ending = ?answer.ending,
                        source = ?answer.source,
                        client = answer.client,
                        "a client answered a parked browser hand-off"
                    );
                    let answered = self.resolve_browser_hand_off(id, &key, answer);
                    if !answered {
                        return Err(DispatchError::NoBrowserHandOffWaiting {
                            key: key.clone(),
                            id,
                        });
                    }
                }
                Command::RespondTerminalHandOff { key, id, answer } => {
                    // Same shape as the browser arm above: the guard already
                    // refused one that is not waiting, and the answer names
                    // its own hand.
                    tracing::debug!(
                        event_name = "terminal_hand_off_answered",
                        key = ?key,
                        id = %id,
                        ending = ?answer.ending,
                        source = ?answer.source,
                        client = answer.client,
                        "a client answered a parked terminal hand-off"
                    );
                    let answered = self.resolve_terminal_hand_off(id, &key, answer);
                    if !answered {
                        return Err(DispatchError::NoTerminalHandOffWaiting {
                            key: key.clone(),
                            id,
                        });
                    }
                }
                Command::AnswerDocumentHandOff { key, id, answer } => {
                    // Same shape as the browser arm above: the guard already
                    // refused one that is not waiting, so a `false` here is a
                    // resolve that landed between the two.
                    tracing::debug!(
                        event_name = "document_hand_off_answered",
                        key = ?key,
                        id = %id,
                        ?answer,
                        "a client answered a parked document hand-off"
                    );
                    let answered = self.resolve_document_hand_off(id, &key, answer);
                    if !answered {
                        return Err(DispatchError::NoDocumentHandOffWaiting {
                            key: key.clone(),
                            id,
                        });
                    }
                }
                Command::RespondSettingsWrite { key, id, approved } => {
                    // Same shape as the two arms above: the guard already
                    // refused one that is not waiting, so a `false` here is a
                    // resolve that landed between the two.
                    let answered = self.resolve_settings_write(id, &key, approved);
                    if !answered {
                        return Err(DispatchError::NoSettingsWriteWaiting { key: key.clone(), id });
                    }
                }
                Command::RespondVaultAsk { key, id, answer } => {
                    let answered = self.resolve_vault_ask(id, &key, answer);
                    if !answered {
                        return Err(DispatchError::NoVaultAskWaiting { key: key.clone(), id });
                    }
                }
                Command::DictateCatalogueCheck => {
                    return self.check_dictate_catalogue();
                }
                Command::PluginInstall { plugin_id, scope, project } => {
                    return self.start_plugin_install(plugin_id, scope, project.as_deref());
                }
                Command::PluginUpdate { plugin_id, scope } => {
                    return self.start_plugin_update(plugin_id, scope);
                }
                Command::PluginUpdateAll => {
                    return self.start_plugin_update_all();
                }
                Command::PluginCheckUpdates => {
                    return self.start_plugin_check();
                }
                Command::MarketplaceAdd { source, dispatch_id } => {
                    return self.start_marketplace_add(source, dispatch_id);
                }
                Command::MarketplaceRepair { name } => {
                    return self.start_marketplace_repair(name);
                }
                Command::DictateInstall { variant } => {
                    return self.start_install(variant);
                }
                Command::DictateActivate { role, file } => {
                    return self.start_activate(role, file);
                }
                Command::DictateDeactivate { role } => {
                    return self.start_deactivate(role);
                }
                Command::DictateBench { target, tier } => {
                    return self.start_bench(target, tier);
                }
                Command::DictateBenchStop => {
                    return self.stop_bench();
                }
                Command::VoiceBenchStart => {
                    let outcome = self.start_speaking_bench();
                    self.push_models();
                    return outcome;
                }
                Command::VoiceBenchStop => {
                    let outcome = self.stop_speaking_bench();
                    self.push_models();
                    return outcome;
                }
                Command::DictateReadAloudStart { initiator } => {
                    let outcome = self.start_read_aloud(initiator);
                    self.push_models();
                    return outcome;
                }
                Command::DictateReadAloudStop { keep, initiator } => {
                    let outcome = self.finish_read_aloud(keep, initiator);
                    self.push_models();
                    return outcome;
                }
                Command::DictateReadAloudDelete { id } => {
                    let outcome = self.delete_read_aloud(&id);
                    self.push_models();
                    return outcome;
                }
                Command::DictateUninstall { file } => {
                    let outcome = self.uninstall_model(&file);
                    self.push_models();
                    return outcome;
                }
                Command::DictateBenchDelete { target, tier, corpus } => {
                    let outcome = self.delete_bench_result(&target, tier, &corpus);
                    self.push_models();
                    return outcome;
                }
                Command::DictateStream { key, options, surface, initiator } => {
                    let updates = self.update_sender();
                    // Registered HERE, inline, rather than on a spawned
                    // task: the connection this arrived on is ordered, so
                    // the audio frame a client sends next must find the
                    // take. Nothing on this path opens a device, so there
                    // is nothing to take off the runtime thread. The test
                    // `a_stream_take_registers_synchronously_and_keeps_its_frames`
                    // fails the moment this moves onto one.
                    match crate::dictate::register_stream_take(
                        self,
                        &key,
                        options,
                        surface.clone(),
                        initiator,
                    ) {
                        Ok(take) => {
                            let _ = updates.send(SessionUpdate::DictateStarted {
                                key: key.clone(),
                                floor_db: take.floor_db,
                                generation: take.generation,
                                initiator,
                            });
                            tokio::spawn(crate::dictate::run_stream_take(
                                Arc::clone(self),
                                key,
                                take,
                                updates,
                            ));
                        }
                        Err(message) => {
                            // The start refused, so any park the press's
                            // release left behind answers a take that will
                            // never exist.
                            self.dictate_runtime.lock().clear_stop_pending(&key, initiator);
                            let _ = updates.send(SessionUpdate::DictateEnded {
                                key,
                                outcome: crate::protocol::DictateOutcome::Refused { message },
                                generation: 0,
                                surface,
                                initiator,
                            });
                        }
                    }
                }
                Command::DictateStop { key, submit, initiator } => {
                    let ws = Arc::clone(self);
                    tokio::spawn(async move {
                        crate::dictate::handle_dictate_stop(&ws, &key, submit, initiator).await;
                    });
                }
                // User-action store writes routed through the command
                // bus. Synchronous inline handlers - the writes are
                // local redb operations, and the view has already
                // applied its optimistic state.
                Command::SetReviewThreadStatus { project, branch, thread_id, status } => {
                    let span = tracing::info_span!(
                        "set_review_thread_status",
                        project = %project,
                        branch = %branch,
                        thread_id = %thread_id,
                        status = ?status,
                    );
                    let _enter = span.enter();
                    self.set_review_thread_status(&project, &branch, &thread_id, status);
                }
                Command::CloseSession { session_key } => {
                    let span = tracing::info_span!(
                        "close_session",
                        slot = %session_key.display(),
                    );
                    let _enter = span.enter();
                    self.release_session_with_cascade(&session_key);
                }
                Command::UpsertReviewThread {
                    project,
                    branch,
                    thread,
                    origin: _,
                    sent_words: _,
                    respond,
                } => {
                    let span = tracing::info_span!(
                        "upsert_review_thread",
                        project = %project,
                        branch = %branch,
                        thread_id = %thread.id,
                    );
                    let _enter = span.enter();
                    if let Some(respond) = respond {
                        let _ = respond.send(self.upsert_review_thread(&project, &branch, thread));
                    }
                }
                Command::DeleteReviewThread { project, branch, thread_id, respond } => {
                    let span = tracing::info_span!(
                        "delete_review_thread",
                        project = %project,
                        branch = %branch,
                        thread_id = %thread_id,
                    );
                    let _enter = span.enter();
                    if let Some(respond) = respond {
                        let _ =
                            respond.send(self.delete_review_thread(&project, &branch, &thread_id));
                    }
                }
                Command::SubmitReview { project, branch, summary, thread_ids, origin, respond } => {
                    let span = tracing::info_span!(
                        "submit_review",
                        project = %project,
                        branch = %branch,
                        threads = thread_ids.len(),
                    );
                    let _enter = span.enter();
                    if let Some(respond) = respond {
                        let _ = respond.send(self.submit_review(
                            &project,
                            &branch,
                            summary,
                            &thread_ids,
                            origin,
                        ));
                    }
                }
                // The board's edits are the user's own moves: stamped
                // `By::User` in the history, and no session routes them -
                // the board is the user's surface, and each carries its
                // project.
                Command::TaskVerdict { project, id, approve, words } => {
                    let id = TaskId::from(id.as_str());
                    let moved = if approve {
                        self.approve_task(&project, &id)
                    } else {
                        self.send_back_task(&project, &id, words.as_deref().unwrap_or(""))
                    };
                    match moved {
                        Ok(Some(task)) => {
                            // A send-back is news its owner wants, with the
                            // user's words in it; an approval ends the row
                            // and has nothing to resume. The notice goes to a
                            // live owner and nowhere else - the
                            // owner-and-liveness check, without the chase's
                            // fallback to the lead.
                            if !approve {
                                let back = words.as_deref().unwrap_or("");
                                self.tell_row_owner(
                                    &task,
                                    if back.is_empty() {
                                        format!(
                                            "task board: \"{}\" came back from the user's look \
                                             with no words - resume it.",
                                            task.subject,
                                        )
                                    } else {
                                        format!(
                                            "task board: \"{}\" came back from the user's look: \
                                             \"{back}\" - resume it.",
                                            task.subject,
                                        )
                                    },
                                );
                            }
                        }
                        Ok(None) => {
                            tracing::debug!(
                                target: "forge_workspace",
                                project = %project,
                                id = %id.as_str(),
                                "a user verdict named a row that is not there",
                            );
                            self.board_edit_refused(
                                "a verdict",
                                "the row it named is no longer there",
                            );
                        }
                        Err(refused) => {
                            tracing::debug!(
                                target: "forge_workspace",
                                project = %project,
                                id = %id.as_str(),
                                refusal = %refused,
                                "a user verdict was refused",
                            );
                            self.board_edit_refused("a verdict", &refused.to_string());
                        }
                    }
                }
                Command::TaskAnswer { project, id, words } => {
                    let id = TaskId::from(id.as_str());
                    match self.answer_task(&project, &id, &words) {
                        Ok(Some(task)) => {
                            // The words ride the notice: the owner should read
                            // what the user said where it is told to resume,
                            // not go looking for it.
                            self.tell_row_owner(
                                &task,
                                if words.is_empty() {
                                    format!(
                                        "task board: the user answered \"{}\" with no words - \
                                         resume it.",
                                        task.subject,
                                    )
                                } else {
                                    format!(
                                        "task board: the user answered \"{}\": \"{}\" - resume it.",
                                        task.subject, words,
                                    )
                                },
                            );
                        }
                        Ok(None) => {
                            tracing::debug!(
                                target: "forge_workspace",
                                project = %project,
                                id = %id.as_str(),
                                "a user answer named a row that is not there",
                            );
                            self.board_edit_refused(
                                "an answer",
                                "the row it named is no longer there",
                            );
                        }
                        Err(refused) => {
                            tracing::debug!(
                                target: "forge_workspace",
                                project = %project,
                                id = %id.as_str(),
                                refusal = %refused,
                                "a user answer was refused",
                            );
                            self.board_edit_refused("an answer", &refused.to_string());
                        }
                    }
                }
                Command::TaskRank { project, id, to } => {
                    match self.rank_task(&project, &TaskId::from(id.as_str()), to) {
                        // A drag that lands the row back where it started is
                        // not an edit: the queue is unchanged, and a notice
                        // would be a turn spent on nothing.
                        Ok(Some((task, true))) => {
                            self.tell_row_owner(
                                &task,
                                format!(
                                    "task board: the user re-ordered \"{}\" in its queue.",
                                    task.subject,
                                ),
                            );
                        }
                        Ok(Some((_, false))) => {}
                        Ok(None) => {
                            tracing::debug!(
                                target: "forge_workspace::tasks",
                                project = %project,
                                id = %id.as_str(),
                                "a board re-order named a row that is not there",
                            );
                            self.board_edit_refused(
                                "a re-order",
                                "the row it named is no longer there",
                            );
                        }
                        Err(refused) => {
                            tracing::debug!(
                                target: "forge_workspace::tasks",
                                project = %project,
                                id = %id.as_str(),
                                refusal = %refused,
                                "a board re-order was refused",
                            );
                            self.board_edit_refused("a re-order", &refused.to_string());
                        }
                    }
                }
                Command::TaskMove { project, id, to, place } => {
                    match self.user_move_task(&project, &TaskId::from(id.as_str()), to) {
                        // The landed status, not the asked one: a drag into
                        // `completed` on a verify=user row lands in waiting,
                        // and the notice must name the lane the board shows.
                        Ok(Some(task)) => {
                            // A drag carries where it landed: the row keeps
                            // the place the reader chose. A place that does
                            // not apply is LOGGED, not said on the board's
                            // line - the move itself landed, and a refusal
                            // would report the whole edit as failed.
                            if let Some(place) = place {
                                match self.rank_task(&project, &TaskId::from(id.as_str()), place) {
                                    Ok(Some(_)) => {}
                                    Ok(None) => {
                                        tracing::debug!(
                                            target: "forge_workspace::tasks",
                                            project = %project,
                                            id = %id.as_str(),
                                            "a drop's place named a row that is not there; the move landed without it",
                                        );
                                    }
                                    Err(refused) => {
                                        tracing::debug!(
                                            target: "forge_workspace::tasks",
                                            project = %project,
                                            id = %id.as_str(),
                                            refusal = %refused,
                                            "a drop's place was refused; the move landed without it",
                                        );
                                    }
                                }
                            }
                            self.tell_row_owner(
                                &task,
                                format!(
                                    "task board: the user moved \"{}\" to {}.",
                                    task.subject,
                                    Self::lane_words(task.status),
                                ),
                            );
                        }
                        Ok(None) => {
                            tracing::debug!(
                                target: "forge_workspace::tasks",
                                project = %project,
                                id = %id.as_str(),
                                "a board move named a row that is not there",
                            );
                            self.board_edit_refused(
                                "a move",
                                "the row it named is no longer there",
                            );
                        }
                        Err(refused) => {
                            tracing::debug!(
                                target: "forge_workspace::tasks",
                                project = %project,
                                id = %id.as_str(),
                                refusal = %refused,
                                "a board move was refused",
                            );
                            self.board_edit_refused("a move", &refused.to_string());
                        }
                    }
                }
                Command::TaskReopen { project, id } => {
                    let id = TaskId::from(id.as_str());
                    match self.reopen_task(&project, &id) {
                        Ok(Some(task)) => {
                            self.tell_row_owner(
                                &task,
                                format!(
                                    "task board: the user reopened \"{}\" - the look is owed \
                                     again; when it completes it parks on the user for the \
                                     new look.",
                                    task.subject,
                                ),
                            );
                        }
                        Ok(None) => self
                            .board_edit_refused("a reopen", "the row it named is no longer there"),
                        Err(refused) => {
                            tracing::debug!(
                                target: "forge_workspace::tasks",
                                project = %project,
                                id = %id.as_str(),
                                refusal = %refused,
                                "a reopen was refused",
                            );
                            self.board_edit_refused("a reopen", &refused.to_string());
                        }
                    }
                }
                Command::TaskReserve { project, id, reserved } => {
                    let id = TaskId::from(id.as_str());
                    match self.reserve_task(&project, &id, reserved) {
                        Ok(Some(_)) => {}
                        Ok(None) => self.board_edit_refused(
                            "a reservation",
                            "the row it named is no longer there",
                        ),
                        Err(refused) => {
                            self.board_edit_refused("a reservation", &refused.to_string());
                        }
                    }
                }
                Command::TaskAssign { project, id, owner } => {
                    // A project this forge does not carry has no seat to name
                    // and no row to hold: an assignment to it is refused
                    // rather than written against an invented empty-org slot.
                    let config = self.config_arc();
                    if let Some(row) = config.projects.iter().find(|p| p.name == project) {
                        let owner_slot =
                            owner.map(|label| SessionSlot::new(&row.org, &project, label.clone()));
                        match self.assign_task(&project, &TaskId::from(id.as_str()), owner_slot) {
                            // Both ends of a hand-over hear it, and neither
                            // does when the owner did not actually change.
                            Ok(Some((task, prior))) if prior != task.owner => {
                                if let Some(old) = prior
                                    && self.seat_is_live(&old)
                                {
                                    let _ = self.dispatch_forged_prompt(
                                        &old,
                                        format!(
                                            "task board: the user took \"{}\" from you.",
                                            task.subject,
                                        ),
                                    );
                                }
                                self.tell_row_owner(
                                    &task,
                                    format!(
                                        "task board: the user gave \"{}\" to you.",
                                        task.subject,
                                    ),
                                );
                            }
                            Ok(Some(_)) => {}
                            Ok(None) => {
                                tracing::debug!(
                                    target: "forge_workspace::tasks",
                                    project = %project,
                                    id = %id.as_str(),
                                    "a board assignment named a row that is not there",
                                );
                                self.board_edit_refused(
                                    "an assignment",
                                    "the row it named is no longer there",
                                );
                            }
                            Err(refused) => {
                                tracing::debug!(
                                    target: "forge_workspace::tasks",
                                    project = %project,
                                    id = %id.as_str(),
                                    refusal = %refused,
                                    "a board assignment was refused",
                                );
                                self.board_edit_refused("an assignment", &refused.to_string());
                            }
                        }
                    } else {
                        self.board_edit_refused("an assignment", "no project carries that name");
                    }
                }
                Command::TaskCreate { project, subject, parent } => {
                    let now = std::time::SystemTime::now();
                    let task = forge_primitives::tasks::Task {
                        id: TaskId::from(uuid::Uuid::new_v4().to_string()),
                        project_name: project.clone(),
                        subject,
                        active_form: None,
                        detail: None,
                        status: forge_primitives::tasks::TaskStatus::Pending,
                        owner: None,
                        parent: parent.map(|id| TaskId::from(id.as_str())),
                        waiting_on: None,
                        estimate: None,
                        rank: None,
                        verify: None,
                        attested: None,
                        reserved: None,
                        links: Vec::new(),
                        attempt: 0,
                        archived_at: None,
                        created_at: now,
                        updated_at: now,
                    };
                    self.push_task(task);
                }
                Command::BiometricEnrol { enrolment, device, purpose, blob, respond } => {
                    // The write's own answer rides the reply: `false` is what
                    // a rotation rewrite turns into a lock (decision 15), and
                    // a refusal is a dispatch error so the two cannot be
                    // mistaken for each other.
                    self.enrol_biometric(enrolment, &device, &purpose, &blob)
                        .map_err(|reason| DispatchError::BiometricRefused { reason })?;
                    if let Some(respond) = respond {
                        let _ = respond.send(true);
                    }
                }
                Command::BiometricRewrite { enrolment, purpose, blob, respond } => {
                    // **Update-only**: an unknown id or purpose answers
                    // `false`, which the rotation turns into a lock rather
                    // than letting a revoked device re-register itself.
                    let replaced = self
                        .rewrite_biometric(enrolment, &purpose, &blob)
                        .map_err(|reason| DispatchError::BiometricRefused { reason })?;
                    if let Some(respond) = respond {
                        let _ = respond.send(replaced);
                    }
                }
                Command::BiometricRelease { enrolment, purpose, respond } => {
                    // The wait the transport answered: a store failure is a
                    // dispatch refusal, so it surfaces as a refusal rather
                    // than as `null` - the answer that means "not enrolled"
                    // and sends the client to its password.
                    let answer = self
                        .release_biometric(enrolment, &purpose)
                        .map_err(|reason| DispatchError::BiometricRefused { reason })?;
                    if let Some(respond) = respond {
                        let _ = respond.send(answer);
                    }
                }
                Command::BiometricRevoke { enrolment, purpose } => {
                    self.revoke_biometric(enrolment, purpose.as_deref())
                        .map_err(|reason| DispatchError::BiometricRefused { reason })?;
                }
                // The shared vault's lock is workspace state, never agent
                // traffic; the press is answered by the re-stamped cards and
                // the settings card's next read.
                Command::VaultLock => {
                    self.lock_vault();
                }
                Command::VaultEnrolmentMaterial { respond } => {
                    // The material rides the reply alone: a locked session
                    // answers `null`, which is the state a device cannot
                    // enrol from.
                    let material = self.vault_enrolment_material();
                    if let Some(respond) = respond {
                        let _ = respond.send(material);
                    }
                }
                other => {
                    tracing::warn!(
                        target: "forge_workspace",
                        command = ?other,
                        "unexpected App-level command (no key but not a spawn variant); ignored",
                    );
                }
            }
            Ok(())
        }
    }

    /// Say on the service line why a board edit did not land: a refusal a
    /// reader cannot see is indistinguishable from a press that did
    /// nothing.
    fn board_edit_refused(&self, what: &str, why: &str) {
        let _ = self.update_tx.send(SessionUpdate::ServiceStatus {
            severity: forge_primitives::cloud::service_status::ServiceSeverity::Warning,
            message: format!("The board refused {what}: {why}"),
        });
    }

    /// Re-spawn this project's persisted workers on lead reconnect,
    /// resuming by label off the id the store holds for that label.
    /// Charter and kick come from the DB row.
    ///
    /// Since this holds the worker set, it decides the kick directly:
    /// a resume of a worker whose row says `in_turn` takes the row's own
    /// `resume_kick` and falls back to the forge restart note, telling it
    /// to continue rather than restart; a resume of a parked worker gets
    /// nothing, and a fresh re-spawn (never prompted, so no store row)
    /// re-delivers the stored kick. `maybe_kick_worker_on_connected` then
    /// just delivers whatever this put on the `WorkerEntry`.
    pub(crate) fn dispatch_worker_respawns(
        self: &Arc<Self>,
        lead: &SessionSlot,
        project_key: &crate::target::ProjectKey,
        dynamic: &[crate::store::sessions::SessionRecord],
        force_new: bool,
    ) {
        // `--new`: the lead came up fresh, so its workers do too - every
        // row spawns fresh rather than resuming its stored id.
        let project = if force_new { None } else { self.project_for_key(project_key) };
        for worker in dynamic {
            let resume_existing = match project
                .as_ref()
                .map(|p| self.stored_session_id(&p.org, &p.name, &worker.label))
            {
                None | Some(Ok(None)) => None,
                Some(Ok(Some(id))) => Some(id),
                Some(Err(error)) => {
                    // A row that cannot be read is not a row without an
                    // id: spawning fresh here would mint over it and fork
                    // the worker's session.
                    tracing::error!(
                        target: "forge_workspace::workers",
                        project = %project_key.as_str(),
                        label = %worker.label,
                        %error,
                        "reading the worker's session row failed; skipping this worker rather than spawning fresh over it",
                    );
                    continue;
                }
            };
            // A resume starts the subprocess in the worker's worktree,
            // and a subprocess cannot enter a directory that is not
            // there: the spawn fails on every boot and the row never
            // clears. A FRESH re-spawn runs in its tree and takes
            // `--worktree`, so it is the resume this skip is for: a
            // fresh one that cannot get a worktree is refused by the
            // spawn itself, which leaves its row failed with the reason.
            //
            // The tree composed here is the ROW's own: a worker the
            // spawn pointed at another directory reads back to that
            // directory, so the wave and the spawn ask about the same
            // one.
            let root = worker.cwd.as_deref().map_or_else(
                || project.as_ref().map(|p| p.path.clone()),
                |cwd| Some(std::path::PathBuf::from(cwd)),
            );
            if let Some(root) = root.as_deref()
                && !crate::mcp::workers::types::worker_row_can_start(
                    root,
                    &worker.label,
                    worker.is_git_repo,
                    resume_existing.is_some(),
                )
            {
                let wanted = crate::mcp::workers::types::worker_tag_dir(
                    root,
                    &worker.label,
                    matches!(worker.is_git_repo, Some(true)),
                );
                tracing::warn!(
                    target: "forge_workspace::workers",
                    event_name = "boot_respawn_skipped_missing_worktree",
                    project = %project_key.as_str(),
                    label = %worker.label,
                    directory = %wanted.display(),
                    "the worker's directory is gone, so this boot re-spawn has nowhere to \
                     start; the row is kept and stays unoffered until it is back",
                );
                continue;
            }
            // **Only a worker that was mid-turn resumes with a kick.** A
            // worker that was idle when forge stopped is resumed parked;
            // its kick stays on the row for a future fresh spawn, and a
            // crash does not put an idle seat back to work. The state is
            // read from the row before this spawn overwrites it.
            let was_mid_turn =
                matches!(worker.seat_state, Some(crate::store::sessions::SeatState::InTurn));
            let kick = if resume_existing.is_some() {
                if was_mid_turn {
                    worker
                        .resume_kick
                        .clone()
                        .or_else(|| Some(DYNAMIC_WORKER_RESTART_NOTE.to_owned()))
                } else {
                    None
                }
            } else {
                worker.kick.clone()
            };
            let (tx, _rx) = tokio::sync::oneshot::channel();
            let cmd = crate::protocol::Command::SpawnWorker {
                project_key: project_key.clone(),
                label: worker.label.clone(),
                charter: worker.charter.clone().unwrap_or_default(),
                spawned_by: lead.clone(),
                resume_existing,
                kick,
                // The row this re-spawn is replaying already holds it.
                resume_kick: None,
                // And its family selection rides the same row; the spawn
                // reads it back rather than restating it here.
                mcp_families: worker.mcp_families.clone(),
                interactive: worker.interactive.unwrap_or(false),
                // The row's own tree, which is what this re-spawn
                // restores: the handler records it back verbatim.
                cwd: worker.cwd.clone(),
                from_boot_respawn: true,
                return_to: Some(tx),
            };
            if let Err(err) = self.dispatch(cmd) {
                tracing::error!(
                    target: "forge_workspace::workers",
                    project = %project_key.as_str(),
                    label = %worker.label,
                    error = ?err,
                    "dispatch_worker_respawns: dispatch failed for label"
                );
            }
        }
    }

    /// Lead Connected-hook entry point. Synchronously claims a
    /// per-project in-flight guard, then dispatches one
    /// `Command::SpawnWorker` per persisted row, resuming by the id the
    /// store holds for that row's label. The guard is released after
    /// the dispatches go out so a fast double-Connected can't slip a
    /// second wave through.
    ///
    /// No-op when the per-project guard is already claimed (another
    /// wave is in flight). The first-pass `live_workers.is_empty()`
    /// gate in `session_task::maybe_respawn_workers_on_connected` catches
    /// the post-dispatch case; this guard covers the in-flight window.
    pub(crate) fn respawn_workers_for_lead(
        self: &Arc<Self>,
        lead: &SessionSlot,
        project_key: crate::target::ProjectKey,
        force_new: bool,
    ) {
        let dynamic = self.worker_rows_for_project(&project_key);
        if dynamic.is_empty() {
            return;
        }
        if !self.try_claim_respawn(&project_key) {
            tracing::debug!(
                target: "forge_workspace::workers",
                project = %project_key.as_str(),
                "worker-spawn already in flight; skipping duplicate Connected fire",
            );
            return;
        }
        // Dispatching a worker probes its project path for git-repo-ness
        // inline, so this runs off the event loop rather than inside
        // `translate_event`. Outside a runtime (the sync `#[test]`
        // fixtures in `connected_hook_tests`) there is none to hand it
        // to, so dispatch inline.
        let Ok(handle) = tokio::runtime::Handle::try_current() else {
            tracing::debug!(
                target: "forge_workspace::workers",
                project = %project_key.as_str(),
                "no tokio runtime in scope; dispatching worker-spawns inline (test path)",
            );
            self.dispatch_worker_respawns(lead, &project_key, &dynamic, force_new);
            self.release_respawn(&project_key);
            return;
        };
        let workspace = Arc::clone(self);
        let lead = lead.clone();
        handle.spawn(async move {
            tracing::info!(
                target: "forge_workspace::workers",
                project = %project_key.as_str(),
                lead_slot = %lead.display(),
                worker_count = dynamic.len(),
                "dispatching SpawnWorker per persisted row",
            );
            workspace.dispatch_worker_respawns(&lead, &project_key, &dynamic, force_new);
            workspace.release_respawn(&project_key);
        });
    }

    /// Claim the per-project respawn in-flight guard. Returns true
    /// if the guard was acquired (entry was absent), false if another
    /// wave was already in flight.
    fn try_claim_respawn(&self, project_key: &crate::target::ProjectKey) -> bool {
        self.respawn_in_flight.lock().insert(project_key.clone())
    }

    /// Whether this fire pass is the FIRST to find `id` unwakeable,
    /// recording it as seen if so. True is the pass that warns; false is
    /// every later pass while the condition holds.
    pub(crate) fn cron_unwakeable_is_new(&self, id: &forge_primitives::CronId) -> bool {
        self.unwakeable_crons.lock().insert(id.clone())
    }

    /// Close a fire pass: `ids` is what it found unwakeable, and it
    /// replaces the previous pass's set wholesale. That replacement is
    /// the only clearing this state needs - an entry cannot survive a
    /// pass that did not find its cron unwakeable, whether the cron fired,
    /// advanced, was deleted, or simply was not due.
    pub(crate) fn cron_unwakeable_commit(
        &self,
        ids: std::collections::HashSet<forge_primitives::CronId>,
    ) {
        *self.unwakeable_crons.lock() = ids;
    }

    /// When the previous fire pass last warned about this cron's cooling,
    /// or `None` when that pass did not find it cooling.
    pub(crate) fn cron_cooling_warned_at(
        &self,
        id: &forge_primitives::CronId,
    ) -> Option<SystemTime> {
        self.cooling_crons.lock().get(id).copied()
    }

    /// Close a fire pass with the crons it still found cooling and the
    /// time each last warned, replacing the previous pass's map wholesale
    /// for the same reason [`Self::cron_unwakeable_commit`] does.
    pub(crate) fn cron_cooling_commit(
        &self,
        warned_at: std::collections::HashMap<forge_primitives::CronId, SystemTime>,
    ) {
        *self.cooling_crons.lock() = warned_at;
    }

    /// The session a worker label resumes onto.
    ///
    /// The row the label is registered under is authoritative while it is
    /// there: a worker that has one opens as it always has. The
    /// transcripts are the recovery path for a row that is gone - a
    /// despawn deleted it, or this install never had it - and there the
    /// newest transcript in `run_dir`'s directory carrying the label's
    /// worker tag wins.
    ///
    /// `Ok(ResumeTarget::None)` is a label with nothing in either, and
    /// `Err` is a store, directory or transcript that is there but could
    /// not be read. Only the first is a fallback: a caller that started a
    /// fresh session on the second would be answering a question the
    /// lookup never answered.
    pub(crate) fn resolve_worker_resume_session(
        &self,
        org: &str,
        project: &str,
        run_dir: &std::path::Path,
        label: &str,
    ) -> Result<ResumeTarget, anyhow::Error> {
        if let Some(session_id) = self.stored_session_id(org, project, label)? {
            return Ok(ResumeTarget::Found { session_id, restamp: false });
        }
        // The tag scan is what the store's cache is for: without it every
        // candidate transcript is read end to end, and the directory a
        // worker without a worktree runs in holds every session that ever
        // ran in its project. A cache that cannot be read or written
        // costs a re-scan, never an answer.
        let cache = {
            let db = self.db.lock();
            load_session_tag_cache(db.as_ref())
        };
        let owner = format!("{org}/{project}");
        let found = forge_agent::userdata::transcripts::newest_worker_session(
            &self.config_dir,
            run_dir,
            label,
            &owner,
            Some(&cache),
        );
        {
            let db = self.db.lock();
            persist_session_tag_cache(db.as_ref(), &cache);
        }
        Ok(match found? {
            Some((session_id, restamp)) => {
                if restamp {
                    // A tag row that predates the project field is adopted
                    // only from a directory no OTHER declared project
                    // reads; the check counts the sanitised key the lookup
                    // opens, so a key collision counts even when the paths
                    // differ.
                    let composing = self.projects_composing(run_dir, label);
                    if let Some((_, other)) =
                        composing.iter().find(|(owner, name)| owner != org || name != project)
                    {
                        anyhow::bail!(
                            "the transcript for '{label}' at '{}' predates project tags and is \
                             in a directory project '{other}' composes, so it cannot be known to \
                             be this project's",
                            run_dir.display(),
                        );
                    }
                }
                ResumeTarget::Found { session_id, restamp }
            }
            None => ResumeTarget::None,
        })
    }

    /// Stamp an adopted pre-field transcript with the adopting project,
    /// so a second project can never adopt it.
    pub(crate) fn stamp_adopted_worker_transcript(
        &self,
        project_key: &crate::ProjectKey,
        label: &str,
        session_id: &str,
        run_dir: &std::path::Path,
    ) -> anyhow::Result<()> {
        let Some((org, name)) = self.project_identity_for_key(project_key) else {
            anyhow::bail!("no configured project for {}", project_key.as_str());
        };
        let tag = forge_primitives::worker_tag(label);
        forge_agent::userdata::catalog::mutations::tag_session(
            &self.config_dir,
            session_id,
            Some(&tag),
            &format!("{org}/{name}"),
            Some(&run_dir.to_string_lossy()),
        )
        .map_err(anyhow::Error::from)
    }

    /// The declared projects whose transcript lookup for `label` opens
    /// `run_dir`: the directory their worker runs in, or the sanitised
    /// key that directory is stored under.
    fn projects_composing(&self, run_dir: &std::path::Path, label: &str) -> Vec<(String, String)> {
        // **One spelling per path, resolved the same way on both sides.** A
        // worker directory that is gone cannot be canonicalised at all, so
        // `resolve_existing_prefix` resolves the part that exists and keeps
        // the rest; the key is then built from that same spelling rather than
        // resolved a second time, or a directory removed between the two
        // resolutions would compare under a different key than its path.
        let composed = resolve_existing_prefix(run_dir);
        let key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &composed.to_string_lossy(),
        ));
        let key_of = |dir: &std::path::Path| {
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                &dir.to_string_lossy(),
            ))
        };
        self.list_projects()
            .into_iter()
            .filter(|view| {
                let is_git = self
                    .recorded_worker_is_git_repo(&view.key, label)
                    .ok()
                    .flatten()
                    .unwrap_or_else(|| forge_agent::env::worktree::is_git_repo(&view.path));
                let root = resolve_existing_prefix(&view.path);
                let dir = crate::mcp::workers::types::worker_tag_dir(&root, label, is_git);
                let dir = resolve_existing_prefix(&dir);
                dir == composed || key_of(&dir) == key
            })
            .map(|view| (view.org, view.name))
            .collect()
    }

    /// Release the per-project respawn in-flight guard. Paired with
    /// `try_claim_respawn`; called once the dispatches have gone out, on
    /// each path that can issue them.
    fn release_respawn(&self, project_key: &crate::target::ProjectKey) {
        self.respawn_in_flight.lock().remove(project_key);
    }

    /// Set the `session_id` field on the workspace's `DomainSession`
    /// for `key`. No-op when no domain handle is registered for
    /// `key`. Stamps the claude-issued UUID once the first
    /// `Connected` event fires - the workspace consults this when
    /// routing `AgentHandle` calls that take a session_id.
    pub fn set_session_id_in_domain(
        &self,
        key: &SessionSlot,
        value: Option<forge_primitives::SessionId>,
    ) {
        let Some(domain) = self.domain_handles.lock().get(key).cloned() else {
            return;
        };
        domain.lock().session_id = value;
    }

    /// Graceful shutdown of every pooled Agent. Drains the pool, then
    /// drops each `Arc<AgentHandle>`.
    ///
    /// The subprocess kill is asynchronous through each `SessionTask`:
    /// dropping the command senders closes every task's command channel,
    /// each task's run loop exits, and its exit path awaits
    /// `AgentHandle::disconnect`, which takes the bridge's client slot
    /// and runs the SDK's graceful shutdown (signal reader task, drain,
    /// close the child). `Client` has no `Drop` of its own, so without
    /// that disconnect the child would survive the pool drain.
    /// A well-behaved caller releases its handle reference before calling
    /// shutdown, so Workspace is the sole owner of every pool entry.
    /// Callers that hold cloned handles across shutdown keep the
    /// AgentHandle's task alive until they release them.
    ///
    /// **The return waits for those exit paths**, because the runtime a
    /// caller is about to drop does not poll them: each child sits in its
    /// own process group and only its own close signals that group, so a
    /// shutdown that returned early would leave the tree running. No
    /// session may start once it begins - the gate goes up before the first
    /// drain and the mint reads it under the same lock - and the drain is
    /// repeated until nothing is registered. The wait is bounded by the
    /// same `TEARDOWN_WAIT` the despawn's removal holds to.
    ///
    /// Returns the slots that had not answered; empty is a clean stop. The
    /// caller turns a non-empty answer into a non-zero exit, so a
    /// supervisor can tell a clean stop from one that left a tree.
    pub async fn shutdown(&self) -> Vec<SessionSlot> {
        self.shutdown_within(crate::spawn::TEARDOWN_WAIT).await
    }

    /// [`Self::shutdown`] with the budget injected, so a case can drive the
    /// expiry without sitting out the production wait. Returns the slots
    /// that had not answered by the deadline; empty is a clean stop.
    pub(crate) async fn shutdown_within(&self, wait: std::time::Duration) -> Vec<SessionSlot> {
        // Up before anything is torn down: from here on a spawn refuses,
        // and a mint cannot land behind the drain below.
        self.shutting_down.store(true, std::sync::atomic::Ordering::Release);
        // A pump left to the task's drop reports a stream end at every
        // clean stop; signalling it reaches its own shutdown branch.
        self.stop_gotify_subsystem();
        // Release any live dictation before the pools go: a recording
        // task outliving its session's teardown would otherwise hold
        // the microphone for a composer nobody can reach.
        crate::dictate::teardown_all(self);
        // Drop command senders first so every SessionTask sees its
        // command channel close and exits cleanly; each task's exit
        // path then disconnects its subprocess (see the doc above).
        let _ = self.command_senders.lock().drain().collect::<Vec<_>>();
        let _ = self.domain_handles.lock().drain().collect::<Vec<_>>();
        drop(self.pool.lock().drain().collect::<Vec<_>>());

        let deadline = tokio::time::Instant::now() + wait;
        loop {
            // The senders are taken with the drain but not dropped: each
            // subscription below reads the answer off the channel.
            let batch: Vec<(SessionSlot, tokio::sync::watch::Sender<bool>)> =
                self.session_teardowns.lock().drain().collect();
            if batch.is_empty() {
                return Vec::new();
            }
            let mut receivers: Vec<(SessionSlot, tokio::sync::watch::Receiver<bool>)> =
                batch.iter().map(|(slot, tx)| (slot.clone(), tx.subscribe())).collect();
            let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                let unready = unready_slots(&receivers);
                warn_shutdown_expired(&unready, wait);
                return unready;
            }
            // One budget for the batch: the tasks run concurrently, so a
            // later one is usually already done by its turn.
            let _ = tokio::time::timeout(remaining, async {
                for (_, rx) in &mut receivers {
                    wait_for_teardown(rx).await;
                }
            })
            .await;
            // Read the answers off the values, never off the order they
            // were polled in: a session that fired at any point counts.
            let unready = unready_slots(&receivers);
            if !unready.is_empty() {
                warn_shutdown_expired(&unready, wait);
                return unready;
            }
            // Nothing is registered now, but a spawn that passed the gate
            // just before it could still have minted: drain again.
        }
    }

    /// Release a single session's pool entry: drops the workspace's
    /// `Arc<AgentHandle>` for that key so the underlying `claude`
    /// subprocess exits once the consumer (a view's bucket) also
    /// drops its reference.
    ///
    /// Cascade-aware lead release. Use this when closing a project's
    /// lead session from a view: the lead-row `×` click, the launchpad's
    /// per-row close on a failed lead bucket, etc.
    ///
    /// When `session_key` is a project's lead - it appears in the
    /// project's catalog AND is NOT in `live_workers[project]` - every
    /// live worker under that project is released first via the
    /// non-cascading `release_session` primitive. Workers' JSONLs
    /// persist on disk; only the in-memory live state + the running
    /// claude subprocesses are torn down.
    ///
    /// The "in-catalog AND not-in-live_workers" rule is the
    /// discriminator (rather than `sessions.first()`): the catalog
    /// also indexes worker sessions once their Connected fires, so
    /// `sessions[0]` is not a reliable lead marker after a worker
    /// reaches Running. `live_workers` is the authoritative
    /// "this session is a child agent" registry.
    pub fn release_session_with_cascade(self: &Arc<Self>, session_key: &SessionSlot) {
        // **The close door is the only thing that closes a seat.** A bare
        // boot skips what it closed; opening the project again resumes its
        // stored session and writes `idle` like any spawn. A worker's row
        // is never written here: the cascade takes its live entries, and
        // its row is the despawn's or its next re-spawn's business.
        if session_key.is_lead() {
            self.record_seat_state(session_key, crate::store::sessions::SeatState::Closed);
        }
        // The cascade is the lead's, and a lead's slot is the one whose
        // label says so: a worker's slot carries its own label, so a
        // closed worker cannot be misidentified as its lead however far
        // the registry has moved.
        let cascade_project = session_key.is_lead().then(|| {
            self.list_projects()
                .into_iter()
                .find(|view| view.org == session_key.org() && view.name == session_key.project())
        });
        let cascade_project = cascade_project.flatten();
        // **Every record this close dismisses is cleared before the first
        // frame that makes a view re-read.** The lead's announcement below is
        // one; each live worker's removal is another. A stranded worker - a
        // record with no live entry left to carry it - is the project's too,
        // so every persisted label is cleared here rather than only what
        // `live_workers` still holds.
        if let Some(view) = cascade_project.as_ref() {
            for row in self.worker_rows_for_project(&view.key) {
                let slot = SessionSlot::worker(&row.org, &row.project, &row.label);
                self.clear_spawn_failure(&slot);
                self.spend_death(&slot);
            }
        }
        // Announced before anything is torn down, so the seat's row starts
        // saying where it is going at the gesture rather than after the
        // workers this cascade takes with it (#1930). A viewer's mark is a
        // set, so a second announcement would be spent.
        self.announce_release(session_key);
        if let Some(view) = cascade_project.as_ref() {
            for entry in self.drain_live_workers(&view.key) {
                // An entry whose label has no persisted row is only here.
                self.clear_spawn_failure(&entry.slot);
                self.spend_death(&entry.slot);
                // The cascade is the lead's close taking its workers with
                // it: their deaths are the stop's, not crashes to heal.
                self.healing().note_stopped(&entry.slot);
                let worktree =
                    crate::protocol::WorktreeDisposition::untouched(entry.is_git_repo_at_spawn);
                let _ = self.update_tx.send(SessionUpdate::WorkerStatusChanged {
                    project_key: view.key.clone(),
                    action: crate::protocol::WorkerStatusAction::Removed,
                    status: entry.to_status(),
                    worktree,
                });
                // The cascade takes a worker's browser tabs with it too;
                // `release_session` is the one door that tells the fleet.
                self.release_session(&entry.slot);
            }
        }
        self.release_session(session_key);
    }

    /// Announce that a seat's release has begun.
    ///
    /// One place for the close doors to say it, so a viewer draws the seat as
    /// going to sleep from the gesture instead of keeping the state it last
    /// read. Each door calls it where the close is certain and the teardown
    /// has not started: a lead before its cascade, a worker before its own
    /// kill - where a despawn's removal frame only follows the worktree
    /// cleanup, minutes later (#1930).
    ///
    /// The seat's failure record and any standing death go with the
    /// announcement, before the frame that makes a view re-read: a close is
    /// the reader acting on the row, and a trace that outlived the seat kept
    /// it in the needs-you group with nothing left to act on.
    pub(crate) fn announce_release(self: &Arc<Self>, key: &SessionSlot) {
        self.clear_spawn_failure(key);
        self.spend_death(key);
        // A stop owns the seat from here: any heal attempt standing for it
        // - a backoff already counted down - is cancelled rather than left
        // to resurrect what the stop is taking down, and the subprocess
        // death the stop causes is not read as a crash.
        self.clear_heal_progress(key);
        self.healing().note_stopped(key);
        let _ = self.update_tx.send(SessionUpdate::Releasing { key: key.clone() });
    }

    /// Non-cascading single-session release - the primitive. Drops
    /// the pool entry, command sender, and domain handle for
    /// `session_key`. No side effects beyond that single session.
    ///
    /// Use this for ANY session close where cascade semantics are
    /// undesirable or undefined:
    /// - `handle_close_worker` (per-row worker X click) - the close
    ///   must affect only the worker being closed.
    /// - The lead-cascade loop inside `release_session_with_cascade`
    ///   itself, when releasing each worker.
    ///
    /// Use `release_session_with_cascade` instead when the caller is
    /// the lead-row close gesture.
    pub(crate) fn release_session(self: &Arc<Self>, session_key: &SessionSlot) {
        // **A closed seat is gone now, not at the next sweep.** The fleet
        // hears the tombstone before the close work, so a hand-off resolved
        // after it does not keep the tab for a session that has ended; the
        // async tab close follows.
        self.release_browser_seat(session_key);
        // **The seat ended, so its terminal ends with it.** A `/new` or
        // `/resume` swaps the occupant and never reaches this path, which is
        // what leaves the PTY, its shell and its scrollback untouched.
        self.close_terminal(session_key);
        crate::dictate::teardown_for_closed_session(self, session_key);
        // A parked write is not a prompt the gone session can answer, and a
        // reused label must not draw the previous occupant's edit on a dock.
        self.abandon_settings_writes(session_key);
        // A parked vault call is the same shape: the blocked tool handler
        // cannot be answered by a session that is gone.
        self.abandon_vault_asks(session_key);
        // Anything parked for this session's owner was waiting on a
        // session that is now gone: fail the peer asks so their callers
        // are told, rather than letting them wait out the timeout.
        self.expire_parked_for_slot(
            session_key,
            crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
        );
        self.domain_handles.lock().remove(session_key);
        let removed = self.pool.lock().remove(session_key);
        drop(removed);
        let _ = self.command_senders.lock().remove(session_key);
        // The task this signal belonged to is exiting (its command channel
        // just closed). Its teardown entry stays: the task's drop is what
        // answers it, and a shutdown may still be waiting on that answer.
    }

    /// Whether a session task still exists for `key`, which is what
    /// makes it live: its command channel is registered and routable.
    pub(crate) fn session_is_live(&self, key: &SessionSlot) -> bool {
        self.command_senders.lock().contains_key(key)
    }

    /// Whether a shutdown has begun: no new session may start.
    pub fn is_shutting_down(&self) -> bool {
        self.shutting_down.load(std::sync::atomic::Ordering::Acquire)
    }

    /// Mint the slot's teardown signal, or `None` when a shutdown is
    /// already underway and no session may start. The refusal is read under
    /// the same lock a shutdown drains with, so a spawn can never register
    /// behind the drain.
    pub(crate) fn mint_session_teardown(
        &self,
        key: &SessionSlot,
    ) -> Option<tokio::sync::watch::Sender<bool>> {
        let mut slots = self.session_teardowns.lock();
        if self.shutting_down.load(std::sync::atomic::Ordering::Acquire) {
            return None;
        }
        let (tx, _rx) = tokio::sync::watch::channel(false);
        let _ = slots.insert(key.clone(), tx.clone());
        Some(tx)
    }

    /// Subscribe to the slot's teardown signal, if a session task is
    /// registered behind it and has not answered yet. `None` for a slot
    /// with no task - a stranded row - and for an entry a finished task
    /// already answered: either way the caller has nothing to wait for,
    /// and the despawn's mid-spawn guard reads `None` exactly that way.
    ///
    /// The entry itself stays in the map, unlike the one receiver it
    /// replaced: more than one waiter may need the same answer, and a
    /// shutdown's drain reads every entry's value rather than subscribing
    /// blind.
    pub(crate) fn session_teardown(
        &self,
        key: &SessionSlot,
    ) -> Option<tokio::sync::watch::Receiver<bool>> {
        let slots = self.session_teardowns.lock();
        let tx = slots.get(key)?;
        // An answered entry belongs to a task that is already gone: a
        // re-spawn's own signal is not minted yet, and handing the previous
        // answer back would wave a despawn's removal through over a child
        // that is only starting (#1767's mid-spawn window).
        if *tx.borrow() {
            return None;
        }
        Some(tx.subscribe())
    }

    /// Supersession-safe release: drop `session_key`'s pool entry,
    /// command sender, and domain handle ONLY when the pooled agent is
    /// still `handle` (by `Arc` identity). A SessionTask whose session
    /// was re-spawned under the same key is a
    /// stale predecessor - when it exits and runs this cleanup, the
    /// pool already holds the successor's handle, so the guard no-ops
    /// and the live re-spawned session is left intact. Gating all three
    /// maps on the one identity check keeps a superseded task from
    /// half-cleaning its successor.
    pub(crate) fn release_session_if_current(
        &self,
        session_key: &SessionSlot,
        handle: &Arc<AgentHandle>,
    ) {
        let mut pool = self.pool.lock();
        if !pool.get(session_key).is_some_and(|pooled| Arc::ptr_eq(&pooled.handle, handle)) {
            return;
        }
        let removed = pool.remove(session_key);
        drop(pool);
        drop(removed);
        let _ = self.command_senders.lock().remove(session_key);
        let _ = self.domain_handles.lock().remove(session_key);
        // The teardown entry stays, as on the release path: this task's
        // drop answers it, and a shutdown may still be waiting. A
        // superseded predecessor stopped above, so the successor's entry
        // is untouched.
    }

    // ---- Live workers (project-internal child-agent coordination) ----

    /// Every seat that exists right now: each configured project's lead, and
    /// every worker the store holds - running or not, because a durable
    /// worker's seat exists until it is despawned.
    ///
    /// The browser sweep reads this: a tab whose owning seat is not here is
    /// an orphan and closes. **No profile is deleted by that sweep** - a
    /// profile's logins are the org's and stay until the idle clock closes
    /// the host - so the cost of a wrong answer is a closed tab, not a lost
    /// login. **Captures are serialised, the lock spanning the mint and the
    /// reads** ([`crate::browser::LiveSeats`]): a higher generation is a later
    /// seat set, which is what lets the fleet drop a stale one - including for
    /// a seat released without a sweep of its own, since only a capture that
    /// read after the release can drop its tombstone and every snapshot still
    /// listing the seat is older than that capture. It still holds two rules,
    /// because a closed tab is a page an agent was working in:
    ///
    /// - **It errs toward INCLUSION**: a seat wrongly present leaves one tab
    ///   to the next sweep, while a seat wrongly absent would close a live
    ///   session's page.
    /// - **It fails closed**: `None` when the store cannot be read, so no
    ///   caller can mistake an unread store for "no seats exist" and sweep
    ///   everything. Nothing sends a set it could not read.
    pub fn live_seats(&self) -> Option<crate::browser::LiveSeats> {
        use std::collections::BTreeSet;

        // **Held across the reads**: the mint ranks a whole capture, so no
        // other capture may read between the two.
        let _capture = self.live_seats_lock.lock();
        let views = self.list_projects();
        let stored = {
            let guard = self.db.lock();
            let db = guard.as_ref()?;
            match crate::store::sessions::worker_row_index(db) {
                Ok(rows) => rows,
                Err(error) => {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        %error,
                        "listing the persisted workers for the seat set failed, so no seat set \
                         is answered",
                    );
                    return None;
                }
            }
        };
        // Minted after the fail-closed read, so a capture that answers no set
        // takes no generation.
        let generation =
            self.live_seats_generation.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + 1;
        #[cfg(any(test, feature = "testing"))]
        self.pass_live_seats_gate();
        let mut triples: BTreeSet<(String, String, String)> = BTreeSet::new();
        for view in &views {
            triples.insert((
                view.org.clone(),
                view.name.clone(),
                String::from(forge_primitives::LEAD_LABEL),
            ));
        }
        for row in stored {
            if row.label != forge_primitives::LEAD_LABEL {
                triples.insert((row.org, row.project, row.label));
            }
        }
        for view in &views {
            for worker in self.list_live_workers(&view.key) {
                triples.insert((view.org.clone(), view.name.clone(), worker.label));
            }
        }
        Some(crate::browser::LiveSeats {
            generation,
            seats: triples
                .into_iter()
                .map(|(org, project, label)| {
                    forge_primitives::SessionSlot::new(org, project, label)
                })
                .collect(),
        })
    }

    /// Snapshot the live workers for `project_key`. Returns an empty
    /// Vec when no workers exist (rather than `None`) so a view's tree-
    /// child render can branch only on `is_empty`.
    pub fn list_live_workers(
        &self,
        project_key: &ProjectKey,
    ) -> Vec<crate::mcp::workers::types::WorkerEntry> {
        self.live_workers.lock().get(project_key).cloned().unwrap_or_default()
    }

    /// Every live worker's liveness, keyed by project.
    ///
    /// The launchpad's worker rows read this once per frame, which is
    /// what the shape is for: one lock answers every project row, and
    /// the projection leaves each worker's charter in the registry
    /// instead of copying it, which [`Self::list_live_workers`] does on
    /// every call.
    pub fn live_worker_states_by_project(
        &self,
    ) -> HashMap<ProjectKey, Vec<crate::mcp::workers::types::LiveWorkerState>> {
        self.live_workers
            .lock()
            .iter()
            .map(|(project, workers)| {
                let states = workers
                    .iter()
                    .map(|w| crate::mcp::workers::types::LiveWorkerState {
                        label: w.label.clone(),
                        status: w.status,
                        slot: w.slot.clone(),
                        diagnostic: w.diagnostic.clone(),
                    })
                    .collect();
                (project.clone(), states)
            })
            .collect()
    }

    /// Whether `slot`'s session has live background work. A fact about the
    /// session rather than about a viewer, so the core holds one answer for
    /// every view.
    pub fn has_background_work(&self, slot: &SessionSlot) -> bool {
        self.domain_session_for(slot).is_some_and(|domain| domain.lock().background_work)
    }

    /// When `slot`'s newest turn ended in failure, for the rail's mark.
    /// `None` for a slot whose newest turn succeeded, never ran, was
    /// cancelled by the reader, or has since been moved past with a new
    /// turn.
    pub fn session_failed_turn(&self, slot: &SessionSlot) -> Option<std::time::SystemTime> {
        self.domain_session_for(slot).and_then(|domain| domain.lock().failed_turn_at)
    }

    /// What the session at `slot` is waiting on a person for, or `None`
    /// when it can advance on its own.
    ///
    /// **The one predicate every needs-you surface reads.** A session
    /// activity, a roster row, a rail mark and a notification all ask this
    /// rather than each keeping a list of sources: the lists drifted, and a
    /// terminal hand-off drew in the dock while its seat read as running
    /// (#2954).
    ///
    /// The order is fixed. The hand-offs lead because each parks in a
    /// registry of the workspace's own rather than in the session's pending
    /// set, so a seat with no domain can still be holding one; then the
    /// question outranks the permission prompt beside it, because both hold
    /// a turn and the question is the one a person has to read; then the
    /// remaining registries, the Slack draft first.
    ///
    /// **The row names the strongest ask; the dock draws its own queue.**
    /// [`Self::pending_asks`] fronts a draft because a card is what a person
    /// reads first, while this answers one kind - so a seat holding a Slack
    /// draft and a document hand-off names the hand-off on its row and shows
    /// the draft at the front of the dock.
    pub fn pending_interaction(&self, slot: &SessionSlot) -> Option<PendingInteractionKind> {
        self.pending_ask_ledger(slot).into_iter().find(|(_, held)| *held > 0).map(|(kind, _)| kind)
    }

    /// How many asks the session at `slot` is holding, zero when none.
    /// **The same ledger [`Self::pending_interaction`] reads**, summed, so a
    /// view showing one of them can say how many wait behind it.
    pub fn pending_interaction_depth(&self, slot: &SessionSlot) -> usize {
        self.pending_ask_ledger(slot).iter().map(|(_, held)| held).sum()
    }

    /// Every ask source, in [`Self::pending_interaction`]'s precedence
    /// order, with the number of asks each holds.
    ///
    /// **One list feeds the kind and the depth**, so a source cannot be
    /// counted without being answered or answered without being counted.
    /// The guard test parks one ask of every kind and reads both back.
    ///
    /// **Lock order:** each registry read takes and releases its own lock,
    /// and the domain guard is off before the registry reads after it, so no
    /// path here holds a registry lock and the domain lock together.
    fn pending_ask_ledger(&self, slot: &SessionSlot) -> [(PendingInteractionKind, usize); 8] {
        let documents = self.document_handoffs.lock().values().filter(|h| &h.seat == slot).count();
        let browsers =
            self.browser_handoffs.lock().values().filter(|(owner, _, _)| owner == slot).count();
        let terminals =
            self.terminal_handoffs.lock().values().filter(|(owner, _, _)| owner == slot).count();
        let (questions, permissions) = match self.domain_session_for(slot) {
            Some(domain) => {
                let guard = domain.lock();
                let questions = guard
                    .pending_interactions
                    .values()
                    .filter(|pending| {
                        matches!(pending, crate::protocol::PendingInteractionSlot::Question { .. })
                    })
                    .count();
                // The set holds questions and permissions and nothing else.
                (questions, guard.pending_interactions.len().saturating_sub(questions))
            }
            None => (0, 0),
        };
        let drafts =
            self.slack_drafts.lock().values().filter(|(owner, _, _)| owner == slot).count();
        let writes =
            self.settings_writes.lock().values().filter(|(owner, _, _)| owner == slot).count();
        let vaults =
            self.parked_vault_asks.lock().values().filter(|(owner, _, _)| owner == slot).count();
        [
            (PendingInteractionKind::DocumentHandOff, documents),
            (PendingInteractionKind::BrowserHandOff, browsers),
            (PendingInteractionKind::TerminalHandOff, terminals),
            (PendingInteractionKind::Question, questions),
            (PendingInteractionKind::Permission, permissions),
            (PendingInteractionKind::SlackDraft, drafts),
            (PendingInteractionKind::SettingsWrite, writes),
            (PendingInteractionKind::Vault, vaults),
        ]
    }

    /// Note that an ask arrived for `slot`.
    ///
    /// **The number is the ask's identity on the wire.** A client announces a
    /// new ask by it, so a re-read of the roster is not news, an ask replacing
    /// another at the same depth is, and an answer that shrinks a batch is
    /// not.
    pub(crate) fn note_ask(&self, slot: &SessionSlot) {
        let mut held = self.pending_seq.lock();
        let next = held.entry(slot.clone()).or_insert(0);
        *next = next.saturating_add(1);
    }

    /// How many asks have ever arrived for `slot`, zero when none has.
    pub fn pending_request_seq(&self, slot: &SessionSlot) -> u64 {
        self.pending_seq.lock().get(slot).copied().unwrap_or(0)
    }

    /// Record a fatal error, so a view that was not attached when it fired
    /// can still read it.
    pub(crate) fn record_fatal_error(&self, error: forge_primitives::error::AppError) {
        *self.last_fatal_error.lock() = Some(error);
    }

    /// The last fatal error, or `None` when nothing has failed fatally.
    ///
    /// A fatal error is App-level: it names the startup that could not
    /// happen rather than a seat, and it arrives once. Without this the
    /// only way to know is to have been subscribed when it went out.
    pub fn last_fatal_error(&self) -> Option<forge_primitives::error::AppError> {
        self.last_fatal_error.lock().clone()
    }

    /// The statuspage's last answer, or `None`.
    ///
    /// `None` covers both "every relevant component is operational" and
    /// "the statuspage could not be reached", which is the fetch's own
    /// contract rather than something invented here - and a view that draws
    /// nothing for it is drawing the answer, not a gap.
    ///
    /// The core probes rather than the view because the answer is the same
    /// for every viewer and because it must outlive any one of them: a
    /// client that attaches later would otherwise never see a
    /// service status at all.
    pub fn service_status(&self) -> Option<ServiceIssue> {
        self.service_status.lock().clone()
    }

    /// Kick off the statuspage probe. Idempotent, and off the boot path.
    fn start_service_status_probe(&self, prober: ServiceStatusProber) {
        spawn_background_service_status_probe(
            &self.service_status_probe_started,
            &self.service_status,
            &self.update_tx,
            prober,
        );
    }

    /// What the seat at `slot` is holding - **a draft leads, then arrival
    /// order** - empty when it is holding nothing. Every hop keeps that
    /// order, so a re-read and the live folds cannot disagree about the
    /// front, with one exception: two drafts held at once - and two
    /// configuration writes held at once - come back in the registry's own
    /// order, because the registry keeps none to offer.
    ///
    /// **The list rather than one ask**, because a parallel batch parks
    /// several at once and a view that attached mid-batch has no other way to
    /// read the ones behind the front: the stream is a mirror with no backlog,
    /// and the request beside the answer's oneshot is what is left. A view
    /// draws the front.
    ///
    /// A draft leads because it is parked in its own registry rather than in
    /// the session's pending set, so a seat with no domain can still hold one.
    pub fn pending_asks(&self, slot: &SessionSlot) -> Vec<crate::protocol::PendingAsk> {
        let mut asks = Vec::new();
        {
            let parked = self.slack_drafts.lock();
            asks.extend(parked.values().filter(|(owner, _, _)| owner == slot).map(
                |(_, draft, _)| crate::protocol::PendingAsk::SlackDraft(Box::new(draft.clone())),
            ));
        }
        {
            let parked = self.browser_handoffs.lock();
            asks.extend(parked.values().filter(|(owner, _, _)| owner == slot).map(
                |(_, handoff, _)| {
                    crate::protocol::PendingAsk::BrowserHandOff(Box::new(handoff.clone()))
                },
            ));
        }
        {
            let parked = self.terminal_handoffs.lock();
            asks.extend(parked.values().filter(|(owner, _, _)| owner == slot).map(
                |(_, handoff, _)| {
                    crate::protocol::PendingAsk::TerminalHandOff(Box::new(handoff.clone()))
                },
            ));
        }
        {
            let parked = self.document_handoffs.lock();
            asks.extend(parked.values().filter(|held| &held.seat == slot).map(|held| {
                crate::protocol::PendingAsk::DocumentHandOff(Box::new(held.ask.clone()))
            }));
        }
        let needs_unlock = self.vault.read().as_ref().is_some_and(|session| session.is_locked());
        asks.extend(self.vault_asks(slot, needs_unlock));
        asks.extend(self.settings_write_asks(slot));
        if let Some(domain) = self.domain_session_for(slot) {
            let guard = domain.lock();
            asks.extend(
                guard
                    .pending_interactions
                    .values()
                    .map(crate::protocol::PendingInteractionSlot::ask),
            );
        }
        asks
    }

    /// What `entry`'s session is doing right now. The two liveness states
    /// that need no session of their own answer here; everything else is
    /// [`Self::session_activity`].
    ///
    /// Call this with no worker lock held - it reaches for
    /// `domain_handles` and then the `DomainSession`.
    pub fn worker_activity(
        &self,
        entry: &crate::mcp::workers::types::WorkerEntry,
    ) -> forge_primitives::SessionLifecycleState {
        use forge_primitives::{SessionLifecycleState as L, WorkerLiveness};

        // None of these has a connected session to interrogate.
        match entry.status {
            WorkerLiveness::Spawning => return L::Spawning,
            WorkerLiveness::Failed => return L::Failed,
            WorkerLiveness::Restarting => return L::Restarting,
            WorkerLiveness::Running => {}
        }
        self.session_activity(&entry.slot)
    }

    /// Why the last spawn or connection for `slot` failed, when it has not
    /// come up since. `None` for a slot that is running, was never tried,
    /// or recovered.
    pub fn spawn_failure(&self, slot: &SessionSlot) -> Option<String> {
        self.spawn_failures.lock().get(slot).cloned()
    }

    /// Record that `slot`'s spawn or connection failed, and why. Called
    /// before the failure releases the session, because the release is
    /// what takes the rest of the evidence with it.
    pub(crate) fn record_spawn_failure(&self, slot: &SessionSlot, message: &str) {
        self.spawn_failures.lock().insert(slot.clone(), message.to_owned());
    }

    /// Clear `slot`'s recorded failure: a session for it came up. Called
    /// from the `Connected` arm, which is the path production takes - the
    /// spawn entries hoist a domain straight into `domain_handles` rather
    /// than registering one, so clearing on registration would never run.
    pub(crate) fn clear_spawn_failure(&self, slot: &SessionSlot) {
        let _ = self.spawn_failures.lock().remove(slot);
    }

    /// Record that the occupant running on `slot` died, with the reason it
    /// left, keeping both until a reader has been shown the seat and the
    /// recovery has announced itself. The lifecycle is NOT held down by
    /// this: a recovering connect clears the failure as it always did, and
    /// what rides on until shown is the death - `died` on the row, with the
    /// reason and the mark the client draws from it.
    pub(crate) fn record_death(&self, slot: &SessionSlot, occupant: SessionId, reason: &str) {
        self.deaths.lock().insert(
            slot.clone(),
            SeatDeath { occupant, reason: reason.to_owned(), announced: false, shown: false },
        );
    }

    /// The died occupant recorded for `slot` when the recovery has not
    /// announced it yet, consuming that one announcement: the notice fires
    /// on the first connect that answers the death and stays quiet after.
    ///
    /// **The spend does not consume it.** A reader who opens the 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 is owed the sentence like any other.
    pub(crate) fn unannounced_death(&self, slot: &SessionSlot) -> Option<SessionId> {
        let mut deaths = self.deaths.lock();
        let death = deaths.get_mut(slot)?;
        if death.announced {
            return None;
        }
        death.announced = true;
        let occupant = death.occupant.clone();
        if death.shown {
            deaths.remove(slot);
        }
        Some(occupant)
    }

    /// Whether a death stands unshown on `slot`: the row carries `died` with
    /// its reason while one does, so a crash nobody watched is still
    /// readable when someone looks. `pub` because the row a view reads
    /// carries it.
    pub fn death_stands(&self, slot: &SessionSlot) -> bool {
        self.deaths.lock().get(slot).is_some_and(|death| !death.shown)
    }

    /// The reason a standing death left, for the row to draw beside its
    /// mark. `None` once a reader has been shown the seat.
    pub fn death_reason(&self, slot: &SessionSlot) -> Option<String> {
        self.deaths.lock().get(slot).filter(|death| !death.shown).map(|death| death.reason.clone())
    }

    /// Record that `slot` is between heal attempts: which attempt is next
    /// and when it fires. Written by the healing supervisor and read by
    /// every row that draws the seat.
    pub fn set_heal_progress(&self, slot: &SessionSlot, attempt: u32, next_at: SystemTime) {
        self.heal_progress.lock().insert(slot.clone(), HealProgress { attempt, next_at });
    }

    /// Forget `slot`'s heal progress: an occupant connected, or the seat
    /// gave up and its row now draws the failure instead.
    pub fn clear_heal_progress(&self, slot: &SessionSlot) {
        let _ = self.heal_progress.lock().remove(slot);
    }

    /// Where `slot`'s heal has got to, or `None` when the seat is not
    /// restarting.
    pub fn heal_progress(&self, slot: &SessionSlot) -> Option<HealProgress> {
        self.heal_progress.lock().get(slot).copied()
    }

    /// How many restarts a heal may make, from the current config: the row
    /// says `restarting (attempt 1 of 3)` from this.
    pub fn heal_attempts(&self) -> Option<u32> {
        u32::try_from(self.config_arc().sessions.heal_attempts).ok()
    }

    /// The supervisor, built on first use.
    fn healing(self: &Arc<Self>) -> Arc<crate::healing::Healing> {
        self.healing.get_or_init(|| crate::healing::Healing::for_workspace(self)).clone()
    }

    /// A seat that had been up died: hand the death to the supervisor. A
    /// resume's new occupant that never came up is a death here too - the
    /// attempt failed rather than a first spawn being surfaced.
    pub(crate) fn note_seat_death(self: &Arc<Self>, slot: &SessionSlot, diagnostic: &str) {
        self.healing().note_death(slot, diagnostic);
    }

    /// A session came up on `slot`, which cancels any scheduled heal.
    pub(crate) fn note_seat_connected(self: &Arc<Self>, slot: &SessionSlot) {
        if let Some(healing) = self.healing.get() {
            healing.note_connected(slot);
        }
    }

    /// `slot`'s worker is between heal attempts: its row draws
    /// `Restarting`, and the label is free for the resume.
    pub(crate) fn mark_worker_restarting(&self, project_key: &ProjectKey, slot: &SessionSlot) {
        let entry = {
            let mut workers = self.live_workers.lock();
            workers.get_mut(project_key).and_then(|entries| {
                entries.iter_mut().find(|entry| entry.slot == *slot).map(|entry| {
                    entry.status = forge_primitives::WorkerLiveness::Restarting;
                    entry.clone()
                })
            })
        };
        if let Some(entry) = entry {
            let status = self.worker_status_snapshot(&entry);
            let _ = self.update_tx.send(SessionUpdate::WorkerStatusChanged {
                project_key: project_key.clone(),
                action: crate::protocol::WorkerStatusAction::StatusChanged,
                status,
                worktree: crate::protocol::WorktreeDisposition::untouched(
                    entry.is_git_repo_at_spawn,
                ),
            });
        }
    }

    /// A reader has been shown the death on `slot` - the seat's page was
    /// opened: the row's trace goes (whether or not the recovery has
    /// announced itself yet), and the answer says whether there was one to
    /// spend. `pub` because the seat being shown is the server's to see,
    /// and this is the spend the server makes on the view's behalf.
    pub fn spend_death(&self, slot: &SessionSlot) -> bool {
        let mut deaths = self.deaths.lock();
        let Some(death) = deaths.get_mut(slot) else {
            return false;
        };
        let spent = !death.shown;
        death.shown = true;
        if death.announced {
            deaths.remove(slot);
        }
        spent
    }

    /// What the session at `slot` is doing right now - the axis
    /// `WorkerLiveness` does not answer, since it stops moving once the
    /// worker connects. Reachable without a `WorkerEntry`, which a project
    /// lead has none of.
    ///
    /// A pending interaction outranks the turn it is blocking:
    /// `Attention` is the state a lead has to act on, and reporting the
    /// blocked worker as `Running` is what let the deadlock stay
    /// invisible.
    ///
    /// Call this with no worker lock held - it reaches for
    /// `domain_handles` and then the `DomainSession`.
    pub fn session_activity(&self, slot: &SessionSlot) -> forge_primitives::SessionLifecycleState {
        use forge_primitives::SessionLifecycleState as L;

        // A seat between heal attempts outranks the failure that started
        // the heal: the failure is being answered, and drawing it would
        // tell a reader nothing is happening when something is.
        if self.heal_progress(slot).is_some() {
            return L::Restarting;
        }
        // Both of these are terminal for the session's own progress, so
        // they answer before anything about turns: a session waiting to
        // be let in, and one whose last attempt to start is still the
        // last thing that happened to it.
        if self.spawn_failure(slot).is_some() {
            return L::Failed;
        }
        let Some(domain) = self.domain_session_for(slot) else {
            return L::Sleeping;
        };
        if domain.lock().awaiting_login {
            return L::AuthRequired;
        }
        let requires_action = {
            let guard = domain.lock();
            // A held interaction only matters while a turn can advance on
            // it, and this gate is what decides that for every ask kind too:
            // one parked on a slot with no turn (busytools/forge#672 - a slot
            // outliving its turn is incoherent state) reads `Idle` here
            // rather than as a person's to answer.
            if !guard.turn_in_flight() {
                return L::Idle;
            }
            // `RequiresAction` is the CLI naming its own block; a held ask
            // is forge naming it, through the predicate below. Either way a
            // human has to move first, and calling that `Running` is what
            // makes a blocked worker invisible. This arm is reachable only
            // because `turn_in_flight()` counts `RequiresAction` as
            // in-flight: drop it from that OR and a `RequiresAction` session
            // falls through the gate above to `Idle` instead.
            matches!(
                guard.runtime_state,
                Some(forge_primitives::RuntimeSessionState::RequiresAction)
            )
        };
        // **Every ask kind reads through the one predicate**, after the
        // domain guard comes off: each parks in its own registry, and
        // `pending_interaction` keeps the registry locks and the domain lock
        // from being held together. Knowing only some sources is what kept
        // the lifecycle quiet while the dock sat unanswered - the Slack
        // draft (#1758), the browser hand-off, the document hand-off, the
        // settings write and the vault call, and the terminal hand-off last
        // (#2954).
        if requires_action || self.pending_interaction(slot).is_some() {
            L::Attention
        } else {
            L::Running
        }
    }

    /// `entry` projected to the wire shape with `activity` derived.
    /// This is the `agents__list` projection; `WorkerEntry::to_status`
    /// is the event-path one that leaves `activity` unset.
    pub fn worker_status_snapshot(
        &self,
        entry: &crate::mcp::workers::types::WorkerEntry,
    ) -> forge_primitives::WorkerStatus {
        let heal = self.heal_progress(&entry.slot);
        forge_primitives::WorkerStatus {
            activity: Some(self.worker_activity(entry)),
            heal_attempt: heal.map(|progress| progress.attempt),
            heal_next_at: heal.map(|progress| progress.next_at),
            ..entry.to_status()
        }
    }

    /// The forge.toml project NAME that owns `cwd`, matched by the
    /// project whose expanded path is an ancestor-or-equal of `cwd`
    /// (component-aware, longest wins), so a worker in a
    /// `<project>/.claude/worktrees/<label>` worktree resolves to its
    /// parent project. `cwd` is `~`-expanded before the lexical match so
    /// a tilde form can't miss the already-expanded `ProjectView.path`.
    /// `None` when `cwd` is blank or under no configured project. The
    /// Inspector stamps this NAME onto a tab's UI bucket once (at
    /// Connect), then scopes SCHEDULES / GOTIFY by name rather than
    /// re-deriving the project every render tick from a stale cwd.
    pub fn project_name_for_path(&self, cwd: &str) -> Option<String> {
        if cwd.is_empty() {
            return None;
        }
        let cwd = crate::config::expand_home(cwd);
        self.list_projects()
            .into_iter()
            .filter(|view| cwd.starts_with(&view.path))
            .max_by_key(|view| view.path.as_os_str().len())
            .map(|view| view.name)
    }

    /// The forge.toml project NAME that owns the RESOLVED `cwd`: the
    /// match [`Self::project_name_for_path`] makes, retried with both
    /// sides canonicalized when the lexical one misses. A spawn's tree is
    /// canonical - the CLI derives its state directory from the canonical
    /// path - while a declared path may reach the same directory through
    /// an alias (`/tmp` for `/private/tmp`, a symlinked parent), and the
    /// lexical rule alone would miss: a crossing-into-another-project
    /// check that misses is the rule the check exists for.
    ///
    /// Both sides resolve together or not at all, the way the sibling's
    /// lexical match keeps them in one form - a per-side canonicalize
    /// would put an existing root on one side of the comparison and an
    /// uncanonicalized child on the other.
    pub fn project_name_for_resolved_path(&self, cwd: &str) -> Option<String> {
        if let Some(name) = self.project_name_for_path(cwd) {
            return Some(name);
        }
        let canonical = std::fs::canonicalize(crate::config::expand_home(cwd)).ok()?;
        self.list_projects()
            .into_iter()
            .filter_map(|view| {
                let declared = std::fs::canonicalize(&view.path).ok()?;
                canonical.starts_with(&declared).then_some((declared, view.name))
            })
            .max_by_key(|(declared, _)| declared.as_os_str().len())
            .map(|(_, name)| name)
    }

    /// The `(org, project name)` a project key names, when forge.toml
    /// still declares it. The `sessions` table is keyed by the pair
    /// while every worker site holds the key, so a worker's row cannot be
    /// written or found without this translation.
    fn project_identity_for_key(&self, project_key: &ProjectKey) -> Option<(String, String)> {
        self.project_for_key(project_key).map(|project| (project.org, project.name))
    }

    /// Write `label`'s worker row: the id it runs under plus the
    /// re-spawn arguments its spawn stated. The row is the only thing a
    /// boot re-spawns from, so the charter, the kick, the interactive
    /// flag and the gitness its worktree derives from land here rather
    /// than staying in memory.
    ///
    /// `Err` when the store is closed, the project is no longer
    /// configured, or the write failed, so the caller can warn the lead
    /// that this worker will not survive a restart.
    pub(crate) fn record_worker_row(
        &self,
        project_key: &ProjectKey,
        label: &str,
        id: &str,
        charter: &str,
        kick: Option<&str>,
        resume_kick: Option<&str>,
        interactive: bool,
        tree: crate::mcp::workers::types::WorkerTree,
        mcp_families: Option<&[String]>,
    ) -> anyhow::Result<()> {
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            anyhow::bail!("no configured project for {}", project_key.as_str());
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            anyhow::bail!("the session store is unavailable this session");
        };
        // A boot re-spawn or a heal passes no re-orient message of its
        // own - it hands the row's `resume_kick` to the child as the kick
        // only when the row says a turn was cut off, and nothing when the
        // worker was parked - so a `None` here carries the stored value
        // forward rather than erasing the field its caller just read. Same
        // for `kick`: only a first spawn states one, and a resume that
        // wrote its own live kick here would replace the worker's original
        // first turn with it.
        let existing = crate::store::sessions::get(db, &org, &project, label).ok().flatten();
        crate::store::sessions::put(
            db,
            &crate::store::sessions::SessionRecord {
                org,
                project,
                label: label.to_owned(),
                session_id: Some(id.to_owned()),
                charter: Some(charter.to_owned()),
                mcp_families: match mcp_families {
                    Some(names) if !names.is_empty() => Some(names.to_vec()),
                    // Empty resolves to every family, stored as absence;
                    // a resume states none and carries the stored value.
                    Some(_) => None,
                    None => existing.as_ref().and_then(|row| row.mcp_families.clone()),
                },
                kick: kick
                    .map(str::to_owned)
                    .or_else(|| existing.as_ref().and_then(|row| row.kick.clone())),
                resume_kick: resume_kick
                    .map(str::to_owned)
                    .or_else(|| existing.and_then(|row| row.resume_kick)),
                interactive: Some(interactive),
                // A spawn and a re-spawn both leave the worker open with
                // no turn in flight; its kick, when one is due, is what
                // flips it.
                seat_state: Some(crate::store::sessions::SeatState::Idle),
                is_git_repo: Some(tree.is_git_repo),
                // Stored as the spawn resolved it, never carried forward
                // from an older row: a spawn that states no tree runs in
                // the project root, and only a resume adopts one.
                cwd: tree.cwd,
            },
        )
    }

    /// The git flag the worker's row records, or `Ok(None)` when there is
    /// no row to read or its row predates the field. The spawn reads it in
    /// preference to probing the project path, so the cwd it builds is the
    /// one the launchpad already checked.
    ///
    /// A read failure is an `Err`, not an absent row: an absent row means
    /// the caller may probe, while an unreadable one means the answer is
    /// unknown and the caller should say so rather than quietly compose a
    /// different directory. Distinct from [`Self::stored_worker_row`],
    /// which reports both the same way because its callers act on the row
    /// itself rather than on a field of it.
    pub(crate) fn recorded_worker_is_git_repo(
        &self,
        project_key: &ProjectKey,
        label: &str,
    ) -> anyhow::Result<Option<bool>> {
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            return Ok(None);
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            anyhow::bail!("the session store is unavailable this session");
        };
        Ok(crate::store::sessions::get(db, &org, &project, label)?.and_then(|row| row.is_git_repo))
    }

    /// The MCP-family selection the worker's row records, or `Ok(None)`
    /// when there is no row or its row names none (which resolves to
    /// every family). Same failure contract as
    /// [`Self::recorded_worker_is_git_repo`]: an unreadable row is an
    /// `Err`, not an absence.
    pub(crate) fn recorded_worker_mcp_families(
        &self,
        project_key: &ProjectKey,
        label: &str,
    ) -> anyhow::Result<Option<Vec<String>>> {
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            return Ok(None);
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            anyhow::bail!("the session store is unavailable this session");
        };
        Ok(crate::store::sessions::get(db, &org, &project, label)?.and_then(|row| row.mcp_families))
    }

    /// Delete a worker's persisted row so it never re-spawns. The row is
    /// the only thing that brings one back, so a delete that cannot land
    /// is an error rather than a warn.
    ///
    /// `Ok` reports whether a row was there to remove. `Err` means the row
    /// could not be addressed or the delete failed - which is not the same
    /// answer as an absent row, so `spawn::handle_despawn_worker` reports
    /// the failure rather than NotFound when it gets one.
    pub(crate) fn delete_worker_row(
        &self,
        project_key: &ProjectKey,
        label: &str,
    ) -> anyhow::Result<bool> {
        // Every failure here is logged where it happens: the callers that
        // roll a spawn back have nothing to do with an `Err` and would
        // otherwise drop it silently.
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            tracing::warn!(
                target: "forge_workspace::workspace",
                project = %project_key.as_str(),
                label = %label,
                "no configured project for this worker's key; its row is left where it is",
            );
            anyhow::bail!("no configured project for {}", project_key.as_str());
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "worker_row_delete_store_unavailable",
                project = %project_key.as_str(),
                label = %label,
                "the session store is unavailable; the worker's row is left where it is",
            );
            anyhow::bail!("the session store is unavailable this session");
        };
        match crate::store::sessions::delete(db, &org, &project, label) {
            Ok(existed) => Ok(existed),
            Err(error) => {
                tracing::error!(
                    target: "forge_workspace::workspace",
                    %error,
                    project = %project_key.as_str(),
                    label = %label,
                    "deleting a persisted worker failed; it may re-spawn on restart",
                );
                Err(error)
            }
        }
    }

    /// Every persisted worker row for `project_key`, the lead's own row
    /// excluded. Empty when the DB isn't open or the read fails. Backs
    /// the lead-reconnect re-spawn merge and the durable-identity read.
    pub(crate) fn worker_rows_for_project(
        &self,
        project_key: &ProjectKey,
    ) -> Vec<crate::store::sessions::SessionRecord> {
        self.worker_rows_for_project_strict(project_key).unwrap_or_else(|error| {
            tracing::warn!(
                target: "forge_workspace::workspace",
                %error,
                project = %project_key.as_str(),
                "listing persisted workers failed",
            );
            Vec::new()
        })
    }

    /// The project's durable worker rows, with a store failure surfaced
    /// rather than swallowed: a caller deciding whether a worktree path is
    /// free refuses on an unknown.
    pub(crate) fn worker_rows_for_project_strict(
        &self,
        project_key: &ProjectKey,
    ) -> anyhow::Result<Vec<crate::store::sessions::SessionRecord>> {
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            return Ok(Vec::new());
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            // A store that is not open is not a project without rows: a
            // caller deciding whether a path is free must refuse on the
            // unknown.
            anyhow::bail!(
                "the session store is unavailable, so project '{project}' has no readable \
                 worker rows"
            );
        };
        Ok(crate::store::sessions::list_for_project(db, &org, &project)?
            .into_iter()
            .filter(|row| row.label != forge_primitives::LEAD_LABEL)
            .collect())
    }

    /// Every persisted worker label the launchpad still offers, keyed by
    /// the project key it holds. A row the boot wave would not start is
    /// not among them, unless a live worker holds it as Failed: that row
    /// is the failure's own record, and its reason has to be drawable.
    ///
    /// The launchpad's worker rows read this once per frame, which is
    /// what the shape is for: one read transaction answers every project
    /// row, over a projection that skips each row's charter. Unlike
    /// [`Self::list_live_workers`] it answers before the project has
    /// launched, which is when the launchpad renders.
    ///
    /// Empty on a read failure rather than surfacing it, deliberately
    /// unlike the sibling `stored_worker_row`: the caller is a render
    /// path, where a warn plus a bare row beats failing the frame.
    pub fn worker_labels_by_project(&self) -> HashMap<ProjectKey, Vec<String>> {
        let rows = {
            let guard = self.db.lock();
            let Some(db) = guard.as_ref() else {
                return HashMap::new();
            };
            crate::store::sessions::worker_row_index(db).unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "listing persisted worker labels failed",
                );
                Vec::new()
            })
        };
        let views = self.list_projects();
        let mut out: HashMap<ProjectKey, Vec<String>> = HashMap::new();
        for row in rows {
            if row.label == forge_primitives::LEAD_LABEL {
                continue;
            }
            let Some(view) = views.iter().find(|v| v.org == row.org && v.name == row.project)
            else {
                continue;
            };
            // A live Failed row is the failure's own record: the start probe
            // would drop it with the reason it exists to show (#1593). Any
            // other row the wave would not start is not a worker the
            // launchpad can offer either - the same question, so the pane
            // and the wave answer it with one call. The tree it asks about is
            // the ROW's own: a worker pointed at another directory is offered
            // on that directory, not the project's.
            let failed_live = self.live_workers.lock().get(&view.key).is_some_and(|entries| {
                entries.iter().any(|entry| {
                    entry.label == row.label
                        && entry.status == forge_primitives::WorkerLiveness::Failed
                })
            });
            if failed_live
                || crate::mcp::workers::types::worker_row_can_start(
                    row.cwd.as_deref().map_or(view.path.as_path(), std::path::Path::new),
                    &row.label,
                    row.is_git_repo,
                    row.session_id.is_some(),
                )
            {
                out.entry(view.key.clone()).or_default().push(row.label);
            }
        }
        out
    }

    /// The row `label` holds in `project_key`. Distinct from
    /// [`Self::worker_rows_for_project`], which swallows a read failure as
    /// empty: this surfaces the error (and treats a missing store as one)
    /// so the cron fire router can tell "conclusively absent" from "could
    /// not read" and leave the cron on a hiccup.
    pub(crate) fn stored_worker_row(
        &self,
        project_key: &ProjectKey,
        label: &str,
    ) -> anyhow::Result<Option<crate::store::sessions::SessionRecord>> {
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            anyhow::bail!("no configured project for {}", project_key.as_str());
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            anyhow::bail!("the session store is unavailable this session");
        };
        crate::store::sessions::get(db, &org, &project, label)
    }

    /// Merge the supplied fields onto the worker row for `(project_key,
    /// label)`, leaving a `None` field at its stored value. Returns
    /// whether a row existed; this never creates one, because a row is
    /// what makes a worker re-spawn on the next lead connect. Read and
    /// write share one store lock so a concurrent despawn cannot land
    /// between them and resurrect the row.
    pub(crate) fn update_worker_row(
        &self,
        project_key: &ProjectKey,
        label: &str,
        charter: Option<String>,
        kick: Option<String>,
        resume_kick: Option<String>,
        mcp_families: Option<Vec<String>>,
    ) -> anyhow::Result<bool> {
        let Some((org, project)) = self.project_identity_for_key(project_key) else {
            anyhow::bail!("no configured project for {}", project_key.as_str());
        };
        let guard = self.db.lock();
        let Some(db) = guard.as_ref() else {
            anyhow::bail!("the session store is unavailable this session");
        };
        crate::store::sessions::update(
            db,
            &crate::store::sessions::SessionRecord {
                org,
                project,
                label: label.to_owned(),
                session_id: None,
                charter,
                kick,
                resume_kick,
                interactive: None,
                // An update of the worker's charter and kick says nothing
                // about whether a turn is running.
                seat_state: None,
                // `update` leaves an absent field alone; the gitness is
                // fixed at spawn and never re-decided here.
                is_git_repo: None,
                // Absent leaves the stored selection alone; `Some(empty)`
                // resets it to every family.
                mcp_families,
                // And absent leaves the stored tree alone: the tree is
                // fixed at spawn, the way the gitness is.
                cwd: None,
            },
        )
    }

    /// Scan the shared session-JSONL pool into a `UsageReport` for the
    /// `usage` subject. Query-style (a direct method, not a Command):
    /// reads the one real `projects` dir, refreshes the incremental
    /// per-file cache, and rolls the deduped summaries up into the four
    /// windows priced from the bundled table. Does blocking file IO, so
    /// callers run it off the UI thread.
    pub fn scan_usage(&self) -> forge_primitives::token_usage::UsageReport {
        use forge_agent::env::{timezone, token_usage};
        use time_tz::OffsetDateTimeExt;
        // Canonicalize so a symlinked projects tree is read once, not
        // once per alias.
        let projects_dir = forge_sdk::projects_dir_for(&self.config_dir);
        let projects_dir = std::fs::canonicalize(&projects_dir).unwrap_or(projects_dir);
        // Resolve the system timezone once so days bucket on the user's
        // wall clock, and derive "now" in the same zone for the windows.
        let tz = timezone::system_timezone();
        let summaries: Vec<_> = token_usage::usage_files(&projects_dir)
            .iter()
            .filter_map(|path| self.usage_summary_for(path, tz))
            .collect();
        let pricing = self.load_pricing();
        let now = time::OffsetDateTime::now_utc().to_timezone(tz);
        token_usage::roll_up(&summaries, &pricing, now)
    }

    /// Cached summary for `path` when its mtime and size still match,
    /// otherwise re-parse (bucketing by `tz`) and refresh the cache.
    /// `None` when the file vanished between listing and parsing.
    fn usage_summary_for(
        &self,
        path: &Path,
        tz: &time_tz::Tz,
    ) -> Option<forge_agent::env::token_usage::FileUsageSummary> {
        let key = path.to_string_lossy();
        let signature =
            std::fs::metadata(path).ok().and_then(|m| Some((m.modified().ok()?, m.len())));
        if let Some(mut cached) = self.load_usage_summary(&key)
            && signature.is_some_and(|(mtime, size)| cached.mtime == mtime && cached.size == size)
        {
            // An inactive session's mtime never changes, so a project
            // label guessed while its repo was absent would otherwise
            // outlive the checkout coming back.
            cached.refresh_unresolved_project(path);
            return Some(cached);
        }
        let parsed = forge_agent::env::token_usage::parse_file(path, tz)?;
        self.store_usage_summary(&key, &parsed);
        Some(parsed)
    }

    fn load_usage_summary(
        &self,
        path: &str,
    ) -> Option<forge_agent::env::token_usage::FileUsageSummary> {
        let guard = self.db.lock();
        let db = guard.as_ref()?;
        crate::store::token_usage::load(db, path).unwrap_or_else(|error| {
            tracing::warn!(
                target: "forge_workspace::workspace",
                %error,
                path = %path,
                "loading a usage summary failed",
            );
            None
        })
    }

    fn store_usage_summary(
        &self,
        path: &str,
        summary: &forge_agent::env::token_usage::FileUsageSummary,
    ) {
        if let Some(db) = self.db.lock().as_ref()
            && let Err(error) = crate::store::token_usage::store(db, path, summary)
        {
            tracing::warn!(
                target: "forge_workspace::workspace",
                %error,
                path = %path,
                "storing a usage summary failed",
            );
        }
    }

    /// Refresh the LiteLLM pricing cache when it is absent or older than
    /// a day, re-fetching immediately on a missed day. Fire-and-forget
    /// from a view: it fetches through the proxy-aware client and is a
    /// no-op on any network failure, so the last-good cache is kept.
    /// Returns whether a new price table was stored (so a caller can
    /// re-price without a redundant scan when nothing changed).
    /// The redb read and the ~1.6 MB write run on the blocking pool so
    /// the once-a-day fsync can't stall a UI frame.
    pub async fn refresh_pricing(self: &Arc<Self>) -> bool {
        let fresh = {
            let workspace = Arc::clone(self);
            tokio::task::spawn_blocking(move || workspace.pricing_is_fresh()).await.unwrap_or_else(
                |error| {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        %error,
                        "pricing freshness-check task failed; treating the cache as stale",
                    );
                    false
                },
            )
        };
        if fresh {
            return false;
        }
        let Some(json) = (self.pricing_fetcher)().await else {
            return false;
        };
        let workspace = Arc::clone(self);
        tokio::task::spawn_blocking(move || workspace.store_fresh_pricing(json))
            .await
            .unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::workspace",
                    %error,
                    "pricing store task failed; the cache was not updated",
                );
                false
            })
    }

    /// Store freshly-fetched pricing json unless it parses to an empty
    /// table - a garbage 200 must not wipe a good cache. Returns whether
    /// it stored.
    fn store_fresh_pricing(&self, json: String) -> bool {
        if forge_agent::env::token_usage::pricing::PricingTable::from_litellm_json(&json).is_empty()
        {
            tracing::warn!(
                target: "forge_workspace::workspace",
                "fetched pricing parsed to an empty table; keeping the existing cache",
            );
            return false;
        }
        self.store_pricing(&crate::store::pricing::CachedPricing {
            fetched_at: std::time::SystemTime::now(),
            json,
        });
        true
    }

    /// The cached pricing, or an empty table before the first fetch
    /// lands (a scan answered in the meantime reports tokens with a blank
    /// cost).
    fn load_pricing(&self) -> forge_agent::env::token_usage::pricing::PricingTable {
        use forge_agent::env::token_usage::pricing::PricingTable;
        let json = self.load_cached_pricing().map(|cached| cached.json);
        PricingTable::from_litellm_json(json.as_deref().unwrap_or("{}"))
    }

    /// Read the cached pricing snapshot, warning (not swallowing) on a
    /// redb or decode error so a corrupt cache is diagnosable.
    fn load_cached_pricing(&self) -> Option<crate::store::pricing::CachedPricing> {
        let guard = self.db.lock();
        let db = guard.as_ref()?;
        crate::store::pricing::load(db).unwrap_or_else(|error| {
            tracing::warn!(
                target: "forge_workspace::workspace",
                %error,
                "loading the pricing cache failed",
            );
            None
        })
    }

    /// Whether the cached pricing is younger than the daily refresh
    /// window; a missing or older cache is stale and re-fetched.
    fn pricing_is_fresh(&self) -> bool {
        const REFRESH_INTERVAL: std::time::Duration = std::time::Duration::from_secs(24 * 60 * 60);
        self.load_cached_pricing()
            .and_then(|cached| cached.fetched_at.elapsed().ok())
            .is_some_and(|age| age < REFRESH_INTERVAL)
    }

    fn store_pricing(&self, entry: &crate::store::pricing::CachedPricing) {
        if let Some(db) = self.db.lock().as_ref()
            && let Err(error) = crate::store::pricing::store(db, entry)
        {
            tracing::warn!(
                target: "forge_workspace::workspace",
                %error,
                "storing the pricing cache failed",
            );
        }
    }

    /// The canonical model forge stamped for `key`'s session: the
    /// project's declared `model`. `None` when the session has no
    /// project registration or the project declares no model.
    pub(crate) fn canonical_model_for_session(&self, key: &SessionSlot) -> Option<String> {
        let project_name = self
            .pool
            .lock()
            .get(key)
            .and_then(|entry| entry.registration.as_ref())
            .map(|registration| registration.project.clone())?;
        self.config_arc()
            .projects
            .iter()
            .find(|project| project.name == project_name)
            .and_then(|project| project.model.clone())
    }

    /// The `/model` picker rows for a session: the declared models of
    /// the session's org's accounts, in pin order, deduped.
    pub(crate) fn declared_models_for_session(
        &self,
        key: &SessionSlot,
    ) -> Vec<forge_primitives::runtime::AvailableModel> {
        let org = self
            .pool
            .lock()
            .get(key)
            .and_then(|entry| entry.registration.as_ref())
            .map(|registration| registration.org.clone());
        let Some(org) = org else {
            return Vec::new();
        };
        // The org's account walk order, from any of its projects
        // (the pin is shared across the org).
        let mut order: Vec<String> = Vec::new();
        let config = self.config_arc();
        if let Some(project) = config.projects.iter().find(|p| p.org == org) {
            order.extend(project.accounts.iter().cloned());
            order.extend(project.fallback_accounts.iter().cloned());
        }
        let mut seen = std::collections::HashSet::new();
        let mut rows = Vec::new();
        for name in order {
            let Some(account) = config.accounts.iter().find(|a| a.display_name == name) else {
                continue;
            };
            for model in &account.models {
                if seen.insert(model.clone()) {
                    rows.push(forge_primitives::runtime::AvailableModel::new(
                        model.clone(),
                        model.clone(),
                    ));
                }
            }
        }
        rows
    }

    /// Install a redb store into a test workspace so the durable-vs-
    /// ephemeral persistence path is exercisable without `Workspace::new`.
    #[cfg(any(test, feature = "test-helpers"))]
    pub fn install_db_for_test(&self, db: crate::store::Db) {
        *self.db.lock() = Some(db);
    }

    /// Snapshot every live worker's session_key across every project.
    /// Used for worker-key routing that excludes worker buckets
    /// from project-row click routing without depending on
    /// `list_projects()` for enumeration.
    pub fn all_live_worker_session_keys(&self) -> Vec<SessionSlot> {
        self.live_workers
            .lock()
            .values()
            .flat_map(|entries| entries.iter().map(|e| e.slot.clone()))
            .collect()
    }

    /// Insert a worker entry into `live_workers[project_key]`.
    /// `remove_latest_worker` resolves the single live match. The
    /// one-live-worker-per-label invariant is enforced by
    /// [`Self::insert_live_worker_if_label_absent`]; this raw push is for
    /// callers (tests, re-tag) that already own that guarantee.
    pub fn insert_live_worker(
        &self,
        project_key: &ProjectKey,
        entry: crate::mcp::workers::types::WorkerEntry,
    ) {
        self.live_workers.lock().entry(project_key.clone()).or_default().push(entry);
    }

    /// Insert `entry` only if no live (non-`Failed`) worker already holds
    /// its label in `project_key`, and - when `cap` is `Some` - only if
    /// that project's live worker count is under it. Holds
    /// `live_workers.lock()` across the label-check, the cap-check AND
    /// the push, so two genuinely-concurrent SpawnWorker dispatches (a
    /// reconnect re-spawn racing a manual `agents__spawn`, say) can't
    /// both pass a check-then-insert window and fork two subprocesses
    /// onto one worktree or overshoot the cap. The label check precedes
    /// the cap check, so a duplicate-label spawn at the cap reports the
    /// collision. `cap: None` is the boot re-spawn exemption. Returns
    /// `Ok(())` on insert. This is the sole enforcement point for the
    /// at-most-one-live-worker-per-label invariant and the per-project
    /// worker cap.
    pub fn insert_live_worker_if_label_absent(
        &self,
        project_key: &ProjectKey,
        entry: crate::mcp::workers::types::WorkerEntry,
        cap: Option<usize>,
    ) -> Result<(), LiveWorkerRefusal> {
        // The cleanup marker is read while holding the live registry's lock,
        // in the same order `mark_despawn_cleanup_pending` writes it, so a
        // spawn cannot pass between "the label is free" and "the cleanup is
        // remembered". A despawn marks before it tears its entry down; from
        // then until the cleanup ends, this refuses.
        let mut workers = self.live_workers.lock();
        if self.despawn_cleanup_pending(project_key, &entry.label) {
            return Err(LiveWorkerRefusal::CleanupPending);
        }
        if let Some(existing) = workers.get(project_key).and_then(|entries| {
            crate::mcp::workers::types::live_worker_with_label(entries, &entry.label)
        }) {
            return Err(LiveWorkerRefusal::LabelLive(existing.slot.clone()));
        }
        if let Some(cap) = cap {
            let live = workers
                .get(project_key)
                .map_or(0, |entries| crate::mcp::workers::types::live_worker_count(entries));
            if live >= cap {
                return Err(LiveWorkerRefusal::AtCap { live, cap });
            }
        }
        // **The heal's tombstone goes with the spawn that supersedes it.**
        // The label gate admits a same-label spawn because a `Restarting`
        // entry is not live, while the cap counts that entry; a push beside
        // it would count the slot twice, and the heal's timer aborts on the
        // now-live label, leaving a tombstone that holds a cap slot for the
        // rest of the run. Cleared after the refusals above, so a refused
        // spawn never frees the heal's slot.
        // **The heal's tombstone goes with the spawn that supersedes it.**
        // The label gate admits a same-label spawn because a `Restarting`
        // entry is not live, while the cap counts that entry; a push beside
        // it would count the slot twice, and the heal's timer aborts on the
        // now-live label, leaving a tombstone that holds a cap slot for the
        // rest of the run. Cleared after the refusals above, so a refused
        // spawn never frees the heal's slot.
        workers.entry(project_key.clone()).or_default().retain(|existing| {
            existing.slot != entry.slot
                || !matches!(existing.status, forge_primitives::WorkerLiveness::Restarting)
        });
        workers.entry(project_key.clone()).or_default().push(entry);
        Ok(())
    }

    /// Mark `label`'s despawn cleanup as in flight in `project_key`, and
    /// hand back the guard that releases it.
    ///
    /// A despawn takes this BEFORE its teardown, under the live registry's
    /// lock: from here until the cleanup ends the label must not read as
    /// free to a spawn, because the worktree that cleanup will delete is
    /// still on disk. `Drop` does the releasing, so a cleanup that returns
    /// early or panics cannot leave the label unspawnable for the run.
    pub(crate) fn mark_despawn_cleanup_pending(
        self: &Arc<Self>,
        project_key: &ProjectKey,
        label: &str,
    ) -> DespawnCleanupPending {
        {
            let _live = self.live_workers.lock();
            self.despawn_cleanups.lock().insert((project_key.clone(), label.to_owned()));
        }
        DespawnCleanupPending {
            workspace: Arc::clone(self),
            project_key: project_key.clone(),
            label: label.to_owned(),
        }
    }

    /// Whether `label`'s despawn cleanup is still running in `project_key`.
    pub(crate) fn despawn_cleanup_pending(&self, project_key: &ProjectKey, label: &str) -> bool {
        self.despawn_cleanups.lock().contains(&(project_key.clone(), label.to_owned()))
    }

    /// The project's cap-relevant worker count: the same number
    /// `insert_live_worker_if_label_absent` enforces against, read for
    /// `WorkerFacade::capacity`.
    pub fn count_live_workers(&self, project_key: &ProjectKey) -> usize {
        self.live_workers
            .lock()
            .get(project_key)
            .map_or(0, |entries| crate::mcp::workers::types::live_worker_count(entries))
    }

    /// Drop any failed tombstone for `label` before a restore appends its
    /// own entry.
    ///
    /// A failed spawn keeps its entry for a worker that has no worktree, so
    /// the failure stays on screen. That entry is not live, so the insert
    /// would append a second entry for the same slot, and the by-slot reads
    /// take the first match: the tombstone would move as the new session
    /// connects while the new entry stayed behind as a phantom. A restore
    /// supersedes the failure it replaces.
    pub(crate) fn clear_failed_worker(&self, project_key: &ProjectKey, label: &str) {
        let mut workers = self.live_workers.lock();
        if let Some(entries) = workers.get_mut(project_key) {
            entries.retain(|entry| entry.label != label || entry.is_live());
        }
    }

    /// Remove the latest-spawned worker matching `label` from
    /// `live_workers[project_key]`. Returns the removed entry, or
    /// `None` when no match exists.
    pub fn remove_latest_worker(
        &self,
        project_key: &ProjectKey,
        label: &str,
    ) -> Option<crate::mcp::workers::types::WorkerEntry> {
        let mut map = self.live_workers.lock();
        let entries = map.get_mut(project_key)?;
        let last_match_idx = entries.iter().rposition(|e| e.label == label)?;
        Some(entries.remove(last_match_idx))
    }

    /// Remove the worker whose `session_key` exactly matches across
    /// any project's `live_workers`. Used by the async-spawn-failure
    /// path so concurrent same-label spawns don't accidentally
    /// roll back the wrong entry (`remove_latest_worker` would peek
    /// the wrong one when two workers share a label). Returns the
    /// matched `(project_key, entry)` pair, or `None` when no entry
    /// matches.
    pub fn remove_worker_by_session_key(
        &self,
        session_key: &SessionSlot,
    ) -> Option<(ProjectKey, crate::mcp::workers::types::WorkerEntry)> {
        let mut map = self.live_workers.lock();
        for (project_key, entries) in map.iter_mut() {
            if let Some(idx) = entries.iter().position(|e| e.slot == *session_key) {
                let entry = entries.remove(idx);
                return Some((project_key.clone(), entry));
            }
        }
        None
    }

    /// Drain every worker entry for `project_key` and return them in
    /// insertion order.
    pub fn drain_live_workers(
        &self,
        project_key: &ProjectKey,
    ) -> Vec<crate::mcp::workers::types::WorkerEntry> {
        self.live_workers.lock().remove(project_key).unwrap_or_default()
    }

    /// Locate `(project_key, label, is_git_repo_at_spawn, needs_tag,
    /// cwd)` for any worker matching `session_key` across every
    /// project's `live_workers`. Used by the Connected handler in
    /// `SessionTask::translate_event` to decide whether a just-
    /// connected session is a worker (and what tag to write).
    /// `is_git_repo_at_spawn` lets the tag-write path route to the
    /// worktree-derived JSONL via `worker_tag_dir` in
    /// `crate::mcp::workers::types`, and `needs_tag` says whether that
    /// write has ever landed - the rollback reads it to tell a worker
    /// that never established itself from one that is simply re-tagging.
    /// `cwd` is the tree the spawn resolved, which every composed
    /// directory reads instead of the project's path.
    /// `None` when the session is a lead (or not a worker at all).
    pub fn worker_lookup_for_session(
        &self,
        session_key: &SessionSlot,
    ) -> Option<(ProjectKey, String, bool, bool, Option<std::path::PathBuf>)> {
        let workers = self.live_workers.lock();
        for (project_key, entries) in workers.iter() {
            if let Some(entry) = entries.iter().find(|e| e.slot == *session_key) {
                return Some((
                    project_key.clone(),
                    entry.label.clone(),
                    entry.is_git_repo_at_spawn,
                    entry.needs_tag,
                    entry.cwd.clone(),
                ));
            }
        }
        None
    }

    /// The tree a live worker runs in when that is NOT its project's own
    /// directory: the root its spawn resolved. `None` for a lead, for a
    /// worker in its project's directory, and for a worker this cannot
    /// place - so a caller that gets one has a tree to name.
    pub fn worker_tree_for_session(&self, session_key: &SessionSlot) -> Option<std::path::PathBuf> {
        let (project_key, _label, _is_git, _needs_tag, cwd) =
            self.worker_lookup_for_session(session_key)?;
        let root = self.live_worker_root(&project_key, cwd.as_deref())?;
        let project = self.project_root_for_key(&project_key)?;
        // Both sides resolve before they compare: a recorded root is
        // canonical, while a declared path may reach the same directory
        // through an alias.
        let same = match (std::fs::canonicalize(&root), std::fs::canonicalize(&project)) {
            (Ok(root), Ok(project)) => root == project,
            _ => root == project,
        };
        (!same).then_some(root)
    }

    /// What a worker's composed worktree path collides with, when it does:
    /// a declared project's own checkout, or the worktree of a worker
    /// under another project with the same label.
    ///
    /// The base is repository-global (#2460), so two projects of one
    /// repository - the main checkout and a linked worktree of it, or two
    /// linked worktrees - compose the same `<main>/.claude/worktrees/
    /// <label>` and the same `worktree-<label>` branch for one label. The
    /// one-live-worker guard is per project, so without this the second
    /// spawn would run in the first worker's tree and a despawn would
    /// remove it; a label naming a checkout parked under `.claude/worktrees`
    /// would do the same to that project. A crashed worker's row still
    /// claims its path until the row is closed - refusing is the safe
    /// direction - and a durable row claims it even with no in-memory
    /// entry (after a restart, before that project's lead connects).
    /// Callers refuse rather than reuse or remove. A separate forge
    /// process is not visible here.
    pub(crate) fn worktree_collision(
        &self,
        path: &std::path::Path,
        own: &ProjectKey,
        own_label: &str,
        own_op: WorktreeOp,
    ) -> Option<String> {
        let composed = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
        if let Some(reason) = self.claim_conflict(&composed, own, own_label, own_op) {
            return Some(reason);
        }
        for view in self.list_projects() {
            let declared = std::fs::canonicalize(&view.path).unwrap_or_else(|_| view.path.clone());
            if declared == composed {
                return Some(format!(
                    "'{}' is the checkout of project '{}'; a worker cannot run in, or be \
                     removed from, a project's own tree",
                    path.display(),
                    view.name
                ));
            }
        }
        // Snapshot the other projects' workers before composing: the tag
        // dir resolves a git root, and no subprocess runs under the
        // registry lock.
        let others: Vec<(ProjectKey, String, bool, Option<std::path::PathBuf>)> = {
            let workers = self.live_workers.lock();
            workers
                .iter()
                .filter(|(key, _)| *key != own)
                .flat_map(|(key, entries)| {
                    // Every state counts: a crashed worker's row still
                    // claims its path until the row is closed.
                    entries.iter().map(|entry| {
                        (
                            key.clone(),
                            entry.label.clone(),
                            entry.is_git_repo_at_spawn,
                            entry.cwd.clone(),
                        )
                    })
                })
                .collect()
        };
        for (key, label, is_git, cwd) in others {
            let Some(root) = self.live_worker_root(&key, cwd.as_deref()) else {
                continue;
            };
            let other = crate::mcp::workers::types::worker_tag_dir(&root, &label, is_git);
            let other = std::fs::canonicalize(&other).unwrap_or(other);
            if other == composed {
                let project = self
                    .project_identity_for_key(&key)
                    .map_or_else(|| key.as_str().to_owned(), |(_, name)| name);
                return Some(format!(
                    "the worker '{label}' of project '{project}' already holds '{}'",
                    path.display()
                ));
            }
        }
        // A worker with a durable row but no in-memory entry - after a
        // restart, or under a project whose lead has not connected yet -
        // still owns its tree on disk. The rows are the same any-state
        // rule: an old row claims the path until it is closed.
        for view in self.list_projects() {
            if view.key == *own {
                continue;
            }
            // A guard that cannot read the rows refuses: an unknown is not
            // a free path.
            let rows = match self.worker_rows_for_project_strict(&view.key) {
                Ok(rows) => rows,
                Err(error) => {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        event_name = "worktree_collision_rows_unreadable",
                        %error,
                        project = %view.name,
                        path = %path.display(),
                        "the project's worker rows could not be read, so the worktree path is \
                         refused rather than reused",
                    );
                    return Some(format!(
                        "could not read the worker rows of project '{}' ({error}), so '{}' \
                         cannot be known to be free",
                        view.name,
                        path.display()
                    ));
                }
            };
            for row in rows {
                if row.is_git_repo == Some(false) {
                    // A non-git worker's tree is its project root, never
                    // the composed worktree.
                    continue;
                }
                // A row from before the field existed still names the
                // path by base+label; refusing on that name is the safe
                // direction.
                let root =
                    row.cwd.as_deref().map_or_else(|| view.path.clone(), std::path::PathBuf::from);
                let other = crate::mcp::workers::types::worker_tag_dir(&root, &row.label, true);
                let other = std::fs::canonicalize(&other).unwrap_or(other);
                if other == composed {
                    return Some(format!(
                        "the worker '{}' of project '{}' already holds '{}'",
                        row.label,
                        view.name,
                        path.display()
                    ));
                }
            }
        }
        None
    }

    /// Claim the composed worktree path for this (project, label) while a
    /// spawn's ensure/insert or a despawn's removal acts on it.
    ///
    /// Re-entrant for the same owner: a resume's pre-ensure claim and the
    /// core handler's claim are one spawn. Refused when another project
    /// or label holds it, which is the repository-wide half of the
    /// one-live rule - the live registry is per project, and two projects
    /// of one repository compose the same path.
    pub(crate) fn claim_worktree(
        &self,
        path: &std::path::Path,
        project_key: &ProjectKey,
        label: &str,
        op: WorktreeOp,
    ) -> Result<WorktreeClaimGuard, String> {
        let path = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
        {
            let mut claims = self.worktree_claims.lock();
            match claims.get_mut(&path) {
                Some(claim)
                    if claim.project_key == *project_key
                        && claim.label == label
                        && claim.op == op =>
                {
                    claim.count += 1;
                }
                Some(claim) => {
                    return Err(self.claim_message(claim, &path));
                }
                None => {
                    claims.insert(
                        path.clone(),
                        WorktreeClaim {
                            project_key: project_key.clone(),
                            label: label.to_owned(),
                            op,
                            count: 1,
                        },
                    );
                }
            }
        }
        Ok(WorktreeClaimGuard { claims: Arc::clone(&self.worktree_claims), path })
    }

    /// What a composed path is claimed by, when a seat other than
    /// `own`/`own_label` on the SAME operation holds it. A different
    /// operation on the same owner and label is a conflict: a despawn must
    /// not enter a resume's claim.
    fn claim_conflict(
        &self,
        composed: &std::path::Path,
        own: &ProjectKey,
        own_label: &str,
        own_op: WorktreeOp,
    ) -> Option<String> {
        let claims = self.worktree_claims.lock();
        let claim = claims.get(composed)?;
        if claim.project_key == *own && claim.label == own_label && claim.op == own_op {
            return None;
        }
        Some(self.claim_message(claim, composed))
    }

    fn claim_message(&self, claim: &WorktreeClaim, path: &std::path::Path) -> String {
        let project = self
            .project_identity_for_key(&claim.project_key)
            .map_or_else(|| claim.project_key.as_str().to_owned(), |(_, name)| name);
        match claim.op {
            WorktreeOp::Spawn => format!(
                "the worktree '{}' is in use by the worker '{}' of project '{project}'",
                path.display(),
                claim.label
            ),
            WorktreeOp::Despawn => format!(
                "the worker '{}' of project '{project}' is still cleaning up the worktree '{}'",
                claim.label,
                path.display()
            ),
        }
    }

    /// What a composed path is held by, when it is held by anything other
    /// than a spawn of `own`/`own_label`: an in-flight claim of another
    /// owner or operation, or a live seat of ANY project (a same-project
    /// winner of a spawn race included). Used by a rollback deciding
    /// whether a tree it minted is still its own.
    pub(crate) fn worktree_held_elsewhere(
        &self,
        path: &std::path::Path,
        own: &ProjectKey,
        own_label: &str,
    ) -> Option<String> {
        let composed = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
        if let Some(reason) = self.claim_conflict(&composed, own, own_label, WorktreeOp::Spawn) {
            return Some(reason);
        }
        let seats: Vec<(ProjectKey, String, bool, Option<std::path::PathBuf>)> = {
            let workers = self.live_workers.lock();
            workers
                .iter()
                .flat_map(|(key, entries)| {
                    entries
                        .iter()
                        .filter(|entry| entry.is_live())
                        .map(|entry| {
                            (
                                key.clone(),
                                entry.label.clone(),
                                entry.is_git_repo_at_spawn,
                                entry.cwd.clone(),
                            )
                        })
                        .collect::<Vec<_>>()
                })
                .collect()
        };
        for (key, label, is_git, cwd) in seats {
            let Some(root) = self.live_worker_root(&key, cwd.as_deref()) else {
                continue;
            };
            let other = crate::mcp::workers::types::worker_tag_dir(&root, &label, is_git);
            let other = std::fs::canonicalize(&other).unwrap_or(other);
            if other == composed {
                let project = self
                    .project_identity_for_key(&key)
                    .map_or_else(|| key.as_str().to_owned(), |(_, name)| name);
                return Some(format!(
                    "the worktree '{}' is in use by the worker '{label}' of project '{project}'",
                    path.display()
                ));
            }
        }
        None
    }

    /// The tree a live worker's directory composes against: the one its
    /// spawn resolved, or the project's own `forge.toml` path when the
    /// spawn stated none. `None` when the session is not a live worker,
    /// or its project is no longer loaded.
    fn live_worker_root(
        &self,
        project_key: &ProjectKey,
        cwd: Option<&std::path::Path>,
    ) -> Option<std::path::PathBuf> {
        match cwd {
            Some(root) => Some(root.to_path_buf()),
            None => self.project_root_for_key(project_key),
        }
    }

    /// The working directory forge holds for `session_key`. Two
    /// sources, in order:
    /// 1. The sessions catalog (`session_cwd_for`). Leads only: the
    ///    boot scan hides worker-tagged sessions and the Connected
    ///    handler skips the catalog mirror for workers, so a worker
    ///    never has a row to read.
    /// 2. The worker registry (`live_workers` via
    ///    `worker_lookup_for_session`), composed by `worker_tag_dir`
    ///    against the tree the worker's spawn resolved - its own root
    ///    when it has one, the project's `forge.toml` path otherwise -
    ///    the worktree for a git worker, that root itself otherwise.
    ///    This is the authoritative source for every worker.
    ///
    /// `None` leaves the caller to decide what an unknown cwd means:
    /// `resume_cwd_for_slot` hands claude an empty cwd, while the
    /// review MCP reports `SessionCwdUnknown` to the caller.
    pub fn cwd_for_session(&self, session_key: &SessionSlot) -> Option<String> {
        if let Some(cwd) = self.session_cwd_for(session_key) {
            return Some(cwd);
        }
        let (project_key, label, is_git, _, cwd) = self.worker_lookup_for_session(session_key)?;
        let Some(root) = self.live_worker_root(&project_key, cwd.as_deref()) else {
            // Unreachable while `forge.toml` and `live_workers` agree,
            // so treat a firing as drift rather than a normal miss.
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "session_cwd_registry_contradiction",
                slot = %session_key.display(),
                project_key = project_key.as_str(),
                worker_label = %label,
                "worker registry resolves this session but no loaded project matches its \
                 project_key, so no cwd can be composed",
            );
            return None;
        };
        Some(
            crate::mcp::workers::types::worker_tag_dir(&root, &label, is_git)
                .to_string_lossy()
                .into_owned(),
        )
    }

    /// The extra document roots the seat's project declares: its
    /// `document_roots` entries, `~` expanded at load. Empty for a project
    /// that declares none, and for a slot whose project is not loaded.
    pub fn document_roots_for_session(&self, session_key: &SessionSlot) -> Vec<PathBuf> {
        self.project_for_slot(session_key).map(|project| project.document_roots).unwrap_or_default()
    }

    /// The cwd to pass `claude --resume` for the session at
    /// `session_key`: [`Self::cwd_for_session`], or an empty string
    /// when forge holds none (pass through and let the bridge surface
    /// ConnectionFailed - the session can't be resumed cleanly anyway).
    ///
    /// `claude --resume` does NOT receive a `--worktree` flag (see
    /// `SessionLaunchSettings::extra_args` in
    /// `forge-agent/src/client.rs` - lead/resume paths leave
    /// extra_args empty), so the subprocess cwd is the ONLY signal
    /// claude uses to derive the JSONL location. Handing a git
    /// worker just its project root makes claude look under the
    /// project's sanitised dir, miss the worker JSONL (which lives
    /// under the worktree's sanitised dir), and exit with "No
    /// conversation found with session ID:" (#245 Layer B).
    pub(crate) fn resume_cwd_for_slot(&self, session_key: &SessionSlot) -> String {
        self.cwd_for_session(session_key).unwrap_or_else(|| {
            tracing::warn!(
                target: "forge_workspace::workspace",
                slot = %session_key.display(),
                "resume_cwd_for_slot: no catalog cwd and no live worker entry; \
                 passing empty cwd to claude (resume will fail with ConnectionFailed)",
            );
            String::new()
        })
    }

    /// Look up a project root path by its `ProjectKey`. Searches
    /// the test overlay first (under `cfg(test)` / `feature =
    /// "testing"`), then `config.projects`. Returns `None` when no
    /// loaded project's path canonicalises to the given key.
    ///
    /// Used by [`Self::git_scan_cwd_for_session`] and
    /// [`Self::resume_cwd_for_slot`] to derive the project root
    /// from a worker's project_key without depending on the worker's
    /// `cwd_raw` value (which carries the project root for fresh
    /// spawns and the worktree path for resumed sessions - the two
    /// cases would otherwise need different composition logic).
    pub(crate) fn project_root_for_key(&self, target: &ProjectKey) -> Option<std::path::PathBuf> {
        self.project_for_key(target).map(|p| p.path)
    }

    /// The project whose path canonicalises to `target`. Consults the
    /// test overlay, like every other project lookup - a resolution
    /// that saw only `config.projects` would return `None` for a seeded
    /// project and make an absence assertion pass vacuously.
    /// The registry key for a project, resolved from its `forge.toml`
    /// name. `None` when the config no longer names it.
    pub(crate) fn project_key_for_name(&self, name: &str) -> Option<ProjectKey> {
        let project = self.find_project_view_by_name(name)?;
        Some(ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(
            Some(&project.path.to_string_lossy()),
        )))
    }

    pub(crate) fn project_for_key(&self, target: &ProjectKey) -> Option<LoadedProject> {
        let derive_key = |project: &LoadedProject| {
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                &project.path.to_string_lossy(),
            )))
        };
        #[cfg(any(test, feature = "testing"))]
        {
            if let Some(project) =
                self.test_extra_projects.lock().iter().find(|p| &derive_key(p) == target).cloned()
            {
                return Some(project);
            }
        }
        // `None` when two projects share the key rather than the first
        // match: the key sanitises away punctuation and resolves
        // symlinks, so one repo declared under two org scopes collides.
        // Picking either would hand one project's env to the other's
        // sessions; no project env is the failure that cannot leak.
        let config = self.config_arc();
        let mut matches = config.projects.iter().filter(|p| &derive_key(p) == target);
        let first = matches.next()?;
        if matches.next().is_some() {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "project_key_ambiguous",
                project_key = target.as_str(),
                "two projects resolve to this session-storage key, so neither project's \
                 settings are applied - give them distinct paths, or merge the entries if they \
                 are the same directory declared twice",
            );
            return None;
        }
        Some(first.clone())
    }

    /// Resolve the cwd a git-diff scan should run against for the
    /// session at `session_key`. Workers spawned in a git tree run
    /// inside claude's `--worktree <label>` fork at
    /// `<base>/.claude/worktrees/<label>/` (`base` the canonical root of
    /// the tree the worker's spawn resolved - its own when it has one, the
    /// project's `forge.toml` path otherwise), and the worker's `cwd_raw`
    /// carries different values depending on lifecycle:
    /// - fresh spawn -> `cwd_raw = <root>` (the value claude
    ///   sends in `AgentEvent::Connected.cwd` before it chdirs into
    ///   the worktree),
    /// - resumed session -> `cwd_raw = <base>/.claude/worktrees/<label>`
    ///   (claude chdirs before writing the first catalog row, so the
    ///   resume path reads the worktree path back as `cwd`).
    ///
    /// Anchor the composition on the worker's own tree (via
    /// [`Self::worker_lookup_for_session`] + the internal
    /// `live_worker_root` lookup) rather than `cwd_raw` so both
    /// lifecycle states resolve to the same final path. For non-
    /// worker sessions (project leads), non-git workers, or workers
    /// whose root can't be resolved, returns `cwd_raw` unchanged.
    pub fn git_scan_cwd_for_session(
        &self,
        session_key: &SessionSlot,
        cwd_raw: &std::path::Path,
    ) -> std::path::PathBuf {
        let Some((project_key, label, is_git_repo_at_spawn, _, cwd)) =
            self.worker_lookup_for_session(session_key)
        else {
            // Trace-level so a real lookup-miss (race during
            // worker spawn, lead-session call) leaves a grep-able
            // trail without flooding normal logs. The lead-session
            // case is the common path and intentionally not
            // promoted higher.
            tracing::trace!(
                target: "forge_workspace::git_scan",
                slot = %session_key.display(),
                "no worker lookup; using cwd_raw unchanged"
            );
            return cwd_raw.to_path_buf();
        };
        if !is_git_repo_at_spawn {
            // Non-git workers don't fork into a worktree; they run
            // in their tree itself, so `cwd_raw` is already
            // the correct scan target.
            return cwd_raw.to_path_buf();
        }
        let Some(root) = self.live_worker_root(&project_key, cwd.as_deref()) else {
            // Root lookup miss is structurally unusual (a worker
            // entry exists but its project_key doesn't resolve to a
            // loaded project) - log so a regression on the
            // forge.toml refresh path is visible, then fall back to
            // cwd_raw rather than synthesise a wrong path.
            tracing::warn!(
                target: "forge_workspace::git_scan",
                slot = %session_key.display(),
                project_key = project_key.as_str(),
                "worker entry present but its tree could not be resolved; falling back to cwd_raw"
            );
            return cwd_raw.to_path_buf();
        };
        crate::mcp::workers::types::worker_tag_dir(&root, &label, true)
    }

    /// Handle an async worker-spawn failure. Two paths, branching
    /// on the classifier outcome (#245 Layer C):
    ///
    /// - **Worktree-creation failure** (the worker never actually
    ///   started because git worktree setup failed): roll back the
    ///   `WorkerEntry` (the worker doesn't exist; the user-visible
    ///   signal is a typed notice routed to the lead's chat) and
    ///   emit `WorkerStatusChanged { Removed }`. Mirrors the sync
    ///   rollback in `handle_spawn_worker`.
    /// - **Any other failure** (resume against missing JSONL,
    ///   generic dispatch error, claude subprocess exit, etc.):
    ///   keep the `WorkerEntry` and transition it to
    ///   [`WorkerLiveness::Failed`](forge_primitives::WorkerLiveness::Failed)
    ///   with the first line of the message as the diagnostic. The Projects
    ///   pane renders the worker as a red `✕` with a DIM sub-row carrying the
    ///   diagnostic, so a stuck-Spawning-forever case becomes visible instead
    ///   of silently disappearing.
    ///
    /// The classifier uses `is_git_repo_at_spawn` + substring match
    /// against the bridge-wrapped message; see
    /// [`classify_worker_spawn_failure`] for the routing rules and
    /// the bridge-prefix contract.
    ///
    /// Returns `true` when the caller IS a worker (so it knows the
    /// failure was consumed here - the existing `ConnectionFailed`
    /// emission still fires for the view side). `false` for lead
    /// sessions or any other non-worker, in which case the caller's
    /// existing behaviour proceeds unchanged.
    ///
    /// [`classify_worker_spawn_failure`]: crate::mcp::workers::facade::classify_worker_spawn_failure
    pub(crate) fn handle_async_worker_spawn_failure(
        self: &Arc<Self>,
        session_key: &SessionSlot,
        message: &str,
        kind: forge_agent::client::SpawnFailureKind,
    ) -> bool {
        // Look up the worker entry WITHOUT removing it yet - the
        // worktree-failure path still removes (rollback semantics
        // for "worker never existed"); the general-failure path
        // transitions to Failed so the user sees what happened.
        //
        // A failed spawn reports the key it ran under, which is the one
        // its entry holds: every worker spawn, fresh or resumed, hands
        // both the same string.
        let Some((project_key, entry)) = ({
            let workers = self.live_workers.lock();
            workers.iter().find_map(|(project_key, entries)| {
                entries
                    .iter()
                    .find(|e| e.slot == *session_key)
                    .map(|entry| (project_key.clone(), entry.clone()))
            })
        }) else {
            return false;
        };
        // A payload parked for this worker's label has no session left to
        // drain it, so its bucket goes with the spawn.
        self.expire_parked_for_slot(
            &entry.slot,
            crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
        );
        // Classify against the entry's recorded is_git_repo_at_spawn
        // flag - same heuristic the sync agents__spawn path uses.
        let classified = crate::mcp::workers::facade::classify_worker_spawn_failure(
            message,
            entry.is_git_repo_at_spawn,
            kind,
        );
        if let crate::mcp::workers::facade::WorkerSpawnError::WorktreeCreationFailed { reason } =
            &classified
        {
            // Worktree-creation failure: roll back the worker entry
            // (the worker never existed; the user-visible signal is
            // the typed notice routed to the lead, not the worker row).
            self.remove_worker_by_session_key(&entry.slot);
            // The failure record goes with the row this arm deletes, or the
            // slot reads Failed with nothing left to clear it.
            self.clear_spawn_failure(session_key);
            // Same release the tag-rollback arm runs: without it the
            // pool entry + command sender + domain handle + SessionTask
            // leak per failed fresh spawn, unbounded across retries.
            self.release_session(session_key);
            // A dynamic worker persisted its row on the optimistic spawn
            // reply, before this async failure. A worktree-creation
            // failure is a hard removal (the worker never started), so
            // delete the row too - otherwise it zombie-re-spawns every
            // restart despite a visibly-failed spawn. The
            // transition-to-Failed path below
            // deliberately keeps the row: a Failed-but-visible worker
            // wasn't despawned, so it should re-spawn to recover or
            // re-fail visibly.
            let _ = self.delete_worker_row(&project_key, &entry.label);
            // Notice goes to the lead session that spawned this
            // worker. Use the workspace's update channel + a fresh
            // Command::Prompt so the lead's claude subprocess sees
            // the envelope as a user turn and the view render path
            // picks up the bracketed prefix via forge_server::envelope::detect_inbound.
            let lead_slot = entry.spawned_by.clone();
            let pool_has_lead = self.pool.lock().contains_key(&lead_slot);
            if pool_has_lead {
                let wrapped = WrappedPrompt {
                    id: MessageId::mint(),
                    kind: WrappedKind::WorkerSpawnFailedNotice,
                    sender_name: entry.label.clone(),
                    sender_org: String::new(),
                    body: reason.clone(),
                };
                let uuid = forge_sdk::request_id::next_prompt_id();
                if let Err(err) = self.dispatch_workspace_prompt_under(
                    &lead_slot,
                    wrapped.to_prose(),
                    PromptSource::Peer,
                    uuid.clone(),
                ) {
                    tracing::warn!(
                        target: "forge_workspace::worker_async_failure",
                        project = %project_key.as_str(),
                        label = %entry.label,
                        error = ?err,
                        "WorkerSpawnFailedNotice dispatch to lead failed",
                    );
                }
                // And the visible echo, the way every other injected prompt
                // paints one: the CLI does not echo a prompt it was handed on
                // stdin, so a view that only drew the wire would show nothing
                // until the page reloaded.
                crate::spawn::push_peer_user_turn_into_chat(self, &lead_slot, &wrapped, &uuid);
            } else {
                tracing::warn!(
                    target: "forge_workspace::worker_async_failure",
                    project = %project_key.as_str(),
                    label = %entry.label,
                    slot = %lead_slot.display(),
                    "worker spawn failed but lead session is gone; dropping notice",
                );
            }
            // Emit WorkerStatusChanged::Removed - parity with the
            // sync rollback in handle_spawn_worker.
            let _ = self.update_tx.send(SessionUpdate::WorkerStatusChanged {
                project_key,
                action: crate::protocol::WorkerStatusAction::Removed,
                status: entry.to_status(),
                // Creating the worktree is what failed, and nothing
                // cleans up a partial one, so Absent is the only claim
                // that holds either way.
                worktree: crate::protocol::WorktreeDisposition::Absent,
            });
        } else {
            // Non-worktree failure (resume not found, generic
            // ConnectionFailed, etc.): transition to Failed via
            // Layer A's machinery. The worker entry stays visible
            // in `live_workers` + the Projects pane renders it as
            // `✕` with the captured message as the diagnostic
            // sub-row. Without this, the worker would vanish (as
            // it did pre-#245) and the user would be left wondering
            // why a team worker disappeared mid-flight.
            let diagnostic = message.lines().next().map(str::to_owned);
            transition_worker_to_failed(self, &project_key, &entry.slot, diagnostic);
        }
        true
    }

    /// Mark a git worker Failed and release its session when the worktree its
    /// connect is about to run in is gone or unusable. Answers whether it
    /// did, so the first-connect branch can stop before it kicks the worker,
    /// announces it live or hands it parked prompts (#1593).
    ///
    /// The path composes from the row's own root, never the connect cwd: a
    /// resumed worker connects with its worktree as cwd, and composing from
    /// that doubled the path in the reason.
    pub(crate) fn fail_worker_without_worktree(self: &Arc<Self>, slot: &SessionSlot) -> bool {
        let Some((project_key, label, is_git, _, root)) = self.worker_lookup_for_session(slot)
        else {
            return false;
        };
        if !is_git {
            return false;
        }
        let Some(root) = self.live_worker_root(&project_key, root.as_deref()) else {
            return false;
        };
        let path = crate::mcp::workers::types::worker_tag_dir(&root, &label, true);
        let Some(reason) = forge_agent::env::worktree::worktree_missing_reason(&path) else {
            return false;
        };
        tracing::warn!(
            target: "forge_workspace::workspace",
            event_name = "worker_worktree_gone_at_connect",
            slot = %slot.display(),
            label = %label,
            worktree = %path.display(),
            "the worker's worktree is not usable at connect; the worker is marked failed",
        );
        transition_worker_to_failed(self, &project_key, slot, Some(reason));
        // A Failed row means nothing is running: every other Failed
        // transition releases the session, and a pooled handle here would let
        // a later re-spawn fast-path a child under an id the row no longer
        // means.
        self.release_session(slot);
        true
    }

    /// Tag a worker session's JSONL with `forge:worker:<label>` and
    /// transition its `WorkerEntry` from `Spawning` to `Running`.
    /// Called from `SessionTask::translate_event` on the worker's first
    /// `Connected`.
    ///
    /// `cwd` is the tree the worker runs in (the `directory`
    /// discriminator `tag_session` uses to find the right `.jsonl` when
    /// CONFIG_DIR hosts multiple project directories).
    ///
    /// The tag-write races against claude CLI's first JSONL write. For
    /// workers spawned with an `initial_prompt`, the file lands within
    /// ~100 ms-2 s of `Connected`, so a 30 x 100 ms retry loop reliably
    /// catches it. For idle-spawned workers (no prompt) claude doesn't
    /// create the JSONL at all until the first user turn arrives later,
    /// so the retry will exhaust with `Io(NotFound)`. That's NOT a
    /// rollback condition - we keep the worker live (it's fully
    /// functional from `live_workers`), transition to `Running`, mark
    /// the entry `needs_tag = true`, and emit `StatusChanged`. The
    /// opportunistic retry on first `DeliverWorkerPrompt`
    /// (see `spawn::handle_deliver_worker_prompt`) catches it once
    /// claude is processing the turn.
    ///
    /// Other errors (permission denied, disk full, invalid UUID) still
    /// indicate the worker can't be properly tracked on disk, so we
    /// roll back: remove from `live_workers`, release the session, emit
    /// a `Removed` status event.
    ///
    /// The tag-write runs in a detached tokio task to keep
    /// `translate_event` synchronous.
    ///
    /// Idempotent - calling twice for the same session_key is a no-op
    /// if the entry is already `Running`.
    pub(crate) fn apply_worker_tag_or_rollback(
        self: &Arc<Self>,
        session_key: &SessionSlot,
        session_id: &str,
        cwd: &str,
        minted_row: bool,
    ) {
        let Some((project_key, label, is_git_repo_at_spawn, needs_tag, _)) =
            self.worker_lookup_for_session(session_key)
        else {
            return;
        };
        // Resolve the config_dir for this session via the bridge so
        // the tag-write lands under the workspace's projects/ tree.
        let Some(config_dir) = self.config_dir_for(session_key) else {
            tracing::warn!(
                target: "forge_workspace::workspace",
                slot = %session_key.display(),
                "apply_worker_tag: no agent registered; cannot resolve config_dir"
            );
            return;
        };
        self.apply_worker_tag_or_rollback_with_config_dir(
            session_key,
            session_id,
            &project_key,
            &label,
            cwd,
            is_git_repo_at_spawn,
            needs_tag,
            minted_row,
            &config_dir,
        );
    }

    /// Testable inner of [`Self::apply_worker_tag_or_rollback`] that
    /// takes the resolved `config_dir` directly. The production caller
    /// resolves via `config_dir_for`; unit tests pass a tempdir to
    /// exercise the retry / rollback / deferred branches without
    /// having to register a full `AgentHandle`.
    ///
    /// `cwd` is the tree this worker runs in - the root its spawn
    /// resolved, which is the project's `forge.toml` path for a worker
    /// that stated none. For git-repo workers
    /// (`is_git_repo_at_spawn = true`) the tag-write is routed to
    /// `<base>/.claude/worktrees/<label>` via
    /// [`crate::mcp::workers::types::worker_tag_dir`], `base` the CLI's
    /// main working tree, so the lookup matches where claude's
    /// `--worktree <label>` actually wrote the JSONL.
    ///
    /// `needs_tag` and `minted_row` together decide whether a rollback
    /// takes the worker's durable row with it; see the arm below.
    pub(crate) fn apply_worker_tag_or_rollback_with_config_dir(
        self: &Arc<Self>,
        session_key: &SessionSlot,
        session_id: &str,
        project_key: &ProjectKey,
        label: &str,
        cwd: &str,
        is_git_repo_at_spawn: bool,
        needs_tag: bool,
        minted_row: bool,
        config_dir: &std::path::Path,
    ) {
        let effective_cwd = crate::mcp::workers::types::worker_tag_dir(
            std::path::Path::new(cwd),
            label,
            is_git_repo_at_spawn,
        );
        // **The spawn checked the path before claude created it; nothing
        // read it again.** A worktree removed before the session connected
        // otherwise left the worker reading live with nowhere to work
        // (#1593). That read is `fail_worker_without_worktree`'s, on the
        // first-connect path before this tag write runs.
        self.apply_worker_tag_or_rollback_with_budget(
            session_key,
            session_id,
            project_key,
            label,
            &effective_cwd,
            WorkerTagFacts { needs_tag, minted_row },
            config_dir,
            WorkerTagRetryBudget {
                max_attempts: WORKER_TAG_RETRY_ATTEMPTS,
                delay: WORKER_TAG_RETRY_DELAY,
            },
        );
    }

    /// [`Self::apply_worker_tag_or_rollback_with_config_dir`] with the
    /// worktree-aware tag directory and the retry budget both injected,
    /// so a test can shrink the detached task's wall time and derive its
    /// own wait from the same numbers the task runs on.
    pub(crate) fn apply_worker_tag_or_rollback_with_budget(
        self: &Arc<Self>,
        session_key: &SessionSlot,
        session_id: &str,
        project_key: &ProjectKey,
        label: &str,
        effective_cwd: &std::path::Path,
        facts: WorkerTagFacts,
        config_dir: &std::path::Path,
        budget: WorkerTagRetryBudget,
    ) {
        use tracing::Instrument;
        let WorkerTagFacts { needs_tag, minted_row } = facts;
        let workspace = Arc::clone(self);
        let project_key = project_key.clone();
        let session_key = session_key.clone();
        let session_id = session_id.to_owned();
        let label = label.to_owned();
        let effective_cwd = effective_cwd.to_path_buf();
        let config_dir = config_dir.to_path_buf();
        let span = tracing::info_span!(
            "forge_workspace::worker_tag_write",
            slot = %session_key.display(),
            label = %label,
        );
        let Some((org, name)) = self.project_identity_for_key(&project_key) else {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "worker_tag_project_unknown",
                project = %project_key.as_str(),
                label = %label,
                "the worker's project is no longer configured, so its transcript is not tagged; \
                 an unscoped row would be another project's to adopt",
            );
            return;
        };
        let project = format!("{org}/{name}");
        tokio::spawn(async move {
            let tag = forge_primitives::worker_tag(&label);
            let result = tag_session_with_retry(
                &config_dir,
                &session_id,
                &tag,
                &project,
                &effective_cwd.to_string_lossy(),
                budget.max_attempts,
                budget.delay,
            )
            .await;
            match result {
                Ok(()) => {
                    transition_worker_to_running(
                        &workspace,
                        &project_key,
                        &session_key,
                        TagWriteResult::Succeeded,
                    );
                }
                Err(forge_sdk::Error::Io(io_err))
                    if io_err.kind() == std::io::ErrorKind::NotFound =>
                {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        slot = %session_key.display(),
                        label = %label,
                        "tag_session_deferred: JSONL not yet on disk after retries; worker stays Running, tag will retry on first turn"
                    );
                    transition_worker_to_running(
                        &workspace,
                        &project_key,
                        &session_key,
                        TagWriteResult::DeferredNotFound,
                    );
                }
                Err(err) => {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        slot = %session_key.display(),
                        label = %label,
                        error = ?err,
                        "tag_session failed for worker (non-NotFound); rolling back spawn"
                    );
                    let removed = workspace.remove_latest_worker(&project_key, &label);
                    if let Some(entry) = removed {
                        // The row goes with the worker only when all
                        // three hold: this connection is the first of a
                        // spawn that minted the row, and the worker never
                        // got as far as a tag.
                        //
                        // Every other shape of this arm - a resume, a
                        // boot re-spawn, a `/new` re-tag - runs over a
                        // row that pre-existed and holds the worker's
                        // charter, kick and the id being resumed, and the
                        // row is the worker rather than this spawn's
                        // leftover: deleting it loses a worker that only
                        // failed to write a JSONL tag. The `/new` case is
                        // why `minted_row` carries the first-connect half:
                        // a `/new` reuses this task and its domain, so the
                        // spawn's provenance is still stamped there, and
                        // only the Connected count tells the two apart.
                        //
                        // `needs_tag` is what separates those from the
                        // case this arm exists for. The spawn sets it and
                        // the first successful tag write clears it, so a
                        // row still carrying it belongs to a worker that
                        // never established itself on disk.
                        if minted_row && needs_tag {
                            let _ = workspace.delete_worker_row(&project_key, &label);
                        }
                        let worktree = crate::protocol::WorktreeDisposition::untouched(
                            entry.is_git_repo_at_spawn,
                        );
                        let _ = workspace.update_tx.send(SessionUpdate::WorkerStatusChanged {
                            project_key,
                            action: crate::protocol::WorkerStatusAction::Removed,
                            status: entry.to_status(),
                            worktree,
                        });
                    }
                    workspace.release_session(&session_key);
                }
            }
        }
        .instrument(span));
    }

    /// Opportunistically retry the JSONL tag-write for a worker whose
    /// `needs_tag` flag is set. Called by
    /// `spawn::handle_deliver_worker_prompt` when a `DeliverWorkerPrompt`
    /// arrives for a worker that was spawned idle (no `initial_prompt`)
    /// and therefore had no JSONL at `Connected`. By the time the first
    /// turn fires, claude is writing the JSONL, so the tag-write should
    /// succeed within a turn or two.
    ///
    /// On success: clear `needs_tag` and emit
    /// `WorkerStatusChanged { StatusChanged }`.
    ///
    /// On failure (any kind): log warn, leave `needs_tag = true` so the
    /// next turn retries again. Never rolls back - the worker stays
    /// functional regardless of the tag's on-disk state.
    pub(crate) fn retry_worker_tag_opportunistic(
        self: &Arc<Self>,
        project_key: &ProjectKey,
        session_key: &SessionSlot,
        session_id: &str,
        label: &str,
        cwd: &str,
        is_git_repo_at_spawn: bool,
    ) {
        let Some(config_dir) = self.config_dir_for(session_key) else {
            tracing::warn!(
                target: "forge_workspace::workspace",
                slot = %session_key.display(),
                "retry_worker_tag: no agent registered; cannot resolve config_dir"
            );
            return;
        };
        self.retry_worker_tag_opportunistic_with_config_dir(
            project_key,
            session_key,
            session_id,
            label,
            cwd,
            is_git_repo_at_spawn,
            &config_dir,
        );
    }

    /// Testable inner of [`Self::retry_worker_tag_opportunistic`] that
    /// takes the resolved `config_dir` directly. Same shape as the
    /// `_with_config_dir` variant of `apply_worker_tag_or_rollback`,
    /// including the worktree-aware cwd routing for git-repo workers.
    pub(crate) fn retry_worker_tag_opportunistic_with_config_dir(
        self: &Arc<Self>,
        project_key: &ProjectKey,
        session_key: &SessionSlot,
        session_id: &str,
        label: &str,
        cwd: &str,
        is_git_repo_at_spawn: bool,
        config_dir: &std::path::Path,
    ) {
        use tracing::Instrument;
        let workspace = Arc::clone(self);
        let project_key = project_key.clone();
        let session_key = session_key.clone();
        let session_id = session_id.to_owned();
        let label = label.to_owned();
        let effective_cwd = crate::mcp::workers::types::worker_tag_dir(
            std::path::Path::new(cwd),
            &label,
            is_git_repo_at_spawn,
        );
        let config_dir = config_dir.to_path_buf();
        let span = tracing::info_span!(
            "forge_workspace::worker_tag_write",
            slot = %session_key.display(),
            label = %label,
        );
        let Some((org, name)) = self.project_identity_for_key(&project_key) else {
            tracing::warn!(
                target: "forge_workspace::workspace",
                event_name = "worker_tag_project_unknown",
                project = %project_key.as_str(),
                label = %label,
                "the worker's project is no longer configured, so its transcript is not tagged; \
                 an unscoped row would be another project's to adopt",
            );
            return;
        };
        let project = format!("{org}/{name}");
        tokio::spawn(async move {
            let tag = forge_primitives::worker_tag(&label);
            let result = tag_session_with_retry(
                &config_dir,
                &session_id,
                &tag,
                &project,
                &effective_cwd.to_string_lossy(),
                WORKER_TAG_RETRY_ATTEMPTS,
                WORKER_TAG_RETRY_DELAY,
            )
            .await;
            match result {
                Ok(()) => {
                    let updated = {
                        let mut workers = workspace.live_workers.lock();
                        workers.get_mut(&project_key).and_then(|entries| {
                            entries.iter_mut().find(|e| e.slot == session_key).map(|entry| {
                                entry.needs_tag = false;
                                (entry.to_status(), entry.is_git_repo_at_spawn)
                            })
                        })
                    };
                    if let Some((status, is_git_repo_at_spawn)) = updated {
                        tracing::info!(
                            target: "forge_workspace::workspace",
                            slot = %session_key.display(),
                            label = %label,
                            "tag_session_retry: deferred tag-write succeeded on opportunistic retry"
                        );
                        let _ = workspace.update_tx.send(SessionUpdate::WorkerStatusChanged {
                            project_key,
                            action: crate::protocol::WorkerStatusAction::StatusChanged,
                            status,
                            worktree: crate::protocol::WorktreeDisposition::untouched(
                                is_git_repo_at_spawn,
                            ),
                        });
                    }
                }
                Err(err) => {
                    tracing::warn!(
                        target: "forge_workspace::workspace",
                        slot = %session_key.display(),
                        label = %label,
                        error = ?err,
                        "tag_session_retry: opportunistic retry failed; will try again on next turn"
                    );
                }
            }
        }
        .instrument(span));
    }

    // ---- Refresh helpers (workspace → agent) ----
    //
    // These two methods are query-style: a view says "re-emit state X
    // for `key`" and the payload returns via `SessionUpdate`. They
    // bypass the [`Command`] envelope because they don't carry
    // mutation state, and they need the workspace-side
    // `Arc<AgentHandle>` lookup rather than per-session task routing.

    /// Request a fresh context-usage snapshot for `key`. The bridge
    /// replies via [`SessionUpdate::ContextUsageSnapshot`].
    ///
    /// # Errors
    ///
    /// Returns [`DispatchError::UnknownSession`] when no agent is
    /// registered for `key` (e.g., the session was just closed) or
    /// when the bridge hasn't stamped a `session_id` yet.
    pub fn refresh_context_usage(&self, key: &SessionSlot) -> Result<(), DispatchError> {
        let (handle, sid) = self.handle_and_session_id(key)?;
        handle.get_context_usage(sid).map_err(|_| DispatchError::SessionClosed(key.clone()))
    }

    /// Request a fresh MCP server snapshot for `key`. The bridge
    /// replies via [`SessionUpdate::McpSnapshot`].
    ///
    /// # Errors
    ///
    /// See [`Self::refresh_context_usage`].
    pub fn refresh_mcp_snapshot(&self, key: &SessionSlot) -> Result<(), DispatchError> {
        let (handle, sid) = self.handle_and_session_id(key)?;
        handle.get_mcp_snapshot(sid).map_err(|_| DispatchError::SessionClosed(key.clone()))
    }

    /// Record the OS walk of `key`'s process tree for views to read.
    ///
    /// The walk itself belongs to whoever owns the tick that drives it,
    /// because a walk is a `sysinfo` refresh that costs tens of
    /// milliseconds and no read should pay for one. The answer belongs
    /// here, so a second view reads the tree rather than walking the OS
    /// again. `None` clears it: the walk described a subprocess tree
    /// that is gone.
    ///
    /// No-op for a slot with no session: minting a domain for whoever
    /// asked would leave the workspace routing to a session nobody runs.
    pub fn store_process_snapshot(
        &self,
        key: &SessionSlot,
        snapshot: Option<forge_agent::env::processes::ProcessSnapshot>,
    ) {
        if let Some(domain) = self.domain_session_for(key) {
            domain.lock().process_snapshot = snapshot;
        }
    }

    /// The last OS walk of `key`'s process tree, or `None` when nothing
    /// has walked it or the tree it described is gone.
    pub fn process_snapshot(
        &self,
        key: &SessionSlot,
    ) -> Option<forge_agent::env::processes::ProcessSnapshot> {
        self.domain_session_for(key)?.lock().process_snapshot.clone()
    }

    // ---- Direct-accessor facades (workspace owns the bridge call) ----

    /// Resolve the auto-memory path the bridge would consult for
    /// `cwd`, scoped to `key`'s configured account. Returns `None`
    /// when no agent is registered for `key`.
    pub fn project_memory_path(&self, key: &SessionSlot, cwd: &std::path::Path) -> Option<PathBuf> {
        let handle = self.agent_handle_for(key)?;
        Some(handle.project_memory_path(cwd))
    }

    /// Snapshot the bridge's settings documents for `key` at `cwd`.
    /// Returns `None` when no agent is registered for `key`.
    pub fn settings_documents(
        &self,
        key: &SessionSlot,
        cwd: Option<&std::path::Path>,
    ) -> Option<forge_agent::userdata::settings::SettingsDocuments> {
        let handle = self.agent_handle_for(key)?;
        Some(handle.settings_documents(cwd))
    }

    /// The CLI's per-user preferences document, from `$HOME/.claude.json`.
    ///
    /// Read on each call rather than held, because the user can change a
    /// preference while forge runs.
    pub fn user_preferences(&self) -> Option<serde_json::Value> {
        #[cfg(any(test, feature = "testing"))]
        {
            if let Some(seeded) = self.test_user_preferences.lock().clone() {
                return Some(seeded);
            }
        }
        forge_agent::userdata::settings::user_preferences()
    }

    /// Resolve the agent's configured config_dir for `key`. Returns
    /// `None` when no agent is registered for `key`.
    pub fn config_dir_for(&self, key: &SessionSlot) -> Option<PathBuf> {
        let handle = self.agent_handle_for(key)?;
        Some(handle.config_dir())
    }

    /// OS PID of the `claude` subprocess bound to `key`. Returns
    /// `None` when the session has no live client (pre-spawn /
    /// post-disconnect). The PID is stable
    /// for the lifetime of the subprocess, so consumers (e.g. the
    /// Inspector pane's PROCESSES OS walk) can cache snapshots
    /// keyed off this value.
    pub fn claude_pid(&self, key: &SessionSlot) -> Option<u32> {
        #[cfg(any(test, feature = "testing"))]
        {
            if let Some(seeded) = self.test_claude_pid.lock().get(key) {
                return Some(*seeded);
            }
        }
        self.agent_handle_for(key).and_then(|handle| handle.claude_pid())
    }

    /// Borrow the [`Arc<AgentHandle>`] registered against `key`.
    /// Workspace-internal helper - surfaces a sometimes-`None` to keep
    /// the early-init / disconnected branches explicit.
    fn agent_handle_for(&self, key: &SessionSlot) -> Option<Arc<AgentHandle>> {
        let pool = self.pool.lock();
        if let Some(pooled) = pool.get(key) {
            return Some(Arc::clone(&pooled.handle));
        }
        drop(pool);
        // Fall back to `domain_handles[key].conn` for pre-Connect /
        // testing-stub callers that never went through the pool path.
        let domain = self.domain_handles.lock().get(key).cloned()?;
        domain.lock().conn.clone()
    }

    /// Resolve `(handle, session_id_string)` for `key`. Both must be
    /// available; missing either surfaces as `UnknownSession` for
    /// uniform error handling.
    fn handle_and_session_id(
        &self,
        key: &SessionSlot,
    ) -> Result<(Arc<AgentHandle>, String), DispatchError> {
        let handle =
            self.agent_handle_for(key).ok_or_else(|| DispatchError::UnknownSession(key.clone()))?;
        let sid = self
            .domain_handles
            .lock()
            .get(key)
            .and_then(|d| d.lock().session_id.as_ref().map(std::string::ToString::to_string))
            .ok_or_else(|| DispatchError::UnknownSession(key.clone()))?;
        Ok((handle, sid))
    }
}

/// The repair line the usage poller logs under an auth-classified
/// failure, keyed on how the account authenticates. A session's
/// credentials are fixed at its spawn, so both classes point at the
/// flat-key edit on the account block, never a re-authentication of the
/// shared config dir.
///
/// The base-url test must stay first: a global `[env]` setup token
/// reaches base-url accounts too, and the re-mint advice is for a
/// credential that account never reads.
fn auth_repair_hint(provider: forge_primitives::account::Provider) -> &'static str {
    if provider.uses_base_url() {
        "usage_poll fetch failed with auth error; fix the account's token and base_url keys and restart forge"
    } else {
        "usage_poll fetch failed with auth error; mint the setup token on the account block (claude setup-token) and restart forge"
    }
}

/// Map a failed probe to the [`forge_gateway::UsageFetchStatus`]
/// bucket. Separates HTTP 429 (the common multi-instance throttle
/// case) from the auth-related
/// failures (`Expired` / `NoCredentials` / `Unauthorized`) and
/// transport failures (`Network`), so each class keeps its own
/// meaning rather than a generic "fetch error". `Unmappable` never
/// reaches the classifiers - both callers handle a 200 that maps to
/// nothing before classifying.
pub(crate) fn classify_oauth_usage_error(
    err: &forge_gateway::ProbeError,
) -> forge_gateway::UsageFetchStatus {
    use forge_gateway::UsageFetchStatus;
    use forge_primitives::usage::oauth::OauthUsageError;
    match err {
        forge_gateway::ProbeError::NoCredentials => UsageFetchStatus::Expired,
        forge_gateway::ProbeError::Unmappable(_) => UsageFetchStatus::Other,
        forge_gateway::ProbeError::Fetch(err) => match err {
            OauthUsageError::RateLimited { .. } | OauthUsageError::HttpStatus(429, _) => {
                UsageFetchStatus::RateLimited
            }
            OauthUsageError::Unauthorized(_) => UsageFetchStatus::Unauthorized,
            OauthUsageError::NoCredentials | OauthUsageError::Expired => UsageFetchStatus::Expired,
            OauthUsageError::Network(_) => UsageFetchStatus::NetworkFailed,
            OauthUsageError::UaProbe(_)
            | OauthUsageError::HttpStatus(_, _)
            // No probe converts a scope refusal - the token arm calls
            // /v1/messages, which has no scope refusal - and a 403
            // there is not an auth failure either.
            | OauthUsageError::ScopeInsufficient
            | OauthUsageError::Decode(_) => UsageFetchStatus::Other,
        },
    }
}

impl Workspace {
    /// Register a fresh `DomainSession` for `key` under this workspace.
    /// `handle` is `None` for pre-spawn / pre-Connect domains (filled
    /// in later when the spawn handler runs); `Some` for test fixtures
    /// that wire a stub handle up front.
    ///
    /// `DomainSession` carries workspace-internal routing metadata
    /// (`conn` / `session_id` / `pending_interactions`). A view's per-
    /// session operational state lives on the view side; the workspace
    /// does not read or write those fields.
    ///
    /// Returns the inserted `Arc<Mutex<DomainSession>>` so callers
    /// can seed fields on the same handle they just registered.
    pub fn register_domain_session(
        &self,
        key: SessionSlot,
        handle: Option<Arc<forge_agent::AgentHandle>>,
    ) -> Arc<Mutex<DomainSession>> {
        let domain = Arc::new(Mutex::new(DomainSession::new(key.clone(), handle)));
        let mut handles = self.domain_handles.lock();
        if handles.contains_key(&key) {
            // Overwriting silently drops the previous DomainSession
            // along with any pending_interactions oneshots - pending
            // permission/question round-trips would then deny with
            // "response channel closed" instead of completing. Log
            // loudly so a future programming error doesn't manifest
            // as a stale-deny that's hard to trace.
            tracing::error!(
                target: "forge_workspace::workspace",
                slot = %key.display(),
                "register_domain_session overwriting existing entry - pending interactions lost"
            );
        }
        handles.insert(key, Arc::clone(&domain));
        domain
    }

    /// Tell a sender its message never landed.
    ///
    /// The one delivery-ack path, and it is NOT outstanding state coming
    /// back: nothing is tracked between the send and this notice. A message
    /// parked for a sleeping project is dropped when the spawn it waited on
    /// fails, and the parked entry itself carries the sender, so the sender
    /// is told rather than left believing the words arrived.
    pub(crate) fn notice_undelivered_message(
        self: &Arc<Self>,
        sender: &SessionSlot,
        target: &SessionSlot,
        reason: crate::mcp::peers::types::PeerFailureReason,
    ) {
        // Body carries the human-readable failure reason - the sender's
        // chat block surfaces it underneath the bracket header.
        let body = match reason {
            crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed => {
                "target session connection lost".to_owned()
            }
        };
        let notice = WrappedPrompt {
            id: MessageId::mint(),
            kind: WrappedKind::DeliveryFailureNotice,
            sender_name: crate::mcp::peers::types::seat_name(target),
            sender_org: target.org().to_owned(),
            body,
        };
        // The CLI never echoes stdin-injected prompts back, so paint the
        // visible notice block ourselves before the LLM-side dispatch.
        let uuid = forge_sdk::request_id::next_prompt_id();
        crate::spawn::push_peer_user_turn_into_chat(self, sender, &notice, &uuid);
        if let Err(err) = self.dispatch_workspace_prompt_under(
            sender,
            notice.to_prose(),
            PromptSource::Peer,
            uuid,
        ) {
            tracing::warn!(
                target: "forge_workspace::workspace",
                slot = %sender.display(),
                error = ?err,
                "notice_undelivered_message: notice dispatch failed (sender closed?)"
            );
        }
    }
}

/// Retry budget for the detached tag-write: how many attempts
/// `tag_session_with_retry` gets to find the worker's
/// `<session_id>.jsonl`, and the delay between them.
#[derive(Clone, Copy)]
pub(crate) struct WorkerTagRetryBudget {
    max_attempts: u32,
    delay: Duration,
}

/// The two facts the connect-time tag path decides on: whether the JSONL
/// still needs its tag, and whether this spawn minted the row a rollback
/// would delete.
#[derive(Clone, Copy)]
pub(crate) struct WorkerTagFacts {
    needs_tag: bool,
    minted_row: bool,
}

/// Discriminator for how a successful `apply_worker_tag_or_rollback`
/// arm decided to transition a worker to `Running`. The `Succeeded`
/// arm clears `needs_tag`; the `DeferredNotFound` arm keeps it set
/// so the opportunistic retry on first `DeliverWorkerPrompt` knows
/// to try again.
#[derive(Clone, Copy)]
enum TagWriteResult {
    /// Tag row was appended to the JSONL on disk.
    Succeeded,
    /// JSONL never appeared during the retry window. Worker stays
    /// live with `needs_tag = true` for opportunistic retry later.
    DeferredNotFound,
}

/// Shared transition: flip a worker's status to `Running`, update
/// `needs_tag` according to the tag-write outcome, and emit
/// `WorkerStatusChanged { StatusChanged }`. Idempotent.
fn transition_worker_to_running(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    session_key: &SessionSlot,
    result: TagWriteResult,
) {
    let updated = {
        let mut workers = workspace.live_workers.lock();
        workers.get_mut(project_key).and_then(|entries| {
            entries.iter_mut().find(|e| e.slot == *session_key).map(|entry| {
                entry.status = forge_primitives::WorkerLiveness::Running;
                entry.needs_tag = matches!(result, TagWriteResult::DeferredNotFound);
                // Clear any stale diagnostic from a prior Failed
                // transition - the worker is alive again.
                entry.diagnostic = None;
                (entry.to_status(), entry.is_git_repo_at_spawn)
            })
        })
    };
    if let Some((status, is_git_repo_at_spawn)) = updated {
        let _ = workspace.update_tx.send(SessionUpdate::WorkerStatusChanged {
            project_key: project_key.clone(),
            action: crate::protocol::WorkerStatusAction::StatusChanged,
            status,
            worktree: crate::protocol::WorktreeDisposition::untouched(is_git_repo_at_spawn),
        });
    }
}

/// Shared transition: flip a worker's status to `Failed` with a
/// human-readable `diagnostic`, and emit `WorkerStatusChanged
/// { StatusChanged }`. Called by the `Connected`-never-arrived
/// paths (subprocess exit, ConnectionFailed event, resume rejected
/// by claude when the fall-through-to-fresh path declines to
/// retry).
///
/// Idempotent: when the entry is already `Failed` with an identical
/// diagnostic, this is a no-op (no mutation, no event emission). A
/// fresh diagnostic for an already-Failed entry DOES re-emit so the
/// UI picks up the new reason text.
///
/// Also clears `needs_tag` because a Failed worker won't be reached
/// by the opportunistic tag-retry path - leaving the flag set keeps
/// stale state on the entry the next time the worker resumes and
/// transitions back to Running.
///
/// The diagnostic should be the first line of claude's stderr (when
/// available) or the error variant name. Keep it short - the
/// Projects pane renders it as a one-row sub-line below the worker
/// label, truncated to the row's available width.
pub(crate) fn transition_worker_to_failed(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    session_key: &SessionSlot,
    diagnostic: Option<String>,
) {
    let updated = {
        let mut workers = workspace.live_workers.lock();
        workers.get_mut(project_key).and_then(|entries| {
            entries.iter_mut().find(|e| e.slot == *session_key).and_then(|entry| {
                // A seat the supervisor is already bringing back keeps its
                // `Restarting`: this failure is the death it is healing, and
                // the row must not be repainted failed under it.
                if workspace.heal_progress(&entry.slot).is_some() {
                    return None;
                }
                // Idempotency: same status + same diagnostic -> no-op.
                if entry.status == forge_primitives::WorkerLiveness::Failed
                    && entry.diagnostic == diagnostic
                {
                    return None;
                }
                entry.status = forge_primitives::WorkerLiveness::Failed;
                entry.diagnostic = diagnostic;
                // Clear needs_tag - a Failed worker won't reach the
                // opportunistic tag-retry path, and leaving the flag
                // set would keep stale state if the entry later
                // transitions back to Running on a successful resume.
                entry.needs_tag = false;
                Some((entry.to_status(), entry.is_git_repo_at_spawn))
            })
        })
    };
    if let Some((status, is_git_repo_at_spawn)) = updated {
        tracing::warn!(
            target: "forge_workspace::workspace",
            event_name = "worker_failed",
            project = %project_key.as_str(),
            slot = %session_key.display(),
            diagnostic = ?status.diagnostic,
            "worker session transitioned to Failed; row will render with diagnostic sub-line",
        );
        let _ = workspace.update_tx.send(SessionUpdate::WorkerStatusChanged {
            project_key: project_key.clone(),
            action: crate::protocol::WorkerStatusAction::StatusChanged,
            status,
            worktree: crate::protocol::WorktreeDisposition::untouched(is_git_repo_at_spawn),
        });
    }
}

/// Wrap `mutations::tag_session` with a retry loop scoped to the JSONL-
/// not-yet-on-disk race after `Connected`. claude CLI creates
/// `<session_id>.jsonl` lazily; until that lands, `find_session_file`
/// returns `None` and `tag_session` surfaces `Io(NotFound)`. We retry
/// only on that variant - any other error (permission denied, disk
/// full, invalid UUID, encode error) propagates immediately. The async
/// `tokio::time::sleep` is mandatory: this runs in a tokio task spawned
/// from `apply_worker_tag_or_rollback` (or `retry_worker_tag_opportunistic`),
/// never on a blocking thread.
async fn tag_session_with_retry(
    config_dir: &std::path::Path,
    session_id: &str,
    tag: &str,
    project: &str,
    directory: &str,
    max_attempts: u32,
    delay: Duration,
) -> Result<(), forge_sdk::Error> {
    let mut last_err: Option<forge_sdk::Error> = None;
    for attempt in 0..max_attempts {
        match forge_agent::userdata::catalog::mutations::tag_session(
            config_dir,
            session_id,
            Some(tag),
            project,
            Some(directory),
        ) {
            Ok(()) => return Ok(()),
            Err(forge_sdk::Error::Io(io_err)) if io_err.kind() == std::io::ErrorKind::NotFound => {
                last_err = Some(forge_sdk::Error::Io(io_err));
                tracing::trace!(
                    target: "forge_workspace::workspace",
                    session_id = %session_id,
                    attempt = attempt + 1,
                    max_attempts,
                    "tag_session: JSONL not yet on disk, retrying"
                );
                tokio::time::sleep(delay).await;
            }
            Err(other) => return Err(other),
        }
    }
    Err(last_err.unwrap_or_else(|| {
        forge_sdk::Error::Io(std::io::Error::new(
            std::io::ErrorKind::NotFound,
            format!("session {session_id} not found after {max_attempts} attempts"),
        ))
    }))
}

/// Env for a spawn: the account env with `project`'s declared keys
/// merged over it. The spawn resolves the project first and refuses a
/// target that maps to none, so there is always one to merge.
fn session_env_for(
    project: &LoadedProject,
    account_env: &std::collections::HashMap<String, String>,
) -> std::collections::HashMap<String, String> {
    // Logged even when the project declares nothing, so a spawn
    // carrying the wrong project's env is visible.
    tracing::info!(
        target: "forge_workspace::workspace",
        event_name = "session_env_project_applied",
        project = %project.name,
        keys = %crate::config::applied_env_keys(project),
        "`keys` lists what the project env contributed, empty when it declares none",
    );
    crate::config::session_env(project, account_env)
}

/// Stamp the project's `permission_mode` into the launch settings'
/// `permissions.defaultMode`. A spawn that resolved to no project
/// stamps nothing, so the launcher's session default applies.
fn apply_project_permission_mode(
    project: Option<&crate::config::LoadedProject>,
    settings: &mut SessionLaunchSettings,
) {
    if let Some(mode) = project.map(|project| project.permission_mode) {
        spawn::stamp_permission_mode(settings, mode);
    }
}

/// Stamp the project's canonical `model` into the launch settings, which
/// is how the session's model reaches the CLI. A project that declares
/// no model stamps nothing, so the caller's pin (forge defaults it to
/// the literal "opus") stands.
fn apply_project_model(
    project: Option<&crate::config::LoadedProject>,
    settings: &mut SessionLaunchSettings,
) {
    if let Some(model) = project.and_then(|project| project.model.as_deref()) {
        settings.settings = Some(pin_model_into_settings(settings.settings.take(), model));
    }
}

/// `settings` with `model` pinned to `model`, every other key kept.
fn pin_model_into_settings(settings: Option<serde_json::Value>, model: &str) -> serde_json::Value {
    let mut document = match settings {
        Some(serde_json::Value::Object(map)) => map,
        _ => serde_json::Map::new(),
    };
    document.insert("model".to_owned(), serde_json::Value::String(model.to_owned()));
    serde_json::Value::Object(document)
}

/// Test helper: ensure `forge/` exists and return the production
/// `forge/forge.toml` path, so tests write where forge reads (not the
/// legacy top-level fallback).
#[cfg(test)]
fn forge_toml_path(config_dir: &std::path::Path) -> PathBuf {
    crate::config::ensure_forge_data_dir(config_dir).expect("forge/ dir").join("forge.toml")
}

/// Test helper: persist a worker row for `label` in `project_key` and
/// fail loudly when it did not land. `project_key` must resolve to a
/// configured project - the row is keyed by `(org, project name, label)`,
/// so a bare map key writes nothing and every assertion downstream would
/// then hold for the wrong reason.
#[cfg(test)]
fn seed_worker_row(ws: &Workspace, project_key: &ProjectKey, label: &str) {
    ws.seed_test_worker_row(project_key, label);
    assert!(
        ws.stored_worker_row(project_key, label).expect("read the seeded row").is_some(),
        "the worker row for {label} did not land; does {project_key:?} resolve to a project?",
    );
}

#[cfg(test)]
mod account_stamp_tests {
    use super::*;
    use crate::config::LoadedProject;

    fn project_with_mode(
        permission_mode: forge_primitives::permission::PermissionMode,
    ) -> LoadedProject {
        LoadedProject {
            name: "forge".to_owned(),
            path: PathBuf::from("/tmp/forge"),
            display_path: "~/Projects/forge".to_owned(),
            org: "Personal".to_owned(),
            accounts: vec!["Stargate".to_owned()],
            fallback_accounts: Vec::new(),
            model: None,
            env: HashMap::new(),
            env_file: None,
            max_workers: None,
            permission_mode,
            document_roots: Vec::new(),
            handoff: None,
            browser_profile: forge_primitives::browser::ProfileKey::of("Personal", "default")
                .expect("a profile key"),
            slack_workspace: None,
        }
    }

    fn stamped_mode(settings: &SessionLaunchSettings) -> Option<String> {
        settings
            .settings
            .as_ref()
            .and_then(|s| s.get("permissions"))
            .and_then(|p| p.get("defaultMode"))
            .and_then(serde_json::Value::as_str)
            .map(str::to_owned)
    }

    #[test]
    fn project_mode_stamps_fresh_spawn_settings_and_projectless_leaves_them() {
        let bypass =
            project_with_mode(forge_primitives::permission::PermissionMode::BypassPermissions);
        let mut stamped = SessionLaunchSettings::default();
        apply_project_permission_mode(Some(&bypass), &mut stamped);
        assert_eq!(
            stamped_mode(&stamped).as_deref(),
            Some("bypassPermissions"),
            "a project carrying permission_mode stamps the fresh spawn settings",
        );

        let mut untouched = SessionLaunchSettings::default();
        apply_project_permission_mode(None, &mut untouched);
        assert!(
            untouched.settings.is_none(),
            "a spawn that resolved to no project leaves fresh settings untouched"
        );
    }
}

/// Wait for one slot's teardown answer. `subscribe` marks the current value
/// as seen, so the value is checked before waiting on a change.
async fn wait_for_teardown(rx: &mut tokio::sync::watch::Receiver<bool>) {
    if *rx.borrow_and_update() {
        return;
    }
    let _ = rx.changed().await;
}

/// The slots whose task has not answered yet, read off the channel values.
fn unready_slots(
    receivers: &[(SessionSlot, tokio::sync::watch::Receiver<bool>)],
) -> Vec<SessionSlot> {
    receivers.iter().filter(|(_, rx)| !*rx.borrow()).map(|(slot, _)| slot.clone()).collect()
}

/// Name each session that outlasted the shutdown's wait. One line per slot:
/// the shared deadline says nothing about which task was slow, and the
/// value is the only thing that does.
fn warn_shutdown_expired(slots: &[SessionSlot], wait: std::time::Duration) {
    for slot in slots {
        tracing::warn!(
            target: "forge_workspace::workspace",
            event_name = "shutdown_teardown_wait_expired",
            org = slot.org(),
            project = slot.project(),
            label = slot.label(),
            wait = ?wait,
            "shutdown: this session's task did not finish its teardown in the wait; the \
             usual stall is the stderr join after the group kill, where a detached \
             descendant still holds the child's stderr open, so its tree may outlive forge"
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::tempdir;

    /// A probe the test steers: a fixed snapshot, and a count of the calls
    /// it answered, so the scheduling around the probe is observable
    /// without a real `claude --version` or a network call.
    fn scripted_prober(
        calls: &Arc<std::sync::atomic::AtomicUsize>,
        snapshot: CliVersionInfo,
    ) -> CliVersionProber {
        let calls = Arc::clone(calls);
        Box::new(move || {
            calls.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
            Box::pin(std::future::ready(snapshot.clone()))
        })
    }

    /// The constructor's own launch is what starts the probe. Delete it and
    /// the core reads no version for the life of the process while every
    /// other test stays green, so nothing else notices that the feature's
    /// only production write is gone.
    #[tokio::test]
    async fn the_boot_construction_starts_the_probe_and_stores_what_it_reads() {
        let dir = make_workspace_dir();
        let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let probed = CliVersionInfo {
            installed: Some("2.1.156".to_owned()),
            latest: Some("2.1.201".to_owned()),
        };
        let workspace = Workspace::new_for_test_with_cli_version_prober(
            dir.path().to_owned(),
            scripted_prober(&calls, probed.clone()),
        )
        .expect("new");
        let mut woken = workspace.subscribe_answerer();

        let event = tokio::time::timeout(Duration::from_secs(5), woken.recv()).await;

        assert!(
            matches!(
                event,
                Ok(Some(frame)) if matches!(&*frame.update, SessionUpdate::CliVersionChanged)
            ),
            "the constructor's launch probed and woke the views; without that launch the core reads no version for the life of the process",
        );
        assert_eq!(
            calls.load(std::sync::atomic::Ordering::Acquire),
            1,
            "the boot launch probed exactly once",
        );
        assert_eq!(
            workspace.cli_version(),
            Some(probed),
            "and the store holds what the probe returned, not a snapshot that resolved nothing",
        );
    }

    /// A second start is a no-op. Two loops would each spawn
    /// `claude --version` and reach npm every five minutes, and each would
    /// write into the store the other one reads.
    #[tokio::test]
    async fn a_second_cli_version_probe_start_is_a_no_op() {
        let dir = make_workspace_dir();
        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");
        let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let first = CliVersionInfo { installed: Some("2.1.156".to_owned()), latest: None };
        let second = CliVersionInfo { installed: Some("2.1.100".to_owned()), latest: None };

        workspace.start_cli_version_probe(scripted_prober(&calls, first.clone()));
        workspace.start_cli_version_probe(scripted_prober(&calls, second));
        let mut woken = workspace.subscribe_answerer();
        let event = tokio::time::timeout(Duration::from_secs(5), woken.recv()).await;
        assert!(
            matches!(
                event,
                Ok(Some(frame)) if matches!(&*frame.update, SessionUpdate::CliVersionChanged)
            ),
            "the first start probed and woke the views",
        );

        // The second loop's first tick is immediate too, so an unguarded
        // start lands a second snapshot and a second event within
        // microseconds of the first.
        let again = tokio::time::timeout(Duration::from_millis(100), woken.recv()).await;
        assert!(
            again.is_err(),
            "the second start was a no-op; two loops would each spawn `claude --version` and reach npm",
        );
        assert_eq!(
            calls.load(std::sync::atomic::Ordering::Acquire),
            1,
            "and only one probe call happened at all",
        );
        assert_eq!(
            workspace.cli_version(),
            Some(first),
            "the store holds the first probe's answer, which is what says the second never ran after it",
        );
    }

    /// A probe that came back empty on one side keeps the value an earlier
    /// probe resolved: a transient failure must not blank a version the
    /// views were already showing.
    #[test]
    fn an_empty_cli_version_probe_keeps_the_resolved_field() {
        let held = CliVersionInfo {
            installed: Some("2.1.156".to_owned()),
            latest: Some("2.1.201".to_owned()),
        };

        let merged = merge_cli_version(
            Some(&held),
            CliVersionInfo { installed: Some("2.1.156".to_owned()), latest: None },
        );
        assert_eq!(
            merged.latest.as_deref(),
            Some("2.1.201"),
            "a latest probe that failed must not wipe the latest an earlier probe found",
        );

        let merged = merge_cli_version(
            Some(&held),
            CliVersionInfo { installed: None, latest: Some("2.1.201".to_owned()) },
        );
        assert_eq!(
            merged.installed.as_deref(),
            Some("2.1.156"),
            "an installed probe that failed must not wipe the version already read",
        );
    }

    /// And a probe that did resolve a side replaces what was held, so the
    /// keep-the-old-value rule cannot pin the views to a stale answer.
    #[test]
    fn a_resolved_cli_version_probe_replaces_the_held_value() {
        let held = CliVersionInfo {
            installed: Some("2.1.156".to_owned()),
            latest: Some("2.1.201".to_owned()),
        };
        let next = CliVersionInfo {
            installed: Some("2.1.160".to_owned()),
            latest: Some("2.1.210".to_owned()),
        };

        assert_eq!(
            merge_cli_version(Some(&held), next.clone()),
            next,
            "a probe that resolved both sides replaces both, rather than pinning the held ones",
        );
    }

    /// Only a change wakes the views. The probe re-runs on a timer, so a
    /// re-probe landing the same snapshot must not wake them - both views
    /// would redraw for nothing every few minutes.
    #[test]
    fn only_a_changed_cli_version_wakes_the_views() {
        let store = Mutex::new(None);
        let update_tx = UpdateFanout::default();
        let mut woken = update_tx.subscribe(SubscriberRole::Answering);
        let first = CliVersionInfo { installed: Some("2.1.156".to_owned()), latest: None };

        store_cli_version(&store, &update_tx, first.clone());
        assert!(
            matches!(
                woken.try_recv(),
                Ok(frame) if matches!(&*frame.update, SessionUpdate::CliVersionChanged)
            ),
            "the first probe is a change from none",
        );

        store_cli_version(&store, &update_tx, first);
        assert!(woken.try_recv().is_err(), "an identical re-probe is not news");

        store_cli_version(
            &store,
            &update_tx,
            CliVersionInfo {
                installed: Some("2.1.156".to_owned()),
                latest: Some("2.1.201".to_owned()),
            },
        );
        assert!(
            matches!(
                woken.try_recv(),
                Ok(frame) if matches!(&*frame.update, SessionUpdate::CliVersionChanged)
            ),
            "a latest that appears where there was none is news",
        );
        assert_eq!(
            store.lock().as_ref().and_then(|held| held.latest.as_deref()),
            Some("2.1.201"),
            "and the store holds what the last merge resolved",
        );

        // A first probe that resolved nothing holds a snapshot and draws
        // what the views already had, so it is not news either.
        let unresolved = Mutex::new(None);
        store_cli_version(
            &unresolved,
            &update_tx,
            CliVersionInfo { installed: None, latest: None },
        );
        assert!(
            woken.try_recv().is_err(),
            "a first probe that resolved nothing draws what the views already had",
        );
        assert_eq!(
            unresolved
                .lock()
                .as_ref()
                .map(|held| (held.installed.as_deref(), held.latest.as_deref())),
            Some((None, None)),
            "the store holds what the probe read, and both sides are still empty",
        );
    }

    /// Every provider logs the repair line that can actually repair
    /// it. The base-url arm is load-bearing: a global `[env]` setup
    /// token reaches base-url accounts too, and a token-first order
    /// would send their 401 to the re-mint advice against a credential
    /// those providers never read.
    #[test]
    fn auth_repair_hint_keys_on_the_credential_shape() {
        use forge_primitives::account::Provider;

        for provider in [Provider::Codex, Provider::Openrouter, Provider::Zai] {
            assert_eq!(
                auth_repair_hint(provider),
                "usage_poll fetch failed with auth error; fix the account's token and \
                 base_url keys and restart forge",
                "{provider:?} is repaired by a flat-key edit",
            );
        }

        assert_eq!(
            auth_repair_hint(Provider::Anthropic),
            "usage_poll fetch failed with auth error; mint the setup token on the account \
             block (claude setup-token) and restart forge",
            "an anthropic account repairs through its setup token, token or not",
        );
    }

    /// The supersession guard that keeps a re-spawn intact: a stale
    /// predecessor task exiting must NOT wipe
    /// the successor's pool entry, command sender, or domain handle -
    /// all three are gated together on `Arc` identity. The current
    /// owner's own exit still releases all three.
    #[test]
    fn release_session_if_current_is_supersession_safe() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("sup-key");

        let (ha, _rxa) = Workspace::testing_stub_handle();
        let arc_a = Arc::new(ha);
        let (hb, _rxb) = Workspace::testing_stub_handle();
        let arc_b = Arc::new(hb);

        // The successor (account B) owns all three registrations.
        let (tx, _cmd_rx) = mpsc::unbounded_channel::<Command>();
        ws.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::clone(&arc_b),
                account: AccountKey("B".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.command_senders.lock().insert(key.clone(), tx);
        ws.register_domain_session(key.clone(), Some(Arc::clone(&arc_b)));

        // The superseded predecessor (account A) exits and runs its
        // cleanup. Its handle no longer matches the pooled one, so the
        // guard no-ops across every map and B's live session survives.
        ws.release_session_if_current(&key, &arc_a);
        assert!(ws.pool.lock().contains_key(&key), "pool entry for B survives A's exit");
        assert!(ws.command_senders.lock().contains_key(&key), "command sender for B survives");
        assert!(ws.domain_handles.lock().contains_key(&key), "domain handle for B survives");

        // The current owner's own exit DOES release all three maps.
        ws.release_session_if_current(&key, &arc_b);
        assert!(!ws.pool.lock().contains_key(&key), "current owner removes the pool entry");
        assert!(!ws.command_senders.lock().contains_key(&key), "command sender removed");
        assert!(!ws.domain_handles.lock().contains_key(&key), "domain handle removed");
    }

    /// The board's reserve toggle reaches the store through the command bus
    /// (#2423/C): the pick is the user's, and releasing it clears it.
    #[tokio::test]
    async fn a_board_reservation_dispatches_and_lands() {
        use forge_primitives::tasks::{ReservedBy, Task, TaskId, TaskStatus};
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-reserve");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        ws.push_task(Task {
            id: TaskId::from("t-1"),
            project_name: "proj".to_owned(),
            subject: "subject t-1".to_owned(),
            active_form: None,
            detail: None,
            status: TaskStatus::Pending,
            owner: None,
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        });

        ws.dispatch(Command::TaskReserve {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            reserved: true,
        })
        .expect("app-level commands are accepted");
        assert_eq!(
            ws.tasks_for_project("proj")[0].reserved,
            Some(ReservedBy::User),
            "the pick is reserved through the board's own command",
        );

        ws.dispatch(Command::TaskReserve {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            reserved: false,
        })
        .expect("accepted");
        assert_eq!(ws.tasks_for_project("proj")[0].reserved, None, "and released");
    }

    /// The board's reopen reaches the store through the command bus
    /// (#2423/B): an attestation is struck, the gate re-minted and the row
    /// parked on the user again.
    #[tokio::test]
    async fn a_board_reopen_dispatches_and_parks_the_row() {
        use forge_primitives::tasks::{By, Task, TaskId, TaskStatus, Verify};
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-reopen");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let lead = SessionSlot::lead("TestOrg", "proj");
        ws.push_task(Task {
            id: TaskId::from("epic"),
            project_name: "proj".to_owned(),
            subject: "the epic".to_owned(),
            active_form: None,
            detail: None,
            status: TaskStatus::Pending,
            owner: None,
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        });
        ws.push_task(Task {
            id: TaskId::from("t-1"),
            project_name: "proj".to_owned(),
            subject: "the looked-at child".to_owned(),
            active_form: None,
            detail: None,
            status: TaskStatus::Pending,
            owner: None,
            parent: Some(TaskId::from("epic")),
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: Some(Verify::User),
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        });
        ws.update_task("proj", &TaskId::from("t-1"), By::System, |task| {
            task.status = TaskStatus::Completed;
        })
        .expect("no refusal")
        .expect("the row is there");
        ws.attest_task("proj", &TaskId::from("t-1"), &lead, "looks good")
            .expect("no refusal")
            .expect("the row is there");

        ws.dispatch(Command::TaskReopen { project: "proj".to_owned(), id: "t-1".to_owned() })
            .expect("app-level commands are accepted");
        let reopened = ws
            .tasks_for_project("proj")
            .into_iter()
            .find(|task| task.id == TaskId::from("t-1"))
            .expect("t-1");
        assert_eq!(reopened.status, TaskStatus::Waiting, "the row is back on the look");
        assert_eq!(reopened.attested, None, "the attestation is struck");
        assert_eq!(reopened.verify, Some(Verify::User), "and the gate re-minted");
        assert!(
            reopened.waiting_on.as_ref().is_some_and(|wait| wait.verification),
            "parked on the user: {:?}",
            reopened.waiting_on,
        );
    }

    /// The board's edits reach the store through the command bus, and a
    /// refusal says so on the service line - a press that did nothing and
    /// a press the core refused must not read the same.
    #[tokio::test]
    async fn a_board_verdict_dispatches_and_a_refusal_says_so() {
        use forge_primitives::tasks::{By, Task, TaskId, TaskStatus};
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-dispatch");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let sample = |id: &str| Task {
            id: TaskId::from(id),
            project_name: "proj".to_owned(),
            subject: format!("subject {id}"),
            active_form: None,
            detail: None,
            status: TaskStatus::Pending,
            owner: None,
            // A child, so the approval completes it on the live board -
            // a root would close and archive, which is a different test.
            parent: Some(TaskId::from("epic")),
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: Some(forge_primitives::tasks::Verify::User),
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        };
        ws.push_task(sample("t-1"));
        ws.update_task("proj", &TaskId::from("t-1"), By::System, |task| {
            task.status = TaskStatus::Completed;
        })
        .expect("no refusal")
        .expect("the row is there");

        ws.dispatch(Command::TaskVerdict {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            approve: true,
            words: None,
        })
        .expect("app-level commands are accepted");
        let stored = ws.tasks_for_project("proj");
        assert_eq!(stored[0].status, TaskStatus::Completed, "the verdict landed");

        // The same verdict again names a row no longer waiting: the refusal
        // reaches the service line rather than only the log.
        ws.dispatch(Command::TaskVerdict {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            approve: true,
            words: None,
        })
        .expect("accepted");
        let mut refused = false;
        while let Ok(frame) = rx.try_recv() {
            if let crate::protocol::SessionUpdate::ServiceStatus { message, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && message.contains("refused a verdict")
            {
                refused = true;
            }
        }
        assert!(refused, "a refused edit is said on the service line");
    }

    /// The rest of the board's edits say so too, the not-found case included:
    /// a rank or an assignment naming a row that has gone, and an assignment
    /// naming a project this forge does not carry, are presses whose silence
    /// would read as success.
    #[tokio::test]
    async fn a_board_edit_that_does_not_land_says_so() {
        use forge_primitives::tasks::TaskStatus;
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-misses");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );

        for (command, named) in [
            (
                Command::TaskRank {
                    project: "proj".to_owned(),
                    id: "gone".to_owned(),
                    to: crate::protocol::RankMove::Top,
                },
                "refused a re-order",
            ),
            (
                Command::TaskAssign {
                    project: "proj".to_owned(),
                    id: "gone".to_owned(),
                    owner: Some("lead".to_owned()),
                },
                "refused an assignment",
            ),
            (
                Command::TaskMove {
                    project: "proj".to_owned(),
                    id: "gone".to_owned(),
                    to: TaskStatus::InProgress,
                    place: None,
                },
                "refused a move",
            ),
            (
                Command::TaskAssign {
                    project: "no-such-project".to_owned(),
                    id: "gone".to_owned(),
                    owner: None,
                },
                "refused an assignment",
            ),
        ] {
            ws.dispatch(command).expect("app-level commands are accepted");
            let mut said = false;
            while let Ok(frame) = rx.try_recv() {
                if let crate::protocol::SessionUpdate::ServiceStatus { message, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && message.contains(named)
                {
                    said = true;
                }
            }
            assert!(said, "{named} was not said on the service line");
        }
    }

    /// **A drag carries its place**: a move with a `place` lands the row at
    /// the position the drop chose, and one without it leaves the queue
    /// alone - the keyboard's lane step moves state only.
    #[tokio::test]
    async fn a_board_move_with_a_place_lands_the_row_there() {
        use forge_primitives::tasks::{Task, TaskId, TaskStatus};
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-place");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let owner = SessionSlot::new("TestOrg", "proj", "w1");
        let sample = |id: &str| Task {
            id: TaskId::from(id),
            project_name: "proj".to_owned(),
            subject: format!("subject {id}"),
            active_form: None,
            detail: None,
            status: TaskStatus::Pending,
            owner: Some(owner.clone()),
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        };
        for id in ["a", "b", "c"] {
            ws.push_task(sample(id));
        }
        let order = || {
            let mut rows = ws.tasks_for_project("proj");
            rows.sort_by_key(|t| (t.rank.unwrap_or(i64::MAX), t.created_at));
            rows.iter().map(|t| t.id.as_str().to_owned()).collect::<Vec<_>>()
        };
        assert_eq!(order(), vec!["a", "b", "c"], "the push order is the queue");

        // A drop above `a`, coming from across the board: `c` lands first.
        ws.dispatch(Command::TaskMove {
            project: "proj".to_owned(),
            id: "c".to_owned(),
            to: TaskStatus::InProgress,
            place: Some(crate::protocol::RankMove::Before(Some("a".to_owned()))),
        })
        .expect("accepted");
        assert_eq!(order(), vec!["c", "a", "b"], "the drop IS the priority");

        // The control: a step carrying no place moves state only. It moves
        // the row in the MIDDLE, so a default that ranks it to either end
        // shows - a row already last would be blind to one.
        ws.dispatch(Command::TaskMove {
            project: "proj".to_owned(),
            id: "a".to_owned(),
            to: TaskStatus::InProgress,
            place: None,
        })
        .expect("accepted");
        assert_eq!(order(), vec!["c", "a", "b"], "a step without a place leaves the queue");
    }

    /// Every `ChatAppended` frame the stub's stream carries, each with the
    /// seat it is addressed to.
    fn told(rx: &mut mpsc::UnboundedReceiver<SeatUpdate>) -> Vec<(SessionSlot, String)> {
        drain_updates(rx)
            .into_iter()
            .filter_map(|update| match update {
                crate::protocol::SessionUpdate::ChatAppended { key, msg, .. } => {
                    Some((key, format!("{msg:?}")))
                }
                _ => None,
            })
            .collect()
    }

    /// The single frame a dispatch drew, or a failure naming what arrived.
    fn told_one(rx: &mut mpsc::UnboundedReceiver<SeatUpdate>) -> (SessionSlot, String) {
        let mut frames = told(rx);
        assert_eq!(frames.len(), 1, "exactly one frame: {frames:?}");
        frames.pop().expect("one frame")
    }

    /// **A board edit the user makes tells the row's live owner**, one line -
    /// and the answer carries the user's own words, because the notice tells
    /// the owner to resume and it should not have to go looking for what was
    /// said. Forged, so the line draws the moment it lands. The owner is a
    /// worker here and the project's lead is just as live, so the frame's
    /// seat is what pins the targeting.
    #[tokio::test]
    async fn a_board_edit_tells_the_rows_live_owner() {
        use forge_primitives::tasks::{Task, TaskId, TaskStatus, Waiting, WaitingKind};
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-owner-told");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let owner = SessionSlot::new("TestOrg", "proj", "w1");
        let lead = SessionSlot::new("TestOrg", "proj", "lead");
        // Both registered (a conn each) so `seat_is_live` reads true: the
        // owner holds the rows, and the lead is the seat a fallback would
        // reach for.
        let _owner_routed = install_fake_session_task(&ws, &owner);
        let _lead_routed = install_fake_session_task(&ws, &lead);
        let sample = |id: &str, status: TaskStatus| Task {
            id: TaskId::from(id),
            project_name: "proj".to_owned(),
            subject: format!("subject {id}"),
            active_form: None,
            detail: None,
            status,
            owner: Some(owner.clone()),
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        };
        let question = || Waiting {
            kind: Some(WaitingKind::Decision),
            detail: None,
            on: None,
            verification: false,
            parked: false,
            since: None,
        };

        // The wait, answered: the words ride the notice, and it goes to the
        // row's owner rather than to the live lead.
        let mut waiting = sample("t-1", TaskStatus::Waiting);
        waiting.waiting_on = Some(question());
        ws.push_task(waiting);
        ws.dispatch(Command::TaskAnswer {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            words: "get going".to_owned(),
        })
        .expect("app-level commands are accepted");
        let (key, text) = told_one(&mut rx);
        assert_eq!(key, owner, "the owner hears it, not the lead");
        assert!(text.contains("get going"), "the words ride the notice: {text}");
        assert!(text.contains("answered"), "and it says what happened: {text}");

        // An answer with no words says so rather than pointing at a detail
        // the empty append never filled.
        let mut quiet = sample("t-2", TaskStatus::Waiting);
        quiet.waiting_on = Some(question());
        ws.push_task(quiet);
        ws.dispatch(Command::TaskAnswer {
            project: "proj".to_owned(),
            id: "t-2".to_owned(),
            words: String::new(),
        })
        .expect("accepted");
        let (_, text) = told_one(&mut rx);
        assert!(text.contains("no words"), "an empty answer is said plainly: {text}");

        // A send-back carries the words too.
        let mut sent = sample("t-3", TaskStatus::Waiting);
        sent.waiting_on = Some(Waiting { verification: true, ..question() });
        ws.push_task(sent);
        ws.dispatch(Command::TaskVerdict {
            project: "proj".to_owned(),
            id: "t-3".to_owned(),
            approve: false,
            words: Some("narrow it".to_owned()),
        })
        .expect("accepted");
        let (_, text) = told_one(&mut rx);
        assert!(text.contains("narrow it"), "a send-back carries the words: {text}");
        assert!(text.contains("came back"), "and names what happened: {text}");

        // A send-back with no words at all says so, the same as the answer.
        let mut bare = sample("t-6", TaskStatus::Waiting);
        bare.waiting_on = Some(Waiting { verification: true, ..question() });
        ws.push_task(bare);
        ws.dispatch(Command::TaskVerdict {
            project: "proj".to_owned(),
            id: "t-6".to_owned(),
            approve: false,
            words: None,
        })
        .expect("accepted");
        let (_, text) = told_one(&mut rx);
        assert!(text.contains("no words"), "an empty send-back is said plainly: {text}");

        // A re-order that lands the row where it started is not an edit: the
        // queue is unchanged and nobody is told.
        let mut queued = sample("t-4", TaskStatus::Pending);
        queued.rank = Some(0);
        ws.push_task(queued);
        ws.dispatch(Command::TaskRank {
            project: "proj".to_owned(),
            id: "t-4".to_owned(),
            to: crate::protocol::RankMove::Up,
        })
        .expect("accepted");
        assert!(told(&mut rx).is_empty(), "no change to the queue, no notice");

        // And a re-order that does move the row is told: the owner hears it.
        let beside = sample("t-5", TaskStatus::Pending);
        ws.push_task(beside);
        ws.dispatch(Command::TaskRank {
            project: "proj".to_owned(),
            id: "t-5".to_owned(),
            to: crate::protocol::RankMove::Up,
        })
        .expect("accepted");
        let (_, text) = told_one(&mut rx);
        assert!(text.contains("re-ordered"), "the owner hears the re-order: {text}");
    }

    /// A row with no owner tells nobody even though the project's lead is
    /// live: the notice goes to the row's owner, and there is no fallback.
    #[tokio::test]
    async fn a_board_edit_on_an_ownerless_row_tells_nobody() {
        use forge_primitives::tasks::{Task, TaskId, TaskStatus};
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-ownerless");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        // Live, so silence can only be the ownerless hold, never a missing
        // recipient.
        let lead = SessionSlot::new("TestOrg", "proj", "lead");
        let _lead_routed = install_fake_session_task(&ws, &lead);
        ws.push_task(Task {
            id: TaskId::from("t-1"),
            project_name: "proj".to_owned(),
            subject: "nobody holds this".to_owned(),
            active_form: None,
            detail: None,
            status: TaskStatus::InProgress,
            owner: None,
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        });
        ws.dispatch(Command::TaskMove {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            to: TaskStatus::Waiting,
            place: None,
        })
        .expect("accepted");
        assert!(
            told(&mut rx).is_empty(),
            "an ownerless row has nobody to tell, and the board is where the move shows",
        );
    }

    /// A sleeping owner is not a recipient either, with the lead live: the
    /// row waits for its owner to read the board.
    #[tokio::test]
    async fn a_board_edit_on_a_sleeping_owners_row_tells_nobody() {
        use forge_primitives::tasks::{Task, TaskId, TaskStatus};
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-sleeping-owner");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let lead = SessionSlot::new("TestOrg", "proj", "lead");
        let _lead_routed = install_fake_session_task(&ws, &lead);
        ws.push_task(Task {
            id: TaskId::from("t-1"),
            project_name: "proj".to_owned(),
            subject: "its owner is asleep".to_owned(),
            active_form: None,
            detail: None,
            status: TaskStatus::InProgress,
            owner: Some(SessionSlot::new("TestOrg", "proj", "sleeper")),
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        });
        ws.dispatch(Command::TaskMove {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            to: TaskStatus::Waiting,
            place: None,
        })
        .expect("accepted");
        assert!(told(&mut rx).is_empty(), "a sleeping owner is told when it wakes, from the board");
    }

    /// **A drag is told by the lane the row LANDED in, not the one it asked
    /// for**: the verify gate turns a drag into `completed` on a verify=user
    /// row into a wait, and `pending` reads as the board's own `backlog`.
    #[tokio::test]
    async fn a_board_move_is_told_by_its_landed_lane() {
        use forge_primitives::tasks::{Task, TaskId, TaskStatus, Verify};
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/tp-board-landed-lane");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let owner = SessionSlot::new("TestOrg", "proj", "w1");
        let _owner_routed = install_fake_session_task(&ws, &owner);
        let sample = |id: &str, verify: Option<Verify>| Task {
            id: TaskId::from(id),
            project_name: "proj".to_owned(),
            subject: format!("subject {id}"),
            active_form: None,
            detail: None,
            status: TaskStatus::InProgress,
            owner: Some(owner.clone()),
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        };

        // Backlog is the board's word for `Pending`, and the notice wears it.
        ws.push_task(sample("t-1", None));
        ws.dispatch(Command::TaskMove {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            to: TaskStatus::Pending,
            place: None,
        })
        .expect("accepted");
        let (key, text) = told_one(&mut rx);
        assert_eq!(key, owner);
        assert!(text.contains("backlog"), "the lane's own word: {text}");
        assert!(!text.contains("pending"), "not the state's spelling: {text}");

        // The verify gate holds the user's own drag too: completed lands in
        // waiting, and the notice follows the row, not the drop.
        ws.push_task(sample("t-2", Some(Verify::User)));
        ws.dispatch(Command::TaskMove {
            project: "proj".to_owned(),
            id: "t-2".to_owned(),
            to: TaskStatus::Completed,
            place: None,
        })
        .expect("accepted");
        let (_, text) = told_one(&mut rx);
        assert!(text.contains("moved") && text.contains("waiting"), "the landed lane: {text}");
        assert!(!text.contains("completed"), "not the asked one: {text}");
    }

    /// **An assignment tells both ends of the hand-over** - the seat that
    /// lost the row and the one that got it - and a re-assignment to the
    /// same owner tells nobody, because nothing changed.
    #[tokio::test]
    async fn a_board_assignment_tells_both_ends() {
        use forge_primitives::tasks::{Task, TaskId, TaskStatus};
        let dir = tempdir().expect("tempdir");
        // The assign arm resolves the project through `config.projects`,
        // which the test overlay does not populate - so this stub carries a
        // real forge.toml.
        let path = dir.path().join("proj");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[orgs]]
name = "TestOrg"
accounts = ["Stargate"]
[[orgs.projects]]
name = "proj"
path = "{}"
"#,
                path.display()
            ),
        )
        .expect("write forge.toml");
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let (ws, mut rx) = Workspace::testing_stub_with_config(dir.path().to_owned(), config)
            .expect("the stub config is well-formed");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let lead = SessionSlot::new("TestOrg", "proj", "lead");
        let worker = SessionSlot::new("TestOrg", "proj", "w1");
        let _lead_routed = install_fake_session_task(&ws, &lead);
        let _worker_routed = install_fake_session_task(&ws, &worker);
        ws.push_task(Task {
            id: TaskId::from("t-1"),
            project_name: "proj".to_owned(),
            subject: "subject t-1".to_owned(),
            active_form: None,
            detail: None,
            status: TaskStatus::InProgress,
            owner: Some(lead.clone()),
            parent: None,
            waiting_on: None,
            estimate: None,
            rank: None,
            verify: None,
            attested: None,
            reserved: None,
            links: Vec::new(),
            attempt: 0,
            archived_at: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
            updated_at: std::time::SystemTime::UNIX_EPOCH,
        });
        ws.dispatch(Command::TaskAssign {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            owner: Some("w1".to_owned()),
        })
        .expect("accepted");
        let mut frames = told(&mut rx).into_iter();
        let (first_key, first_text) = frames.next().expect("the seat that lost it is told");
        assert_eq!(first_key, lead, "the one who lost the row hears first");
        assert!(first_text.contains("took"), "and hears what happened: {first_text}");
        let (second_key, second_text) = frames.next().expect("the seat that got it is told");
        assert_eq!(second_key, worker, "then the one who got it");
        assert!(second_text.contains("gave"), "hearing what happened: {second_text}");
        assert!(frames.next().is_none(), "and exactly the two ends");

        // The same owner again: nothing changed, nobody is told.
        ws.dispatch(Command::TaskAssign {
            project: "proj".to_owned(),
            id: "t-1".to_owned(),
            owner: Some("w1".to_owned()),
        })
        .expect("accepted");
        assert!(told(&mut rx).is_empty(), "a re-assignment to the same owner is not an edit");
    }

    fn usage_workspace() -> (tempfile::TempDir, Arc<Workspace>) {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        (dir, ws)
    }

    #[test]
    fn scan_usage_rolls_up_lifetime_and_dedups() {
        let (dir, ws) = usage_workspace();
        let slug_dir = dir.path().join("projects").join("-slug");
        std::fs::create_dir_all(&slug_dir).expect("mkdir");
        let rec = |id: &str, model: &str, out: u64| {
            format!(
                r#"{{"type":"assistant","timestamp":"2026-07-08T09:30:34.184Z","message":{{"id":"{id}","model":"{model}","usage":{{"output_tokens":{out}}}}}}}"#
            )
        };
        // "a" appears twice (a resume re-log) and must count once; "b"
        // lands on a second model in the same project.
        std::fs::write(
            slug_dir.join("s.jsonl"),
            [rec("a", "m", 10), rec("a", "m", 10), rec("b", "n", 5)].join("\n"),
        )
        .expect("write");

        let report = ws.scan_usage();
        assert_eq!(report.lifetime.total.output, 15, "duplicate id counted once");
        let m = report.lifetime.by_model.iter().find(|r| r.label == "m").expect("m row");
        assert_eq!(m.output, 10, "the re-logged duplicate is not double-counted");
        assert_eq!(
            report.lifetime.by_model.iter().find(|r| r.label == "n").expect("n row").output,
            5,
        );
        assert_eq!(report.lifetime.by_project.len(), 1, "one project folds from one slug");
        assert_eq!(report.lifetime.by_project[0].output, 15);
    }

    #[test]
    fn scan_usage_reuses_cached_summary_for_unchanged_file() {
        let (dir, ws) = usage_workspace();
        let slug_dir = dir.path().join("projects").join("-slug");
        std::fs::create_dir_all(&slug_dir).expect("mkdir");
        std::fs::write(
            slug_dir.join("s.jsonl"),
            r#"{"type":"assistant","timestamp":"2026-07-08T00:00:00Z","message":{"id":"a","model":"m","usage":{"output_tokens":10}}}"#,
        )
        .expect("write");

        // First scan parses and caches the file.
        let _ = ws.scan_usage();

        // Poison the cache under the exact key scan_usage uses, keeping
        // the file's real mtime/size so the reuse condition holds. A
        // second scan returning the poison proves it did not re-parse.
        let canonical = std::fs::canonicalize(dir.path().join("projects")).expect("canon");
        let file = forge_agent::env::token_usage::usage_files(&canonical)
            .into_iter()
            .next()
            .expect("one file");
        let meta = std::fs::metadata(&file).expect("meta");
        let mut days = std::collections::BTreeMap::new();
        days.insert(
            "2026-07-08".to_owned(),
            forge_agent::env::token_usage::TokenCounts {
                output: 999,
                ..forge_agent::env::token_usage::TokenCounts::default()
            },
        );
        let mut by_model_day = std::collections::BTreeMap::new();
        by_model_day.insert("POISON".to_owned(), days);
        ws.store_usage_summary(
            &file.to_string_lossy(),
            &forge_agent::env::token_usage::FileUsageSummary {
                mtime: meta.modified().expect("mtime"),
                size: meta.len(),
                folded_project: "slug".to_owned(),
                project_resolved: true,
                by_model_day,
            },
        );

        let report = ws.scan_usage();
        assert!(
            report.lifetime.by_model.iter().any(|r| r.label == "POISON"),
            "an unchanged file reuses the cached summary instead of re-parsing",
        );
    }

    #[test]
    fn scan_usage_reparses_a_changed_file() {
        let (dir, ws) = usage_workspace();
        let slug_dir = dir.path().join("projects").join("-slug");
        std::fs::create_dir_all(&slug_dir).expect("mkdir");
        let path = slug_dir.join("s.jsonl");
        let rec = |id: &str, out: u64| {
            format!(
                r#"{{"type":"assistant","timestamp":"2026-07-08T09:30:34.184Z","message":{{"id":"{id}","model":"m","usage":{{"output_tokens":{out}}}}}}}"#
            )
        };
        std::fs::write(&path, rec("a", 10)).expect("write");
        assert_eq!(ws.scan_usage().lifetime.total.output, 10);

        // Appending a record grows the file, so the cached summary's size
        // no longer matches and the file must be re-parsed - otherwise
        // "usage never updates" until a restart.
        std::fs::write(&path, [rec("a", 10), rec("b", 5)].join("\n")).expect("rewrite");
        assert_eq!(
            ws.scan_usage().lifetime.total.output,
            15,
            "a changed file is re-parsed, not served stale from the cache",
        );
    }

    #[test]
    fn scan_usage_re_derives_only_an_unresolved_project_label() {
        let (dir, ws) = usage_workspace();
        let rec = r#"{"type":"assistant","timestamp":"2026-07-08T09:30:34.184Z","message":{"id":"a","model":"m","usage":{"output_tokens":10}}}"#;
        for slug in ["-guessed", "-settled"] {
            let slug_dir = dir.path().join("projects").join(slug);
            std::fs::create_dir_all(&slug_dir).expect("mkdir");
            std::fs::write(slug_dir.join("s.jsonl"), rec).expect("write");
        }
        let _ = ws.scan_usage();

        // Poison both cached labels, keeping each file's real mtime/size
        // so the reuse condition still holds. The unresolved row stands
        // for a label guessed while the repo was not checked out.
        let canonical = std::fs::canonicalize(dir.path().join("projects")).expect("canon");
        for file in forge_agent::env::token_usage::usage_files(&canonical) {
            let mut summary = ws
                .load_usage_summary(&file.to_string_lossy())
                .expect("the first scan cached this file");
            let guessed = file.to_string_lossy().contains("-guessed");
            summary.folded_project =
                if guessed { "GUESS-POISON" } else { "SETTLED-POISON" }.to_owned();
            summary.project_resolved = !guessed;
            ws.store_usage_summary(&file.to_string_lossy(), &summary);
        }

        let labels: Vec<String> =
            ws.scan_usage().lifetime.by_project.into_iter().map(|row| row.label).collect();
        assert!(
            labels.iter().any(|l| l == "guessed") && !labels.iter().any(|l| l == "GUESS-POISON"),
            "a guessed label is re-derived on cache reuse, so it heals: {labels:?}",
        );
        assert!(
            labels.iter().any(|l| l == "SETTLED-POISON"),
            "a settled label is trusted from cache, not re-derived: {labels:?}",
        );
    }

    #[test]
    fn pricing_is_fresh_only_within_the_daily_window() {
        let (_dir, ws) = usage_workspace();
        assert!(!ws.pricing_is_fresh(), "no cache is not fresh");
        ws.store_pricing(&crate::store::pricing::CachedPricing {
            fetched_at: std::time::SystemTime::now(),
            json: r#"{"m":{"input_cost_per_token":1,"output_cost_per_token":1}}"#.to_owned(),
        });
        assert!(ws.pricing_is_fresh(), "a just-now fetch is within the window");
        ws.store_pricing(&crate::store::pricing::CachedPricing {
            fetched_at: std::time::SystemTime::now()
                - std::time::Duration::from_secs(2 * 24 * 60 * 60),
            json: "{}".to_owned(),
        });
        assert!(!ws.pricing_is_fresh(), "a two-day-old fetch is stale and re-fetched");
    }

    // -- /model pricing cache ----------------------------------------

    #[test]
    fn store_fresh_pricing_keeps_a_good_cache_on_a_garbage_response() {
        let (_dir, ws) = usage_workspace();
        let good = r#"{"m":{"input_cost_per_token":0.001,"output_cost_per_token":0.002}}"#;
        assert!(ws.store_fresh_pricing(good.to_owned()), "a valid table stores");
        assert!(!ws.load_pricing().is_empty(), "the cache holds the priced model");
        // A garbage 200 parses empty and must NOT wipe the good cache.
        assert!(!ws.store_fresh_pricing("not json".to_owned()), "garbage is rejected");
        assert!(!ws.load_pricing().is_empty(), "the good cache survives the garbage response");
    }

    #[test]
    fn project_name_for_path_resolves_by_cwd_and_degrades_cleanly() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());

        let path = "/tmp/cron-project-path-proj";
        ws.seed_test_project("cronproj", path);

        // The escalation guard for the one-time Connected stamp: a clean
        // project-root cwd MUST resolve the name. If this ever returns
        // None the prefix logic itself is broken, not the input cwd.
        assert_eq!(
            ws.project_name_for_path(path).as_deref(),
            Some("cronproj"),
            "a clean project-root cwd resolves the project name",
        );
        assert_eq!(
            ws.project_name_for_path(&format!("{path}/.claude/worktrees/reviewer")).as_deref(),
            Some("cronproj"),
            "a worktree worker's cwd resolves to its parent project",
        );
        assert!(
            ws.project_name_for_path("/tmp/no-such-configured-project").is_none(),
            "a cwd mapping to no configured project resolves to no name",
        );
        assert!(ws.project_name_for_path("").is_none(), "a blank cwd resolves to no name");
    }

    /// Regression guard for symmetric matching: the project root exists
    /// on disk under a symlinked ancestor (`link` -> `real`, so the root
    /// canonicalizes to a different path) while the queried worktree
    /// subdir does NOT exist. A per-side canonicalize would resolve the
    /// root but leave the absent subdir lexical, so the two would stop
    /// sharing a prefix and the tab's SCHEDULES / GOTIFY would go blank.
    /// Lexical matching keeps both sides in the same form.
    #[test]
    #[cfg(unix)]
    fn project_name_for_path_resolves_absent_worktree_under_symlinked_root() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());

        std::fs::create_dir_all(dir.path().join("real").join("proj")).expect("create real root");
        let link = dir.path().join("link");
        std::os::unix::fs::symlink(dir.path().join("real"), &link).expect("symlink");
        let root = link.join("proj");
        ws.seed_test_project("symproj", &root.to_string_lossy());

        let absent_worktree = root.join(".claude").join("worktrees").join("reviewer");
        assert_eq!(
            ws.project_name_for_path(&absent_worktree.to_string_lossy()).as_deref(),
            Some("symproj"),
            "an absent worktree subdir under a symlinked-ancestor root resolves to its parent",
        );
    }

    /// Buffer tracing output so the applied record can be read back.
    #[derive(Clone, Default)]
    struct LogCapture(Arc<Mutex<Vec<u8>>>);

    impl std::io::Write for LogCapture {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            self.0.lock().extend_from_slice(buf);
            Ok(buf.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for LogCapture {
        type Writer = Self;
        fn make_writer(&'a self) -> Self::Writer {
            self.clone()
        }
    }

    /// A stuck one-shot is re-evaluated on every 60s tick, so its warning
    /// has to be given once rather than once a minute for as long as the
    /// directory is missing. The repeat is still recorded, at debug, under
    /// the same `event_name`, so one filter still finds the whole story.
    ///
    /// The clearing is the half that matters. The state holds only the
    /// last pass's answer, so a cron that goes unwakeable AGAIN warns
    /// again; a set that never cleared would leave a durable cron that IS
    /// firing silent, which is the failure this family of changes exists
    /// to remove.
    ///
    /// Runs real fire passes under a log capture, which is why it sits
    /// beside `LogCapture` rather than with the other cron tests.
    #[test]
    fn a_stuck_cron_warns_once_then_warns_again_after_it_clears() {
        use forge_primitives::cron::{CronEntry, CronId, CronKind};
        let (ws, _rx) = Workspace::testing_stub();
        let db_dir = tempdir().expect("db dir");
        ws.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        let project_dir = tempdir().expect("project dir");
        ws.seed_test_project("proj", &project_dir.path().to_string_lossy());
        let key = ws.project_key_for_name("proj").expect("seeded project");
        // A git worker whose worktree is not there, so the wave would skip
        // it and no fire can land.
        ws.record_worker_row(
            &key,
            "steward",
            "steward-uuid",
            "c",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
            None,
        )
        .expect("seed the stranded row");

        // A whole minute, so the recurring's next `*/5` slot is at least a
        // minute later and the middle pass below cannot catch it.
        let t0 = std::time::SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(600_000_000);
        for (id, kind) in
            [("once", CronKind::Once(t0)), ("again", CronKind::Recurring("*/5 * * * *".to_owned()))]
        {
            ws.push_cron(CronEntry {
                id: CronId::from(id),
                project_name: "proj".to_owned(),
                kind,
                prompt: "p".to_owned(),
                created_at: std::time::SystemTime::UNIX_EPOCH,
                description: None,
                last_fire: None,
                next_fire: t0,
                team_role: Some("steward".to_owned()),
                wake: true,
            });
        }

        let log_of = |capture: &LogCapture| String::from_utf8_lossy(&capture.0.lock()).into_owned();
        let warns = |capture: &LogCapture| -> usize {
            log_of(capture)
                .lines()
                .filter(|line| line.contains("cron_owner_cannot_be_woken") && line.contains("WARN"))
                .count()
        };
        let pass = |capture: &LogCapture, now: std::time::SystemTime| {
            let subscriber = tracing_subscriber::fmt()
                .with_max_level(tracing::Level::DEBUG)
                .with_writer(capture.clone())
                .finish();
            tracing::subscriber::with_default(subscriber, || ws.fire_due_crons(now));
        };

        let first = LogCapture::default();
        pass(&first, t0);
        assert_eq!(
            warns(&first),
            2,
            "both crons are newly unwakeable, so both warn: {}",
            log_of(&first)
        );

        // Half a minute on: the one-shot is still stuck and still due, and
        // the recurring has advanced past this pass entirely.
        let second = LogCapture::default();
        pass(&second, t0 + std::time::Duration::from_secs(30));
        assert_eq!(
            warns(&second),
            0,
            "a cron that was already unwakeable last pass does not warn again: {}",
            log_of(&second),
        );
        assert!(
            log_of(&second).contains("cron_owner_cannot_be_woken"),
            "and it is still recorded, at debug, under the same event_name: {}",
            log_of(&second),
        );

        // A day on, the recurring is due again with its owner still
        // stranded: this time that is new again.
        let third = LogCapture::default();
        pass(&third, t0 + std::time::Duration::from_secs(86_400));
        assert_eq!(
            warns(&third),
            1,
            "a cron unwakeable again after a pass that did not see it must warn again - a \
             set that never cleared would leave a firing cron silent: {}",
            log_of(&third),
        );
    }

    /// The applied record names the keys a project contributed and must
    /// never carry their values - it is always-on, so a widened field
    /// writes tokens to disk on every spawn. Asserted on a DIRECT call:
    /// the record is emitted in this crate before any subprocess, so
    /// this needs no binary and no wait.
    #[test]
    fn the_applied_record_logs_key_names_and_never_a_value() {
        const SENTINEL: &str = "value-must-never-be-logged";
        let dir = tempdir().expect("tempdir");
        let root = dir.path().join("solo");
        fs::create_dir_all(&root).expect("root");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "solo"
path = "{root}"
env = {{ SOLO_TOKEN = "value-must-never-be-logged" }}
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                root = root.display()
            ),
        )
        .expect("write forge.toml");
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let project = config.projects[0].clone();

        let capture = LogCapture::default();
        let subscriber = tracing_subscriber::fmt().with_writer(capture.clone()).finish();
        tracing::subscriber::with_default(subscriber, || {
            session_env_for(&project, &std::collections::HashMap::new());
        });
        let log = String::from_utf8_lossy(&capture.0.lock()).into_owned();

        assert!(log.contains("SOLO_TOKEN"), "the record names the key: {log}");
        assert!(!log.contains(SENTINEL), "and never its value: {log}");
    }

    /// Two projects at one path collide on the session-storage key, so
    /// neither can be told apart: an ambiguous target resolves to NO
    /// project rather than the first match's, which is what refuses the
    /// spawn rather than handing it one twin's env and the other's pin.
    /// Second assertion is the control: an unambiguous project still
    /// resolves, so the refusal above is about the twins and not about
    /// the lookup being broken for every target.
    #[test]
    fn an_ambiguous_storage_key_resolves_to_no_project() {
        let dir = tempdir().expect("tempdir");
        let shared = dir.path().join("shared");
        let solo = dir.path().join("solo");
        fs::create_dir_all(&shared).expect("shared");
        fs::create_dir_all(&solo).expect("solo");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "twin-a"
path = "{shared}"
env = {{ TWIN_TOKEN = "twin-a-secret" }}
[[orgs.projects]]
name = "twin-b"
path = "{shared}"
[[orgs.projects]]
name = "solo"
path = "{solo}"
env = {{ SOLO_TOKEN = "solo-secret" }}

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                shared = shared.display(),
                solo = solo.display()
            ),
        )
        .expect("write forge.toml");
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let (ws, _rx) = Workspace::testing_stub_with_config(dir.path().to_owned(), config)
            .expect("the stub config's [[slack]] entries are well-formed");
        let key = |p: &std::path::Path| {
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                &p.to_string_lossy(),
            )))
        };

        let _ = key(&shared);
        let ambiguous = SessionTarget::FreshInProject {
            slot: SessionSlot::worker("TestOrg", "no-such-project", "minted-twin-id"),
            cwd: None,
        };
        assert!(
            ws.project_for_target(&ambiguous).is_none(),
            "a slot naming no declared project resolves to none, which refuses the spawn",
        );

        let solo_target = SessionTarget::Named("solo".to_owned());
        assert_eq!(
            ws.project_for_target(&solo_target).map(|project| project.name),
            Some("solo".to_owned()),
            "an unambiguous project still resolves with nothing on disk yet",
        );
    }

    /// The case where cwd has nothing to read: a resume of a session
    /// whose transcript is gone. The slot names the project, so the
    /// project resolves from `forge.toml` with an empty catalog - there
    /// is no transcript to carry it.
    #[test]
    fn a_resume_with_no_transcript_resolves_its_project() {
        let dir = tempdir().expect("tempdir");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "gone"
path = "/tmp/gone"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let (ws, _rx) = Workspace::testing_stub_with_config(dir.path().to_owned(), config)
            .expect("the stub config's [[slack]] entries are well-formed");
        assert!(ws.catalog.lock().is_empty(), "no transcript was ever scanned");
        let key = SessionSlot::lead("Personal", "gone");

        assert_eq!(
            ws.project_for_target(&SessionTarget::Session(key)).map(|p| p.name),
            Some("gone".to_owned()),
            "the project resolves from the slot, with no transcript to read it from",
        );
    }

    /// A mock `claude` that reports the id the spawn was told to resume, so
    /// a test can see which session the seat actually runs under. The
    /// fixture always names `mock-session-001`; awk rewrites that on each
    /// line and flushes, because a buffered init line would stall the
    /// handshake instead of arriving.
    fn id_preserving_mock(dir: &std::path::Path) -> String {
        use std::os::unix::fs::PermissionsExt;

        let fixture =
            concat!(env!("CARGO_MANIFEST_DIR"), "/../forge-sdk/tests/fixtures/mock_claude.sh");
        let path = dir.join("mock_claude_id.sh");
        fs::write(
            &path,
            format!(
                r#"#!/bin/sh
id=""
prev=""
for arg in "$@"; do
  if [ "$prev" = "--resume" ] || [ "$prev" = "--session-id" ]; then
    id="$arg"
  fi
  prev="$arg"
done
if [ -z "$id" ]; then id="mock-session-001"; fi
"{fixture}" "$@" | awk -v id="$id" '{{ gsub("mock-session-001", id); print; fflush() }}'
"#
            ),
        )
        .expect("write the id-preserving mock");
        fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).expect("chmod the mock");
        path.to_string_lossy().into_owned()
    }

    /// A workspace whose lead slot has no task, a ready account and a mock
    /// CLI that reports the resumed id.
    fn resume_workspace(dir: &std::path::Path, project: &std::path::Path) -> Arc<Workspace> {
        let forge_dir = crate::config::ensure_forge_data_dir(dir).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "{}"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                project.display()
            ),
        )
        .expect("write forge.toml");
        let workspace = Arc::new(Workspace::new_for_test(dir.to_owned()).expect("workspace"));
        workspace
            .install_db_for_test(crate::store::Db::open(&dir.join("db.redb")).expect("open db"));
        workspace.seed_test_ready_account("Stargate");
        workspace.seed_test_gateway_ready(true);
        workspace
    }

    /// **A `/resume` on a slot whose task has exited must start the seat.**
    /// The task leaves with its child, so the forge command lands with no
    /// sender; answering `UnknownSession` is the defect the handoff's
    /// recovery promises against. The lead goes through the project wake.
    #[tokio::test]
    async fn a_resume_with_no_task_starts_the_lead_on_the_named_id() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = resume_workspace(dir.path(), project.path());
        forge_agent::set_test_sdk_binary(Some(id_preserving_mock(dir.path())));
        let mut updates = workspace.subscribe_mirror();
        let key = SessionSlot::lead("Default", "forge");
        let known = "11111111-2222-3333-4444-555555555555";

        let sent = workspace.dispatch_from_view(Command::Prompt {
            key: key.clone(),
            text: format!("/resume {known}"),
            attachments: Vec::new(),
        });
        assert!(sent.is_ok(), "the resume is taken rather than refused: {sent:?}");

        let connected = tokio::time::timeout(Duration::from_secs(30), async {
            while let Some(seat) = updates.recv().await {
                if let SessionUpdate::Connected { key: seen, session_id, .. } = &*seat.update
                    && *seen == key
                {
                    return session_id.to_string();
                }
                if let SessionUpdate::ConnectionFailed { key: seen, message, .. } = &*seat.update
                    && *seen == key
                {
                    panic!("the resume's start failed: {message}");
                }
            }
            panic!("the update stream closed before the resumed seat connected");
        })
        .await
        .expect("the task-less resume reaches Connected");
        assert_eq!(connected, known, "the seat runs under the id that was named");
        let domain = workspace.domain_session_for(&key).expect("the task registered its domain");
        assert_eq!(
            domain.lock().session_id.as_ref().map(std::string::ToString::to_string),
            Some(known.to_owned()),
            "and the domain is the resumed occupant",
        );
        let stored = {
            let db = workspace.db.lock();
            let db = db.as_ref().expect("db");
            crate::store::sessions::get(db, "Default", "forge", "lead")
                .expect("read")
                .and_then(|row| row.session_id)
        };
        assert_eq!(stored.as_deref(), Some(known), "and the row names it for the next boot");
        forge_agent::set_test_sdk_binary(None);
    }

    /// A workspace whose lead can actually spawn, over a mock CLI that
    /// reports the id it was told to resume, with the kick dispatcher
    /// running so a stamped note would reach the stream.
    fn boot_lead_workspace(dir: &std::path::Path, project: &std::path::Path) -> Arc<Workspace> {
        let workspace = resume_workspace(dir, project);
        forge_agent::set_test_sdk_binary(Some(id_preserving_mock(dir)));
        workspace.start_kick_dispatcher();
        workspace
    }

    /// Dispatch a `SpawnProject` for the fixture's lead with the launch
    /// settings a caller states. The boot wave passes the restart note for
    /// a seat it read as mid-turn; a parked seat and every other wake pass
    /// `None`.
    fn spawn_lead(workspace: &Arc<Workspace>, force_new: bool, resume_kick: Option<String>) {
        let spawned = workspace.dispatch(Command::SpawnProject {
            project_name: "forge".to_owned(),
            launch_settings: SessionLaunchSettings { force_new, resume_kick, ..Default::default() },
        });
        assert!(spawned.is_ok(), "the spawn is taken: {spawned:?}");
    }

    /// Whether `update` is a user turn carrying the restart note on `key`.
    fn is_restart_note(update: &SessionUpdate, key: &SessionSlot) -> bool {
        if let SessionUpdate::ChatAppended { key: seen, msg: Message::User { message, .. }, .. } =
            update
            && seen == key
        {
            matches!(
                message.content.first(),
                Some(forge_primitives::ContentBlock::Text { text, .. }) if text == LEAD_RESTART_NOTE
            )
        } else {
            false
        }
    }

    /// Watch the stream until the lead connects, noting any restart turn
    /// that arrives before or just after it. The extra `note_window`
    /// after `Connected` is what makes a negative meaningful: the kick
    /// dispatcher fires a first enqueue with no added latency, so a note
    /// a first boot or `--new` should not send has to be absent by then.
    async fn lead_boot_frames(
        updates: &mut tokio::sync::mpsc::UnboundedReceiver<SeatUpdate>,
        key: &SessionSlot,
        note_window: Duration,
    ) -> (bool, bool) {
        let before = tokio::time::timeout(Duration::from_secs(30), async {
            let mut note_seen = false;
            while let Some(seat) = updates.recv().await {
                note_seen |= is_restart_note(&seat.update, key);
                if let SessionUpdate::Connected { key: seen, .. } = &*seat.update
                    && seen == key
                {
                    return (true, note_seen);
                }
            }
            (false, note_seen)
        })
        .await
        .expect("the spawn reaches Connected");
        if !before.0 {
            return before;
        }
        let after = tokio::time::timeout(note_window, async {
            while let Some(seat) = updates.recv().await {
                if is_restart_note(&seat.update, key) {
                    return true;
                }
            }
            false
        })
        .await
        .unwrap_or(false);
        (true, before.1 || after)
    }

    /// **The first boot on this build seeds a row written before the field
    /// and opens it.** The migration is what every existing install relies
    /// on: without it the row's state is absent, which the wave reads as a
    /// lead that never spawned, and no project reopens after the upgrade.
    #[test]
    fn the_boot_seeds_a_row_written_before_the_field_and_opens_it() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "{}"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                project.path().display()
            ),
        )
        .expect("write forge.toml");
        // A row of the shape the previous build wrote, in the store the
        // workspace will open.
        let app_support = dir.path().join("app-support");
        std::fs::create_dir_all(app_support.join("stores")).expect("stores dir");
        let db = crate::store::Db::open(&crate::store::path_for(&app_support, dir.path()))
            .expect("open the scratch store");
        crate::store::sessions::put_raw_for_test(
            &db,
            "Default",
            "forge",
            "lead",
            br#"{"session_id":"id-1"}"#,
        )
        .expect("plant the pre-change row");
        drop(db);

        let workspace =
            Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        let key = SessionSlot::lead("Default", "forge");

        let targets = workspace.boot_wave_targets(None);
        assert_eq!(targets.len(), 1, "the seeded seat is in the wave: {targets:?}");
        assert_eq!(targets[0].project_name, "forge");
        assert_eq!(
            targets[0].resume_kick, None,
            "a row from before the field has no interrupted turn to report",
        );
        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::Idle),
            "the migration wrote the state the wave then read",
        );
    }

    /// **A bare boot opens exactly the seats that were open.** A mid-turn
    /// lead takes the restart note, a parked one is resumed with nothing, a
    /// closed one is left shut, and a project whose lead never spawned has
    /// no row to open.
    #[test]
    fn the_boot_wave_opens_the_seats_that_were_open() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = resume_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");

        assert!(
            workspace.boot_wave_targets(None).is_empty(),
            "a lead that never spawned has no row to open",
        );

        workspace.record_session_id("Default", "forge", "lead", "id-1");
        workspace.record_seat_state(&key, SeatState::Idle);
        let parked = workspace.boot_wave_targets(None);
        assert_eq!(parked.len(), 1, "a parked seat is open");
        assert_eq!(parked[0].project_name, "forge");
        assert_eq!(parked[0].resume_kick, None, "a parked seat is resumed with nothing");

        workspace.record_seat_state(&key, SeatState::InTurn);
        let interrupted = workspace.boot_wave_targets(None);
        assert_eq!(interrupted.len(), 1, "a seat mid-turn is open");
        assert_eq!(
            interrupted[0].resume_kick.as_deref(),
            Some(LEAD_RESTART_NOTE),
            "an interrupted turn earns the restart note",
        );

        workspace.record_seat_state(&key, SeatState::Closed);
        assert!(
            workspace.boot_wave_targets(None).is_empty(),
            "the close door keeps the project shut at the next boot",
        );
        let named = workspace.boot_wave_targets(Some("forge"));
        assert_eq!(named.len(), 1, "naming the project opens it whether or not it was closed");
        assert_eq!(named[0].project_name, "forge");
        assert_eq!(named[0].resume_kick, None, "a closed seat has no interrupted turn to report");
    }

    /// **A boot spawn that carries a stored id hands the lead the restart
    /// note as its first turn.** This is the whole chain: the launch
    /// setting the boot wave sends, the spawn's stored-id gate, and the
    /// Connected hook.
    #[tokio::test]
    async fn a_boot_spawn_kicks_a_resumed_lead_with_the_restart_note() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");
        workspace.record_session_id(
            "Default",
            "forge",
            "lead",
            "11111111-2222-3333-4444-555555555555",
        );

        let mut updates = workspace.subscribe_mirror();
        spawn_lead(&workspace, false, Some(LEAD_RESTART_NOTE.to_owned()));
        let (connected, note) = lead_boot_frames(&mut updates, &key, Duration::from_secs(5)).await;
        assert!(connected, "the lead connects before the note arrives");
        assert!(note, "a lead with a stored id to resume is kicked with the restart note");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A first boot carries no stored id**, so the lead it starts gets
    /// no restart note even though the boot wave asked for one. The
    /// `--new` test pins the same gate from the other side, where an id
    /// exists and the launch refuses it.
    #[tokio::test]
    async fn a_first_boot_lead_gets_no_restart_note() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");

        let mut updates = workspace.subscribe_mirror();
        spawn_lead(&workspace, false, Some(LEAD_RESTART_NOTE.to_owned()));
        let (connected, note) = lead_boot_frames(&mut updates, &key, Duration::from_secs(2)).await;
        assert!(connected, "the lead connects, so the absence of a note is the property");
        assert!(!note, "a first boot delivers no restart note");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A spawn leaves the seat open with no turn in flight.** The boot
    /// wave read the pre-spawn state to decide whether to kick it; once the
    /// child is up and parked, the row says so, and only a prompt moves it.
    #[tokio::test]
    async fn a_spawn_leaves_the_seat_idle() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");

        let mut updates = workspace.subscribe_mirror();
        spawn_lead(&workspace, false, None);
        let (connected, note) = lead_boot_frames(&mut updates, &key, Duration::from_secs(2)).await;
        assert!(connected, "the spawn reaches Connected");
        assert!(!note, "a spawn with no requested note is not kicked");
        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::Idle),
            "the spawned seat is open and parked",
        );
        forge_agent::set_test_sdk_binary(None);
    }

    /// **`--new` mints over the stored session**, so the lead starts fresh
    /// even though an id exists, and gets no restart note.
    #[tokio::test]
    async fn a_force_new_boot_lead_gets_no_restart_note() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");
        workspace.record_session_id(
            "Default",
            "forge",
            "lead",
            "11111111-2222-3333-4444-555555555555",
        );

        let mut updates = workspace.subscribe_mirror();
        spawn_lead(&workspace, true, Some(LEAD_RESTART_NOTE.to_owned()));
        let (connected, note) = lead_boot_frames(&mut updates, &key, Duration::from_secs(2)).await;
        assert!(connected, "the lead connects, so the absence of a note is the property");
        assert!(!note, "`--new` delivers no restart note over the stored session it replaced");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A spawn with a stored id but no requested note sends none.** The
    /// note is a request the boot wave makes, not something a resume earns:
    /// a wake that states ordinary launch settings (a peer prompt, a cron)
    /// resumes the seat without kicking it with a restart note. Without
    /// this, defaulting the note whenever an id exists passes every test.
    #[tokio::test]
    async fn a_stored_id_without_a_requested_note_sends_none() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");
        workspace.record_session_id(
            "Default",
            "forge",
            "lead",
            "11111111-2222-3333-4444-555555555555",
        );

        let mut updates = workspace.subscribe_mirror();
        spawn_lead(&workspace, false, None);
        let (connected, note) = lead_boot_frames(&mut updates, &key, Duration::from_secs(2)).await;
        assert!(connected, "the lead connects, so the absence of a note is the property");
        assert!(!note, "a spawn that was not asked for the note sends none");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **The worker restore dispatches the row's own spawn.** The id named
    /// wins over the stale id its row still holds, and the row's charter,
    /// kick, tree, families and interactive flag carry the spawn. The boot
    /// re-spawn's tests are the pattern for reading the command.
    #[tokio::test]
    async fn a_resume_with_no_task_dispatches_the_workers_stored_spawn() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = resume_workspace(dir.path(), project.path());
        let project_key = workspace.project_key_for_name("forge").expect("project");
        let stale = "33333333-4444-5555-6666-777777777777";
        let named = "22222222-3333-4444-5555-666666666666";
        workspace
            .record_worker_row(
                &project_key,
                "labourer",
                stale,
                "the stored charter",
                Some("the first kick"),
                Some("the stored resume kick"),
                true,
                crate::mcp::workers::types::WorkerTree {
                    is_git_repo: false,
                    cwd: Some(project.path().to_string_lossy().into_owned()),
                },
                Some(&["tasks".to_owned(), "agents".to_owned()]),
            )
            .expect("seed the worker row");
        workspace.enable_test_dispatch_intercept();
        let key = SessionSlot::worker("Default", "forge", "labourer");

        // The intercept sits on the route, so it would capture the outer
        // `ResumeSession` itself; the fields under test are the spawn the
        // task-less route dispatches, so drive that route's own call. The
        // forged-prompt path is covered by the lead test and the refusals
        // below.
        workspace
            .resume_without_task(&key, named, SessionLaunchSettings::default())
            .expect("the restore is accepted");

        let dispatched = workspace.drain_test_dispatch_buffer();
        let Some(Command::SpawnWorker {
            project_key: seen_project,
            label,
            charter,
            resume_existing,
            kick,
            resume_kick,
            interactive,
            mcp_families,
            cwd,
            from_boot_respawn,
            ..
        }) = dispatched.iter().find(|command| matches!(command, Command::SpawnWorker { .. }))
        else {
            panic!("the restore dispatches a worker spawn: {dispatched:?}");
        };
        assert_eq!(seen_project.as_str(), project_key.as_str(), "the row's project");
        assert_eq!(label, "labourer");
        assert_eq!(
            resume_existing.as_deref(),
            Some(named),
            "the id that was named, not the row's stale one",
        );
        assert_eq!(charter, "the stored charter");
        assert_eq!(
            kick.as_deref(),
            Some("the stored resume kick"),
            "the row's resume kick, not its first kick",
        );
        assert!(resume_kick.is_none());
        assert!(*interactive, "the row's interactive flag");
        assert_eq!(
            mcp_families.as_ref().map(|families| families.join(",")).as_deref(),
            Some("tasks,agents"),
            "the row's family selection",
        );
        assert_eq!(
            cwd.as_deref(),
            Some(project.path().to_string_lossy().as_ref()),
            "the row's tree",
        );
        assert!(*from_boot_respawn, "a restore carries the boot re-spawn's row semantics");
    }

    /// **A failed tombstone is replaced, not doubled.** A failed spawn keeps
    /// its entry for a worker with no worktree; it is not live, so an insert
    /// that ignored it would append a second entry for the slot and the
    /// by-slot reads would move the tombstone while the new entry stranded as
    /// a phantom. The restore leaves exactly one entry, the live one.
    #[tokio::test]
    async fn a_worker_resume_replaces_the_failed_tombstone() {
        use forge_primitives::WorkerLiveness;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = resume_workspace(dir.path(), project.path());
        let project_key = workspace.project_key_for_name("forge").expect("project");
        let stale = "33333333-4444-5555-6666-777777777777";
        let named = "22222222-3333-4444-5555-666666666666";
        workspace
            .record_worker_row(
                &project_key,
                "labourer",
                stale,
                "the stored charter",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the worker row");
        let slot = SessionSlot::worker("Default", "forge", "labourer");
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "labourer".to_owned(),
                charter: "the stored charter".to_owned(),
                slot: slot.clone(),
                session_id: Some(forge_primitives::SessionId::new(stale)),
                status: WorkerLiveness::Failed,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::lead("Default", "forge"),
                needs_tag: false,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: Some("the failed start's reason".to_owned()),
                kick: None,
            },
        );
        assert_eq!(workspace.count_live_workers(&project_key), 0, "the tombstone is not live");
        forge_agent::set_test_sdk_binary(Some(id_preserving_mock(dir.path())));
        let mut updates = workspace.subscribe_mirror();

        let sent = workspace.dispatch_from_view(Command::Prompt {
            key: slot.clone(),
            text: format!("/resume {named}"),
            attachments: Vec::new(),
        });
        assert!(sent.is_ok(), "the resume is taken rather than refused: {sent:?}");

        let connected = tokio::time::timeout(Duration::from_secs(30), async {
            while let Some(seat) = updates.recv().await {
                if let SessionUpdate::Connected { key: seen, session_id, .. } = &*seat.update
                    && *seen == slot
                {
                    return session_id.to_string();
                }
                if let SessionUpdate::ConnectionFailed { key: seen, message, .. } = &*seat.update
                    && *seen == slot
                {
                    panic!("the restore's start failed: {message}");
                }
            }
            panic!("the update stream closed before the restored worker connected");
        })
        .await
        .expect("the restore reaches Connected");
        assert_eq!(connected, named, "the restored worker runs under the named id");

        let entries = {
            let workers = workspace.live_workers.lock();
            workers.get(&project_key).cloned().unwrap_or_default()
        };
        assert_eq!(entries.len(), 1, "the tombstone is replaced, not doubled: {entries:?}");
        assert!(entries[0].is_live(), "and the entry left is the live one, not the tombstone");
        assert_eq!(
            entries[0].session_id.as_ref().map(std::string::ToString::to_string),
            Some(named.to_owned()),
            "carrying the resumed id",
        );
        assert_eq!(workspace.count_live_workers(&project_key), 1, "and one cap slot");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A refused restore says so.** The spawn handler answers a refusal
    /// with its reason; the route surfaces that as a Notice rather than
    /// echoing the `/resume` as accepted.
    #[tokio::test]
    async fn a_refused_worker_restore_says_so() {
        use forge_primitives::WorkerLiveness;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = resume_workspace(dir.path(), project.path());
        let project_key = workspace.project_key_for_name("forge").expect("project");
        let named = "22222222-3333-4444-5555-666666666666";
        workspace
            .record_worker_row(
                &project_key,
                "labourer",
                "33333333-4444-5555-6666-777777777777",
                "the stored charter",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the worker row");
        let slot = SessionSlot::worker("Default", "forge", "labourer");
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "labourer".to_owned(),
                charter: "the stored charter".to_owned(),
                slot: slot.clone(),
                session_id: Some(forge_primitives::SessionId::new(named)),
                status: WorkerLiveness::Running,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::lead("Default", "forge"),
                needs_tag: false,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );
        let mut updates = workspace.subscribe_mirror();

        let sent = workspace.dispatch_from_view(Command::Prompt {
            key: slot.clone(),
            text: format!("/resume {named}"),
            attachments: Vec::new(),
        });
        assert!(sent.is_ok(), "the route takes the request: {sent:?}");

        let said = tokio::time::timeout(Duration::from_secs(5), async {
            while let Some(seat) = updates.recv().await {
                if let SessionUpdate::Notice { key: seen, severity, text } = &*seat.update
                    && *seen == slot
                {
                    return (*severity, text.clone());
                }
            }
            panic!("the update stream closed before the refusal was announced");
        })
        .await
        .expect("the refusal is announced");
        assert_eq!(said.0, NoticeSeverity::Error, "as a failure the reader can act on");
        assert!(said.1.contains("the resume was refused"), "and it says what happened: {}", said.1);
        assert!(said.1.contains("already live"), "with the handler's own reason: {}", said.1);
    }

    /// The worker door refuses, by name, what it cannot restore: a project
    /// the config does not declare, a label with no row, and a row the store
    /// cannot read.
    #[tokio::test]
    async fn a_resume_with_no_task_refuses_a_worker_it_cannot_restore() {
        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = resume_workspace(dir.path(), project.path());

        let unknown = SessionSlot::worker("Default", "gone", "labourer");
        let sent = workspace.dispatch_from_view(Command::Prompt {
            key: unknown.clone(),
            text: "/resume 22222222-3333-4444-5555-666666666666".to_owned(),
            attachments: Vec::new(),
        });
        assert!(
            matches!(sent, Err(DispatchError::UnknownSession(_))),
            "an undeclared project is refused: {sent:?}",
        );

        let absent = SessionSlot::worker("Default", "forge", "absent");
        let sent = workspace.dispatch_from_view(Command::Prompt {
            key: absent.clone(),
            text: "/resume 22222222-3333-4444-5555-666666666666".to_owned(),
            attachments: Vec::new(),
        });
        assert!(
            matches!(sent, Err(DispatchError::UnknownSession(_))),
            "a label with no row is refused: {sent:?}",
        );

        // No store at all: the row cannot be read, which is a refusal rather
        // than a spawn composed from defaults.
        *workspace.db.lock() = None;
        let unreadable = SessionSlot::worker("Default", "forge", "labourer");
        let sent = workspace.dispatch_from_view(Command::Prompt {
            key: unreadable.clone(),
            text: "/resume 22222222-3333-4444-5555-666666666666".to_owned(),
            attachments: Vec::new(),
        });
        assert!(
            matches!(sent, Err(DispatchError::UnknownSession(_))),
            "an unreadable row is refused: {sent:?}",
        );
    }

    /// An update merges only the supplied fields onto the stored row and
    /// survives the redb round-trip. It must never create a row: a row
    /// means the worker should be alive, so an absent one reports "not
    /// updated" rather than bringing a worker into existence at the next
    /// lead connect.
    #[test]
    fn update_worker_row_merges_only_supplied_fields() {
        let (ws, _rx) = Workspace::testing_stub();
        let dir = tempdir().expect("tempdir");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        ws.seed_test_project("forge", "/tmp/update-worker-row");
        let project = ws.project_key_for_name("forge").expect("seeded project");
        ws.record_worker_row(
            &project,
            "steward",
            "steward-test-id",
            "original charter",
            Some("original kick"),
            Some("original resume"),
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
            None,
        )
        .expect("seed the row this test then updates");
        let stored = |ws: &Arc<Workspace>| {
            ws.worker_rows_for_project(&project)
                .into_iter()
                .find(|w| w.label == "steward")
                .expect("row present")
        };

        assert!(
            ws.update_worker_row(
                &project,
                "steward",
                Some("new charter".to_owned()),
                None,
                None,
                None
            )
            .expect("update succeeds"),
            "an existing row reports updated",
        );
        let row = stored(&ws);
        assert_eq!(row.charter.as_deref(), Some("new charter"), "the supplied field changed");
        assert_eq!(row.kick.as_deref(), Some("original kick"), "an absent field is untouched");
        assert_eq!(
            row.resume_kick.as_deref(),
            Some("original resume"),
            "an absent field is untouched",
        );

        // The other two fields update independently, and the charter set
        // above persists across a second call.
        assert!(
            ws.update_worker_row(
                &project,
                "steward",
                None,
                Some("new kick".to_owned()),
                Some("new resume".to_owned()),
                None,
            )
            .expect("second update succeeds"),
        );
        let row = stored(&ws);
        assert_eq!(row.charter.as_deref(), Some("new charter"), "the earlier update survived");
        assert_eq!(row.kick.as_deref(), Some("new kick"));
        assert_eq!(row.resume_kick.as_deref(), Some("new resume"));

        // The family selection follows the same contract: supplied
        // replaces, absent keeps, empty resets to every family.
        assert!(
            ws.update_worker_row(
                &project,
                "steward",
                None,
                None,
                None,
                Some(vec!["cron".to_owned()])
            )
            .expect("families update succeeds"),
        );
        assert_eq!(stored(&ws).mcp_families, Some(vec!["cron".to_owned()]));
        assert!(
            ws.update_worker_row(&project, "steward", None, None, None, None)
                .expect("absent families update succeeds"),
        );
        assert_eq!(stored(&ws).mcp_families, Some(vec!["cron".to_owned()]), "absent keeps");
        assert!(
            ws.update_worker_row(&project, "steward", None, None, None, Some(Vec::new()))
                .expect("reset succeeds"),
        );
        assert_eq!(stored(&ws).mcp_families, None, "an empty list resets to every family");

        assert!(
            !ws.update_worker_row(&project, "ghost", Some("c".to_owned()), None, None, None)
                .expect("absent row is not an error"),
            "no row means not updated",
        );
        assert!(
            ws.worker_rows_for_project(&project).iter().all(|w| w.label != "ghost"),
            "a failed update must not create the row",
        );
    }

    fn live_worker_entry(label: &str, key: &str) -> crate::mcp::workers::types::WorkerEntry {
        crate::mcp::workers::types::WorkerEntry {
            label: label.to_owned(),
            charter: "c".to_owned(),
            slot: SessionSlot::from_str_for_test(key),
            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,
        }
    }

    /// The Projects-pane close (`handle_close_worker` -> `teardown_worker`)
    /// deletes the persisted dynamic-worker row so it never re-spawns,
    /// scoped to the closed label - siblings survive.
    #[tokio::test]
    async fn projects_pane_close_deletes_persisted_dynamic_worker_row() {
        let (ws, _rx) = Workspace::testing_stub();
        let dir = tempdir().expect("tempdir");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        ws.seed_test_project("forge", "/tmp/pane-close-forge");
        let project = ws.project_key_for_name("forge").expect("seeded project");

        seed_worker_row(&ws, &project, "reviewer");
        seed_worker_row(&ws, &project, "tester");
        ws.insert_live_worker(&project, live_worker_entry("reviewer", "worker-1"));
        ws.insert_live_worker(&project, live_worker_entry("tester", "worker-2"));

        crate::spawn::handle_close_worker(&ws, &project, "reviewer");

        let rows = {
            let guard = ws.db.lock();
            crate::store::sessions::list_for_project(
                guard.as_ref().expect("db installed"),
                "TestOrg",
                "forge",
            )
            .expect("list")
        };
        let labels: Vec<&str> = rows.iter().map(|w| w.label.as_str()).collect();
        assert_eq!(labels, vec!["tester"], "close deletes only the closed worker's row");
    }

    /// The `agents__despawn` path (`handle_despawn_worker` ->
    /// `teardown_worker`) deletes the persisted dynamic-worker row too.
    #[tokio::test]
    async fn mcp_despawn_deletes_persisted_dynamic_worker_row() {
        let (ws, _rx) = Workspace::testing_stub();
        let dir = tempdir().expect("tempdir");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        ws.seed_test_project("forge", "/tmp/despawn-forge");
        let project = ws.project_key_for_name("forge").expect("seeded project");

        seed_worker_row(&ws, &project, "reviewer");
        ws.insert_live_worker(&project, live_worker_entry("reviewer", "worker-1"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        crate::spawn::handle_despawn_worker(&ws, &project, "reviewer", false, tx);
        assert!(matches!(rx.await, Ok(crate::protocol::DespawnResult::Despawned { .. })));

        let rows = {
            let guard = ws.db.lock();
            crate::store::sessions::list_for_project(
                guard.as_ref().expect("db installed"),
                "TestOrg",
                "forge",
            )
            .expect("list")
        };
        assert!(rows.is_empty(), "despawn deletes the persisted dynamic-worker row");
    }

    fn worker_cron(
        id: &str,
        project: &str,
        team_role: Option<&str>,
    ) -> forge_primitives::CronEntry {
        forge_primitives::CronEntry {
            id: forge_primitives::CronId::from(id),
            project_name: project.to_owned(),
            kind: forge_primitives::CronKind::Recurring("0 9 * * *".to_owned()),
            prompt: "p".to_owned(),
            created_at: std::time::SystemTime::UNIX_EPOCH,
            description: None,
            last_fire: None,
            next_fire: std::time::SystemTime::UNIX_EPOCH,
            team_role: team_role.map(str::to_owned),
            wake: true,
        }
    }

    #[tokio::test]
    async fn teardown_worker_drops_its_crons_and_subs_keeps_others() {
        let (ws, _rx) = Workspace::testing_stub();
        let dir = tempdir().expect("tempdir");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        ws.seed_test_project("forge", "/tmp/cron-teardown-dyn");
        let view_key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .map(|v| v.key)
            .expect("seeded project view");
        ws.insert_live_worker(&view_key, live_worker_entry("scratch", "worker-1"));

        let scratch_cron = worker_cron("scratch-cron", "forge", Some("scratch"));
        let lead_cron = worker_cron("lead-cron", "forge", None);
        let sibling_cron = worker_cron("sibling-cron", "forge", Some("reviewer"));
        ws.push_cron(scratch_cron.clone());
        ws.push_cron(lead_cron.clone());
        ws.push_cron(sibling_cron.clone());
        let mut scratch_sub = gotify_sub("forge", &[], None);
        scratch_sub.team_role = Some("scratch".to_owned());
        let lead_sub = gotify_sub("forge", &[], None);
        ws.add_gotify_subscription(scratch_sub.clone(), true);
        ws.add_gotify_subscription(lead_sub.clone(), true);

        crate::spawn::handle_close_worker(&ws, &view_key, "scratch");

        let crons = ws.crons_for_project("forge");
        assert!(
            crons.iter().all(|c| c.id != scratch_cron.id),
            "the dynamic worker's cron is dropped"
        );
        assert!(crons.iter().any(|c| c.id == lead_cron.id), "the lead cron survives");
        assert!(crons.iter().any(|c| c.id == sibling_cron.id), "a sibling worker's cron survives");
        let persisted_crons = {
            let guard = ws.db.lock();
            crate::store::cron::list(guard.as_ref().expect("db installed")).expect("list")
        };
        assert!(
            persisted_crons.iter().all(|c| c.id != scratch_cron.id),
            "the cron is dropped from the store too",
        );
        assert!(
            persisted_crons.iter().any(|c| c.id == lead_cron.id),
            "the lead cron is still stored"
        );

        let subs = ws.gotify_subscriptions_for_project("forge");
        assert!(subs.iter().all(|s| s.id != scratch_sub.id), "the dynamic worker's sub is dropped");
        assert!(subs.iter().any(|s| s.id == lead_sub.id), "the lead sub survives");
    }

    /// #3: persisting reports failure (rather than swallowing it) when
    /// the store is unavailable, so the MCP spawn path can warn the lead
    /// that the worker won't survive a restart.
    #[test]
    fn record_worker_row_errors_when_store_unavailable() {
        let (ws, _rx) = Workspace::testing_stub();
        // The project resolves, so the only thing left to fail on is the
        // store: without this seed an unresolvable key would error too and
        // the assertion would hold for the wrong reason.
        ws.seed_test_project("forge", "/tmp/row-no-store");
        let project = ws.project_key_for_name("forge").expect("seeded project");
        // No install_db_for_test: the store is closed for this session.
        let error = ws
            .record_worker_row(
                &project,
                "reviewer",
                "id",
                "charter",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect_err("a closed store must surface a durability failure, not a silent no-op");
        assert!(
            error.to_string().contains("store is unavailable"),
            "and it names the store as the reason, got: {error}",
        );
    }

    fn gotify_sub(
        project: &str,
        applications: &[&str],
        min_priority: Option<u8>,
    ) -> forge_primitives::GotifySubscription {
        forge_primitives::GotifySubscription {
            id: uuid::Uuid::new_v4(),
            project: project.to_owned(),
            team_role: None,
            applications: applications.iter().map(|s| (*s).to_owned()).collect(),
            min_priority,
            created_at: std::time::SystemTime::UNIX_EPOCH,
        }
    }

    fn gotify_notif(
        app: &str,
        title: &str,
        message: &str,
        priority: u8,
    ) -> crate::GotifyNotification {
        crate::GotifyNotification {
            app: app.to_owned(),
            title: title.to_owned(),
            message: message.to_owned(),
            priority,
        }
    }

    /// Drain every currently-queued `SessionUpdate` from the test rx.
    fn drain_updates(
        rx: &mut tokio::sync::mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<crate::protocol::SessionUpdate> {
        let mut out = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            out.push(std::sync::Arc::unwrap_or_clone(frame.update));
        }
        out
    }

    /// Each caller of `subscribe()` gets a stream of its own, so a second
    /// view attaches beside the first instead of being refused the one
    /// receiver. Catches a revert to the single-take slot, where the
    /// second caller receives nothing.
    #[tokio::test]
    async fn subscribe_hands_every_caller_its_own_stream() {
        let dir = make_workspace_dir();
        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");
        let mut first = workspace.subscribe_answerer();
        let mut second = workspace.subscribe_answerer();

        assert!(
            workspace.update_tx().send(SessionUpdate::CatalogLoaded),
            "a subscribed workspace delivers",
        );

        assert!(
            matches!(
                first.try_recv(),
                Ok(frame) if matches!(&*frame.update, SessionUpdate::CatalogLoaded)
            ),
            "the first subscriber receives the update",
        );
        assert!(
            matches!(
                second.try_recv(),
                Ok(frame) if matches!(&*frame.update, SessionUpdate::CatalogLoaded)
            ),
            "the second subscriber receives the same update",
        );
    }

    /// A prompt forge wrote itself and no view drew - a worker kick, an
    /// auto-continue - draws as the words the model received: the CLI does
    /// not echo a prompt back, and nothing else carries them. The delivery
    /// path is the other half of the pair: a delivery's words are drawn by
    /// the envelope update its own caller emits, so a bare frame beside it
    /// would draw the same turn twice.
    #[test]
    fn a_forged_prompt_draws_its_words_where_a_delivery_prompt_forges_none() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("fkey", "/tmp/f-forged-prompt");
        let cwd = project_expanded_path(&ws, "fkey");
        ws.record_connected_session(&cwd, "f-uuid", None);
        let key = SessionSlot::from_str_for_test("f-uuid");
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        ws.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.mark_session_connected_for_test(&key, "f-uuid");
        ws.enable_test_dispatch_intercept();

        ws.dispatch_forged_prompt(&key, "get on with it".to_owned()).expect("forged dispatch");
        let drawn = drain_updates(&mut rx);
        let frame = drawn.iter().find_map(|u| match u {
            SessionUpdate::ChatAppended { msg, source, .. } => Some((msg, source)),
            _ => None,
        });
        let Some((msg, source)) = frame else {
            panic!("a forged prompt draws its words; got {drawn:?}")
        };
        // **And the source is forge's own**, which is what keeps a parked
        // reader off the foot: the frame is the same one a person's send
        // forges, so a reader's follow has only this to tell the two apart
        // (#2198).
        assert!(
            matches!(source, Some(PromptSource::Forge)),
            "a forged machinery turn is nobody's send, and the frame says whose it is: {source:?}",
        );
        let Message::User { message, uuid, .. } = msg else {
            panic!("a forged prompt draws as the user turn the model received, got {msg:?}")
        };
        assert!(
            matches!(
                message.content.first(),
                Some(forge_primitives::ContentBlock::Text { text, .. }) if text == "get on with it"
            ),
            "the frame carries the prose the model received: {message:?}",
        );
        // **The id says whose words they are**: it is the one fact about the
        // sender the CLI carries into the transcript, so a view draws a
        // reloaded row as the machinery's own - never the reader's - by its
        // prefix alone.
        assert!(
            uuid.as_deref().is_some_and(|id| id.starts_with("forge_nudge_")),
            "a forged dispatch mints the machinery's own id: {uuid:?}",
        );

        ws.dispatch_workspace_prompt(&key, "[Cron]\n\nrun the summary".to_owned())
            .expect("delivery dispatch");
        assert!(
            !drain_updates(&mut rx).iter().any(|u| matches!(u, SessionUpdate::ChatAppended { .. })),
            "a delivery's words are drawn by its own envelope update, so this path forges no frame",
        );
        // Both dispatches wire one prompt each, and both are the machinery's
        // own words: the source `Forge` is what the prefix follows.
        let ids: Vec<String> = ws
            .drain_test_dispatch_buffer()
            .iter()
            .filter_map(|command| match command {
                Command::PromptUnder { uuid, .. } => Some(uuid.clone()),
                _ => None,
            })
            .collect();
        assert_eq!(ids.len(), 2, "both dispatches wired one prompt: {ids:?}");
        assert!(
            ids.iter().all(|id| id.starts_with("forge_nudge_")),
            "a machinery dispatch carries the marker whatever door it took: {ids:?}",
        );
    }

    /// **A cooldown and its thaw each announce the roster.** A project row's
    /// `would_bind` is derived from the selection walk, so a home subscriber
    /// that hears nothing keeps drawing an account's old bindability. The
    /// cooling start is a write the gateway publishes; the thaw is only a
    /// clock, so the announcer sleeps to it.
    ///
    /// **The arrival instants are the evidence that the second frame is the
    /// thaw and not a repeat.** A watcher announcing on every wake, or a
    /// second watcher the duplicate-start guard failed to stop, delivers its
    /// second frame before the reset; only the clock-driven wake lands after.
    #[tokio::test]
    async fn a_rotation_cool_and_its_thaw_each_announce_the_accounts() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        assert!(
            !ws.test_rotation_announcer_started(),
            "premise: no announcer before the boot call",
        );
        ws.start_rotation_announcer();
        ws.start_rotation_announcer();
        assert!(
            ws.test_rotation_announcer_started(),
            "the boot call starts the one watcher, and a second call is a no-op",
        );

        let reset_at = SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("after the epoch")
            .as_secs()
            + 6;
        let thaw = forge_gateway::rotation::reset_instant(reset_at);
        ws.gateway.report_probe_limit(&AccountKey("Cooling".to_owned()), Some(reset_at));

        let mut arrivals = Vec::new();
        // A ~5 s window for the cool's frame, so a loaded machine does not
        // red code that is right; the bound covers the thaw behind it.
        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(20);
        while arrivals.len() < 2 {
            let frame = tokio::time::timeout_at(deadline, rx.recv())
                .await
                .expect("the cool and the thaw both announce inside the bound")
                .expect("the update channel stays open");
            if matches!(&*frame.update, SessionUpdate::AccountsChanged { .. }) {
                arrivals.push(SystemTime::now());
            }
        }
        assert!(
            arrivals[0] < thaw,
            "the cool is announced when the write lands, before the thaw: {:?}",
            arrivals[0],
        );
        assert!(
            arrivals[1] >= thaw,
            "the second frame is the thaw the clock drives, not a repeat: {:?} vs {thaw:?}",
            arrivals[1],
        );
    }

    /// **The row forge's machinery forges carries the stamp a clock is read
    /// from.** The CLI never echoes a prompt, so these rows are the only
    /// opening rows a turn has, and a page attaching mid-turn anchors its
    /// running clock on the first row carrying a stamp. A view's own send is
    /// stamped by the session task that draws it now; that half is pinned
    /// beside the frame-order test in `session_task`.
    #[test]
    fn a_forged_prompt_row_carries_the_stamp_a_clock_starts_from() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("skey", "/tmp/f-stamped-prompt");
        let cwd = project_expanded_path(&ws, "skey");
        ws.record_connected_session(&cwd, "s-uuid", None);
        let key = SessionSlot::from_str_for_test("s-uuid");
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        ws.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.mark_session_connected_for_test(&key, "s-uuid");
        ws.enable_test_dispatch_intercept();

        let before = time::OffsetDateTime::now_utc();
        ws.dispatch_forged_prompt(&key, "get on with it".to_owned()).expect("forged dispatch");
        let after = time::OffsetDateTime::now_utc();

        let stamps: Vec<Option<String>> = drain_updates(&mut rx)
            .into_iter()
            .filter_map(|update| match update {
                SessionUpdate::ChatAppended { msg, .. } => Some(msg),
                _ => None,
            })
            .map(|msg| {
                serde_json::to_value(&msg).expect("encode")["timestamp"].as_str().map(str::to_owned)
            })
            .collect();
        assert_eq!(stamps.len(), 1, "the machinery's prompt forges a row: {stamps:?}");
        let forged =
            stamps[0].as_deref().expect("the row forge's machinery forges carries a stamp");

        // **The code's own clock, not merely a parseable string.** A constant
        // stamp would draw every forged row a clock years old while a
        // parse-only pin stayed green, so it has to land where the two
        // `now_utc`s bracket the dispatch.
        let slack = time::Duration::seconds(5);
        let at =
            time::OffsetDateTime::parse(forged, &time::format_description::well_known::Rfc3339)
                .unwrap_or_else(|error| {
                    panic!("the machinery stamped a time no client can read: {forged} ({error})")
                });
        assert!(
            at >= before - slack && at <= after + slack,
            "the row the machinery forges carries the forge's own clock, not a constant: \
             {forged} sits outside {before}..{after}",
        );
    }

    /// A forged prompt that never landed draws nothing: the words did not
    /// reach a model, so a frame for them would show a turn nothing answers.
    #[test]
    fn a_refused_forged_prompt_draws_nothing() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        let gone = SessionSlot::from_str_for_test("no-such-seat");

        let refused = ws.dispatch_forged_prompt(&gone, "get on with it".to_owned());

        assert!(refused.is_err(), "a seat nothing holds refuses the dispatch");
        assert!(
            !drain_updates(&mut rx).iter().any(|u| matches!(u, SessionUpdate::ChatAppended { .. })),
            "a refused prompt never reached a model, so nothing draws its words",
        );
    }

    /// **Only the reader's own send is a reader looking.** A standing death
    /// is spent by a prompt the person typed - they have moved the seat on -
    /// and is NOT spent by a cron's, a peer's or forge's own prompt, which
    /// are the machinery talking rather than anyone having seen it.
    #[test]
    fn a_readers_prompt_spends_a_death_and_another_sources_does_not() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        let key = SessionSlot::from_str_for_test("prompt-spend");
        // The routed path is what spends, so a command sender has to exist:
        // without one the dispatch falls to the bare stub below.
        let (tx, mut sent) = mpsc::unbounded_channel();
        ws.command_senders.lock().insert(key.clone(), tx);
        ws.record_death_for_test(
            &key,
            "dead-occupant",
            "the claude subprocess closed its output stream",
        );

        let prompt = |uuid: &str, source: crate::protocol::PromptSource| Command::PromptUnder {
            key: key.clone(),
            text: "hello".to_owned(),
            attachments: Vec::new(),
            uuid: uuid.to_owned(),
            source,
            dispatch_id: None,
        };

        ws.dispatch(prompt("cron-1", crate::protocol::PromptSource::Cron)).expect("routed");
        assert!(ws.death_stands(&key), "a cron's prompt is not a reader looking");

        ws.dispatch(prompt("peer-1", crate::protocol::PromptSource::Peer)).expect("routed");
        assert!(ws.death_stands(&key), "a peer's prompt is not a reader looking");

        ws.dispatch(prompt("you-1", crate::protocol::PromptSource::You)).expect("routed");
        assert!(!ws.death_stands(&key), "the reader's own send spends the death");
        assert!(!ws.spend_death(&key), "and there is nothing left to spend");

        let delivered: Vec<Command> = std::iter::from_fn(|| sent.try_recv().ok()).collect();
        assert_eq!(delivered.len(), 3, "all three prompts still reached the seat");
    }

    /// **A `/new` is a replacement, not a sweep.** The slot stays and the
    /// previous occupant's tabs close; a sweep would ask about every seat
    /// that is not live, which is the wrong question for a respawn.
    #[tokio::test]
    async fn a_new_session_replaces_the_seats_tabs_in_the_fleet() {
        let (ws, _rx) = Workspace::testing_stub();
        let (calls, mut heard) = tokio::sync::mpsc::unbounded_channel();
        ws.install_browser_host(std::sync::Arc::new(crate::browser::testing::StubHost { calls }));
        let seat = SessionSlot::lead("TestOrg", "proj");

        let _ = ws.run_forge_prompt(&seat, &crate::prompt::ForgePrompt::NewSession);

        assert_eq!(
            heard.recv().await,
            Some(("replace_seat".to_owned(), serde_json::json!(seat))),
            "the fleet is told whose tabs the respawn replaces",
        );
    }

    /// A seat with a live domain session whose dispatch is captured rather
    /// than routed, plus the workspace's update stream. The caller folds the
    /// failure it wants - the arming under test - then calls
    /// [`Workspace::fire_auto_continue`], the way the session task does the
    /// moment that failure lands.
    fn nudge_seat(
        dir: &tempfile::TempDir,
        label: &str,
    ) -> (Arc<Workspace>, SessionSlot, tokio::sync::mpsc::UnboundedReceiver<SeatUpdate>) {
        let (ws, rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        let key = SessionSlot::from_str_for_test(label);
        ws.mark_session_connected_for_test(&key, label);
        ws.enable_test_dispatch_intercept();
        (ws, key, rx)
    }

    /// Fold one agent event into `key`'s domain the way a session task
    /// would, so these tests drive the real arming rather than hand-set it.
    fn fold_event(ws: &Arc<Workspace>, key: &SessionSlot, event: &forge_agent::client::AgentEvent) {
        let domain = ws.domain_session_for(key).expect("the seat's session");
        let mut guard = domain.lock();
        crate::session_task::apply_event_to_domain(&mut guard, event);
    }

    /// An errored `Result` carrying the CLI's own errors.
    fn failed_result(errors: &[&str]) -> forge_agent::client::AgentEvent {
        forge_agent::client::AgentEvent::SdkMessage {
            session_id: "nudge".to_owned(),
            msg: 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": "nudge",
                "errors": errors,
            }))
            .expect("parse result message"),
        }
    }

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

    /// The words the continuation carries for `reason`.
    fn expected_prompt(reason: &str) -> String {
        format!(
            "forge continued this session automatically after the previous turn failed: {reason}. \
Pick up exactly where you stopped - everything completed before the failure is in the history \
above, so do not restart the task, and do not repeat any step, tool call or side effect that \
already completed."
        )
    }

    /// The want #1841 is about: a failed turn gets one prompt of forge's own
    /// through the dispatched-prompt path, and the frame draws in every view
    /// as the turn the model received.
    #[test]
    fn a_failed_turn_is_continued_in_forges_own_words() {
        let dir = tempdir().expect("tempdir");
        let (ws, key, mut rx) = nudge_seat(&dir, "nudge");
        fold_event(&ws, &key, &failed_result(&["API Error: 400 ..."]));

        ws.fire_auto_continue(&key);

        assert_eq!(
            dispatched_prompts(&ws),
            [expected_prompt("API Error: 400 ...")],
            "one prompt, naming who continued the session and the failure it answers",
        );
        let drawn = drain_updates(&mut rx);
        assert!(
            drawn.iter().any(|u| matches!(
                u,
                SessionUpdate::ChatAppended { msg: Message::User { .. }, .. }
            )),
            "the continuation draws as the turn the model received: {drawn:?}",
        );
    }

    /// Condition (a): a turn the reader cancelled is the reader's own act.
    /// It arms nothing, so the fire sends nothing.
    #[test]
    fn a_cancelled_turn_never_fires() {
        let dir = tempdir().expect("tempdir");
        let (ws, key, _rx) = nudge_seat(&dir, "cancelled");
        ws.domain_session_for(&key).expect("session").lock().pending_cancel = true;

        fold_event(&ws, &key, &failed_result(&["aborted_streaming"]));
        assert!(
            ws.domain_session_for(&key).expect("session").lock().auto_continue.is_none(),
            "the fold refuses to arm a cancelled turn",
        );
        ws.domain_session_for(&key).expect("session").lock().failed_turn_at =
            Some(SystemTime::now() - Duration::from_secs(60));
        ws.fire_auto_continue(&key);

        assert!(
            dispatched_prompts(&ws).is_empty(),
            "a failure that armed nothing is nothing to send",
        );
    }

    /// The sighting #2146 is about: the person was reading the seat when its
    /// turn failed, and nothing was continued until they typed. A seat a
    /// view is showing is continued like any other.
    #[tokio::test]
    async fn a_seat_a_view_is_holding_is_still_continued() {
        let dir = tempdir().expect("tempdir");
        let (ws, key, _rx) = nudge_seat(&dir, "watching");
        ws.hold_seat(&key);

        fold_event(&ws, &key, &failed_result(&["API Error: 400 ..."]));
        ws.fire_auto_continue(&key);

        assert_eq!(
            dispatched_prompts(&ws),
            [expected_prompt("API Error: 400 ...")],
            "the seat under the reader's eyes is resumed the same way",
        );
    }

    /// The repeat case, settled: once per failure episode. The
    /// continuation's own turn failing must not become a prompt loop.
    #[test]
    fn a_second_failure_after_a_fire_does_not_fire_again() {
        let dir = tempdir().expect("tempdir");
        let (ws, key, _rx) = nudge_seat(&dir, "repeat");
        fold_event(&ws, &key, &failed_result(&["API Error: 400 ..."]));
        ws.fire_auto_continue(&key);
        assert_eq!(dispatched_prompts(&ws).len(), 1, "precondition: the failure was nudged");

        fold_event(&ws, &key, &failed_result(&["API Error: 400 ..."]));
        assert!(
            ws.domain_session_for(&key).expect("session").lock().auto_continue.is_none(),
            "the episode has had its continuation; a second failure arms nothing",
        );
        ws.fire_auto_continue(&key);

        assert!(
            dispatched_prompts(&ws).is_empty(),
            "and nothing more goes out for the same episode",
        );
    }

    /// The episode ends when the reader looks: a later failure is a new one
    /// and gets its own continuation.
    #[tokio::test]
    async fn an_opened_seat_reopens_the_nudge_for_a_later_failure() {
        let dir = tempdir().expect("tempdir");
        let (ws, key, _rx) = nudge_seat(&dir, "reopened");
        fold_event(&ws, &key, &failed_result(&["API Error: 400 ..."]));
        ws.fire_auto_continue(&key);
        assert_eq!(dispatched_prompts(&ws).len(), 1, "precondition: the first failure was nudged");

        ws.hold_seat(&key);
        ws.release_seat(&key);
        fold_event(&ws, &key, &failed_result(&["API Error: 400 ..."]));
        ws.fire_auto_continue(&key);

        assert_eq!(
            dispatched_prompts(&ws).len(),
            1,
            "the reader looked, so the next failure is a new episode and is nudged",
        );
    }

    /// The cron delivery path rides the helper: a cron fired into a lead
    /// draws its `CronPromptAppended` echo and lands, idle or mid-turn.
    #[test]
    fn a_cron_fire_into_a_lead_draws_its_echo() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("cronlead", "/tmp/cron-lead-queued");
        let cwd = project_expanded_path(&ws, "cronlead");
        ws.record_connected_session(&cwd, "lead-uuid", None);
        let lead_key = SessionSlot::lead("TestOrg", "cronlead");
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        ws.pool.lock().insert(
            lead_key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.mark_session_connected_for_test(&lead_key, "lead-uuid");
        ws.enable_test_dispatch_intercept();

        let outcome =
            crate::spawn::deliver_cron_prompt(&ws, &test_cron("c1", "cronlead", "morning"), false);
        assert!(matches!(outcome, crate::spawn::CronFireOutcome::Delivered));
        assert!(
            drain_updates(&mut rx)
                .iter()
                .any(|u| matches!(u, SessionUpdate::CronPromptAppended { .. })),
            "an idle cron fire draws its echo",
        );

        ws.domain_session_for(&lead_key).expect("domain").lock().turn_pending = true;
        let outcome =
            crate::spawn::deliver_cron_prompt(&ws, &test_cron("c2", "cronlead", "again"), false);
        assert!(matches!(outcome, crate::spawn::CronFireOutcome::Delivered));
        assert!(
            drain_updates(&mut rx)
                .iter()
                .any(|u| matches!(u, SessionUpdate::CronPromptAppended { .. })),
            "and so does one fired mid-turn",
        );
    }

    /// The gotify running-lead delivery rides the helper too - a second
    /// family (after cron) through a different entry path, and its echo
    /// draws idle or mid-turn.
    #[test]
    fn a_gotify_delivery_into_a_lead_draws_its_echo() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("glead", "/tmp/gotify-lead-queued");
        let cwd = project_expanded_path(&ws, "glead");
        ws.record_connected_session(&cwd, "lead-uuid", None);
        let lead_key = SessionSlot::lead("TestOrg", "glead");
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        ws.pool.lock().insert(
            lead_key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.mark_session_connected_for_test(&lead_key, "lead-uuid");
        ws.enable_test_dispatch_intercept();
        let notif = gotify_notif("Backups", "Nightly backup", "done", 5);

        crate::spawn::deliver_gotify_message(&ws, "glead", None, notif.clone());
        assert!(
            drain_updates(&mut rx)
                .iter()
                .any(|u| matches!(u, SessionUpdate::GotifyNotificationAppended { .. })),
            "an idle gotify fire draws its echo",
        );

        ws.domain_session_for(&lead_key).expect("domain").lock().turn_pending = true;
        crate::spawn::deliver_gotify_message(&ws, "glead", None, notif);
        assert!(
            drain_updates(&mut rx)
                .iter()
                .any(|u| matches!(u, SessionUpdate::GotifyNotificationAppended { .. })),
            "and so does one delivered mid-turn",
        );
    }

    fn slack_message_for(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(),
        }
    }

    /// The lead-owned subscription's running lead receives the message as
    /// a prompt, and the asleep path never fires.
    #[test]
    fn slack_delivery_to_a_running_lead_dispatches_a_prompt() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut update_rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("glead", "/tmp/slack-lead-running");
        let cwd = project_expanded_path(&ws, "glead");
        ws.record_connected_session(&cwd, "lead-uuid", None);
        let lead_key = SessionSlot::lead("TestOrg", "glead");
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        ws.pool.lock().insert(
            lead_key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.mark_session_connected_for_test(&lead_key, "lead-uuid");
        ws.enable_test_dispatch_intercept();

        crate::spawn::deliver_slack_message(&ws, "glead", None, vec![slack_message_for("ping")]);

        let dispatched = ws.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|cmd| matches!(
                cmd,
                crate::protocol::Command::Prompt { key, .. }
                    | crate::protocol::Command::PromptUnder { key, .. }
                    if *key == lead_key
            )),
            "the running lead receives the message as a prompt: {dispatched:?}",
        );
        assert!(
            dispatched
                .iter()
                .all(|cmd| !matches!(cmd, crate::protocol::Command::SpawnProject { .. })),
            "a running lead must not fire the asleep spawn path",
        );
        assert_eq!(
            ws.parked_by_slot
                .lock()
                .get(&crate::SessionSlot::lead("TestOrg", "glead"))
                .map_or(0, |parked| parked.slack.len()),
            0,
            "a running lead's delivery is dispatched, not parked",
        );

        // The delivery ALSO echoes the block into the lead's chat: the CLI
        // never echoes a stdin-injected prompt, so without it the user sees
        // nothing.
        let echoed = drain_updates(&mut update_rx).into_iter().any(|u| {
            matches!(
                u,
                crate::protocol::SessionUpdate::SlackMessageAppended { key, prose, .. }
                    if key == lead_key
                        && prose.starts_with("[Slack")
                        && prose.contains("ping")
            )
        });
        assert!(echoed, "a running-lead delivery emits a SlackMessageAppended echo with the body");
    }

    /// The lead arm carries the stricter rule - a failed dispatch returns false
    /// so the sweep re-runs the message - and must not have echoed before it.
    /// The pooled lead stays in place so the delivery reaches the lead arm; the
    /// failure is a task channel whose receiver is gone, the teardown window a
    /// session close leaves behind.
    #[test]
    fn a_failed_lead_dispatch_leaves_no_echo_for_the_sweep_to_duplicate() {
        let dir = tempdir().expect("tempdir");
        let (ws, mut update_rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("glead", "/tmp/slack-lead-doomed");
        let lead_key = SessionSlot::lead("TestOrg", "glead");
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        ws.pool.lock().insert(
            lead_key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        ws.mark_session_connected_for_test(&lead_key, "lead-uuid");
        // A sender whose receiver is dropped: `dispatch` takes the production
        // routing path and returns `SessionClosed`, instead of falling through
        // to the test-only path that would run it against the stub handle.
        let (tx, rx) = mpsc::unbounded_channel::<crate::protocol::Command>();
        drop(rx);
        ws.command_senders.lock().insert(lead_key.clone(), tx);

        let delivered = crate::spawn::deliver_slack_message(
            &ws,
            "glead",
            None,
            vec![slack_message_for("ping")],
        );

        assert!(!delivered, "a failed dispatch tells the sweep to re-run the message");
        let echoed = drain_updates(&mut update_rx)
            .into_iter()
            .any(|u| matches!(u, crate::protocol::SessionUpdate::SlackMessageAppended { .. }));
        assert!(!echoed, "a failed lead dispatch must not echo a SlackMessageAppended");
    }

    /// With no running session, the message parks for the project
    /// lead's slot and the project's spawn is fired to pick it up.
    #[test]
    fn slack_delivery_to_an_asleep_lead_buffers_and_spawns_the_project() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("glead", "/tmp/slack-lead-asleep");
        ws.enable_test_dispatch_intercept();

        crate::spawn::deliver_slack_message(&ws, "glead", None, vec![slack_message_for("wake up")]);

        let dispatched = ws.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|cmd| matches!(
                cmd,
                crate::protocol::Command::SpawnProject { project_name, .. }
                    if project_name == "glead"
            )),
            "the asleep project is spawned: {dispatched:?}",
        );
        assert!(
            dispatched.iter().all(|cmd| !matches!(
                cmd,
                crate::protocol::Command::Prompt { .. }
                    | crate::protocol::Command::PromptUnder { .. }
            )),
            "no session is prompted directly",
        );
        assert_eq!(
            parked_slack_count(&ws, "glead", None),
            1,
            "the message waits for the spawned session to drain",
        );
    }

    /// A sweep re-run of the same message must not double-prompt: the
    /// dedupe drops the second hand-off to the same destination, which is
    /// what makes a post-failure re-sweep idempotent.
    #[test]
    fn a_second_delivery_of_the_same_message_to_the_same_owner_is_dropped() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("glead", "/tmp/slack-double");
        ws.enable_test_dispatch_intercept();

        let message = slack_message_for("hello");
        assert!(
            crate::spawn::deliver_slack_message(&ws, "glead", None, vec![message.clone()]),
            "the first delivery lands",
        );
        assert!(
            crate::spawn::deliver_slack_message(&ws, "glead", None, vec![message]),
            "the re-run reads as already delivered, not as a failure",
        );

        let dispatched = ws.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().all(|cmd| !matches!(
                cmd,
                crate::protocol::Command::Prompt { .. }
                    | crate::protocol::Command::PromptUnder { .. }
            )),
            "the asleep path buffers; the second delivery added no prompt",
        );
        assert_eq!(parked_slack_count(&ws, "glead", None), 1, "one buffered message, not two");
    }

    /// How many Slack messages are parked for `(project, label)`, under the
    /// org the seeded project belongs to.
    fn parked_slack_count(ws: &Workspace, project: &str, label: Option<&str>) -> usize {
        let org =
            ws.list_projects().into_iter().find(|v| v.name == project).expect("seeded project").org;
        ws.parked_by_slot
            .lock()
            .get(&crate::SessionSlot::for_label(&org, project, label))
            .map_or(0, |parked| parked.slack.len())
    }

    fn make_workspace_dir() -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// The project declares a model, so a respawn has a canonical name
    /// to stamp over the caller's pin.
    fn make_workspace_dir_declaring_model() -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Personal", "OpenRouter-TM"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "deepseek-v4.1-flash"

[[accounts]]
display_name = "Personal"
token = "t"
models = ["claude-opus-5"]
provider = "anthropic"

[[accounts]]
display_name = "OpenRouter-TM"
token = "t"
models = ["deepseek-v4.1-flash"]
provider = "openrouter"
base_url = "https://openrouter.ai/api"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// An unrelated reload keeps the live vault session: a settings save must
    /// not lock a vault and make the next tool call ask for the password.
    #[tokio::test]
    async fn an_unrelated_reload_keeps_the_vault_session() {
        let dir = make_workspace_dir_declaring_model();
        let path = forge_toml_path(dir.path());
        let raw = fs::read_to_string(&path).expect("read fixture");
        let raw = format!(
            "{raw}\n[vault]\nurl = \"https://bitwarden.hub\"\nemail = \"hi@vedhavyas.dev\"\n"
        );
        fs::write(&path, &raw).expect("write vault section");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let before =
            Arc::clone(workspace.vault.read().as_ref().expect("the fixture configures a vault"));

        let changed = raw.replace(
            "model = \"deepseek-v4.1-flash\"",
            "model = \"deepseek-v4.1-flash\"\nmax_workers = 2",
        );
        fs::write(&path, changed).expect("write the unrelated edit");
        workspace.reload_config().expect("the file still loads");

        let after = Arc::clone(workspace.vault.read().as_ref().expect("still configured"));
        assert!(
            Arc::ptr_eq(&before, &after),
            "an unrelated reload must keep the session and its unlocked keys",
        );
    }

    /// A valid reload replaces the whole config, and the live value equals
    /// what a boot on the same file would load.
    #[tokio::test]
    async fn a_valid_reload_applies_the_file_and_equals_a_fresh_load() {
        let dir = make_workspace_dir_declaring_model();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        assert_eq!(
            workspace.config_arc().projects[0].model.as_deref(),
            Some("deepseek-v4.1-flash"),
            "the fixture starts on its own model, or this test proves nothing",
        );

        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Personal"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-opus-5"
env = { RELOADED = "yes" }

[[accounts]]
display_name = "Personal"
token = "t2"
models = ["claude-opus-5"]
provider = "anthropic"
"#,
        )
        .expect("write the new config");

        let reload = workspace.reload_config().expect("the new file is valid");
        assert!(
            reload.changed.iter().any(|key| key.starts_with("accounts.")),
            "the account set moved: {reload:?}",
        );
        assert!(
            reload.changed.iter().any(|key| key.starts_with("orgs.")),
            "the project set moved: {reload:?}",
        );

        let live = workspace.config_arc();
        assert_eq!(live.projects[0].model.as_deref(), Some("claude-opus-5"));
        assert_eq!(
            live.projects[0].env.get("RELOADED").map(String::as_str),
            Some("yes"),
            "the project's env is live for the next spawn",
        );
        assert_eq!(live.accounts[0].display_name, "Personal");

        let fresh = crate::config::load_from_dir(dir.path()).expect("a fresh boot load");
        assert_eq!(live.projects.len(), fresh.projects.len());
        assert_eq!(live.projects[0].name, fresh.projects[0].name);
        assert_eq!(live.projects[0].model, fresh.projects[0].model);
        assert_eq!(live.projects[0].env, fresh.projects[0].env);
        assert_eq!(live.accounts.len(), fresh.accounts.len());
        assert_eq!(live.accounts[0].display_name, fresh.accounts[0].display_name);
        assert_eq!(
            live.accounts[0].env, fresh.accounts[0].env,
            "the live config equals what a restart on the same file loads",
        );
    }

    /// An invalid file is rejected whole; the last good config stays live.
    #[tokio::test]
    async fn an_invalid_reload_keeps_the_last_good_config() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        fs::write(forge_toml_path(dir.path()), "this is not toml = [").expect("write invalid");

        let error = workspace.reload_config().expect_err("an invalid file is rejected");

        assert!(
            matches!(error, WorkspaceError::ConfigParse { .. }),
            "the parse failure is reported: {error}",
        );
        assert_eq!(
            workspace.config_arc().projects[0].name,
            "forge",
            "the previous config is still live after a rejected file",
        );
    }

    fn settings_key(workspace: &Workspace, path: &str) -> (String, String, String) {
        let document =
            crate::settings::document(&workspace.config_arc(), "", &workspace.config_path());
        let key = document
            .areas
            .iter()
            .flat_map(|area| &area.keys)
            .find(|key| key.path == path)
            .unwrap_or_else(|| panic!("{path} has no row"));
        let area = document
            .areas
            .iter()
            .find(|area| area.keys.iter().any(|key| key.path == path))
            .map(|area| area.id.clone())
            .expect("the key has an area");
        (area, key.pattern.clone(), key.path.clone())
    }

    fn settings_fingerprint(workspace: &Workspace) -> String {
        let raw = fs::read_to_string(workspace.config_path()).expect("read the config");
        crate::config::fingerprint_of(&raw)
    }

    fn set_edit(
        workspace: &Workspace,
        path: &str,
        value: serde_json::Value,
    ) -> SettingsEditRequest {
        let (area, pattern, key_path) = settings_key(workspace, path);
        SettingsEditRequest { area, key_path, pattern, op: SettingsEditOp::Set, value: Some(value) }
    }

    /// **A project's path is checked on a set too, and the refusal names the
    /// key.** The loader accepts any string, so a row pointing at nothing is
    /// a project that can never start.
    #[tokio::test]
    async fn a_project_path_set_that_is_not_a_directory_is_refused_at_its_key() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let fingerprint = settings_fingerprint(&workspace);
        let edit = set_edit(
            &workspace,
            "orgs.Default.projects.forge.path",
            serde_json::json!("/nonexistent/forge"),
        );
        let error =
            workspace.save_settings(&fingerprint, &[edit]).expect_err("a missing directory");
        match error {
            SettingsSaveError::Refused { message, key_path } => {
                assert!(message.contains("directory"), "{message}");
                assert_eq!(key_path.as_deref(), Some("orgs.Default.projects.forge.path"));
            }
            other => panic!("expected a refusal, got {other:?}"),
        }
        let after = fs::read_to_string(workspace.config_path()).expect("read");
        assert!(after.contains("path = \"~/Projects/forge\""), "the file did not move: {after}");
    }

    /// A save writes the candidate, keeps the file's comments, and the next
    /// load reads the new value.
    #[tokio::test]
    async fn a_settings_save_writes_the_file_and_keeps_its_comments() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let path = workspace.config_path();
        let raw = fs::read_to_string(&path).expect("read");
        fs::write(&path, format!("# hand-written note\n{raw}")).expect("write the comment");
        workspace.reload_config().expect("the commented file loads");
        let fingerprint = settings_fingerprint(&workspace);
        let edit =
            set_edit(&workspace, "orgs.Default.projects.forge.max_workers", serde_json::json!(4));

        workspace.save_settings(&fingerprint, &[edit]).expect("the save lands");

        let saved = fs::read_to_string(&path).expect("read the saved file");
        assert!(saved.contains("# hand-written note"), "the comment stayed: {saved}");
        assert!(saved.contains("max_workers = 4"), "the value landed: {saved}");
        workspace.reload_config().expect("the saved file loads");
        assert_eq!(workspace.config_arc().projects[0].max_workers, Some(4));
    }

    /// A fingerprint that is not the file's refuses the save and writes
    /// nothing.
    #[tokio::test]
    async fn a_stale_settings_save_writes_nothing() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let path = workspace.config_path();
        let before = fs::read_to_string(&path).expect("read");
        let edit =
            set_edit(&workspace, "orgs.Default.projects.forge.max_workers", serde_json::json!(4));
        let error = workspace
            .save_settings("0000000000000000", &[edit])
            .expect_err("a stale save is refused");
        assert_eq!(error, SettingsSaveError::Stale);
        assert_eq!(fs::read_to_string(&path).expect("read"), before, "the file did not move");
    }

    /// **A spawn refused before the pool gives back what it wrote.** The id
    /// it recorded returns to the store's own and a domain handle it created
    /// goes, or the project reads live for ever and a boot resumes a
    /// transcript that never existed.
    #[tokio::test]
    async fn a_refused_spawn_rolls_back_its_id_and_domain() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let slot = SessionSlot::lead("Default", "forge");
        let previous = workspace
            .stored_session_id(slot.org(), slot.project(), slot.label())
            .expect("the store reads");
        let minted = workspace.record_spawn_id(&slot, previous.clone(), true);
        assert_ne!(previous.as_deref(), Some(minted.as_str()), "the spawn pinned a new id");
        workspace
            .domain_handles
            .lock()
            .insert(slot.clone(), Arc::new(Mutex::new(DomainSession::new(slot.clone(), None))));
        {
            let _rollback = SpawnRollback {
                workspace: Arc::clone(&workspace),
                slot: slot.clone(),
                stored: previous.clone(),
                prior_seat_state: None,
                domain_created: true,
                armed: true,
            };
        }
        assert_eq!(
            workspace.stored_session_id(slot.org(), slot.project(), slot.label()).expect("read"),
            previous,
            "the pinned id went back to the store's own",
        );
        assert!(
            !workspace.domain_handles.lock().contains_key(&slot),
            "the domain handle the spawn created went",
        );
    }

    /// **A real spawn refused by the loader between its id record and the
    /// pool rolls all of it back.** The live config stays the valid one it
    /// loaded; the file moves under it and no longer parses, so the bind's
    /// own re-read refuses - the guarded return, not a hand-built guard.
    /// The seat state goes back too: a refusal must not turn a cut-off turn
    /// into a parked seat, or reopen one the reader shut.
    #[tokio::test]
    async fn a_spawn_refused_by_a_changed_config_rolls_back_its_id_and_domain() {
        use crate::store::sessions::SeatState;

        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        let slot = SessionSlot::lead("Default", "forge");
        workspace.record_session_id(slot.org(), slot.project(), slot.label(), "previous-id");
        workspace.record_seat_state(&slot, SeatState::InTurn);
        let previous = workspace
            .stored_session_id(slot.org(), slot.project(), slot.label())
            .expect("the store reads");
        fs::write(forge_toml_path(dir.path()), "this is not toml [").expect("write the bad file");
        let Err(error) = workspace.get_agent_handle(
            SessionTarget::Default,
            SessionLaunchSettings::default(),
            &crate::protocol::SpawnRole::Lead,
        ) else {
            panic!("the bind's re-read refuses an unparseable file")
        };
        assert!(error.to_string().contains("failed to parse"), "the loader's words: {error}");
        assert_eq!(
            workspace.stored_session_id(slot.org(), slot.project(), slot.label()).expect("read"),
            previous,
            "the pinned id went back to the store's own",
        );
        assert_eq!(
            workspace.stored_seat_state(&slot),
            Some(SeatState::InTurn),
            "the interrupted turn is still what the next boot reads",
        );
        assert!(
            !workspace.domain_handles.lock().contains_key(&slot),
            "the domain handle the spawn created went",
        );
    }

    /// **A close that lands after the spawn's own write is not undone by
    /// the rollback.** The restore only reverses the state the spawn wrote;
    /// a newer decision - the reader closing the project mid-spawn - stands,
    /// or the next heal attempt would reopen the project the reader shut.
    #[test]
    fn a_refused_spawn_does_not_undo_a_close_that_landed_after_its_write() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let (workspace, _rx) = 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 _refused = SpawnRollback {
                workspace: Arc::clone(&workspace),
                slot: key.clone(),
                stored: Some("id-1".to_owned()),
                prior_seat_state: workspace.stored_seat_state(&key),
                domain_created: false,
                armed: true,
            };
            // The spawn's own write, then the reader's close landing while
            // the spawn is still building.
            workspace.write_seat_state(&key, SPAWNED_SEAT_STATE, true);
            workspace.record_seat_state(&key, SeatState::Closed);
        }

        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::Closed),
            "the close is newer than the spawn's write, so the rollback leaves it",
        );
    }

    /// A candidate the loader refuses writes nothing and carries the loader's
    /// own words, anchored at the key the save named.
    #[tokio::test]
    async fn an_invalid_settings_save_writes_nothing_and_names_the_key() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let path = workspace.config_path();
        let before = fs::read_to_string(&path).expect("read");
        let fingerprint = settings_fingerprint(&workspace);
        let edit = set_edit(
            &workspace,
            "orgs.Default.projects.forge.model",
            serde_json::json!("no-such-model"),
        );
        let error = workspace
            .save_settings(&fingerprint, &[edit])
            .expect_err("an unserved model is refused");
        match error {
            SettingsSaveError::Invalid { message, key_path } => {
                assert!(message.contains("no-such-model"), "the loader named the model: {message}");
                assert_eq!(
                    key_path.as_deref(),
                    Some("orgs.Default.projects.forge.model"),
                    "the refusal is anchored at the edit",
                );
            }
            other => panic!("expected an invalid save, got {other:?}"),
        }
        assert_eq!(fs::read_to_string(&path).expect("read"), before, "the file did not move");
    }

    /// Removing a project that has a live session is refused, and the refusal
    /// names the session.
    #[tokio::test]
    async fn a_project_removal_with_a_live_session_is_refused() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.register_domain_session(SessionSlot::lead("Default", "forge"), None);
        let fingerprint = settings_fingerprint(&workspace);
        let edit = SettingsEditRequest {
            area: "projects".to_owned(),
            key_path: "orgs.Default.projects.forge".to_owned(),
            pattern: String::new(),
            op: SettingsEditOp::Remove,
            value: None,
        };
        let error =
            workspace.save_settings(&fingerprint, &[edit]).expect_err("a live project is refused");
        match error {
            SettingsSaveError::Refused { message, .. } => {
                assert!(message.contains("Default/forge/lead"), "the refusal named it: {message}");
            }
            other => panic!("expected a refusal, got {other:?}"),
        }
    }

    /// Removing an account whose usage probe has not settled is refused
    /// (#2681), and the refusal names the account.
    #[tokio::test]
    async fn an_account_removal_while_loading_is_refused() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let path = workspace.config_path();
        let before = fs::read_to_string(&path).expect("read");
        let fingerprint = settings_fingerprint(&workspace);
        let edit = SettingsEditRequest {
            area: "accounts".to_owned(),
            key_path: "accounts.Stargate".to_owned(),
            pattern: String::new(),
            op: SettingsEditOp::Remove,
            value: None,
        };
        let error = workspace
            .save_settings(&fingerprint, &[edit])
            .expect_err("a loading account is refused");
        match error {
            SettingsSaveError::Refused { message, .. } => {
                assert!(message.contains("Stargate"), "the refusal named it: {message}");
                assert!(message.contains("loading"), "the refusal said why: {message}");
            }
            other => panic!("expected a refusal, got {other:?}"),
        }
        assert_eq!(fs::read_to_string(&path).expect("read"), before, "the file did not move");
    }

    /// **A save keeps the file's mode.** `forge.toml` holds every account,
    /// Slack, Gotify and System One token, and the temp file must not land
    /// its own 0644 over the operator's 0600.
    #[cfg(unix)]
    #[test]
    fn a_settings_write_keeps_the_files_mode() {
        use std::os::unix::fs::PermissionsExt as _;

        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("forge.toml");
        std::fs::write(&path, "a = 1\n").expect("write");
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).expect("chmod");
        write_atomically(&path, "a = 2\n", None).expect("write atomically");
        let mode = std::fs::metadata(&path).expect("metadata").permissions().mode() & 0o777;
        assert_eq!(mode, 0o600, "the config keeps the mode the operator gave it");
        assert_eq!(std::fs::read_to_string(&path).expect("read"), "a = 2\n");
    }

    /// **The file is re-read after the temp exists and before the rename.**
    /// A fingerprint that no longer matches refuses, and the file is
    /// untouched.
    #[test]
    fn a_write_refuses_a_file_that_moved_before_the_rename() {
        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("forge.toml");
        std::fs::write(&path, "a = 1\n").expect("write");
        let refusal = write_atomically(&path, "a = 2\n", Some("not-the-file"));
        assert!(matches!(refusal, Err(WriteRefusal::Stale)), "{refusal:?}");
        assert_eq!(
            std::fs::read_to_string(&path).expect("read"),
            "a = 1\n",
            "the file did not move",
        );
    }

    /// **A symlinked config stays a link.** The write goes through to the
    /// target rather than replacing the link with a regular file.
    #[cfg(unix)]
    #[test]
    fn a_settings_write_follows_a_symlinked_config() {
        let dir = tempfile::tempdir().expect("tempdir");
        let target = dir.path().join("real.toml");
        let link = dir.path().join("forge.toml");
        std::fs::write(&target, "a = 1\n").expect("write");
        std::os::unix::fs::symlink(&target, &link).expect("symlink");
        write_atomically(&link, "a = 2\n", None).expect("write atomically");
        assert!(
            std::fs::symlink_metadata(&link).expect("metadata").file_type().is_symlink(),
            "the config is still a symlink",
        );
        assert_eq!(std::fs::read_to_string(&target).expect("read"), "a = 2\n");
    }

    /// **The account guard refuses only an entry the save drops.** A save
    /// that keeps the loading account is the positive control the guard's
    /// own test needs: a guard that refused everything would pass that test
    /// and fail this one.
    #[tokio::test]
    async fn an_unrelated_save_while_an_account_loads_is_written() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let fingerprint = settings_fingerprint(&workspace);
        let edit = set_edit(&workspace, "usage.poll_seconds", serde_json::json!(120));
        workspace
            .save_settings(&fingerprint, &[edit])
            .expect("a save that keeps the account writes");
        let saved = fs::read_to_string(workspace.config_path()).expect("read");
        assert!(saved.contains("poll_seconds = 120"), "the value landed: {saved}");
    }

    /// **A rename is a removal the guard can see.** Renaming a project with
    /// a live session strands that session exactly as removing it would, so
    /// the before/after identity diff refuses it by name.
    #[tokio::test]
    async fn a_project_rename_with_a_live_session_is_refused() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.register_domain_session(SessionSlot::lead("Default", "forge"), None);
        let fingerprint = settings_fingerprint(&workspace);
        let edit =
            set_edit(&workspace, "orgs.Default.projects.forge.name", serde_json::json!("forge2"));
        let error = workspace
            .save_settings(&fingerprint, &[edit])
            .expect_err("a live project rename is refused");
        match error {
            SettingsSaveError::Refused { message, .. } => {
                assert!(message.contains("Default/forge/lead"), "the refusal named it: {message}");
            }
            other => panic!("expected a refusal, got {other:?}"),
        }
    }

    /// **An account rename is a removal too.** The retired identity is the
    /// one still loading, so renaming it is refused until the probe settles.
    #[tokio::test]
    async fn an_account_rename_while_loading_is_refused() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let fingerprint = settings_fingerprint(&workspace);
        let edit =
            set_edit(&workspace, "accounts.Stargate.display_name", serde_json::json!("Stargate2"));
        // The org must keep referencing a declared account, or the loader
        // refuses the candidate before the guard is reached.
        let reference =
            set_edit(&workspace, "orgs.Default.accounts", serde_json::json!(["Stargate2"]));
        let error = workspace
            .save_settings(&fingerprint, &[reference, edit])
            .expect_err("a loading rename is refused");
        match error {
            SettingsSaveError::Refused { message, .. } => {
                assert!(message.contains("Stargate"), "the refusal named it: {message}");
                assert!(message.contains("loading"), "the refusal said why: {message}");
            }
            other => panic!("expected a refusal, got {other:?}"),
        }
    }

    /// A bound port is stored but named restart-only; the socket is never
    /// rebound on a reload.
    #[tokio::test]
    async fn a_changed_port_is_reported_restart_only_and_stored() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut raw = fs::read_to_string(forge_toml_path(dir.path())).expect("read");
        raw.push_str("\n[server]\nport = 49321\n");
        fs::write(forge_toml_path(dir.path()), raw).expect("write with the new port");

        let reload = workspace.reload_config().expect("the new file is valid");

        assert!(
            reload.restart_only.iter().any(|key| key == "server.port"),
            "the new port needs a restart: {reload:?}",
        );
        assert!(
            !reload.changed.iter().any(|key| key.starts_with("server.")),
            "a port change is not a live server change: {reload:?}",
        );
        assert_eq!(
            workspace.server_config().port,
            49321,
            "the value is stored even though the bound socket keeps the old one",
        );
    }

    /// A snapshot a reader took before the reload keeps the values it read;
    /// the next reader sees the new config.
    #[tokio::test]
    async fn a_config_snapshot_taken_before_a_reload_keeps_its_values() {
        let dir = make_workspace_dir_declaring_model();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let before = workspace.config_arc();

        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Personal"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-opus-5"

[[accounts]]
display_name = "Personal"
token = "t"
models = ["claude-opus-5"]
provider = "anthropic"
"#,
        )
        .expect("write the new config");

        workspace.reload_config().expect("the new file is valid");

        assert_eq!(
            before.projects[0].model.as_deref(),
            Some("deepseek-v4.1-flash"),
            "a spawn already reading the old config keeps what it read",
        );
        assert_eq!(
            workspace.config_arc().projects[0].model.as_deref(),
            Some("claude-opus-5"),
            "the next reader gets the new value",
        );
    }

    /// `[dictate]`'s derived state is built once at boot, so an edit is
    /// stored and named restart-only rather than reported as live.
    #[tokio::test]
    async fn a_dictate_change_is_restart_only() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut raw = fs::read_to_string(forge_toml_path(dir.path())).expect("read");
        raw.push_str("\n[dictate]\nenabled = true\n");
        fs::write(forge_toml_path(dir.path()), raw).expect("write");

        let reload = workspace.reload_config().expect("the new file is valid");

        assert!(reload.restart_only.iter().any(|key| key.starts_with("dictate.")), "{reload:?}");
        assert!(!reload.changed.iter().any(|key| key.starts_with("dictate.")), "{reload:?}");
    }

    /// A reload that did not move the gateway's rotation numbers must not
    /// rebuild the rotation state: an unrelated edit cannot make a cooling
    /// account eligible again.
    #[tokio::test]
    async fn an_unrelated_reload_keeps_the_live_rotation_state() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let account = forge_gateway::AccountKey("Stargate".to_owned());
        let registration = forge_gateway::binding::Registration {
            org: "Default".to_owned(),
            project: "forge".to_owned(),
            session: "s".to_owned(),
            account: account.clone(),
            provider: forge_primitives::account::Provider::Anthropic,
        };
        workspace.gateway.bindings.register(
            &registration,
            "http://127.0.0.1:1",
            &std::collections::HashMap::new(),
        );
        let reset = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("clock")
            .as_secs()
            + 3_600;
        workspace.gateway.report_rate_limit("Default", "forge", "s", Some(reset));
        assert!(workspace.gateway.is_cooling(&account), "the fixture cools the account");

        let mut raw = fs::read_to_string(forge_toml_path(dir.path())).expect("read");
        raw.push_str("\n[documents]\nmax_size_mib = 11\n");
        fs::write(forge_toml_path(dir.path()), raw).expect("write");
        workspace.reload_config().expect("the new file is valid");
        assert!(
            workspace.gateway.is_cooling(&account),
            "a reload outside [gateway] leaves the live cooldown alone",
        );

        let mut raw = fs::read_to_string(forge_toml_path(dir.path())).expect("read");
        raw.push_str("\n[gateway]\nport = 49322\n");
        fs::write(forge_toml_path(dir.path()), raw).expect("write");
        workspace.reload_config().expect("the new file is valid");
        assert!(
            workspace.gateway.is_cooling(&account),
            "a restart-only gateway port is not a move of the rotation numbers",
        );

        let mut raw = fs::read_to_string(forge_toml_path(dir.path())).expect("read");
        raw = raw.replace("port = 49322", "port = 49322\nstreak_count = 7");
        fs::write(forge_toml_path(dir.path()), raw).expect("write");
        workspace.reload_config().expect("the new file is valid");
        assert!(
            !workspace.gateway.is_cooling(&account),
            "a reload that moved the numbers replaces the rotation state",
        );
    }

    /// The parity check is what stops a spawn accepting a resolution that
    /// straddled a reload: an odd generation is a swap in progress, so an
    /// equal-but-odd pair is not a settled read.
    #[test]
    fn a_resolution_must_start_and_end_on_a_settled_generation() {
        assert!(Workspace::resolution_held(4, 4), "an even, unchanged pair held");
        assert!(!Workspace::resolution_held(4, 6), "a completed reload invalidates it");
        assert!(
            !Workspace::resolution_held(5, 5),
            "an odd generation is a swap in progress, not a settled read",
        );
        assert!(!Workspace::resolution_held(5, 6), "a start mid-swap is never settled");
    }

    #[tokio::test]
    async fn new_for_test_opens_redb_under_the_tempdir() {
        let dir = make_workspace_dir();
        let _workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // The test constructor redirects redb into the config dir's own
        // tempdir, so no test ever opens the real machine store (#392).
        let base = dir.path().join("app-support");
        let redirected = store_path(&base, dir.path());
        assert!(redirected.exists(), "new_for_test opens redb under the tempdir app-support base");
    }

    #[tokio::test]
    async fn new_for_test_writes_the_lock_under_the_tempdir() {
        let dir = make_workspace_dir();
        let _workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // Everything under the app-support base follows the same
        // redirect as redb, so a test run leaves the real directory
        // untouched.
        let base = dir.path().join("app-support");
        assert!(
            base.join("locks").is_dir(),
            "new_for_test takes the single-instance lock under the tempdir base",
        );
    }

    #[tokio::test]
    async fn get_agent_handle_default_is_idempotent() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        let settings = SessionLaunchSettings::default();

        let handle1 = workspace
            .get_agent_handle(
                SessionTarget::Default,
                settings.clone(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("first");
        let handle2 = workspace
            .get_agent_handle(SessionTarget::Default, settings, &crate::protocol::SpawnRole::Lead)
            .expect("second");

        assert!(Arc::ptr_eq(&handle1, &handle2), "expected pool hit for repeated Default target");
        assert_eq!(workspace.pool.lock().len(), 1);
    }

    #[tokio::test]
    async fn distinct_targets_pool_distinct_entries() {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[orgs.projects]]
name = "dotfiles"
path = "~/Projects/dotfiles"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        let settings = SessionLaunchSettings::default();

        let _ = workspace
            .get_agent_handle(
                SessionTarget::Default,
                settings.clone(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("default");
        let _ = workspace
            .get_agent_handle(
                SessionTarget::Default,
                settings.clone(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("default again");
        assert_eq!(workspace.pool.lock().len(), 1, "Default is idempotent");

        // `Default` is the alphabetically-first project, which is
        // `dotfiles`; this names the other one so the targets stay
        // distinct.
        let _ = workspace
            .get_agent_handle(
                SessionTarget::Named("forge".to_owned()),
                settings,
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("named");
        assert_eq!(workspace.pool.lock().len(), 2, "a distinct target adds a pool entry");
    }

    #[tokio::test]
    async fn shutdown_drains_pool() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        let handle = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("default");

        // Pool has one entry going in.
        assert_eq!(workspace.pool.lock().len(), 1);

        // Shutdown consumes self and must return. Drops `command_senders`,
        // which closes each `SessionTask`'s command channel; the spawned
        // task then exits and drops its `handle` clone.
        workspace.shutdown().await;

        // The spawned `SessionTask` exits asynchronously after its
        // command channel closes; yield to let it run to completion
        // so the final `handle` drop is observable in `strong_count`.
        for _ in 0..16 {
            tokio::task::yield_now().await;
            if Arc::strong_count(&handle) == 1 {
                break;
            }
        }
        assert_eq!(Arc::strong_count(&handle), 1);
    }

    /// The wait reads every slot's own answer: one that fired counts as
    /// done however late in the budget it did, and only the slot that
    /// never answered is named - which is what makes a non-empty answer
    /// mean "a tree may be left", never "this one was slow".
    #[tokio::test]
    async fn shutdown_names_only_the_sessions_that_did_not_answer() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let answered = SessionSlot::new("org", "proj", "answered");
        let silent = SessionSlot::new("org", "proj", "silent");
        let firing = workspace.mint_session_teardown(&answered).expect("a mint before shutdown");
        let _held = workspace.mint_session_teardown(&silent).expect("a second mint");
        tokio::spawn(async move {
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
            let _ = firing.send_replace(true);
        });

        let unready = workspace.shutdown_within(std::time::Duration::from_millis(400)).await;

        assert_eq!(unready, vec![silent], "only the slot that never answered is named");
    }

    /// A released session's entry survives the release: the task it
    /// belongs to is still exiting, and a shutdown that started after the
    /// gesture must still wait for that exit.
    #[tokio::test]
    async fn a_released_session_is_still_awaited_by_a_shutdown() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let slot = SessionSlot::new("org", "proj", "released");
        let _held = workspace.mint_session_teardown(&slot).expect("a mint before shutdown");
        workspace.release_session(&slot);

        let unready = workspace.shutdown_within(std::time::Duration::from_millis(200)).await;

        assert_eq!(unready, vec![slot], "the released slot is still one the exit waits on");
    }

    /// One deadline for the whole drain, not one per session: two silent
    /// sessions come back together inside a single budget. A fresh timeout
    /// per receiver would spend the budget twice and red the elapsed bound.
    #[tokio::test]
    async fn a_shutdown_spends_one_budget_across_every_session() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let first = SessionSlot::new("org", "proj", "first");
        let second = SessionSlot::new("org", "proj", "second");
        let _first = workspace.mint_session_teardown(&first).expect("a mint before shutdown");
        let _second = workspace.mint_session_teardown(&second).expect("a second mint");

        let started = tokio::time::Instant::now();
        let unready = workspace.shutdown_within(std::time::Duration::from_millis(300)).await;
        let elapsed = started.elapsed();

        assert_eq!(unready.len(), 2, "both silent sessions are named: {unready:?}");
        assert!(
            elapsed < std::time::Duration::from_millis(450),
            "one budget for the drain, not one per session: it took {elapsed:?}"
        );
    }

    /// Once a shutdown has begun, no session can mint its teardown signal -
    /// which is the door a spawn would have to get through to sit outside
    /// the drain.
    #[tokio::test]
    async fn no_session_can_mint_once_a_shutdown_began() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        assert!(workspace.shutdown_within(std::time::Duration::from_millis(50)).await.is_empty());

        let after = workspace.mint_session_teardown(&SessionSlot::new("org", "proj", "late"));

        assert!(after.is_none(), "a mint after the gate went up is refused");
        assert!(workspace.is_shutting_down(), "and the gate is what refuses it");
    }

    #[tokio::test]
    async fn get_agent_handle_named_project_resolves() {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[orgs.projects]]
name = "dotfiles"
path = "~/Projects/dotfiles"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");

        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        let _ = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("default");
        // `Default` resolves to `dotfiles` now that the fallback is the
        // alphabetically-first project, so the named one is `forge`.
        let _ = workspace
            .get_agent_handle(
                SessionTarget::Named("forge".to_owned()),
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("named");
        assert_eq!(workspace.pool.lock().len(), 2);
    }

    #[tokio::test]
    async fn get_agent_handle_named_unknown_errors() {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");

        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let result = workspace.get_agent_handle(
            SessionTarget::Named("nonexistent".to_owned()),
            SessionLaunchSettings::default(),
            &crate::protocol::SpawnRole::Lead,
        );
        let Err(err) = result else { panic!("unknown project name should error") };
        let err_string = format!("{err}");
        assert!(
            err_string.contains("nonexistent"),
            "error should mention the project name; got: {err_string}"
        );
    }

    fn make_workspace_dir_with_two_accounts() -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate", "Gateway"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Gateway"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// The migration's other half: a boot has to run the copy, or the
    /// table stays empty and every persisted worker starts fresh on
    /// every boot.
    #[tokio::test]
    async fn booting_copies_the_persisted_workers_into_the_sessions_table() {
        let dir = make_workspace_dir_with_two_accounts();
        let app_support = dir.path().join("app-support");
        fs::create_dir_all(&app_support).expect("app-support dir");
        let db_path = store_path(&app_support, dir.path());
        fs::create_dir_all(db_path.parent().expect("the stores dir")).expect("stores dir");
        let db = crate::store::Db::open(&db_path).expect("open db");
        // The key the boot derives, so the seeded row is one it can match:
        // the config resolves the project path, so a literal from the
        // fixture is not the same string.
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let project_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &config.projects[0].path.to_string_lossy(),
        ));
        crate::store::dynamic_workers::insert_for_test(
            &db,
            &crate::store::dynamic_workers::DynamicWorker {
                project_key,
                label: "steward".to_owned(),
                charter: "mind the queues".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
            },
        )
        .expect("seed the worker a previous build persisted");
        drop(db);

        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");
        let db = workspace.db.lock();
        let row =
            crate::store::sessions::get(db.as_ref().expect("db"), "Default", "forge", "steward")
                .expect("read")
                .expect("the boot moved the persisted worker over");
        assert_eq!(row.label, "steward");
        assert_eq!(row.session_id, None, "its id is derived when the row is read");
    }

    /// The ordinary case the merge exists for: `sessions` already holds a
    /// row - every lead spawn writes one - while a worker's spawn args
    /// live only in the retired table, because the release before this one
    /// wrote the worker's id to `sessions` and its args to
    /// `dynamic_workers`. A sweep gated on "the sessions table is empty"
    /// skips this store entirely and then drops the only copy of the
    /// args, so the worker comes back on the next boot with an empty
    /// charter.
    ///
    /// The steward's own row is there too, because that is what the
    /// released build leaves: `record_session_id` wrote the worker's
    /// occupant id to `sessions` under the same `(org, project, label)`
    /// the retired table keys its args by. Every worker live at the
    /// moment of upgrade therefore arrives at the merge arm, and the id
    /// on that row is the thing it must not lose.
    #[tokio::test]
    async fn booting_merges_worker_args_when_the_sessions_table_already_has_rows() {
        let dir = make_workspace_dir_with_two_accounts();
        let app_support = dir.path().join("app-support");
        fs::create_dir_all(&app_support).expect("app-support dir");
        let db_path = store_path(&app_support, dir.path());
        fs::create_dir_all(db_path.parent().expect("the stores dir")).expect("stores dir");
        let db = crate::store::Db::open(&db_path).expect("open db");
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let project_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &config.projects[0].path.to_string_lossy(),
        ));
        crate::store::sessions::put(
            &db,
            &crate::store::sessions::SessionRecord {
                org: "Default".to_owned(),
                project: "forge".to_owned(),
                label: forge_primitives::LEAD_LABEL.to_owned(),
                session_id: Some("lead-session-id".to_owned()),
                charter: None,
                kick: None,
                resume_kick: None,
                interactive: None,
                seat_state: None,
                is_git_repo: None,
                mcp_families: None,
                cwd: None,
            },
        )
        .expect("seed the lead row a spawn writes");
        crate::store::sessions::put(
            &db,
            &crate::store::sessions::SessionRecord {
                org: "Default".to_owned(),
                project: "forge".to_owned(),
                label: "steward".to_owned(),
                session_id: Some("steward-id".to_owned()),
                charter: None,
                kick: None,
                resume_kick: None,
                interactive: None,
                seat_state: None,
                is_git_repo: None,
                mcp_families: None,
                cwd: None,
            },
        )
        .expect("seed the steward's own row, as the released build leaves it");
        crate::store::dynamic_workers::insert_for_test(
            &db,
            &crate::store::dynamic_workers::DynamicWorker {
                project_key,
                label: "steward".to_owned(),
                charter: "mind the queues".to_owned(),
                kick: Some("begin".to_owned()),
                resume_kick: Some("re-read the notes".to_owned()),
                interactive: true,
            },
        )
        .expect("seed the worker only the retired table describes");
        drop(db);

        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");

        let guard = workspace.db.lock();
        let db = guard.as_ref().expect("db");
        let steward = crate::store::sessions::get(db, "Default", "forge", "steward")
            .expect("read")
            .expect("the sweep runs even though the lead row is there");
        assert_eq!(
            steward.charter.as_deref(),
            Some("mind the queues"),
            "and carries the spawn args over from the retired table",
        );
        assert_eq!(steward.kick.as_deref(), Some("begin"));
        assert_eq!(steward.resume_kick.as_deref(), Some("re-read the notes"));
        assert_eq!(
            steward.session_id.as_deref(),
            Some("steward-id"),
            "onto the row it already had, keeping the occupant that row names - a plain write \
             here would blank the id, re-minting one and orphaning the transcript",
        );
        assert_eq!(
            crate::store::dynamic_workers::count(db).expect("count"),
            0,
            "the retired table is drained",
        );
        // The drop itself, which the count cannot show: an emptied table
        // and a dropped one both report zero rows, so ask whether there is
        // still a table to drop.
        assert!(
            !crate::store::dynamic_workers::drop_table(db).expect("drop"),
            "and the boot dropped it, rather than leaving an empty table behind",
        );
        assert_eq!(steward.interactive, Some(true));
        let lead =
            crate::store::sessions::get(db, "Default", "forge", forge_primitives::LEAD_LABEL)
                .expect("read")
                .expect("the row that was already there survives");
        assert_eq!(lead.session_id.as_deref(), Some("lead-session-id"), "with its id untouched");
    }

    /// The fired-prompt pairings are swept by the boot itself: a sweep wired
    /// nowhere is the unbounded table the issue names.
    #[tokio::test]
    async fn booting_sweeps_fired_prompt_pairings_past_the_window() {
        let dir = make_workspace_dir_with_two_accounts();
        let app_support = dir.path().join("app-support");
        fs::create_dir_all(&app_support).expect("app-support dir");
        let db_path = store_path(&app_support, dir.path());
        fs::create_dir_all(db_path.parent().expect("the stores dir")).expect("stores dir");
        let db = crate::store::Db::open(&db_path).expect("open db");
        let name = forge_primitives::cron::CronName {
            cron_id: "c1".to_owned(),
            description: Some("Morning summary".to_owned()),
        };
        let stale = std::time::SystemTime::now()
            .checked_sub(std::time::Duration::from_secs(31 * 24 * 60 * 60))
            .expect("a window ago");
        crate::store::cron_names::put(&db, "fired", &name, stale).expect("seed a stale pairing");
        // A row nine tenths of the way through the window: a seconds/minutes
        // mix-up in the constant would drop this one, so it pins the magnitude
        // from below as the stale row pins it from above.
        let inside = std::time::SystemTime::now()
            .checked_sub(std::time::Duration::from_secs(29 * 24 * 60 * 60))
            .expect("inside the window");
        crate::store::cron_names::put(&db, "inside", &name, inside).expect("seed a young pairing");
        crate::store::cron_names::put(&db, "fresh", &name, std::time::SystemTime::now())
            .expect("seed a fresh pairing");
        drop(db);

        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");

        let guard = workspace.db.lock();
        let db = guard.as_ref().expect("db");
        let kept =
            crate::store::cron_names::for_uuids(db, &["fired", "inside", "fresh"]).expect("read");
        assert_eq!(
            kept.keys().collect::<Vec<_>>(),
            vec!["fresh", "inside"],
            "the boot drops the pairing past the window and keeps the ones inside it"
        );
    }

    /// The retired table is dropped only once every row it held has been
    /// copied. A row no configured project can key stays where it is, so
    /// the table has to stay with it: dropped, that worker exists nowhere
    /// else and its label silently stops re-spawning, with nothing on
    /// screen to say which one went.
    #[tokio::test]
    async fn booting_keeps_the_retired_table_when_a_row_could_not_be_keyed() {
        let dir = make_workspace_dir_with_two_accounts();
        let app_support = dir.path().join("app-support");
        fs::create_dir_all(&app_support).expect("app-support dir");
        let db_path = store_path(&app_support, dir.path());
        fs::create_dir_all(db_path.parent().expect("the stores dir")).expect("stores dir");
        let db = crate::store::Db::open(&db_path).expect("open db");
        crate::store::dynamic_workers::insert_for_test(
            &db,
            &crate::store::dynamic_workers::DynamicWorker {
                project_key: "a-project-the-config-no-longer-names".to_owned(),
                label: "steward".to_owned(),
                charter: "mind the queues".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
            },
        )
        .expect("seed a worker whose project is gone");
        drop(db);

        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");

        let guard = workspace.db.lock();
        let left = crate::store::dynamic_workers::list_all(guard.as_ref().expect("db"))
            .expect("read the retired table");
        assert_eq!(
            left.len(),
            1,
            "the row could not be keyed, so it is still only there and the table must survive",
        );
        assert_eq!(left[0].label, "steward");
    }

    /// A project with no lead anywhere spawns under an id forge mints,
    /// and the row holds it: the second start re-enters that session
    /// instead of minting a third id for a project that had none.
    #[tokio::test]
    async fn a_lead_spawn_mints_an_id_and_records_it() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
        workspace.seed_test_ready_account("Stargate");

        let _handle = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("spawn");

        let id = workspace
            .stored_session_id("Default", "forge", forge_primitives::LEAD_LABEL)
            .expect("the store is readable")
            .expect("the lead's id reaches the store");
        assert!(
            uuid::Uuid::parse_str(&id).is_ok(),
            "the id is a uuid, which is what the catalog's validators accept: {id}",
        );
        assert_eq!(
            workspace
                .stored_resume_id(&SessionSlot::lead("Default", "forge"), false)
                .expect("the store is readable"),
            Some(id.clone()),
            "a later start re-enters the recorded session",
        );
    }

    /// The row outlives the process: a second workspace on the same store
    /// reads the id the first one recorded rather than starting another
    /// session under a new one.
    #[tokio::test]
    async fn a_lead_row_survives_a_restart() {
        let dir = make_workspace_dir_with_two_accounts();
        let id = {
            let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
            workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
            workspace.seed_test_ready_account("Stargate");
            let _handle = workspace
                .get_agent_handle(
                    SessionTarget::Default,
                    SessionLaunchSettings::default(),
                    &crate::protocol::SpawnRole::Lead,
                )
                .expect("spawn");
            workspace
                .stored_session_id("Default", "forge", forge_primitives::LEAD_LABEL)
                .expect("the store is readable")
                .expect("the lead's id reaches the store")
        };

        let restarted = Workspace::new_for_test(dir.path().to_owned()).expect("second boot");
        let project = restarted.config_arc().default_project().clone();
        assert_eq!(
            restarted
                .stored_resume_id(&SessionSlot::lead(&project.org, &project.name), false)
                .expect("the store is readable"),
            Some(id.clone()),
            "the second boot re-enters the session the first one recorded",
        );
    }

    /// `--new` rewrites the lead's row rather than reusing what it holds:
    /// the flag is what makes the boot wave's leads come up fresh, and a
    /// `force_new` that fell through to the store would resume the very
    /// session it was given to replace.
    #[tokio::test]
    async fn force_new_rewrites_the_lead_row_rather_than_reusing_it() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
        workspace.seed_test_ready_account("Stargate");
        let project = workspace.config_arc().default_project().clone();
        workspace.record_session_id(
            &project.org,
            &project.name,
            forge_primitives::LEAD_LABEL,
            "stored-lead-id",
        );

        let _handle = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings { force_new: true, ..SessionLaunchSettings::default() },
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("spawn");

        let id = workspace
            .stored_session_id(&project.org, &project.name, forge_primitives::LEAD_LABEL)
            .expect("the store is readable")
            .expect("the row still holds an id");
        assert_ne!(id, "stored-lead-id", "`--new` must not reuse the id the store held");
        assert!(
            uuid::Uuid::parse_str(&id).is_ok(),
            "the row is rewritten with the id this spawn minted: {id}",
        );
    }

    /// A row with no id, as the first boot after the store gained ids
    /// leaves it.
    fn seed_session_row(workspace: &Workspace, org: &str, project: &str, label: &str) {
        let db = workspace.db.lock();
        let db = db.as_ref().expect("db");
        crate::store::sessions::put(
            db,
            &crate::store::sessions::SessionRecord {
                org: org.to_owned(),
                project: project.to_owned(),
                label: label.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");
    }

    fn project_key_for(project: &LoadedProject) -> crate::target::ProjectKey {
        ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &project.path.to_string_lossy(),
        )))
    }

    /// The store is the only source for a lead's resume. A row with no id
    /// is a session that has never run, so the spawn mints a fresh one -
    /// even with a lead transcript sitting in the catalog, which is what
    /// every boot read before the store held ids.
    #[tokio::test]
    async fn a_lead_row_with_no_id_starts_fresh() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let project = workspace.config_arc().default_project().clone();
        workspace.catalog.lock().insert(
            project_key_for(&project),
            vec![forge_primitives::SDKSessionInfo {
                session_id: "catalog-lead-id".to_owned(),
                summary: "lead".to_owned(),
                last_modified: 0,
                file_size: None,
                custom_title: None,
                first_prompt: None,
                git_branch: None,
                cwd: None,
                storage_key: String::new(),
                tag: None,
                created_at: None,
            }],
        );
        seed_session_row(&workspace, &project.org, &project.name, forge_primitives::LEAD_LABEL);

        assert_eq!(
            workspace
                .stored_resume_id(&SessionSlot::lead(&project.org, &project.name), false)
                .expect("the store is readable"),
            None,
            "a row with no id has nothing to resume, whatever the catalog holds",
        );
    }

    /// A row that cannot be read is not a row without an id. Minting on a
    /// read error would fork the session and write the new id over the
    /// row it failed to read, so the spawn is refused instead.
    #[tokio::test]
    async fn an_unreadable_session_row_refuses_the_spawn_rather_than_forking() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let project = workspace.config_arc().default_project().clone();
        {
            let db = workspace.db.lock();
            crate::store::sessions::put_raw_for_test(
                db.as_ref().expect("test store"),
                &project.org,
                &project.name,
                forge_primitives::LEAD_LABEL,
                b"not a session record",
            )
            .expect("plant the undecodable row");
        }

        assert!(
            matches!(
                workspace.stored_resume_id(&SessionSlot::lead(&project.org, &project.name), false),
                Err(crate::error::WorkspaceError::SessionStoreUnreadable { .. })
            ),
            "a row that cannot be read is refused, not treated as absent",
        );
        assert!(
            workspace.resolve_slot(&SessionTarget::Named(project.name.clone())).is_err()
                || workspace
                    .stored_resume_id(&SessionSlot::lead(&project.org, &project.name), false)
                    .is_err(),
            "and the refusal reaches the spawn's target resolution, so nothing mints over it",
        );
        assert!(
            crate::store::sessions::get(
                workspace.db.lock().as_ref().expect("test store"),
                &project.org,
                &project.name,
                forge_primitives::LEAD_LABEL,
            )
            .is_err(),
            "the refused spawn left the unreadable row exactly as it found it",
        );
    }

    /// The store follows the id the CLI is actually running. An
    /// in-session `/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: without this the next boot resumes the
    /// stale id and the registration keeps naming a session that is no
    /// longer running.
    #[tokio::test]
    async fn the_store_follows_the_id_the_cli_adopted() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let key = SessionSlot::lead("Default", "forge");
        workspace.seed_test_bound_session(&key, "Stargate");
        seed_session_row(&workspace, "Default", "forge", forge_primitives::LEAD_LABEL);

        workspace.note_running_session_id(&key, "adopted-id");
        assert_eq!(
            workspace
                .stored_session_id("Default", "forge", forge_primitives::LEAD_LABEL)
                .expect("the store is readable")
                .as_deref(),
            Some("adopted-id"),
            "the row holds the id the CLI adopted, not a stale one",
        );

        workspace.note_running_session_id(&key, "adopted-id");
        assert_eq!(
            workspace
                .stored_session_id("Default", "forge", forge_primitives::LEAD_LABEL)
                .expect("the store is readable")
                .as_deref(),
            Some("adopted-id"),
            "and re-noting the same id leaves it alone",
        );
    }

    #[tokio::test]
    async fn a_fresh_spawn_stamps_the_gateway_base_url_and_dummy_credential() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // The listener's own tests cover the socket; this one pins what
        // the child is stamped with, so the boot gate is opened by hand.
        workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
        workspace.seed_test_ready_account("Stargate");

        let handle = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("spawn");
        let env = handle.env();
        let base = env
            .get("ANTHROPIC_BASE_URL")
            .expect("the gateway stamps a base URL on every registered spawn");
        assert!(
            base.starts_with("http://127.0.0.1:") && base.contains("/Default/forge/"),
            "the base URL names the listener and the three routing segments: {base}",
        );
        assert_eq!(
            env.get("CLAUDE_CODE_OAUTH_TOKEN").map(String::as_str),
            Some(forge_gateway::binding::DUMMY_CREDENTIAL),
            "the child's credential variable carries the dummy, not the real token",
        );
        assert_eq!(
            env.get("ANTHROPIC_API_KEY").map(String::as_str),
            Some(""),
            "an API-key source is forced empty so the CLI cannot ship a foreign credential",
        );

        // The binding is keyed by the session's own id - the third
        // routing segment, and the tail of the base URL above - not by
        // the slot, which is the routing key rather than the occupant.
        let session_key = workspace.resolve_slot(&SessionTarget::Default).expect("resolves");
        let session_id = {
            let pool = workspace.pool.lock();
            pool.get(&session_key).expect("the spawn pooled the lead").session_id.clone()
        };
        assert_eq!(
            workspace.gateway.bindings.binding_for("Default", "forge", &session_id),
            Some(AccountKey("Stargate".to_owned())),
            "the spawn registered the session with the gateway",
        );
    }

    #[tokio::test]
    async fn a_project_env_cannot_unstamp_the_gateway_base_url() {
        let dir = make_workspace_dir_with_two_accounts();
        // The project layer carries a base-url key pointing elsewhere:
        // exactly the silent-bypass hazard the stamp closes.
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate", "Gateway"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[orgs.projects.env]
ANTHROPIC_BASE_URL = "http://169.254.10.10:9999"
CLAUDE_CODE_API_BASE_URL = "http://169.254.10.10:9999"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Gateway"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.gateway_ready.store(true, std::sync::atomic::Ordering::Release);
        workspace.seed_test_ready_account("Stargate");

        let handle = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("spawn");
        let env = handle.env();
        let base = env.get("ANTHROPIC_BASE_URL").expect("base url stamped");
        assert!(
            base.starts_with("http://127.0.0.1:") && base.contains("/Default/forge/"),
            "the project layer must not point the child away from the listener: {base}",
        );
        assert_eq!(
            env.get("CLAUDE_CODE_API_BASE_URL").map(String::as_str),
            Some(base.as_str()),
            "the alt base-url variable is stamped to the listener too",
        );
        assert!(
            !env.values().any(|v| v.contains("169.254.10.10")),
            "the foreign host never reaches the child: {env:?}",
        );
    }

    #[tokio::test]
    async fn a_closed_boot_gate_refuses_spawns_naming_the_port() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.gateway_ready.store(false, std::sync::atomic::Ordering::Release);

        let message = match workspace.get_agent_handle(
            SessionTarget::Default,
            SessionLaunchSettings::default(),
            &crate::protocol::SpawnRole::Lead,
        ) {
            Err(error) => error.to_string(),
            Ok(_) => panic!("a shut boot gate refuses spawns"),
        };
        assert!(
            message.contains("8787") || message.contains("port"),
            "the refusal names the port, got: {message}",
        );
        assert!(
            message.contains("not ready") || message.contains("boot gate"),
            "the refusal says the gateway is the cause, got: {message}",
        );
    }

    #[tokio::test]
    async fn pool_records_picked_account() {
        let dir = make_workspace_dir_with_two_accounts();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        workspace.seed_test_ready_account("Gateway");
        let _ = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("default");
        let bound = workspace.pool.lock().values().map(|p| p.account.0.clone()).collect::<Vec<_>>();
        assert_eq!(bound.len(), 1);
        // Every spawn walks, so the pick is the first ready account in
        // the org's own order - there is no per-spawn spread.
        assert_eq!(bound[0], "Stargate");
    }

    #[tokio::test]
    async fn project_account_pin_excludes_unpinned_account() {
        // Three accounts globally, all Ready; the default org pins only
        // {Stargate, Gateway}, so a spawn under the default project
        // walks the pinned pair in its own order and never reaches
        // Personal.
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate", "Gateway"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Gateway"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Personal"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");

        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        for account in ["Stargate", "Gateway", "Personal"] {
            workspace.seed_test_ready_account(account);
        }
        let _ = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("default spawn");

        let bound = workspace.pool.lock().values().map(|p| p.account.0.clone()).collect::<Vec<_>>();
        assert_eq!(bound.len(), 1);
        assert_eq!(
            bound[0], "Stargate",
            "the walk takes the first pinned account; Personal is never reached",
        );
    }

    // ---- Refresh + facade tests ----
    //
    // Use a synthetically-registered `DomainSession` so the test
    // doesn't need a real subprocess. The stub handle's command
    // dispatcher captures whatever the workspace pushes through it,
    // which is what we assert on.

    /// Wire one `DomainSession` for `key` against a fresh testing
    /// stub. Returns the workspace, the matching primitives command
    /// receiver, and the registered key.
    fn ws_with_stub_session()
    -> (Arc<Workspace>, mpsc::UnboundedReceiver<forge_primitives::AgentCommand>, SessionSlot) {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("refresh-test");
        let rx = workspace.install_testing_stub(&key);
        // Stamp a session_id so refresh paths don't bail on
        // "no session_id yet".
        if let Some(domain) = workspace.domain_session_for(&key) {
            domain.lock().session_id = Some(forge_primitives::SessionId::new(key.display()));
        }
        (workspace, rx, key)
    }

    #[test]
    fn refresh_context_usage_dispatches_get_context_usage() {
        let (workspace, mut rx, key) = ws_with_stub_session();
        workspace.refresh_context_usage(&key).expect("dispatch");
        let cmd = rx.try_recv().expect("queued");
        assert!(matches!(cmd, forge_primitives::AgentCommand::GetContextUsage { .. }));
    }

    #[test]
    fn refresh_mcp_snapshot_dispatches() {
        let (workspace, mut rx, key) = ws_with_stub_session();
        workspace.refresh_mcp_snapshot(&key).expect("dispatch");
        let cmd = rx.try_recv().expect("queued");
        assert!(matches!(cmd, forge_primitives::AgentCommand::GetMcpSnapshot { .. }));
    }

    /// The OS walk's answer lands on the session that produced it, and a
    /// second session's read does not see it: the walk describes one
    /// subprocess tree, so a read that answered another slot's would
    /// report a process tree that is not running there.
    #[test]
    fn a_stored_process_snapshot_answers_only_its_own_session() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let walked = key_with_stub_handle(&workspace, "walked");
        let other = key_with_stub_handle(&workspace, "other");
        let walked_at = std::time::SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(60);

        workspace.store_process_snapshot(&walked, Some(snapshot_walked_at(walked_at)));

        assert_eq!(
            workspace.process_snapshot(&walked).map(|snapshot| snapshot.scanned_at),
            Some(walked_at),
            "the session that was walked reads its own snapshot back",
        );
        assert!(
            workspace.process_snapshot(&other).is_none(),
            "and its neighbour reads none, rather than the walk of another tree",
        );
    }

    /// The walk described a subprocess tree that is gone, so the read
    /// must not keep serving it.
    #[test]
    fn a_cleared_process_snapshot_reads_as_none() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = key_with_stub_handle(&workspace, "walked");
        workspace.store_process_snapshot(
            &key,
            Some(snapshot_walked_at(std::time::SystemTime::UNIX_EPOCH)),
        );

        workspace.store_process_snapshot(&key, None);

        assert!(workspace.process_snapshot(&key).is_none(), "a cleared snapshot reads as none");
    }

    /// A slot with no session at all answers rather than panicking, and
    /// holds nothing: a store that minted a domain for whoever asked
    /// would leave the workspace routing to a session nobody runs.
    #[test]
    fn a_process_snapshot_for_an_unregistered_slot_reads_as_none() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let stranger = SessionSlot::from_str_for_test("never-registered");

        workspace.store_process_snapshot(
            &stranger,
            Some(snapshot_walked_at(std::time::SystemTime::UNIX_EPOCH)),
        );

        assert!(
            workspace.process_snapshot(&stranger).is_none(),
            "an unregistered slot holds nothing rather than creating one",
        );
    }

    fn snapshot_walked_at(
        scanned_at: std::time::SystemTime,
    ) -> forge_agent::env::processes::ProcessSnapshot {
        forge_agent::env::processes::ProcessSnapshot { processes: Vec::new(), scanned_at }
    }

    fn key_with_stub_handle(workspace: &Arc<Workspace>, label: &str) -> SessionSlot {
        let key = SessionSlot::from_str_for_test(label);
        drop(workspace.install_testing_stub(&key));
        key
    }

    #[test]
    fn refresh_context_usage_unknown_session_errors() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("never-registered");
        let err = workspace.refresh_context_usage(&key).expect_err("unknown session");
        assert!(matches!(err, DispatchError::UnknownSession(_)));
    }

    /// `dispatch(Command::Cancel)` falls back to synchronous direct
    /// dispatch when no SessionTask is registered. This is the path
    /// a view's unit tests rely on - the stub-handle wiring installs a
    /// stub handle but never spawns a task, and tests need to observe
    /// the primitive command on the rx.
    #[test]
    fn dispatch_falls_back_to_direct_when_no_session_task() {
        let (workspace, mut rx, key) = ws_with_stub_session();
        workspace.dispatch(Command::Cancel { key }).expect("dispatch");
        let cmd = rx.try_recv().expect("queued");
        assert!(matches!(cmd, forge_primitives::AgentCommand::Cancel { .. }));
    }

    /// The two facts the failed-turn mark reads from the routing seam, on
    /// the production path a registered sender puts a dispatch on: Cancel
    /// arms the exempt stamp only while a turn is in flight, and a
    /// committed prompt spends the previous failure.
    #[test]
    fn routing_arms_cancels_in_flight_and_spends_the_failure_mark_on_a_committed_prompt() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("routing-seam");
        workspace.register_domain_session(key.clone(), None);
        // Registers the sender, so dispatch takes the routed path rather
        // than the test-only synchronous fallback.
        workspace.mark_test_session_live(&key);
        let domain = workspace.domain_session_for(&key).expect("registered domain");
        domain.lock().session_id = Some(forge_primitives::SessionId::new(key.display()));

        // An idle Cancel arms nothing: there is no turn to exempt.
        workspace.dispatch(Command::Cancel { key: key.clone() }).expect("dispatch");
        assert!(!domain.lock().pending_cancel, "an idle cancel arms nothing");

        domain.lock().failed_turn_at = Some(std::time::SystemTime::now());
        domain.lock().turn_pending = true;
        workspace.dispatch(Command::Cancel { key: key.clone() }).expect("dispatch");
        assert!(domain.lock().pending_cancel, "a cancel over a live turn arms the stamp");
        assert!(
            workspace.session_failed_turn(&key).is_some(),
            "and leaves the standing mark in place",
        );

        workspace
            .dispatch(Command::Prompt {
                key: key.clone(),
                text: "go".to_owned(),
                attachments: Vec::new(),
            })
            .expect("dispatch");
        assert!(
            workspace.session_failed_turn(&key).is_some(),
            "a prompt that only queues behind the busy turn keeps the failure mark - \
             the running turn is still the one that failed",
        );
        assert!(
            domain.lock().pending_cancel,
            "a prompt that only queues behind the busy turn keeps the cancel stamp - \
             its error Result still has to read as the reader's own cancel",
        );

        // The busy turn ends, and a prompt committed with nothing in flight
        // starts a new one: the stamp and the failure mark expire there, or
        // this turn's genuine failure would go unmarked.
        domain.lock().turn_pending = false;
        domain.lock().pending_cancel = true;
        workspace
            .dispatch(Command::Prompt {
                key: key.clone(),
                text: "go".to_owned(),
                attachments: Vec::new(),
            })
            .expect("dispatch");
        assert!(
            !domain.lock().pending_cancel,
            "a prompt committed with no turn in flight expires the stamp",
        );
        assert!(
            workspace.session_failed_turn(&key).is_none(),
            "and spends the previous turn's failure mark: the newest turn is this one",
        );
    }

    /// A committed prompt is the newest turn, so it spends the pending
    /// continuation left by the failure before it - left standing, it would
    /// resume a turn that is no longer the seat's newest.
    #[test]
    fn routing_drops_the_pending_nudge_on_a_prompt() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("routing-nudge");
        workspace.register_domain_session(key.clone(), None);
        // Registers the sender, so dispatch takes the routed path rather
        // than the test-only synchronous fallback.
        workspace.mark_test_session_live(&key);
        let domain = workspace.domain_session_for(&key).expect("registered domain");
        domain.lock().session_id = Some(forge_primitives::SessionId::new(key.display()));
        domain.lock().auto_continue =
            Some(crate::domain_session::PendingAutoContinue { reason: "server_error".to_owned() });

        workspace
            .dispatch(Command::Prompt {
                key: key.clone(),
                text: "go".to_owned(),
                attachments: Vec::new(),
            })
            .expect("dispatch");

        assert!(
            domain.lock().auto_continue.is_none(),
            "a committed prompt is the newest turn, so the continuation for the old one goes",
        );
    }

    /// The review store write routes through the command bus: an
    /// `UpsertReviewThread` dispatch lands in the redb store (observable
    /// via the query-side load) and carries its confirmation back on the
    /// responder - the overlay's at-risk flag depends on it.
    #[test]
    fn dispatch_buses_the_review_and_spinner_writes() {
        use forge_primitives::review::{ReviewAnchor, ReviewSide, ReviewStatus, ReviewThread};
        let (workspace, _update_rx) = Workspace::testing_stub();
        let db_dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("db"),
        );
        let thread = ReviewThread {
            id: "t1".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::new(),
            status: ReviewStatus::Open,
            created_at: "t".to_owned(),
            updated_at: "t".to_owned(),
            commit: None,
        };

        let (respond_tx, mut respond_rx) = tokio::sync::oneshot::channel();
        workspace
            .dispatch(Command::UpsertReviewThread {
                project: "forge".to_owned(),
                branch: "feat".to_owned(),
                thread: thread.clone(),
                origin: None,
                sent_words: None,
                respond: Some(respond_tx),
            })
            .expect("dispatch");
        assert!(
            respond_rx.try_recv().expect("response present"),
            "an open store confirms the upsert on the responder"
        );
        let loaded = workspace.load_review_threads("forge", "feat").expect("load");
        assert_eq!(loaded.len(), 1, "the bus-routed upsert landed in the store");
    }

    /// The same for the retraction: a `DeleteReviewThread` dispatch removes
    /// the thread from the store and confirms on the responder, and a
    /// second delete of the same id confirms `false` rather than lying.
    #[test]
    fn dispatch_buses_the_review_delete() {
        use forge_primitives::review::{ReviewAnchor, ReviewSide, ReviewStatus, ReviewThread};
        let (workspace, _update_rx) = Workspace::testing_stub();
        let db_dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("db"),
        );
        let thread = ReviewThread {
            id: "t1".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::new(),
            status: ReviewStatus::Open,
            created_at: "t".to_owned(),
            updated_at: "t".to_owned(),
            commit: None,
        };
        workspace.upsert_review_thread("forge", "feat", thread);

        let (respond_tx, mut respond_rx) = tokio::sync::oneshot::channel();
        workspace
            .dispatch(Command::DeleteReviewThread {
                project: "forge".to_owned(),
                branch: "feat".to_owned(),
                thread_id: "t1".to_owned(),
                respond: Some(respond_tx),
            })
            .expect("dispatch");
        assert!(
            respond_rx.try_recv().expect("response present"),
            "an open store confirms the delete on the responder"
        );
        let loaded = workspace.load_review_threads("forge", "feat").expect("load");
        assert!(loaded.is_empty(), "the bus-routed delete left the store empty");

        let (again_tx, mut again_rx) = tokio::sync::oneshot::channel();
        workspace
            .dispatch(Command::DeleteReviewThread {
                project: "forge".to_owned(),
                branch: "feat".to_owned(),
                thread_id: "t1".to_owned(),
                respond: Some(again_tx),
            })
            .expect("dispatch");
        assert!(!again_rx.try_recv().expect("response present"), "an absent id deletes nothing");
    }

    /// `/new` and `/resume` re-spawn on the already-pooled handle, where
    /// the spawn-path stamp in `get_agent_handle_at_key` never
    /// runs - the launch settings must pick the pooled session's mode up
    /// at dispatch instead.
    #[test]
    fn respawn_commands_on_a_pooled_session_carry_its_mode() {
        use forge_primitives::permission::PermissionMode;
        let (workspace, _update_rx) = Workspace::testing_stub();
        // The slot is the routing key; the id it is pooled under is the
        // occupant, and the registration's third segment is that id.
        let session_id = "respawn-mode-test";
        let key = SessionSlot::from_str_for_test(session_id);
        let (handle, mut agent_rx) = Workspace::testing_stub_handle();
        workspace.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("Openrouter".to_owned()),
                permission_mode: Some(PermissionMode::BypassPermissions),
                registration: Some(forge_gateway::binding::Registration {
                    org: "Busytools".to_owned(),
                    project: "forge".to_owned(),
                    session: session_id.to_owned(),
                    account: AccountKey("Openrouter".to_owned()),
                    provider: forge_primitives::account::Provider::Openrouter,
                }),
                session_id: session_id.to_owned(),
            },
        );

        let auto_settings = || SessionLaunchSettings {
            settings: Some(serde_json::json!({ "permissions": { "defaultMode": "auto" } })),
            ..SessionLaunchSettings::default()
        };
        workspace
            .dispatch(Command::NewSession {
                key: key.clone(),
                cwd: "/tmp".to_owned(),
                launch_settings: auto_settings(),
                session_id: None,
            })
            .expect("dispatch new");
        workspace
            .dispatch(Command::ResumeSession {
                key: key.clone(),
                session_id: "old-uuid".to_owned(),
                cwd: "/tmp".to_owned(),
                launch_settings: auto_settings(),
            })
            .expect("dispatch resume");

        let carried_mode = |value: &serde_json::Value| -> Option<String> {
            value
                .get("settings")
                .and_then(|s| s.get(SessionLaunchSettings::PERMISSIONS_KEY))
                .and_then(|p| p.get(SessionLaunchSettings::PERMISSIONS_DEFAULT_MODE_KEY))
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned)
        };
        let first = agent_rx.try_recv().expect("new session agent command");
        let second = agent_rx.try_recv().expect("resume agent command");
        let forge_primitives::AgentCommand::NewSession {
            session_id: new_id,
            launch_settings: new,
            ..
        } = first
        else {
            panic!("expected a NewSession agent command");
        };
        let forge_primitives::AgentCommand::ResumeSession { launch_settings: resume, .. } = second
        else {
            panic!("expected a ResumeSession agent command");
        };
        assert_eq!(
            carried_mode(&new).as_deref(),
            Some("bypassPermissions"),
            "/new must carry the pooled session's mode, not the session default",
        );
        assert_eq!(
            carried_mode(&resume).as_deref(),
            Some("bypassPermissions"),
            "/resume must carry the pooled session's mode, not the session default",
        );
        // The respawn also re-registers with the gateway: the fresh env
        // set rides the launch settings as overrides, so the respawned
        // child is pointed at this generation's listener - under the id
        // it will run as, not the one it replaces.
        let base_url = |value: &serde_json::Value| -> Option<String> {
            value
                .get("env_overrides")
                .and_then(|e| e.get("ANTHROPIC_BASE_URL"))
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned)
        };
        let minted = new_id.expect("`/new` starts under a minted id");
        assert_eq!(
            base_url(&new).as_deref(),
            Some(
                format!("http://127.0.0.1:{}/Busytools/forge/{minted}", workspace.gateway_port)
                    .as_str()
            ),
            "`/new` stamps the base URL with the id it mints for the child",
        );
        assert_eq!(
            base_url(&resume).as_deref(),
            Some(
                format!("http://127.0.0.1:{}/Busytools/forge/old-uuid", workspace.gateway_port)
                    .as_str()
            ),
            "`/resume` stamps the base URL with the transcript it re-enters",
        );
        assert_eq!(
            workspace.gateway.bindings.binding_for("Busytools", "forge", "old-uuid"),
            Some(AccountKey("Openrouter".to_owned())),
            "the binding follows the occupant the resume leaves running",
        );
        assert_eq!(
            workspace.gateway.bindings.binding_for("Busytools", "forge", &minted),
            None,
            "and the segment the new session left behind is dropped",
        );
        // The overrides carry ONLY the four gateway-owned keys. Carrying
        // the whole env would let a key declared in both layers revert
        // to its account value on respawn.
        let overrides =
            new.get("env_overrides").and_then(|e| e.as_object()).expect("env overrides present");
        assert_eq!(overrides.len(), 4, "exactly the four gateway-owned keys");
    }

    /// `/new` and `/resume` re-spawn on the already-pooled handle, where
    /// the spawn-path stamp never runs - the launch settings must pick
    /// the project's canonical model up at dispatch instead, the way
    /// they pick up the mode.
    #[test]
    fn respawn_commands_on_a_pooled_session_carry_the_project_model() {
        let dir = make_workspace_dir_declaring_model();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let key = SessionSlot::from_str_for_test("respawn-model-test");
        let (handle, mut agent_rx) = Workspace::testing_stub_handle();
        workspace.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("OpenRouter-TM".to_owned()),
                permission_mode: None,
                registration: Some(forge_gateway::binding::Registration {
                    org: "Default".to_owned(),
                    project: "forge".to_owned(),
                    session: key.display(),
                    account: AccountKey("OpenRouter-TM".to_owned()),
                    provider: forge_primitives::account::Provider::Openrouter,
                }),
                session_id: key.display(),
            },
        );

        // The caller's pin is the literal opus - exactly the string the
        // respawn must replace with the project's canonical model.
        let caller_settings = || SessionLaunchSettings {
            settings: Some(serde_json::json!({ "model": "opus" })),
            ..SessionLaunchSettings::default()
        };
        workspace
            .dispatch(Command::NewSession {
                key: key.clone(),
                cwd: "/tmp".to_owned(),
                launch_settings: caller_settings(),
                session_id: None,
            })
            .expect("dispatch new");
        workspace
            .dispatch(Command::ResumeSession {
                key: key.clone(),
                session_id: "old-uuid".to_owned(),
                cwd: "/tmp".to_owned(),
                launch_settings: caller_settings(),
            })
            .expect("dispatch resume");

        let carried_model = |value: &serde_json::Value| -> Option<String> {
            value
                .get("settings")
                .and_then(|settings| settings.get("model"))
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned)
        };
        let first = agent_rx.try_recv().expect("new session agent command");
        let second = agent_rx.try_recv().expect("resume agent command");
        let forge_primitives::AgentCommand::NewSession { launch_settings: new, .. } = first else {
            panic!("expected a NewSession agent command");
        };
        let forge_primitives::AgentCommand::ResumeSession { launch_settings: resume, .. } = second
        else {
            panic!("expected a ResumeSession agent command");
        };
        assert_eq!(
            carried_model(&new).as_deref(),
            Some("deepseek-v4.1-flash"),
            "/new must carry the project's canonical model, not the caller's pin",
        );
        assert_eq!(
            carried_model(&resume).as_deref(),
            Some("deepseek-v4.1-flash"),
            "/resume must carry the project's canonical model, not the caller's pin",
        );
    }

    /// A session that spawned with no project mode must not gain a
    /// fallback mode at dispatch: the launcher's own session default
    /// survives a respawn.
    #[test]
    fn respawn_commands_on_a_session_with_no_mode_keep_the_launcher_default() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("respawn-modeless-test");
        let (handle, mut agent_rx) = Workspace::testing_stub_handle();
        workspace.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("Plain".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );

        workspace
            .dispatch(Command::NewSession {
                key: key.clone(),
                cwd: "/tmp".to_owned(),
                launch_settings: SessionLaunchSettings {
                    // "plan", not the real launcher default "auto": an Auto
                    // fallback mutant would survive an auto seed.
                    settings: Some(serde_json::json!({ "permissions": { "defaultMode": "plan" } })),
                    ..SessionLaunchSettings::default()
                },
                session_id: None,
            })
            .expect("dispatch new");

        let forge_primitives::AgentCommand::NewSession { launch_settings, .. } =
            agent_rx.try_recv().expect("new session agent command")
        else {
            panic!("expected a NewSession agent command");
        };
        let carried = launch_settings
            .get("settings")
            .and_then(|s| s.get(SessionLaunchSettings::PERMISSIONS_KEY))
            .and_then(|p| p.get(SessionLaunchSettings::PERMISSIONS_DEFAULT_MODE_KEY))
            .and_then(serde_json::Value::as_str);
        assert_eq!(
            carried,
            Some("plan"),
            "a session with no project mode must keep the launcher's session default",
        );
        // The pool entry carries no registration, so the respawn stays
        // direct: no gateway-owned key rides the overrides, and the
        // child keeps whatever credential its launch settings compose.
        let overrides_empty = launch_settings
            .get("env_overrides")
            .and_then(|e| e.as_object())
            .is_none_or(serde_json::Map::is_empty);
        assert!(
            overrides_empty,
            "a None-registration respawn applies no gateway overrides: {launch_settings}",
        );
    }

    // ---- Session-task routing tests ----
    //
    // A routed command names the slot, and the `SessionTask` is
    // registered under that same slot, so nothing has to be migrated
    // when the occupant changes. What these tests pin is what still
    // moves on its own: pool membership when a task exits, and the
    // binding a slot's occupant reads.

    /// Seed `command_senders`, `pool`, and `domain_handles` at `key`
    /// against a fresh stub handle so `Workspace::dispatch` will
    /// route through the `SessionTask`-style fast path (rather than
    /// the test-only direct fallback). Returns the routed-command
    /// receiver so the test can assert on what flows through.
    fn install_fake_session_task(
        workspace: &Arc<Workspace>,
        key: &SessionSlot,
    ) -> mpsc::UnboundedReceiver<Command> {
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        let arc = Arc::new(handle);
        workspace.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::clone(&arc),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        let (cmd_tx, cmd_rx) = mpsc::unbounded_channel::<Command>();
        workspace.command_senders.lock().insert(key.clone(), cmd_tx);
        let domain = workspace.register_domain_session(key.clone(), Some(arc));
        domain.lock().session_id = Some(forge_primitives::SessionId::new(key.display()));
        cmd_rx
    }

    /// **A prompt a dead task never receives spends the turn it committed.**
    /// The send is refused, so no Result will ever serve it; leaving
    /// `turn_pending` set draws a turn in flight on the header that nothing
    /// can close.
    #[test]
    fn a_prompt_a_dead_task_never_receives_leaves_no_turn_in_flight() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        let key = SessionSlot::lead("TestOrg", "forge");
        ws.record_session_id("TestOrg", "forge", "lead", "id-1");
        ws.record_seat_state(&key, SeatState::InTurn);
        let receiver = install_fake_session_task(&ws, &key);
        drop(receiver);

        let refused = ws.dispatch(Command::Prompt {
            key: key.clone(),
            text: "hello".to_owned(),
            attachments: Vec::new(),
        });

        assert!(refused.is_err(), "the dead task refuses the prompt");
        let domain = ws.domain_session_for(&key).expect("the fixture registers the seat");
        assert!(
            !domain.lock().turn_in_flight(),
            "a refused prompt leaves no turn in flight for the header",
        );
        assert_eq!(
            ws.stored_seat_state(&key),
            Some(SeatState::Idle),
            "and the row must not say a turn is running for a prompt no task ever saw",
        );
    }

    /// **The turn is on the row before the CLI hears of it.** A boot that
    /// finds the seat mid-turn hands it the restart note, so a crash
    /// between this send and the turn's Result leaves the interrupted turn
    /// standing rather than reading as a seat that was parked. Both prompt
    /// arms mark it: a send the reader typed, and the `PromptUnder` a
    /// handoff's note and a peer's message arrive as.
    #[test]
    fn a_committed_turn_marks_the_seat_in_turn() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        let key = SessionSlot::lead("TestOrg", "forge");
        let _commands = install_fake_session_task(&ws, &key);
        ws.record_session_id("TestOrg", "forge", "lead", "id-1");

        for (label, command) in [
            (
                "a typed prompt",
                Command::Prompt {
                    key: key.clone(),
                    text: "start the turn".to_owned(),
                    attachments: Vec::new(),
                },
            ),
            (
                "a handoff's note",
                Command::PromptUnder {
                    key: key.clone(),
                    text: "continue from the brief".to_owned(),
                    attachments: Vec::new(),
                    uuid: "note-id".to_owned(),
                    source: crate::protocol::PromptSource::Forge,
                    dispatch_id: None,
                },
            ),
        ] {
            ws.record_seat_state(&key, SeatState::Idle);
            ws.domain_session_for(&key)
                .expect("the fixture registers the seat")
                .lock()
                .reset_turns();

            ws.dispatch(command).expect("the live task takes the prompt");

            assert_eq!(
                ws.stored_seat_state(&key),
                Some(SeatState::InTurn),
                "{label} starts a turn, so the row says one is in flight",
            );
        }
    }

    /// The close door is the one close that outlives the process: a bare
    /// boot leaves the project shut, while opening it again resumes the
    /// stored occupant.
    #[test]
    fn the_close_door_closes_the_lead_row() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        let key = SessionSlot::lead("TestOrg", "forge");
        ws.record_session_id("TestOrg", "forge", "lead", "id-1");
        ws.record_seat_state(&key, SeatState::InTurn);

        ws.dispatch(Command::CloseSession { session_key: key.clone() })
            .expect("the close dispatches");

        assert_eq!(
            ws.stored_seat_state(&key),
            Some(SeatState::Closed),
            "a closed lead is not reopened by a bare boot",
        );

        // **The task a close tore down can still land a write.** A Result
        // being translated and a buffered swap both write through this door
        // after the close; neither may reopen the project the user shut.
        for late in [SeatState::Idle, SeatState::InTurn] {
            ws.record_seat_state(&key, late);
            assert_eq!(
                ws.stored_seat_state(&key),
                Some(SeatState::Closed),
                "a late {late:?} write leaves the close as the last word",
            );
        }
    }

    /// **A `/new` a dying task drains after the close does not reopen the
    /// row.** The mint is a swap, not an opening door: it records the id
    /// the successor runs under and leaves the reader's close standing.
    #[test]
    fn a_fresh_id_for_a_closed_seat_leaves_it_closed() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        let key = SessionSlot::lead("TestOrg", "forge");
        ws.record_session_id("TestOrg", "forge", "lead", "id-1");
        ws.record_seat_state(&key, SeatState::Closed);

        let minted = ws.fresh_session_id_for(&key);

        assert_eq!(
            ws.stored_seat_state(&key),
            Some(SeatState::Closed),
            "a swap leaves the close as the last word",
        );
        assert_eq!(
            ws.stored_session_id(key.org(), key.project(), key.label()).expect("read"),
            Some(minted),
            "and the row still names the occupant the swap minted",
        );
    }

    /// **Opening a closed project is the reader's act, and it reopens the
    /// row.** Closing is not forgetting: the named spawn resumes the stored
    /// occupant and marks the seat open, or the project could never be
    /// opened again.
    #[tokio::test]
    async fn a_named_spawn_reopens_a_closed_lead() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");
        workspace.record_session_id(
            "Default",
            "forge",
            "lead",
            "11111111-2222-3333-4444-555555555555",
        );
        workspace.record_seat_state(&key, SeatState::Closed);

        let mut updates = workspace.subscribe_mirror();
        spawn_lead(&workspace, false, None);
        let (connected, _note) =
            lead_boot_frames(&mut updates, &key, Duration::from_millis(200)).await;
        assert!(connected, "the lead connects");

        assert_eq!(
            workspace.stored_seat_state(&key),
            Some(SeatState::Idle),
            "a named spawn is an opening door",
        );
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A close that refuses the heal's spawn is the stop, not a spawn
    /// failure.** It leaves no failure record and no Failed row for the
    /// project the reader just shut.
    #[tokio::test]
    async fn a_close_refusing_a_heal_spawn_records_no_failure() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let project = tempdir().expect("project");
        let workspace = boot_lead_workspace(dir.path(), project.path());
        let key = SessionSlot::lead("Default", "forge");
        workspace.record_session_id(
            "Default",
            "forge",
            "lead",
            "11111111-2222-3333-4444-555555555555",
        );
        workspace.record_seat_state(&key, SeatState::Closed);

        let outcome = crate::spawn::handle_heal_project_spawn(
            &workspace,
            "forge",
            SessionLaunchSettings::default(),
        );

        assert!(outcome.is_ok(), "the close ends the heal quietly: {outcome:?}");
        assert_eq!(workspace.stored_seat_state(&key), Some(SeatState::Closed), "the close stands");
        assert_eq!(workspace.spawn_failure(&key), None, "a close is not a spawn failure");
        forge_agent::set_test_sdk_binary(None);
    }

    /// `/new` mints the successor's id, and a swap leaves the seat parked:
    /// the successor starts with no turn in flight even though the seat it
    /// replaced may have been mid-turn.
    #[test]
    fn an_occupant_swap_leaves_the_seat_idle() {
        use crate::store::sessions::SeatState;

        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        let key = SessionSlot::lead("TestOrg", "forge");
        ws.record_session_id("TestOrg", "forge", "lead", "old-id");
        ws.record_seat_state(&key, SeatState::InTurn);

        let fresh = ws.fresh_session_id_for(&key);
        assert_ne!(fresh, "old-id", "the swap mints a new occupant");

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

    /// A session's `SessionTask` exiting (agent event channel closed -
    /// the subprocess died, e.g. after a cron turn) must RELEASE the
    /// session from the pool + command_senders. Without this the entry
    /// lingers as a dead-but-pooled zombie: the next cron fire's
    /// `running_lead` check still finds it "open" and dispatches a
    /// `Command::Prompt` to the closed channel, which fails with
    /// `SessionClosed` and is silently dropped - so durable crons quietly
    /// stop firing for that project.
    #[tokio::test]
    async fn session_task_exit_releases_dead_pooled_session() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("lead-uuid");
        // Register the session as a connected lead (pool + command_senders
        // + domain_handles).
        let command_rx = install_fake_session_task(&workspace, &key);
        assert!(workspace.pool.lock().contains_key(&key), "precondition: session pooled");

        // In production the SessionTask holds the SAME `Arc<AgentHandle>`
        // that sits in the pool, so the exit-cleanup identity guard
        // (`release_session_if_current`) recognises this task as the
        // current owner. Reuse the pooled handle here rather than a
        // fresh one; its testing-stub event channel is already closed,
        // so `run()` takes the "agent event channel closed" exit path
        // immediately - exactly the post-cron-turn subprocess exit.
        let domain = workspace.domain_session_for(&key).expect("domain registered");
        let pooled_handle = domain.lock().conn.clone().expect("pooled handle on domain");
        let update_tx = UpdateFanout::default();
        let _task_update_rx = update_tx.subscribe(SubscriberRole::Answering);
        let task = crate::session_task::SessionTask {
            key: key.clone(),
            handle: pooled_handle,
            command_rx,
            domain,
            update_tx,
            connected_once: true,
            workspace: Arc::downgrade(&workspace),
            compaction_count: 0,
            successor: None,
            teardown_done: None,
        };
        task.run().await;

        assert!(
            !workspace.pool.lock().contains_key(&key),
            "pool entry must be released when the SessionTask exits",
        );
        assert!(
            !workspace.command_senders.lock().contains_key(&key),
            "command sender must be released when the SessionTask exits",
        );
    }

    /// A binding is keyed by the segment the child's base URL was
    /// stamped with, which is the id the slot's occupant runs under:
    /// the read follows the live binding rather than the account the
    /// spawn picked.
    #[test]
    fn the_bound_account_follows_the_live_binding_for_the_slot() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("first-uuid");
        install_fake_session_task(&workspace, &key);
        let segment = key.display();
        workspace.pool.lock().get_mut(&key).expect("pooled").registration =
            Some(forge_gateway::binding::Registration {
                org: "Org".to_owned(),
                project: "forge".to_owned(),
                session: segment.clone(),
                account: AccountKey("A".to_owned()),
                provider: forge_primitives::account::Provider::Anthropic,
            });
        workspace.gateway.bindings.bind("Org", "forge", &segment, AccountKey("A".to_owned()));

        assert_eq!(
            workspace.bound_account_for(&key),
            Some(AccountKey("A".to_owned())),
            "the stamped segment is what the binding is keyed by",
        );

        // The gateway re-selecting on the next request is the whole
        // point: the registration's own account is the spawn-time pick
        // and stays "A" here.
        workspace.gateway.bindings.bind("Org", "forge", &segment, AccountKey("B".to_owned()));
        assert_eq!(
            workspace.bound_account_for(&key),
            Some(AccountKey("B".to_owned())),
            "the read follows the live binding, not the spawn-time pick",
        );
    }

    /// Stub carrying one project, `companies`, whose lead session is
    /// already up: catalogued, pooled, and - because
    /// `install_fake_session_task` stamps it - carrying the
    /// `session_id` the retire gate reads. The returned `TempDir`
    /// guards the config dir for the caller's lifetime.
    fn stub_with_connected_lead()
    -> (Arc<Workspace>, mpsc::UnboundedReceiver<SeatUpdate>, SessionSlot, tempfile::TempDir) {
        let dir = tempdir().expect("tempdir");
        let root = dir.path().join("companies");
        fs::create_dir_all(&root).expect("project root");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "companies"
path = "{root}"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                root = root.display()
            ),
        )
        .expect("write forge.toml");
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        let (ws, update_rx) = Workspace::testing_stub_with_config(dir.path().to_owned(), config)
            .expect("the stub config's [[slack]] entries are well-formed");

        let lead = SessionSlot::lead("Personal", "companies");
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        // The store is what a project-rooted spawn resumes from, so the
        // fixture records the lead's id there the way a boot would.
        ws.record_session_id(
            "Personal",
            "companies",
            forge_primitives::LEAD_LABEL,
            &lead.display(),
        );
        ws.record_connected_session(&root.to_string_lossy(), &lead.display(), None);
        let _cmd_rx = install_fake_session_task(&ws, &lead);
        assert_eq!(
            ws.resolve_slot(&SessionTarget::Named("companies".to_owned())).expect("resolves"),
            lead,
            "precondition: the project resolves to the lead this fixture pooled",
        );
        (ws, update_rx, lead, dir)
    }

    /// Every `Spawning` key an update stream carried, in order.
    fn spawning_keys(update_rx: &mut mpsc::UnboundedReceiver<SeatUpdate>) -> Vec<SessionSlot> {
        let mut keys: Vec<SessionSlot> = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::Spawning { key, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                keys.push(key);
            }
        }
        keys
    }

    /// Any second wake of a live project reaches the fast path: a cron,
    /// a peer prompt, a gotify message, a slack delivery or the boot
    /// wave landing after one of them. It announces the same
    /// key the live session already holds, so a view has one bucket
    /// rather than a second one to retire.
    #[test]
    fn respawn_of_connected_project_announces_the_live_key() {
        let (ws, mut update_rx, lead, _dir) = stub_with_connected_lead();

        let _ =
            crate::spawn::handle_spawn_project(&ws, "companies", SessionLaunchSettings::default());

        let announced = spawning_keys(&mut update_rx);
        assert_eq!(
            announced,
            vec![lead],
            "a re-spawn announces the key the live session already holds, not a second one",
        );
    }

    /// A background rate-limit clears `DomainSession.session_id` while
    /// the pool entry lives. The emit must not read that mirror: the key
    /// it announces is the session's own, whatever the mirror says.
    #[test]
    fn a_rate_limited_session_still_announces_its_own_key() {
        let (ws, mut update_rx, lead, _dir) = stub_with_connected_lead();
        // What `apply_session_update_connection_failed` does to a
        // rate-limited background session: clear the mirror, leave the
        // pool entry alone.
        ws.set_session_id_in_domain(&lead, None);

        let _ =
            crate::spawn::handle_spawn_project(&ws, "companies", SessionLaunchSettings::default());

        assert_eq!(
            spawning_keys(&mut update_rx),
            vec![lead],
            "a cleared session_id must not change the key announced",
        );
    }

    /// `classify_oauth_usage_error` must distinguish HTTP 429 from
    /// auth-related failures, keeping the `rate-limited` class (the
    /// common case under multiple forge instances) rather than
    /// collapsing every failure to a single generic bucket.
    #[test]
    fn classify_oauth_usage_error_buckets_known_variants() {
        use forge_gateway::ProbeError;
        use forge_gateway::UsageFetchStatus;
        use forge_primitives::usage::oauth::OauthUsageError;

        let fetch = |err| ProbeError::Fetch(err);
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::HttpStatus(429, String::new()))),
            UsageFetchStatus::RateLimited,
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::RateLimited {
                retry_after: Some(std::time::Duration::from_secs(60)),
                snapshot: None,
            })),
            UsageFetchStatus::RateLimited,
            "new dedicated 429 variant also maps to RateLimited",
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::RateLimited {
                retry_after: None,
                snapshot: None,
            })),
            UsageFetchStatus::RateLimited,
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::Unauthorized(401))),
            UsageFetchStatus::Unauthorized,
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::Expired)),
            UsageFetchStatus::Expired,
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::NoCredentials)),
            UsageFetchStatus::Expired,
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::Network("dns".to_owned()))),
            UsageFetchStatus::NetworkFailed,
        );
        // Non-429 HTTP errors and decode failures fall through to the
        // generic `Other` bucket, so an unmapped failure keeps its own
        // class instead of being read as a named cause.
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::HttpStatus(500, String::new()))),
            UsageFetchStatus::Other,
        );
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::Decode("bad json".to_owned()))),
            UsageFetchStatus::Other,
        );
        // A failed `claude --version` shell-out is a local exec problem,
        // not a reachability verdict, so it must not land in
        // NetworkFailed.
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::UaProbe("no binary".to_owned()))),
            UsageFetchStatus::Other,
        );
        // A scope refusal is anomalous (OAuth tokens carry user:profile)
        // and must not render as an auth failure.
        assert_eq!(
            classify_oauth_usage_error(&fetch(OauthUsageError::ScopeInsufficient)),
            UsageFetchStatus::Other,
        );
        // The backend's own credential miss rides the same Expired
        // bucket as the wire class, and the unmappable 200 - which the
        // callers handle before classifying - keeps the match total.
        assert_eq!(
            classify_oauth_usage_error(&ProbeError::NoCredentials),
            UsageFetchStatus::Expired,
        );
        assert_eq!(
            classify_oauth_usage_error(&ProbeError::Unmappable("no window".to_owned())),
            UsageFetchStatus::Other,
        );
    }

    /// An Anthropic account (setup token on its account block) derives
    /// the token auth class, whose bailed-row repair copy names the
    /// token and never a re-authentication of the shared config dir.
    #[tokio::test]
    async fn a_token_mode_account_derives_the_token_auth_class() {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["TokenAcct"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "TokenAcct"
token = "setup-token"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");

        let rows = workspace.account_loading_snapshot();
        assert_eq!(rows.len(), 1, "the fixture has one account; got {rows:?}");
        assert_eq!(
            rows[0].auth,
            crate::views::AccountAuth::Token,
            "a setup-token account is the token auth class; got {:?}",
            rows[0].auth,
        );
    }

    // ─────────────────────────────────────────────────────────────────
    // I3 - peer-MCP lifecycle tests
    // ─────────────────────────────────────────────────────────────────

    /// Resolve a project's expanded path from the workspace's view.
    /// Catalog keys derive from `project_key_for_directory(expanded_path)`,
    /// not the literal `~/`-prefixed forge.toml string, so callers that
    /// want `record_connected_session` to populate the right project's
    /// session list need this lookup.
    fn project_expanded_path(workspace: &Workspace, name: &str) -> String {
        workspace.list_projects().into_iter().find(|p| p.name == name).map_or_else(
            || panic!("project '{name}' missing from workspace"),
            |p| p.path.to_string_lossy().into_owned(),
        )
    }

    /// A cron entry carrying what a delivery routes and reads: the id, the
    /// project, the prompt and a description.
    fn test_cron(id: &str, project: &str, prompt: &str) -> forge_primitives::cron::CronEntry {
        use forge_primitives::cron::{CronEntry, CronId, CronKind};
        CronEntry {
            id: CronId::from(id),
            project_name: project.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,
        }
    }

    /// A message parked for a seat that never came up is acknowledged to
    /// its sender: the notice lands on the sender's slot and names the
    /// seat that did not take it.
    ///
    /// This is the delivery-ack path, and the parked entry's sender is the
    /// only thing that knows where the notice goes - the ask registry that
    /// used to carry it is gone.
    #[tokio::test]
    async fn notice_undelivered_message_names_the_target_and_reaches_the_sender() {
        use crate::mcp::peers::types::PeerFailureReason;

        let (ws, mut rx) = Workspace::testing_stub();
        ws.enable_test_dispatch_intercept();

        let sender = SessionSlot::from_str_for_test("sender-proj");
        let target = SessionSlot::lead("Default", "gateway-backend");
        ws.notice_undelivered_message(&sender, &target, PeerFailureReason::TargetConnectionFailed);

        let mut echo = None;
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                echo = Some((key, wrapped));
            }
        }
        let (key, notice) = echo.expect("the notice is painted for the sender");
        assert_eq!(key, sender, "the notice lands on the sender, not the target");
        assert_eq!(
            notice.sender_name, "gateway-backend",
            "and names the seat that did not take it"
        );
        assert_eq!(notice.sender_org, "Default", "with that seat's org");
        assert!(
            notice.body.contains("connection lost"),
            "the reason reaches the reader: {}",
            notice.body
        );

        let dispatched = ws.drain_test_dispatch_buffer();
        assert_eq!(dispatched.len(), 1, "the notice is also dispatched as a turn");
        match &dispatched[0] {
            Command::Prompt { key, text, .. } | Command::PromptUnder { key, text, .. } => {
                assert_eq!(*key, sender, "the dispatched turn goes to the sender");
                assert!(text.contains("failed to deliver"), "carrying the failure prose: {text}");
            }
            other => panic!("expected a prompt command, got {other:?}"),
        }
    }

    /// **Two seat captures never overlap.** The generation ranks whole
    /// captures, so a capture held between its mint and its reads must hold
    /// the next one off: a capture that ran there would carry the higher
    /// number over the older seat set, and the fleet would drop the capture
    /// that actually read the newer one.
    #[test]
    fn a_live_seats_capture_cannot_overlap_another() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let dir = tempdir().expect("a temp dir");
        let db = crate::store::Db::open(&dir.path().join("db.redb")).expect("the store");
        workspace.attach_store_for_test(db);
        workspace.seed_test_project("forge", "/tmp/forge-capture-overlap");
        workspace.insert_live_worker(
            &project,
            crate::mcp::workers::types::WorkerEntry {
                label: "w".to_owned(),
                charter: "c".to_owned(),
                slot: SessionSlot::worker("Default", "forge", "w"),
                session_id: None,
                status: forge_primitives::WorkerLiveness::Running,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::lead("Default", "forge"),
                needs_tag: false,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );
        let (reached, resume) = workspace.pause_next_live_seats_capture();

        let held = {
            let workspace = Arc::clone(&workspace);
            std::thread::spawn(move || workspace.live_seats())
        };
        reached
            .recv_timeout(std::time::Duration::from_secs(10))
            .expect("the first capture is held between its mint and its reads");

        let (done_tx, done_rx) = std::sync::mpsc::channel();
        let second = {
            let workspace = Arc::clone(&workspace);
            std::thread::spawn(move || {
                let snapshot = workspace.live_seats();
                let _ = done_tx.send(());
                snapshot
            })
        };
        // A capture that could run between the first one's mint and its reads
        // finishes here; one that cannot reports nothing.
        let overtook = done_rx.recv_timeout(std::time::Duration::from_millis(500)).is_ok();

        // The seat goes while the first capture is open.
        let drained = workspace.drain_live_workers(&project);
        assert_eq!(drained.len(), 1, "the worker was live before the drain");
        let _ = resume.send(());

        let held = held.join().expect("the held capture returns").expect("the store is readable");
        let second =
            second.join().expect("the second capture returns").expect("the store is readable");

        assert!(
            !overtook,
            "a second capture must not run while the first is between its mint and its reads",
        );
        assert!(held.generation < second.generation, "the held capture keeps the earlier number");
        assert!(
            !held.seats.iter().any(|seat| seat.label() == "w"),
            "the held capture read after the drain",
        );
        assert!(
            second.seats.iter().all(|seat| held.seats.contains(seat)),
            "the newer number must not carry an older seat set: second={:?} held={:?}",
            second.seats,
            held.seats,
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod workers_state_tests {
    use super::*;
    use crate::mcp::workers::types::WorkerEntry;
    use forge_primitives::WorkerLiveness;
    use std::time::SystemTime;

    fn fake_entry(label: &str, key: &str) -> WorkerEntry {
        WorkerEntry {
            label: label.into(),
            charter: "test charter".into(),
            slot: SessionSlot::from_str_for_test(key),
            session_id: None,
            status: WorkerLiveness::Running,
            spawned_at: 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,
        }
    }

    #[test]
    fn live_workers_starts_empty() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        assert!(ws.list_live_workers(&project).is_empty());
    }

    /// A store that is not open is not "no rows": the collision guard
    /// refuses on the unknown rather than admitting another project's
    /// path.
    #[test]
    fn a_collision_refuses_when_a_projects_rows_cannot_be_read() {
        let (ws, _rx) = Workspace::testing_stub();
        ws.seed_test_project("proj-a", "/tmp/proj-a-unreadable");
        ws.seed_test_project("proj-b", "/tmp/proj-b-unreadable");
        let own = ws.project_key_for_name("proj-a").expect("proj-a");

        let collision = ws.worktree_collision(
            std::path::Path::new("/tmp/proj-b-unreadable/.claude/worktrees/shared"),
            &own,
            "shared",
            WorktreeOp::Spawn,
        );

        let reason = collision.expect("an unreadable store refuses the path");
        assert!(
            reason.contains("could not read the worker rows"),
            "the refusal names the unknown it is refusing on: {reason}",
        );
    }

    /// The claim on a composed path is repository-wide and atomic: one
    /// owner at a time, re-entrant only for the same project and label.
    #[test]
    fn a_worktree_claim_admits_one_owner_across_projects() {
        let (ws, _rx) = Workspace::testing_stub();
        let path = std::path::Path::new("/tmp/claimed-worktree");
        let proj_a = ProjectKey::new("proj-a");
        let proj_b = ProjectKey::new("proj-b");

        let first =
            ws.claim_worktree(path, &proj_a, "shared", WorktreeOp::Spawn).expect("the first claim");
        let reentrant = ws
            .claim_worktree(path, &proj_a, "shared", WorktreeOp::Spawn)
            .expect("the same owner may claim twice: a resume's ensure and the core's insert");
        let refused = ws
            .claim_worktree(path, &proj_b, "shared", WorktreeOp::Spawn)
            .expect_err("another project cannot claim the same path");
        assert!(refused.contains("worker 'shared'"), "the refusal names the holder: {refused}");
        assert!(refused.contains("proj-a"), "and its project: {refused}");
        let despawn = ws
            .claim_worktree(path, &proj_a, "shared", WorktreeOp::Despawn)
            .expect_err("the same owner and label under another operation cannot enter");
        assert!(
            despawn.contains("is in use by the worker 'shared'"),
            "the refusal says the spawn holds it: {despawn}",
        );

        drop(reentrant);
        ws.claim_worktree(path, &proj_b, "shared", WorktreeOp::Spawn)
            .expect_err("the first claim is still held");
        drop(first);
        ws.claim_worktree(path, &proj_b, "shared", WorktreeOp::Spawn)
            .expect("free once every claim is released");
    }

    #[test]
    fn insert_then_list_returns_entry() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        ws.insert_live_worker(&project, fake_entry("reviewer", "abc"));
        let entries = ws.list_live_workers(&project);
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].label, "reviewer");
    }

    #[test]
    fn remove_latest_by_label_picks_most_recent_duplicate() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        ws.insert_live_worker(&project, fake_entry("dup", "old"));
        ws.insert_live_worker(&project, fake_entry("dup", "new"));
        let removed = ws.remove_latest_worker(&project, "dup");
        assert_eq!(removed.unwrap().slot.label(), "new");
        assert_eq!(ws.list_live_workers(&project).len(), 1);
    }

    #[test]
    fn remove_returns_none_when_missing() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        assert!(ws.remove_latest_worker(&project, "missing").is_none());
    }

    /// The atomic guard rejects a second insert for a live label (holding
    /// the lock across the check + push closes the concurrent-dispatch
    /// TOCTOU) and hands back the existing worker.
    #[test]
    fn insert_if_label_absent_rejects_duplicate_label() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        assert!(
            ws.insert_live_worker_if_label_absent(&project, fake_entry("reviewer", "first"), None)
                .is_ok(),
            "the first insert for a label wins",
        );
        let existing = ws
            .insert_live_worker_if_label_absent(&project, fake_entry("reviewer", "second"), None)
            .expect_err("a second live worker for the same label is rejected");
        let existing = match existing {
            LiveWorkerRefusal::LabelLive(session_key) => session_key,
            LiveWorkerRefusal::CleanupPending => panic!("no despawn cleanup is in flight"),
            LiveWorkerRefusal::AtCap { .. } => panic!("no cap was supplied"),
        };
        assert_eq!(existing.label(), "first", "the live holder is returned");
        assert_eq!(ws.list_live_workers(&project).len(), 1, "no duplicate is inserted");
    }

    /// A `Failed` entry does not hold its label - the atomic guard lets
    /// its label be re-spawned (parity with `live_worker_with_label`).
    #[test]
    fn insert_if_label_absent_allows_reinsert_over_failed() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let mut failed = fake_entry("reviewer", "dead");
        failed.status = WorkerLiveness::Failed;
        ws.insert_live_worker(&project, failed);
        assert!(
            ws.insert_live_worker_if_label_absent(&project, fake_entry("reviewer", "fresh"), None)
                .is_ok(),
            "a Failed entry does not block a re-spawn of its label",
        );
        assert_eq!(ws.list_live_workers(&project).len(), 2);
    }

    /// **A spawn supersedes a heal's tombstone rather than sitting beside
    /// it.** A same-label spawn is admitted because a `Restarting` entry is
    /// not live while the cap still counts it; leaving the tombstone would
    /// count the slot twice, and the heal's timer aborts on the live label,
    /// so it would hold a cap slot for the rest of the run.
    #[test]
    fn insert_if_label_absent_supersedes_a_restarting_tombstone() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let mut tombstone = fake_entry("reviewer", "w1");
        tombstone.status = WorkerLiveness::Restarting;
        ws.insert_live_worker(&project, tombstone);

        ws.insert_live_worker_if_label_absent(&project, fake_entry("reviewer", "w1"), None)
            .expect("a Restarting tombstone does not hold the label");

        let entries = ws.list_live_workers(&project);
        assert_eq!(entries.len(), 1, "the tombstone went with the spawn that superseded it");
        assert_eq!(
            entries[0].status,
            WorkerLiveness::Running,
            "the spawn's own entry is what remains",
        );
        assert_eq!(ws.count_live_workers(&project), 1, "and the cap counts the slot once");
    }

    #[test]
    fn drain_for_project_clears_and_returns_all() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        ws.insert_live_worker(&project, fake_entry("a", "k1"));
        ws.insert_live_worker(&project, fake_entry("b", "k2"));
        let drained = ws.drain_live_workers(&project);
        assert_eq!(drained.len(), 2);
        assert!(ws.list_live_workers(&project).is_empty());
    }
}

#[cfg(test)]
mod worker_activity_tests {
    use super::*;
    use crate::mcp::workers::types::WorkerEntry;
    use crate::protocol::PendingInteractionSlot;
    use forge_primitives::{SessionLifecycleState as L, WorkerLiveness};
    use std::time::SystemTime;

    fn entry(key: &str, status: WorkerLiveness) -> WorkerEntry {
        WorkerEntry {
            label: "implementer".into(),
            charter: "test charter".into(),
            slot: SessionSlot::from_str_for_test(key),
            session_id: None,
            status,
            spawned_at: 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,
        }
    }

    /// The same derivation has to be reachable by slot: a project lead has
    /// no `WorkerEntry` to hand `worker_activity`, and a view drawing the
    /// lead's row needs its state from somewhere.
    #[test]
    fn session_activity_reads_a_slot_with_no_worker_entry() {
        let (ws, _rx) = Workspace::testing_stub();

        assert_eq!(
            ws.session_activity(&SessionSlot::from_str_for_test("s-gone")),
            L::Sleeping,
            "a slot with no domain session is asleep, not idle",
        );

        let blocked = SessionSlot::from_str_for_test("s-blocked");
        let domain = ws.register_domain_session(blocked.clone(), None);
        {
            let mut guard = domain.lock();
            guard.turn_pending = true;
            let (tx, _rx) = tokio::sync::oneshot::channel();
            guard.pending_interactions.insert("tool-1".to_owned(), testing::test_permission(tx));
        }
        assert_eq!(
            ws.session_activity(&blocked),
            L::Attention,
            "a turn in flight holding a pending interaction needs a person",
        );
    }

    /// Two states the lifecycle derivation has to reach or a view cannot
    /// draw them: a session held on `/login`, and one whose last attempt
    /// to start failed and has not been retried. Both are facts about the
    /// session, so the core answers them rather than each view folding
    /// them out of the events it happened to see.
    #[test]
    fn session_activity_reaches_login_and_failure() {
        let (ws, _rx) = Workspace::testing_stub();
        let held = SessionSlot::from_str_for_test("s-login");
        let domain = ws.register_domain_session(held.clone(), None);
        assert_eq!(ws.session_activity(&held), L::Idle, "a fresh domain is idle");

        {
            let mut guard = domain.lock();
            guard.awaiting_login = true;
            // A login wait is not a turn, so a state that claims one is in
            // flight must not outrank it.
            guard.turn_pending = true;
        }
        assert_eq!(
            ws.session_activity(&held),
            L::AuthRequired,
            "a session waiting on /login cannot proceed, whatever its turn state says",
        );

        // The signal that actually arrives: a turn that died on a missing
        // credential. Without it the state is unreachable and the row draws
        // a calm idle for a session held on `/login`.
        let by_error = SessionSlot::from_str_for_test("s-login-error");
        let domain = ws.register_domain_session(by_error.clone(), None);
        let auth_message = "authentication failed: please log in";
        crate::session_task::apply_event_to_domain(
            &mut domain.lock(),
            &forge_agent::client::AgentEvent::TurnError {
                session_id: "uuid".to_owned(),
                message: auth_message.to_owned(),
                class: forge_agent::translate::error_handling::classify_turn_error(auth_message),
            },
        );
        assert_eq!(
            ws.session_activity(&by_error),
            L::AuthRequired,
            "a turn error the classifier calls auth-required holds the session on /login",
        );

        // A failed attempt is recorded where the failure releases the
        // session, so it survives the release.
        let dead = SessionSlot::from_str_for_test("s-dead");
        ws.record_spawn_failure(&dead, "OAuth token expired");
        assert_eq!(ws.session_activity(&dead), L::Failed, "an unrecovered failure is failed");
        assert_eq!(
            ws.spawn_failure(&dead).as_deref(),
            Some("OAuth token expired"),
            "and carries why",
        );

        // Registering a domain is not what clears it. Production hoists a
        // domain itself rather than registering one, so the clear lives in
        // the `Connected` arm - see `a_connection_failure_is_recorded_and_
        // a_connected_clears_it`, which drives a real task through both.
        ws.register_domain_session(dead.clone(), None);
        assert_eq!(
            ws.spawn_failure(&dead).as_deref(),
            Some("OAuth token expired"),
            "registering a domain does not clear the record, because production never registers one",
        );
        assert_eq!(
            ws.session_activity(&dead),
            L::Failed,
            "so the slot still reads failed until something connects",
        );
    }

    /// What a session is waiting on a person for, which is what a
    /// needs-you row has to name. A question outranks a permission prompt,
    /// so a slot holding both reads as the question.
    #[test]
    fn pending_interaction_answers_the_kind_a_slot_is_waiting_on() {
        let (ws, _rx) = Workspace::testing_stub();
        let held = |name: &str, slots: Vec<PendingInteractionSlot>| {
            let key = SessionSlot::from_str_for_test(name);
            let domain = ws.register_domain_session(key.clone(), None);
            {
                let mut guard = domain.lock();
                for (index, slot) in slots.into_iter().enumerate() {
                    guard.pending_interactions.insert(format!("{name}-{index}"), slot);
                }
            }
            key
        };
        let permission = || {
            let (tx, _rx) = tokio::sync::oneshot::channel();
            testing::test_permission(tx)
        };
        let question = || {
            let (tx, _rx) = tokio::sync::oneshot::channel();
            testing::test_question(tx)
        };

        assert_eq!(
            ws.pending_interaction(&SessionSlot::from_str_for_test("p-none")),
            None,
            "a slot with no domain session is waiting on nothing",
        );

        let asked = held("p-question", vec![question()]);
        assert_eq!(
            ws.pending_interaction(&asked),
            Some(PendingInteractionKind::Question),
            "a held question is what the slot is waiting on",
        );

        let prompted = held("p-permission", vec![permission()]);
        assert_eq!(
            ws.pending_interaction(&prompted),
            Some(PendingInteractionKind::Permission),
            "a permission prompt alone is what the slot is waiting on",
        );

        let both = held("p-both", vec![permission(), question()]);
        assert_eq!(
            ws.pending_interaction(&both),
            Some(PendingInteractionKind::Question),
            "a question outranks the permission prompt beside it",
        );
    }

    /// One list, expanded twice: the exhaustive match naming an ask's
    /// needs-you kind, and the fixture list the guard test parks.
    ///
    /// **A new `PendingAsk` variant cannot be named without being parked.**
    /// The generated match is exhaustive, so the variant must be added to
    /// this one list; the list is also what the test iterates, so its
    /// fixture is constructed, read back and asserted. A variant mapped onto
    /// a kind another variant already names leaves a duplicate in
    /// `ASK_KINDS`, which the test refuses - so every ask kind is exercised
    /// on its own.
    macro_rules! ask_census {
        ($($kind:ident => $variant:ident),* $(,)?) => {
            ask_census!(@match; [] $($kind $variant,)*);

            /// Every ask kind the list names, one entry per `PendingAsk`
            /// variant.
            const ASK_KINDS: &[PendingInteractionKind] = &[ $( PendingInteractionKind::$kind, )* ];
        };
        (@match; [$($arms:tt)*]) => {
            /// The kind a needs-you row draws for an ask - exhaustive, and
            /// generated from the same list as `ASK_KINDS`.
            fn needs_you_kind(ask: &crate::protocol::PendingAsk) -> PendingInteractionKind {
                match ask {
                    $($arms)*
                }
            }
        };
        (@match; [$($arms:tt)*] $kind:ident $variant:ident, $($rest:tt)*) => {
            ask_census!(@match;
                [$($arms)* crate::protocol::PendingAsk::$variant(_) => PendingInteractionKind::$kind,]
                $($rest)*);
        };
    }

    ask_census! {
        Question => Question,
        Permission => Permission,
        SlackDraft => SlackDraft,
        BrowserHandOff => BrowserHandOff,
        TerminalHandOff => TerminalHandOff,
        DocumentHandOff => DocumentHandOff,
        SettingsWrite => SettingsWrite,
        Vault => Vault,
    }

    /// Park one ask of `kind` on a seat of its own and answer the seat.
    ///
    /// A prompt is inserted into the session's pending set the way
    /// `session_task` parks one, taking the ask's number; every registry kind
    /// goes through its own registration. Both are the app's path.
    ///
    /// The terminal takes the seeded project's lead slot because its PTY
    /// resolves a cwd; every other kind gets a fresh seat, so nothing parked
    /// here competes with another kind for the same row.
    async fn park_one(
        ws: &std::sync::Arc<Workspace>,
        name: &str,
        kind: PendingInteractionKind,
    ) -> SessionSlot {
        let seat = if kind == PendingInteractionKind::TerminalHandOff {
            SessionSlot::lead("TestOrg", "guard")
        } else {
            SessionSlot::from_str_for_test(name)
        };
        let domain = ws.register_domain_session(seat.clone(), None);
        domain.lock().turn_pending = true;
        match kind {
            PendingInteractionKind::Question => {
                let (tx, _rx) = tokio::sync::oneshot::channel();
                ws.domain_session_for(&seat)
                    .expect("the seat's own domain")
                    .lock()
                    .pending_interactions
                    .insert(format!("{name}-0"), testing::test_question(tx));
                // The arrival is what numbers a prompt; the direct insert
                // stands in for it.
                ws.note_ask(&seat);
            }
            PendingInteractionKind::Permission => {
                let (tx, _rx) = tokio::sync::oneshot::channel();
                ws.domain_session_for(&seat)
                    .expect("the seat's own domain")
                    .lock()
                    .pending_interactions
                    .insert(format!("{name}-0"), testing::test_permission(tx));
                ws.note_ask(&seat);
            }
            PendingInteractionKind::SlackDraft => {
                let (_id, _decision) = ws.register_slack_draft(
                    &seat,
                    forge_primitives::slack::SlackDraft {
                        id: uuid::Uuid::new_v4(),
                        workspace: "acme".to_owned(),
                        conversation: "C1".to_owned(),
                        conversation_label: "acme".to_owned(),
                        thread_ts: None,
                        text: "hello".to_owned(),
                        operation: forge_primitives::slack::SlackDraftOperation::Post,
                        thread: None,
                        tagged: Vec::new(),
                    },
                );
            }
            PendingInteractionKind::BrowserHandOff => {
                let (_id, _answer) = ws
                    .register_browser_hand_off(&seat, "solve the CAPTCHA", "T2")
                    .await
                    .expect("the browser hand-off parks");
            }
            PendingInteractionKind::TerminalHandOff => {
                let entry = ws.terminal_for(&seat).expect("a terminal");
                let (_id, _answer) = ws
                    .register_terminal_hand_off(&seat, entry.id, "the sudo password")
                    .expect("the terminal hand-off parks");
            }
            PendingInteractionKind::DocumentHandOff => {
                ws.note_client_attached();
                let (_id, _ending) = ws
                    .register_document_hand_off(&seat, "/proj/docs/plan.md", true)
                    .expect("the document hand-off parks");
            }
            PendingInteractionKind::SettingsWrite => {
                let (_id, _answer, _) = ws.register_settings_write(
                    &seat,
                    forge_primitives::settings::SettingsWriteAsk {
                        id: uuid::Uuid::new_v4(),
                        edits: vec![forge_primitives::settings::SettingsWriteChange {
                            key: "sessions.heal_attempts".to_owned(),
                            current: serde_json::json!(2),
                            proposed: serde_json::json!(4),
                            unset: false,
                        }],
                    },
                );
            }
            PendingInteractionKind::Vault => {
                ws.note_client_attached();
                let (_id, _answer, _) = ws.register_vault_ask(
                    &seat,
                    forge_primitives::vault::VaultDraft::new(
                        forge_primitives::vault::VaultTool::Search,
                        "search for 'bank'",
                    ),
                    false,
                );
            }
        }
        seat
    }

    /// **Every ask kind is a needs-you kind.** Each kind the census names is
    /// parked on a seat of its own and must read the kind back, say
    /// `Attention`, count exactly one, and carry its own number - the last
    /// what proves a registry registration announced its ask, and for a
    /// prompt what proves its arrival was numbered. The terminal is here
    /// because it drew in the dock and marked nothing (#2954).
    #[tokio::test]
    async fn every_ask_kind_marks_its_seat() {
        let (ws, _rx) = Workspace::testing_stub();
        ws.seed_test_project("guard", "/tmp");
        let (calls, _heard) = tokio::sync::mpsc::unbounded_channel();
        ws.install_browser_host(std::sync::Arc::new(crate::browser::testing::StubHost { calls }));

        let mut named: Vec<PendingInteractionKind> = Vec::new();
        for (index, kind) in ASK_KINDS.iter().enumerate() {
            assert!(
                !named.contains(kind),
                "{kind:?} is named by two ask variants, so one of them is never parked",
            );
            named.push(*kind);
            let seat = park_one(&ws, &format!("ask-{index}"), *kind).await;
            let asks = ws.pending_asks(&seat);
            assert_eq!(asks.len(), 1, "one ask parked on {}", seat.display());
            assert_eq!(
                needs_you_kind(&asks[0]),
                *kind,
                "the parked ask names the kind {} draws for it",
                seat.display(),
            );
            assert_eq!(
                ws.pending_interaction(&seat),
                Some(*kind),
                "the needs-you kind for {}",
                seat.display(),
            );
            assert_eq!(
                ws.session_activity(&seat),
                L::Attention,
                "the lifecycle for {} is what every needs mark draws",
                seat.display(),
            );
            assert_eq!(
                ws.pending_interaction_depth(&seat),
                1,
                "the depth counts exactly the ask on {}",
                seat.display(),
            );
            assert_eq!(
                ws.pending_request_seq(&seat),
                1,
                "and the ask has its own identity on {}",
                seat.display(),
            );
        }

        // A seat holding nothing is the control: every assertion above reads
        // a parked ask, so a predicate that answered every seat would still
        // have to answer this one not at all.
        let quiet = SessionSlot::from_str_for_test("ask-quiet");
        let domain = ws.register_domain_session(quiet.clone(), None);
        domain.lock().turn_pending = true;
        assert_eq!(ws.pending_interaction(&quiet), None);
        assert_eq!(ws.pending_interaction_depth(&quiet), 0);
        assert_eq!(ws.session_activity(&quiet), L::Running);

        ws.close_terminal(&SessionSlot::lead("TestOrg", "guard"));
    }

    /// **The row names the strongest ask; the dock fronts its own queue.**
    /// The adjacencies pinned here are hand-off over question, hand-off over
    /// draft, and draft over settings write - one per run of the fixed order
    /// in [`Workspace::pending_interaction`]; the ends of each run stand for
    /// the rest. `pending_asks` still leads with the draft, because a card
    /// is what a person reads first.
    #[tokio::test]
    async fn the_row_names_the_strongest_ask_and_the_dock_fronts_the_draft() {
        let (ws, _rx) = Workspace::testing_stub();
        ws.seed_test_project("guard", "/tmp");

        let seat = SessionSlot::lead("TestOrg", "guard");
        let entry = ws.terminal_for(&seat).expect("a terminal");
        let (_id, _answer) = ws
            .register_terminal_hand_off(&seat, entry.id, "the sudo password")
            .expect("the terminal hand-off parks");
        ws.seed_test_pending_interaction(&seat, PendingInteractionKind::Question);
        assert_eq!(
            ws.pending_interaction(&seat),
            Some(PendingInteractionKind::TerminalHandOff),
            "the terminal hand-off outranks the question beside it",
        );

        let other = SessionSlot::from_str_for_test("precedence-other");
        ws.register_domain_session(other.clone(), None).lock().turn_pending = true;
        ws.note_client_attached();
        let (_id, _ending) = ws
            .register_document_hand_off(&other, "/proj/docs/plan.md", true)
            .expect("the document hand-off parks");
        ws.seed_test_pending_interaction(&other, PendingInteractionKind::SlackDraft);
        assert_eq!(
            ws.pending_interaction(&other),
            Some(PendingInteractionKind::DocumentHandOff),
            "the document hand-off outranks the Slack draft beside it",
        );
        assert!(
            matches!(
                ws.pending_asks(&other).first(),
                Some(crate::protocol::PendingAsk::SlackDraft(_))
            ),
            "the dock still fronts the draft",
        );

        let third = SessionSlot::from_str_for_test("precedence-third");
        ws.seed_test_pending_interaction(&third, PendingInteractionKind::SettingsWrite);
        ws.seed_test_pending_interaction(&third, PendingInteractionKind::SlackDraft);
        assert_eq!(
            ws.pending_interaction(&third),
            Some(PendingInteractionKind::SlackDraft),
            "the Slack draft outranks the settings write beside it",
        );

        ws.close_terminal(&seat);
    }

    /// **A second ask of the same kind is a second number.** The registries
    /// that park a draft, a settings write and a vault call each note the ask
    /// they hold, so a second one on the same seat is news to a client rather
    /// than reusing the first one's identity.
    #[test]
    fn every_registry_ask_gets_its_own_number() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("w-registry-numbers");
        let draft = |text: &str| forge_primitives::slack::SlackDraft {
            id: uuid::Uuid::new_v4(),
            workspace: "acme".to_owned(),
            conversation: "C1".to_owned(),
            conversation_label: "acme".to_owned(),
            thread_ts: None,
            text: text.to_owned(),
            operation: forge_primitives::slack::SlackDraftOperation::Post,
            thread: None,
            tagged: Vec::new(),
        };

        let (_id, _decision) = ws.register_slack_draft(&seat, draft("first"));
        assert_eq!(ws.pending_request_seq(&seat), 1, "the first draft is an ask");
        // A seat with no domain still holds a registry ask, and the kind
        // answers through the ledger's no-domain arm.
        assert_eq!(
            ws.pending_interaction(&seat),
            Some(PendingInteractionKind::SlackDraft),
            "the draft is the seat's needs-you kind with no domain at all",
        );
        let (_id, _decision) = ws.register_slack_draft(&seat, draft("second"));
        assert_eq!(ws.pending_request_seq(&seat), 2, "a second draft is a second ask");

        let (_id, _answer, _) = ws.register_settings_write(
            &seat,
            forge_primitives::settings::SettingsWriteAsk {
                id: uuid::Uuid::new_v4(),
                edits: vec![forge_primitives::settings::SettingsWriteChange {
                    key: "sessions.heal_attempts".to_owned(),
                    current: serde_json::json!(2),
                    proposed: serde_json::json!(4),
                    unset: false,
                }],
            },
        );
        assert_eq!(ws.pending_request_seq(&seat), 3, "a settings write is an ask");
        let (_id, _answer, _) = ws.register_vault_ask(
            &seat,
            forge_primitives::vault::VaultDraft::new(
                forge_primitives::vault::VaultTool::Search,
                "search for 'bank'",
            ),
            false,
        );
        assert_eq!(ws.pending_request_seq(&seat), 4, "a vault call is an ask");
        assert_eq!(
            ws.pending_interaction_depth(&seat),
            4,
            "and the depth sums all four rather than any one of them",
        );
    }

    /// **The sequence is the ask's identity, and a read never moves it.**
    /// Two asks on one seat are two numbers; reading the roster is not an
    /// ask, so a client can tell the first from the second without seeing
    /// the depth move and be fooled by an answer that shrinks the batch.
    #[test]
    fn every_ask_gets_its_own_number() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("w-numbered");
        assert_eq!(ws.pending_request_seq(&seat), 0, "a seat nothing asked is zero");

        ws.note_ask(&seat);
        assert_eq!(ws.pending_request_seq(&seat), 1);
        ws.note_ask(&seat);
        assert_eq!(ws.pending_request_seq(&seat), 2, "a second ask is a second number");
        assert_eq!(
            ws.pending_request_seq(&SessionSlot::from_str_for_test("w-quiet")),
            0,
            "another seat's asks are not this seat's",
        );
    }

    /// **A parked browser hand-off is in the READ as well as on the stream**:
    /// a view that attached after it landed has nothing else to draw the dock
    /// from, and the dock is the only place its answer can come from.
    #[tokio::test]
    async fn a_parked_hand_off_is_in_the_pending_asks_read() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("caller-uuid");
        let (calls, _heard) = tokio::sync::mpsc::unbounded_channel();
        ws.install_browser_host(std::sync::Arc::new(crate::browser::testing::StubHost { calls }));
        let (id, _answer) =
            ws.register_browser_hand_off(&key, "solve the CAPTCHA", "T2").await.expect("parks");

        assert!(
            ws.pending_asks(&key)
                .iter()
                .any(|ask| matches!(ask, crate::protocol::PendingAsk::BrowserHandOff(held)
                    if held.id == id)),
            "the hand-off is in the read a late view makes",
        );
        let other = SessionSlot::from_str_for_test("other-uuid");
        assert!(
            !ws.pending_asks(&other)
                .iter()
                .any(|ask| matches!(ask, crate::protocol::PendingAsk::BrowserHandOff(_))),
            "and another seat's read does not carry it",
        );
    }

    /// What a view that attached after the prompt landed reads: the requests
    /// the core kept beside the answer's oneshots, which is the only place
    /// they survive a stream that carries each once.
    ///
    /// **The list in arrival order**, because a parallel batch parks several
    /// at once and the read is all a mid-batch attach has - and the dock
    /// draws the front, which is the oldest, so the order is the read's own
    /// contract and not a reader's choice.
    #[test]
    fn pending_asks_reads_the_requests_the_core_kept_in_order() {
        let (ws, _rx) = Workspace::testing_stub();
        let held = |name: &str, slots: Vec<PendingInteractionSlot>| {
            let key = SessionSlot::from_str_for_test(name);
            let domain = ws.register_domain_session(key.clone(), None);
            {
                let mut guard = domain.lock();
                for (index, slot) in slots.into_iter().enumerate() {
                    guard.pending_interactions.insert(format!("{name}-{index}"), slot);
                }
            }
            key
        };
        let permission = || {
            let (tx, _rx) = tokio::sync::oneshot::channel();
            testing::test_permission(tx)
        };
        let question = || {
            let (tx, _rx) = tokio::sync::oneshot::channel();
            testing::test_question(tx)
        };

        assert!(
            ws.pending_asks(&SessionSlot::from_str_for_test("a-none")).is_empty(),
            "a slot holding nothing kept nothing to read back",
        );

        let prompted = held("a-permission", vec![permission()]);
        let asks = ws.pending_asks(&prompted);
        assert_eq!(asks.len(), 1, "a held permission prompt reads back");
        assert!(
            matches!(asks[0], crate::protocol::PendingAsk::Permission(_)),
            "and reads back as the kind it is",
        );
        assert_eq!(
            asks[0].tool_id(),
            Some(testing::TEST_TOOL_ID),
            "naming the call an answer addresses"
        );

        let asked = held("a-question", vec![question()]);
        assert!(
            matches!(ws.pending_asks(&asked)[0], crate::protocol::PendingAsk::Question(_)),
            "a held question reads back as the kind it is",
        );

        // A parallel batch, in the order the requests parked: the read hands
        // both back with the permission prompt leading, because it parked
        // first - the view's own queue rule.
        let both = held("a-both", vec![permission(), question()]);
        let asks = ws.pending_asks(&both);
        assert_eq!(asks.len(), 2, "both asks of a parallel batch read back");
        assert!(
            matches!(asks[0], crate::protocol::PendingAsk::Permission(_))
                && matches!(asks[1], crate::protocol::PendingAsk::Question(_)),
            "oldest first, which is the front a dock draws",
        );

        // A repeated call id replaces in place rather than parking twice: the
        // set is keyed by the call an answer addresses.
        let repeated = SessionSlot::from_str_for_test("a-repeat");
        let domain = ws.register_domain_session(repeated.clone(), None);
        {
            let mut guard = domain.lock();
            guard.pending_interactions.insert("a-call".to_owned(), permission());
            guard.pending_interactions.insert("a-call".to_owned(), question());
        }
        let asks = ws.pending_asks(&repeated);
        assert_eq!(asks.len(), 1, "a repeated call id does not park twice");
        assert!(
            matches!(asks[0], crate::protocol::PendingAsk::Question(_)),
            "and the newer slot is the one held",
        );
    }

    /// The statuspage answer is the same for every viewer, and it has to
    /// outlive any one of them: the probe lives in the core, so a client
    /// that attaches later still sees a service status at all. The answer
    /// is held as well as announced, so a view that attached after the one
    /// update that carried it can still read it.
    #[tokio::test]
    async fn the_service_status_is_held_and_announced() {
        use forge_primitives::cloud::service_status::{ServiceIssue, ServiceSeverity};

        let (ws, mut rx) = Workspace::testing_stub();
        let found = ServiceIssue {
            severity: ServiceSeverity::Warning,
            message: "Claude Code status: degraded.".to_owned(),
        };
        let prober: ServiceStatusProber = {
            let found = found.clone();
            Box::new(move || {
                let found = found.clone();
                Box::pin(async move { Some(found) })
            })
        };

        assert!(ws.service_status().is_none(), "nothing has been probed yet");

        run_service_status_probe(
            std::sync::Arc::clone(&ws.service_status),
            ws.update_tx().clone(),
            prober,
        )
        .await;

        assert_eq!(
            ws.service_status(),
            Some(found),
            "the answer the probe found is the answer the read hands back",
        );
        assert!(
            matches!(
                rx.try_recv(),
                Ok(frame) if matches!(&*frame.update, SessionUpdate::ServiceStatus { .. })
            ),
            "and the one update that carried it still goes out",
        );
    }

    /// A seat can be held on a Slack draft, which the registry parks on a
    /// reply exactly the way a permission or a question is parked - the
    /// same shape, the same awaited answer, a different kind.
    ///
    /// The record had no room for it, so a view that attached after the
    /// draft landed could not read that one was waiting: a record named
    /// for a category has to carry every member of it, or the name says
    /// it is complete when it is not. A draft leads the list, which is the
    /// precedence the read has always given it - it is held in its own
    /// registry rather than in the session's pending set.
    #[test]
    fn a_parked_slack_draft_reads_back_as_the_third_kind() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("a-draft");
        let draft = forge_primitives::slack::SlackDraft {
            id: uuid::Uuid::new_v4(),
            workspace: "acme".to_owned(),
            conversation: "C1".to_owned(),
            conversation_label: "acme".to_owned(),
            thread_ts: None,
            text: "hello".to_owned(),
            operation: forge_primitives::slack::SlackDraftOperation::Post,
            thread: None,
            tagged: Vec::new(),
        };
        let (_id, _decision) = ws.register_slack_draft(&seat, draft);

        let asks = ws.pending_asks(&seat);
        assert_eq!(asks.len(), 1, "a parked draft reads back");
        assert!(
            matches!(asks[0], crate::protocol::PendingAsk::SlackDraft(_)),
            "and reads back as the kind it is",
        );
        assert!(
            asks[0].tool_id().is_none(),
            "a draft is answered by its own id, so it names no tool call",
        );
        assert!(
            ws.pending_asks(&SessionSlot::from_str_for_test("a-bystander")).is_empty(),
            "and a seat holding nothing is not handed another seat's draft",
        );

        // The draft leads a question parked beside it, which is what the
        // single read did before the list existed.
        let domain = ws.register_domain_session(seat.clone(), None);
        let (tx, _rx) = tokio::sync::oneshot::channel();
        domain.lock().pending_interactions.insert("a-call".to_owned(), testing::test_question(tx));
        assert!(
            matches!(ws.pending_asks(&seat)[0], crate::protocol::PendingAsk::SlackDraft(_)),
            "a draft answers first, ahead of the question waiting behind it",
        );
    }

    /// Background work is a fact about the session rather than about who
    /// is looking, so the read is slot-shaped and answers from the slot's
    /// own domain: a lead has background work too.
    #[test]
    fn background_work_is_read_from_the_slots_own_domain() {
        let (ws, _rx) = Workspace::testing_stub();
        let absent = SessionSlot::from_str_for_test("bg-absent");
        assert!(
            !ws.has_background_work(&absent),
            "a slot with no domain session has no live background work",
        );

        let live = SessionSlot::from_str_for_test("bg-live");
        let domain = ws.register_domain_session(live.clone(), None);
        assert!(!ws.has_background_work(&live), "a fresh domain has none");

        domain.lock().background_work = true;
        assert!(ws.has_background_work(&live), "the read answers the slot's own registry");
        assert!(
            !ws.has_background_work(&absent),
            "one slot's background work must not answer for another",
        );
    }

    /// The whole point of the field: a worker that finished its turn is
    /// still `WorkerLiveness::Running`, so a lead polling `agents__list`
    /// used to have no way to tell it from one mid-turn.
    #[test]
    fn connected_worker_with_no_turn_in_flight_reports_idle() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-idle");
        ws.register_domain_session(key.clone(), None);
        let worker = entry("w-idle", WorkerLiveness::Running);

        assert_eq!(
            ws.worker_activity(&worker),
            L::Idle,
            "liveness Running with no turn in flight is idle, not working",
        );
    }

    /// **A turn that opens with the model's own output reads in flight.**
    ///
    /// The wire header went idle while a worker was demonstrably working:
    /// `turn_pending` is spent by the previous `Result` and
    /// `session_state_changed` no longer arrives, so thinking and prose left
    /// it false for 41 seconds (measured on the seat, 2026-10-09) while the
    /// terminal showed the turn running. The model's own frames are the proof
    /// a view reads; this is that reading on the wire's side.
    #[test]
    fn a_turn_opening_with_the_models_own_output_reads_in_flight() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-opening");
        let domain = ws.register_domain_session(key, None);
        let mut guard = domain.lock();

        // The previous turn's Result has landed, which is the state the header
        // was stuck in: the routed-prompt stamp is spent and nothing else has
        // said a turn is open.
        guard.turn_pending = false;
        assert!(!guard.turn_in_flight(), "precondition: nothing yet says a turn is open");

        guard.note_liveness(crate::domain_session::TurnLiveness::Working);
        assert!(guard.turn_in_flight(), "the model is producing output, so a turn is open");
    }

    /// **The mapping itself, not just the setter.**
    ///
    /// The two tests above drive `note_liveness` directly, so they pin the
    /// predicate and stop short of the fold that feeds it: deleting the
    /// `ThinkingTokens` arm here leaves them both green while a turn that
    /// opens with thinking regresses to the 41-second idle window the mirror
    /// exists to close. This is the arm, so it is the one pinned.
    #[test]
    fn a_frame_that_proves_a_turn_maps_to_working() {
        let counter = 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_eq!(
            crate::domain_session::liveness_of(&counter),
            Some(crate::domain_session::TurnLiveness::Working),
            "the model's own output opens a turn",
        );

        // A report ABOUT the turn is not a liveness signal, and
        // `session_state_changed` is the subtype to pin: it is the one the fold
        // already parses, so an arm reading it as "running" would otherwise
        // survive every test there is.
        let report = forge_primitives::Message::System {
            subtype: "session_state_changed".to_owned(),
            session_id: None,
            data: serde_json::Value::Null,
        };
        assert_eq!(
            crate::domain_session::liveness_of(&report),
            None,
            "a system report is not a liveness signal",
        );
    }

    /// The same mirror closes: a `Result` ends the turn the frames opened.
    #[test]
    fn a_result_closes_the_turn_the_frames_opened() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-closing");
        let domain = ws.register_domain_session(key, None);
        let mut guard = domain.lock();

        guard.note_liveness(crate::domain_session::TurnLiveness::Working);
        assert!(guard.turn_in_flight(), "precondition: the frames opened a turn");

        guard.note_liveness(crate::domain_session::TurnLiveness::Ended);
        assert!(!guard.turn_in_flight(), "the Result ended it");
    }

    /// Every state the derivation can land on, including the precedence
    /// that matters: a pending interaction outranks the in-flight turn it
    /// is blocking, otherwise the deadlock stays invisible.
    #[test]
    fn worker_activity_covers_every_derived_state() {
        let (ws, _rx) = Workspace::testing_stub();

        let with_domain = |name: &str, f: &dyn Fn(&mut DomainSession)| {
            let key = SessionSlot::from_str_for_test(name);
            let domain = ws.register_domain_session(key, None);
            f(&mut domain.lock());
            ws.worker_activity(&entry(name, WorkerLiveness::Running))
        };

        assert_eq!(
            with_domain("w-pending", &|d| d.turn_pending = true),
            L::Running,
            "turn_pending is the synchronous turn-start marker",
        );
        assert_eq!(
            with_domain("w-wire-running", &|d| {
                d.runtime_state = Some(forge_primitives::RuntimeSessionState::Running);
            }),
            L::Running,
            "the wire-confirmed Running state counts even before turn_pending",
        );
        // Unreachable today rather than merely untested: nothing in the
        // tree emits `requires_action`, and `session_state_changed`
        // itself is in no wire-conformance baseline. Pinned so the
        // mapping is already right if the CLI ever sends it.
        assert_eq!(
            with_domain("w-wire-action", &|d| {
                d.runtime_state = Some(forge_primitives::RuntimeSessionState::RequiresAction);
            }),
            L::Attention,
            "RequiresAction is the CLI asking for a human, not a turn making progress",
        );
        assert_eq!(
            with_domain("w-blocked", &|d| {
                d.turn_pending = true;
                let (tx, _rx) = tokio::sync::oneshot::channel();
                d.pending_interactions.insert("tool-1".to_owned(), testing::test_permission(tx));
            }),
            L::Attention,
            "a pending interaction outranks the turn it is blocking",
        );

        // No DomainSession at all: the subprocess is gone even though the
        // registry still lists the worker.
        assert_eq!(ws.worker_activity(&entry("w-gone", WorkerLiveness::Running)), L::Sleeping);

        // Liveness that already answers the question passes straight
        // through - neither has a connected session to interrogate.
        assert_eq!(ws.worker_activity(&entry("w-spawning", WorkerLiveness::Spawning)), L::Spawning);
        assert_eq!(ws.worker_activity(&entry("w-failed", WorkerLiveness::Failed)), L::Failed);
    }

    /// Contract, not a reproduction: `Attention` is only ever truthful
    /// while a turn is in flight, so a held slot without one reads
    /// `Idle`. No production route is known to reach this state - it
    /// pins the invariant, so a slot that outlives its turn can never
    /// pin a worker at `Attention` for the life of the session.
    #[test]
    fn stranded_interaction_slot_on_an_idle_session_reports_idle() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-stranded");
        let domain = ws.register_domain_session(key, None);
        {
            let mut guard = domain.lock();
            // A held slot with no turn: the shape the invariant forbids.
            guard.turn_pending = false;
            let (tx, _rx) = tokio::sync::oneshot::channel();
            guard
                .pending_interactions
                .insert("tool-stranded".to_owned(), testing::test_permission(tx));
        }

        assert_eq!(
            ws.worker_activity(&entry("w-stranded", WorkerLiveness::Running)),
            L::Idle,
            "a held slot with no turn in flight is incoherent state, not a worker awaiting input",
        );
    }

    /// A parked Slack draft is a pending interaction like any other: the
    /// seat is waiting on a person, so the lifecycle has to say
    /// `Attention` - or every view that draws its needs mark from the
    /// lifecycle (the client's) stays quiet while the dock sits
    /// unanswered. The draft lives in the workspace's own registry rather
    /// than the session's pending set, which is exactly why this arm needs
    /// the read of its own.
    #[tokio::test]
    async fn a_parked_slack_draft_reads_as_attention() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("w-draft");
        let domain = ws.register_domain_session(seat.clone(), None);
        domain.lock().turn_pending = true;
        assert_eq!(
            ws.session_activity(&seat),
            L::Running,
            "a turn advancing on its own is Running, which is the control",
        );

        let draft = forge_primitives::slack::SlackDraft {
            id: uuid::Uuid::new_v4(),
            workspace: "acme".to_owned(),
            conversation: "C1".to_owned(),
            conversation_label: "acme".to_owned(),
            thread_ts: None,
            text: "hello".to_owned(),
            operation: forge_primitives::slack::SlackDraftOperation::Post,
            thread: None,
            tagged: Vec::new(),
        };
        let (_id, _decision) = ws.register_slack_draft(&seat, draft);

        assert_eq!(
            ws.session_activity(&seat),
            L::Attention,
            "a held draft is a person's to answer, not a running turn's",
        );

        // A draft belongs to the seat that asked: another seat holding
        // nothing of its own stays Running.
        let bystander = SessionSlot::from_str_for_test("w-bystander");
        let other = ws.register_domain_session(bystander.clone(), None);
        other.lock().turn_pending = true;
        assert_eq!(
            ws.session_activity(&bystander),
            L::Running,
            "another seat's draft is not this seat's news",
        );
    }

    /// A parked browser hand-off is a pending interaction like any other:
    /// the seat waits on a person, so the lifecycle says `Attention` - every
    /// needs mark draws from this. Ved, live round 2026-10-07: the hand-off
    /// dock waited while the rail and the tabs stayed quiet. Same shape as
    /// the parked draft's arm, registry read and all.
    #[tokio::test]
    async fn a_parked_browser_hand_off_reads_as_attention() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("w-handoff");
        let domain = ws.register_domain_session(seat.clone(), None);
        domain.lock().turn_pending = true;
        assert_eq!(ws.session_activity(&seat), L::Running, "the control, as for the draft");

        let (calls, _heard) = tokio::sync::mpsc::unbounded_channel();
        ws.install_browser_host(std::sync::Arc::new(crate::browser::testing::StubHost { calls }));
        let (_id, _answer) =
            ws.register_browser_hand_off(&seat, "solve the CAPTCHA", "T2").await.expect("parks");

        assert_eq!(
            ws.session_activity(&seat),
            L::Attention,
            "a held hand-off is a person's to answer, not a running turn's",
        );
        assert_eq!(
            ws.pending_interaction(&seat),
            Some(crate::workspace::PendingInteractionKind::BrowserHandOff),
            "and the roster says what the seat is waiting on",
        );
        assert_eq!(ws.pending_interaction_depth(&seat), 1, "with the ask it holds");
        assert_eq!(ws.pending_request_seq(&seat), 1, "and the ask has its own identity");

        let bystander = SessionSlot::from_str_for_test("w-bystander2");
        let other = ws.register_domain_session(bystander.clone(), None);
        other.lock().turn_pending = true;
        assert_eq!(
            ws.session_activity(&bystander),
            L::Running,
            "another seat's hand-off is not this seat's news",
        );
    }

    /// **A parked document hand-off rides the same machinery every ask
    /// does.** It parks in its own registry, so without this read a seat
    /// holding one kept its running mark and the needs-you row said
    /// nothing - the silence #1758 and the browser hand-off both had.
    #[test]
    fn a_parked_document_hand_off_reads_as_attention() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("w-dochandoff");
        let domain = ws.register_domain_session(seat.clone(), None);
        domain.lock().turn_pending = true;
        assert_eq!(ws.session_activity(&seat), L::Running, "the control, mid-turn");
        assert_eq!(ws.pending_interaction(&seat), None, "and no ask is held yet");

        ws.note_client_attached();
        let (id, _ending) = ws
            .register_document_hand_off(&seat, "/proj/docs/plan.md", true)
            .expect("the park lands with a client attached");

        assert_eq!(
            ws.session_activity(&seat),
            L::Attention,
            "a held ask is a person's to answer, not a running turn's",
        );
        assert_eq!(
            ws.pending_interaction(&seat),
            Some(crate::PendingInteractionKind::DocumentHandOff),
            "and the row's needs-you names the kind",
        );
        assert_eq!(ws.pending_interaction_depth(&seat), 1, "the depth counts it");

        assert!(ws.resolve_document_hand_off(
            id,
            &seat,
            forge_primitives::document::DocumentHandOffEnding::Approve {
                review_id: None,
                note: None,
            },
        ));
        assert_eq!(ws.session_activity(&seat), L::Running, "answered, the turn runs again");
        assert_eq!(ws.pending_interaction(&seat), None, "and the row stands down");
    }

    /// **A parked vault call rides the same machinery every ask does.** It
    /// parks in its own registry, so without `has_vault_ask` a seat holding
    /// one kept its running mark and the needs-you row said nothing.
    #[test]
    fn a_parked_vault_ask_reads_as_attention() {
        let (ws, _rx) = Workspace::testing_stub();
        let seat = SessionSlot::from_str_for_test("w-vaultask");
        let domain = ws.register_domain_session(seat.clone(), None);
        domain.lock().turn_pending = true;
        assert_eq!(ws.session_activity(&seat), L::Running, "the control, mid-turn");

        ws.note_client_attached();
        let draft = forge_primitives::vault::VaultDraft::new(
            forge_primitives::vault::VaultTool::Search,
            "search for 'bank'",
        );
        let (id, _held, _) = ws.register_vault_ask(&seat, draft, false);
        assert_eq!(
            ws.session_activity(&seat),
            L::Attention,
            "a held vault call is a person's to answer, not a running turn's",
        );

        assert!(ws.resolve_vault_ask(
            id,
            &seat,
            forge_primitives::vault::VaultAskAnswer {
                decision: forge_primitives::vault::VaultAskDecision::Decline,
                master_password: None,
                two_factor: None,
                released: None,
            },
        ));
        assert!(ws.settle_vault_ask(id, &seat, forge_primitives::vault::VaultAskEnding::Declined,));
        assert_eq!(ws.session_activity(&seat), L::Running, "answered, the turn runs again");
    }

    /// `activity` is populated by the `agents__list` read path only; the
    /// `WorkerStatusChanged` event path leaves it `None`.
    #[test]
    fn event_path_leaves_activity_none() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = SessionSlot::from_str_for_test("w-both");
        ws.register_domain_session(key.clone(), None);
        let worker = entry("w-both", WorkerLiveness::Running);

        assert_eq!(worker.to_status().activity, None, "the event path derives no activity");
        assert_eq!(
            ws.worker_status_snapshot(&worker).activity,
            Some(L::Idle),
            "the read path always derives one",
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod release_session_cascade_tests {
    use super::*;
    use crate::mcp::workers::types::WorkerEntry;
    use forge_primitives::WorkerLiveness;
    use std::fs;
    use std::time::SystemTime;
    use tempfile::tempdir;

    /// The `forge` project's lead slot, the slot the fixtures in this
    /// module release to trigger the cascade.
    fn lead_slot() -> SessionSlot {
        SessionSlot::lead("Default", "forge")
    }

    fn fake_entry(label: &str) -> WorkerEntry {
        WorkerEntry {
            label: label.into(),
            charter: "test charter".into(),
            slot: SessionSlot::worker("Default", "forge", label),
            session_id: None,
            status: WorkerLiveness::Running,
            spawned_at: SystemTime::UNIX_EPOCH,
            spawned_by: lead_slot(),
            needs_tag: false,
            is_git_repo_at_spawn: false,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    fn make_workspace_dir() -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// `release_session_with_cascade` cascades worker termination when
    /// the released session is a project's lead: its slot carries the
    /// lead label and names a declared project. Workers' JSONLs persist
    /// on disk (we don't delete them); only the in-memory live_workers
    /// entries + the running session subprocesses are torn down.
    #[tokio::test]
    async fn release_session_on_lead_cascades_workers() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut rx = workspace.subscribe_answerer();
        let (calls, mut heard) = tokio::sync::mpsc::unbounded_channel();
        workspace
            .install_browser_host(std::sync::Arc::new(crate::browser::testing::StubHost { calls }));

        let project = workspace.list_projects().into_iter().next().expect("forge project");
        let project_key = project.key.clone();
        let lead_key = lead_slot();

        // Insert two workers under the project.
        workspace.insert_live_worker(&project_key, fake_entry("r1"));
        workspace.insert_live_worker(&project_key, fake_entry("r2"));
        assert_eq!(workspace.list_live_workers(&project_key).len(), 2);

        // Release the lead. Cascade fires before the lead release
        // itself; workers' live_workers entries are gone afterward.
        workspace.release_session_with_cascade(&lead_key);
        assert!(
            workspace.list_live_workers(&project_key).is_empty(),
            "workers must be cascade-closed"
        );
        // **Every closed seat is ended and takes its tabs with it**, the
        // cascaded workers' included: the fleet hears the session-ended fact
        // for the lead and each worker, and a replacement for each. **The
        // order is part of the contract**: a seat's end is told before its
        // replacement is asked for.
        let mut calls: Vec<(String, serde_json::Value)> = Vec::new();
        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);
        while tokio::time::Instant::now() < deadline {
            let left = deadline.saturating_duration_since(tokio::time::Instant::now());
            let Ok(Some((what, args))) = tokio::time::timeout(left, heard.recv()).await else {
                break;
            };
            match what.as_str() {
                "replace_seat" | "session_ended" => calls.push((what, args)),
                other => panic!("unexpected fleet call {other}"),
            }
            let count = |name: &str| calls.iter().filter(|(what, _)| what == name).count();
            if count("replace_seat") >= 3 && count("session_ended") >= 3 {
                break;
            }
        }
        let named = |name: &str| -> Vec<serde_json::Value> {
            calls.iter().filter(|(what, _)| what == name).map(|(_, args)| args.clone()).collect()
        };
        let replaced = named("replace_seat");
        let ended = named("session_ended");
        assert_eq!(replaced.len(), 3, "every closed seat is replaced: {replaced:?}");
        assert_eq!(ended.len(), 3, "and every one is ended: {ended:?}");
        assert!(
            replaced.contains(&serde_json::json!(lead_key)),
            "the lead's seat is replaced: {replaced:?}",
        );
        assert!(
            ended.contains(&serde_json::json!(lead_key)),
            "the lead's end is told, not inferred: {ended:?}",
        );
        for (at, (what, seat)) in calls.iter().enumerate() {
            if what != "session_ended" {
                continue;
            }
            let replaced_at =
                calls.iter().position(|(other, args)| other == "replace_seat" && args == seat);
            assert!(
                replaced_at.is_some_and(|replaced_at| replaced_at > at),
                "seat {seat} is ended before its replacement is asked for",
            );
        }

        // Drain the channel and confirm we saw a Removed
        // WorkerStatusChanged for each worker.
        let mut removed_count = 0;
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::WorkerStatusChanged { action, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && action == crate::protocol::WorkerStatusAction::Removed
            {
                removed_count += 1;
            }
        }
        assert_eq!(removed_count, 2, "two Removed events fire for the two workers");
    }

    /// **The release is announced before anything is torn down** (#1930).
    /// A viewer marks the seat from this frame, so it has to be out ahead of
    /// the cascade: announced after, a lead's row would keep reading as
    /// working for exactly the seconds the teardown takes - and a close made
    /// from another view has no other frame at all.
    #[tokio::test]
    async fn a_release_is_announced_before_the_cascade_runs() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut rx = workspace.subscribe_answerer();

        let project = workspace.list_projects().into_iter().next().expect("forge project");
        let project_key = project.key.clone();
        let lead_key = lead_slot();
        workspace.insert_live_worker(&project_key, fake_entry("r1"));

        workspace.release_session_with_cascade(&lead_key);

        let announced: Vec<SessionUpdate> = std::iter::from_fn(|| rx.try_recv().ok())
            .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
            .collect();
        let first = announced.first().expect("the release announces something");
        assert!(
            matches!(first, SessionUpdate::Releasing { key } if key == &lead_key),
            "the lead's release is the first thing announced: {first:?}",
        );
        assert!(
            announced.iter().any(|update| matches!(
                update,
                SessionUpdate::WorkerStatusChanged { action, .. }
                    if *action == crate::protocol::WorkerStatusAction::Removed
            )),
            "and the cascade's own removal follows it: {announced:?}",
        );
    }

    /// `release_session_with_cascade` on a non-lead (or unknown) session
    /// is a plain release with NO cascade. Confirms the cascade is gated on
    /// "session is a lead of some project."
    #[tokio::test]
    async fn release_session_on_non_lead_does_not_cascade() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));

        let project_key = workspace.list_projects().into_iter().next().expect("forge").key;
        workspace.insert_live_worker(&project_key, fake_entry("r1"));

        // A worker of the very project the lead slot above names: it
        // resolves, so only the label keeps the cascade off.
        let unknown = SessionSlot::worker("Default", "forge", "r1");
        workspace.release_session_with_cascade(&unknown);
        assert_eq!(
            workspace.list_live_workers(&project_key).len(),
            1,
            "non-lead release must not cascade"
        );
    }

    /// The cascade is gated on the slot's own label, not on where the
    /// session sits in the catalog. A worker whose Connected landed it
    /// at `catalog[0]` is still a worker, so closing it must not drain
    /// its peers; the lead's slot, released with the same catalog order,
    /// still cascades.
    #[tokio::test]
    async fn release_session_cascades_when_worker_sits_at_catalog_head() {
        let dir = make_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));

        let project = workspace.list_projects().into_iter().next().expect("forge project");
        let project_key = project.key.clone();
        let project_path = project.path.to_string_lossy().into_owned();

        // Seed the lead FIRST, then the worker. record_connected_session
        // inserts at index 0, so after both calls catalog[0] is the
        // worker and catalog[1] is the lead.
        let lead_key = lead_slot();
        let worker_key = SessionSlot::worker("Default", "forge", "reviewer");
        workspace.record_connected_session(&project_path, &lead_key.display(), None);
        workspace.record_connected_session(&project_path, &worker_key.display(), None);
        workspace.insert_live_worker(&project_key, fake_entry("reviewer"));

        // Sanity: catalog head is the worker, not the lead.
        let projects_now = workspace.list_projects();
        let first_session = &projects_now[0].sessions[0].session;
        assert_eq!(
            first_session.as_str(),
            worker_key.display(),
            "catalog[0] must be the worker for the discrimination to bite"
        );

        // Closing the WORKER: its slot carries the worker's label, so
        // nothing reads it as its lead however the registry is ordered.
        workspace.release_session_with_cascade(&worker_key);
        assert_eq!(
            workspace.list_live_workers(&project_key).len(),
            1,
            "a worker's slot is never mistaken for its lead, whatever the catalog order"
        );

        // Release the LEAD, with the catalog still ordering the worker
        // first: the label is what cascades.
        workspace.release_session_with_cascade(&lead_key);

        assert!(
            workspace.list_live_workers(&project_key).is_empty(),
            "lead release must cascade even when a worker sits at catalog[0]"
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod tag_retry_tests {
    use super::*;
    use std::fs;
    use tempfile::tempdir;

    /// Build the on-disk `<config_dir>/projects/<sanitized_cwd>/`
    /// directory `tag_session` expects and return the path the JSONL
    /// would land at. Caller decides when to actually create the file.
    fn jsonl_path_for(
        config_dir: &std::path::Path,
        cwd: &std::path::Path,
        session_id: &str,
    ) -> std::path::PathBuf {
        let sanitized = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &cwd.to_string_lossy(),
        ));
        let project_dir = forge_sdk::projects_dir_for(config_dir).join(&sanitized);
        fs::create_dir_all(&project_dir).expect("project dir");
        project_dir.join(format!("{session_id}.jsonl"))
    }

    /// Init a repo at `root` and add the worker's worktree at
    /// `<root>/.claude/worktrees/<label>`, so the connected-time worktree
    /// check reads a tree git can reuse. The caller names the worktree path
    /// itself, as the spawn does.
    fn init_worker_worktree(root: &std::path::Path, label: &str) {
        let git = |args: &[&str]| {
            let status = std::process::Command::new("git")
                .args(args)
                .current_dir(root)
                .status()
                .expect("spawn git");
            assert!(status.success(), "git {args:?} failed in {root:?}");
        };
        git(&["init", "-q"]);
        git(&["config", "user.email", "t@example.com"]);
        git(&["config", "user.name", "Test"]);
        git(&["config", "commit.gpgsign", "false"]);
        fs::write(root.join("README.md"), "seed").expect("write seed");
        git(&["add", "."]);
        git(&["commit", "-q", "-m", "init"]);
        let worktree = root.join(".claude").join("worktrees").join(label);
        fs::create_dir_all(worktree.parent().expect("worktrees dir")).expect("mkdir worktrees");
        let branch = format!("worktree-{label}");
        let path = worktree.to_string_lossy().into_owned();
        git(&["worktree", "add", "-q", "-b", &branch, &path]);
    }

    /// JSONL exists from the start: tag_session_with_retry succeeds on
    /// the first attempt and appends a tag row.
    #[tokio::test]
    async fn succeeds_immediately_when_jsonl_exists() {
        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let session_id = "550e8400-e29b-41d4-a716-446655440001";
        let path = jsonl_path_for(cfg.path(), cwd.path(), session_id);
        fs::write(&path, "").expect("seed jsonl");

        let result = tag_session_with_retry(
            cfg.path(),
            session_id,
            "forge:worker:smoke",
            "Default/forge",
            &cwd.path().to_string_lossy(),
            5,
            Duration::from_millis(10),
        )
        .await;
        assert!(result.is_ok(), "tag should succeed: {result:?}");
        let body = fs::read_to_string(&path).expect("read");
        assert!(body.contains("\"tag\":\"forge:worker:smoke\""), "tag row appended: {body:?}");
    }

    /// JSONL appears after a few attempts: retry loop wins. Spawns the
    /// retry, sleeps long enough for it to hit `NotFound` once or twice,
    /// then creates the file and observes a successful tag.
    #[tokio::test]
    async fn retries_until_jsonl_appears() {
        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let session_id = "550e8400-e29b-41d4-a716-446655440002";
        let path = jsonl_path_for(cfg.path(), cwd.path(), session_id);
        // File doesn't exist yet; create it after a brief delay.
        let path_clone = path.clone();
        tokio::spawn(async move {
            tokio::time::sleep(Duration::from_millis(120)).await;
            fs::write(&path_clone, "").expect("create jsonl");
        });

        let result = tag_session_with_retry(
            cfg.path(),
            session_id,
            "forge:worker:smoke",
            "Default/forge",
            &cwd.path().to_string_lossy(),
            30,
            Duration::from_millis(50),
        )
        .await;
        assert!(result.is_ok(), "retry should win: {result:?}");
        let body = fs::read_to_string(&path).expect("read");
        assert!(body.contains("\"tag\":\"forge:worker:smoke\""), "tag row appended: {body:?}");
    }

    /// JSONL never appears: retry exhausts and surfaces NotFound.
    #[tokio::test]
    async fn gives_up_after_max_attempts() {
        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let session_id = "550e8400-e29b-41d4-a716-446655440003";
        let _path = jsonl_path_for(cfg.path(), cwd.path(), session_id);
        // Don't create the JSONL.

        let result = tag_session_with_retry(
            cfg.path(),
            session_id,
            "forge:worker:smoke",
            "Default/forge",
            &cwd.path().to_string_lossy(),
            3,
            Duration::from_millis(10),
        )
        .await;
        match result {
            Err(forge_sdk::Error::Io(io_err)) => {
                assert_eq!(io_err.kind(), std::io::ErrorKind::NotFound);
            }
            other => panic!("expected Io(NotFound), got {other:?}"),
        }
    }

    /// Invalid UUID is a non-NotFound error: must propagate immediately
    /// without retrying.
    #[tokio::test]
    async fn invalid_uuid_propagates_without_retry() {
        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let start = std::time::Instant::now();
        let result = tag_session_with_retry(
            cfg.path(),
            "not-a-valid-uuid",
            "forge:worker:smoke",
            "Default/forge",
            &cwd.path().to_string_lossy(),
            30,
            Duration::from_millis(500),
        )
        .await;
        let elapsed = start.elapsed();
        assert!(matches!(result, Err(forge_sdk::Error::MessageParse { .. })));
        // Should NOT have slept through 30 * 500ms = 15s of retries.
        assert!(
            elapsed < Duration::from_secs(1),
            "non-NotFound errors must skip retry: {elapsed:?}"
        );
    }

    /// A `Spawning` worker entry keyed by the slot its spawn names -
    /// the triple the tag path looks the entry up by. The slot does not
    /// move across `/new`, so a re-keyed worker keeps the one it was
    /// spawned under.
    fn fake_spawning_entry(
        label: &str,
        session_key: &SessionSlot,
        needs_tag: bool,
    ) -> crate::mcp::workers::types::WorkerEntry {
        crate::mcp::workers::types::WorkerEntry {
            label: label.into(),
            charter: "test".into(),
            slot: session_key.clone(),
            session_id: None,
            status: forge_primitives::WorkerLiveness::Spawning,
            spawned_at: std::time::SystemTime::UNIX_EPOCH,
            spawned_by: SessionSlot::lead("TestOrg", "forge"),
            needs_tag,
            is_git_repo_at_spawn: false,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    /// `apply_worker_tag_or_rollback_with_config_dir`: when the JSONL
    /// never appears, the retry exhausts with NotFound, but the worker
    /// stays in `live_workers` (NO rollback), transitions to Running,
    /// and `needs_tag` remains true so the opportunistic retry on the
    /// first turn can try again. A single `StatusChanged` event fires.
    ///
    /// The durable row stays too, and it is the store that makes that
    /// assertion mean something: the worker is live and Running, so a
    /// delete reaching this arm would drop the only handle on a worker
    /// nothing has rolled back.
    #[tokio::test]
    async fn notfound_keeps_worker_with_needs_tag_flag() {
        let (workspace, mut rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/notfound-tag-keeps");
        let db_dir = 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 =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                "/tmp/notfound-tag-keeps",
            )));
        let session_id = "550e8400-e29b-41d4-a716-446655440010";
        let session_key = SessionSlot::worker("TestOrg", "forge", "idle");
        workspace.insert_live_worker(&project_key, fake_spawning_entry("idle", &session_key, true));
        workspace
            .record_worker_row(
                &project_key,
                "idle",
                session_id,
                "charter",
                Some("kick"),
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the row this arm must keep");

        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        // Do NOT create the JSONL: tag_session will see NotFound every
        // attempt and the retry will exhaust.
        let _path = jsonl_path_for(cfg.path(), cwd.path(), session_id);

        // A tight retry budget keeps the detached task fast without
        // bypassing the wrapper: this test verifies the wrapper's
        // classification + transition logic, so it must go through the
        // spawn the production path uses.
        let retry_budget =
            WorkerTagRetryBudget { max_attempts: 3, delay: Duration::from_millis(10) };
        workspace.apply_worker_tag_or_rollback_with_budget(
            &session_key,
            session_id,
            &project_key,
            "idle",
            cwd.path(),
            WorkerTagFacts { needs_tag: true, minted_row: true },
            cfg.path(),
            retry_budget,
        );

        // The detached task sleeps once per attempt - after the last one
        // too - before it can classify the exhaustion, so the wait
        // derives from the budget handed to it above plus a stall
        // allowance a loaded machine cannot eat.
        let task_budget = retry_budget.delay * retry_budget.max_attempts;
        let status_changed =
            tokio::time::timeout(task_budget * 10 + Duration::from_secs(5), async {
                loop {
                    match rx.recv().await.map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                    {
                        Some(SessionUpdate::WorkerStatusChanged { action, status, .. }) => {
                            if matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                            {
                                return Some(status);
                            }
                            if matches!(action, crate::protocol::WorkerStatusAction::Removed) {
                                return None;
                            }
                        }
                        Some(_) => {}
                        None => return None,
                    }
                }
            })
            .await
            .expect("timed out waiting for StatusChanged");

        let status = status_changed.expect("expected StatusChanged, not Removed (rollback)");
        assert_eq!(status.label, "idle");
        assert!(matches!(status.status, forge_primitives::WorkerLiveness::Running));

        // Worker entry should remain in live_workers with needs_tag=true.
        let entries = workspace.list_live_workers(&project_key);
        assert_eq!(entries.len(), 1, "worker must NOT have been rolled back");
        assert_eq!(entries[0].label, "idle");
        assert!(entries[0].needs_tag, "needs_tag stays true so opportunistic retry can fire");
        assert!(matches!(entries[0].status, forge_primitives::WorkerLiveness::Running));
        assert!(
            !workspace.worker_rows_for_project(&project_key).is_empty(),
            "the durable row stays: nothing was rolled back, and the row is what re-spawns this \
             worker after a restart",
        );
    }

    /// Drive the connect-time worktree check for a worker whose session is
    /// pooled behind the row, and answer the row's status, its reason, and
    /// whether the pool, sender and domain were released with the failure.
    fn connect_worktree_check(
        cwd: &std::path::Path,
    ) -> (forge_primitives::WorkerLiveness, Option<String>, bool) {
        let (workspace, _updates) = Workspace::testing_stub();
        workspace.seed_test_project("proj-x", "/tmp/proj-x");
        let project_key = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some("/tmp/proj-x")),
        );
        let session_key = SessionSlot::worker("TestOrg", "proj-x", "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: None,
                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(cwd.to_path_buf()),
                diagnostic: None,
                kick: None,
            },
        );
        // The session the row is about, so the release the failure owes can
        // be seen: a Failed row must leave none behind.
        let (handle, _commands) = Workspace::testing_stub_handle();
        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 (cmd_tx, _cmd_rx) = tokio::sync::mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(session_key.clone(), cmd_tx);
        workspace.register_domain_session(session_key.clone(), Some(Arc::clone(&handle)));

        let failed = workspace.fail_worker_without_worktree(&session_key);
        assert!(failed, "the connect check refuses a git worker without a usable worktree");
        let entry = workspace
            .list_live_workers(&project_key)
            .into_iter()
            .find(|entry| entry.label == "builder")
            .expect("the entry stays as the visible failure");
        let released = !workspace.session_is_pooled(&session_key)
            && !workspace.command_senders.lock().contains_key(&session_key)
            && !workspace.domain_handles.lock().contains_key(&session_key);
        (entry.status, entry.diagnostic, released)
    }

    /// A worker whose worktree went missing between its creation and its
    /// first connect reads Failed with the reason, not Running, and the
    /// session behind it is released (#1593).
    #[test]
    fn a_worker_whose_worktree_is_gone_by_connect_reads_failed() {
        let cwd = tempdir().expect("cwd");
        let (status, diagnostic, released) = connect_worktree_check(cwd.path());

        assert_eq!(
            status,
            forge_primitives::WorkerLiveness::Failed,
            "a worker with no worktree must not read live",
        );
        let diagnostic = diagnostic.expect("the row carries the reason");
        assert!(
            diagnostic.contains("worktree") && diagnostic.contains("gone"),
            "the reason names what went missing: {diagnostic}",
        );
        assert!(released, "a Failed row leaves no pooled session behind");
    }

    /// The same check for a tree that is there but is not a git worktree git
    /// can reuse: the branch the tag-write also reads, and the reason says
    /// so rather than that the directory is gone (#1593).
    #[test]
    fn a_worker_whose_worktree_is_not_a_git_worktree_reads_failed() {
        let cwd = tempdir().expect("cwd");
        let worktree = cwd.path().join(".claude/worktrees/builder");
        fs::create_dir_all(&worktree).expect("the worktree dir stands");
        let (status, diagnostic, released) = connect_worktree_check(cwd.path());

        assert_eq!(status, forge_primitives::WorkerLiveness::Failed);
        let diagnostic = diagnostic.expect("the row carries the reason");
        assert!(
            diagnostic.contains("not a git worktree"),
            "the reason names the unusable tree: {diagnostic}",
        );
        assert!(released, "a Failed row leaves no pooled session behind");
    }

    /// **A failed worker stays in the persisted-row listing.** The agents
    /// surface draws its worker rows from these labels; a gone worktree
    /// fails the start probe, and dropping the row there would hide both
    /// the failure and its reason (#1593).
    #[test]
    fn a_failed_worker_with_a_gone_worktree_stays_in_the_listing() {
        let (workspace, _updates) = Workspace::testing_stub();
        let root = tempdir().expect("root");
        let path = root.path().to_string_lossy().into_owned();
        workspace.seed_test_project("proj-x", &path);
        let project_key = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&path)),
        );
        let db_dir = tempdir().expect("db tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        workspace
            .record_worker_row(
                &project_key,
                "builder",
                "builder-session",
                "charter",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
                None,
            )
            .expect("seed the worker's row");
        let session_key = SessionSlot::worker("TestOrg", "proj-x", "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,
            },
        );

        assert!(workspace.fail_worker_without_worktree(&session_key));
        assert!(
            workspace
                .worker_labels_by_project()
                .get(&project_key)
                .is_some_and(|labels| labels.iter().any(|label| label == "builder")),
            "the failed row stays listed, so its reason is drawable",
        );
    }

    /// Drive a non-NotFound tag failure over a seeded row and live worker,
    /// and return the row that survived it. `needs_tag` and `minted_row`
    /// are the two facts the rollback decides the row on; the malformed
    /// session id is the failure, since no amount of waiting puts a JSONL
    /// on disk that makes that write succeed.
    async fn non_notfound_rollback_leftover_row(
        needs_tag: bool,
        minted_row: bool,
    ) -> Option<crate::store::sessions::SessionRecord> {
        let (workspace, mut rx) = Workspace::testing_stub();
        workspace.seed_test_project("proj-x", "/tmp/proj-x");
        let db_dir = 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 = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some("/tmp/proj-x")),
        );
        let session_key = SessionSlot::worker("TestOrg", "proj-x", "crashed");
        workspace.insert_live_worker(
            &project_key,
            fake_spawning_entry("crashed", &session_key, needs_tag),
        );
        workspace
            .record_worker_row(
                &project_key,
                "crashed",
                "crashed-uuid",
                "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 cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        workspace.apply_worker_tag_or_rollback_with_config_dir(
            &session_key,
            "not-a-uuid",
            &project_key,
            "crashed",
            &cwd.path().to_string_lossy(),
            false,
            needs_tag,
            minted_row,
            cfg.path(),
        );

        loop {
            let frame = rx.recv().await.expect("the rollback emits an update");
            if let SessionUpdate::WorkerStatusChanged { action, status, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && action == crate::protocol::WorkerStatusAction::Removed
            {
                assert_eq!(status.label, "crashed", "the rolled-back worker is the one removed");
                break;
            }
        }
        assert!(
            workspace.list_live_workers(&project_key).is_empty(),
            "the rollback removes the live entry whatever becomes of the row",
        );

        let db = workspace.db.lock();
        crate::store::sessions::get(db.as_ref().expect("db"), "TestOrg", "proj-x", "crashed")
            .expect("read the row the rollback left")
    }

    /// The non-NotFound rollback discards a spawn that minted its own row,
    /// so the row goes with it: left behind, it is a row with no live
    /// worker - which `agents__despawn` cannot clear - and the next boot
    /// re-spawns the worker this arm just rolled back (#1142).
    #[tokio::test]
    async fn a_non_notfound_tag_failure_rolls_back_the_row_with_the_worker() {
        assert!(
            non_notfound_rollback_leftover_row(true, true).await.is_none(),
            "a spawn that wrote the row takes it with it",
        );
    }

    /// A resume and a boot re-spawn are handed a row that pre-existed and
    /// holds the worker's charter, kick and the id being resumed. Taking
    /// it away loses a worker that only failed to write a JSONL tag, and
    /// leaves nothing to resume it from.
    #[tokio::test]
    async fn a_non_notfound_tag_failure_keeps_a_row_this_spawn_did_not_mint() {
        assert_eq!(
            non_notfound_rollback_leftover_row(true, false).await.and_then(|row| row.charter),
            Some("charter".to_owned()),
            "a row this spawn did not write is not this spawn's to delete",
        );
    }

    /// The arm also fires on every `/new` re-tag, over a row whose worker
    /// has already been tagged on disk. That row belongs to the worker,
    /// not to the connection that failed to re-tag it.
    #[tokio::test]
    async fn a_non_notfound_tag_failure_keeps_a_row_the_worker_already_holds() {
        assert_eq!(
            non_notfound_rollback_leftover_row(false, true).await.and_then(|row| row.charter),
            Some("charter".to_owned()),
            "a worker already tagged on disk keeps its row when a later tag write fails",
        );
    }

    /// `apply_worker_tag_or_rollback_with_config_dir`: when the JSONL
    /// exists from the start, the retry succeeds on the first attempt,
    /// the worker transitions to Running, and `needs_tag` is cleared.
    #[tokio::test]
    async fn jsonl_present_clears_needs_tag() {
        let (workspace, mut rx) = Workspace::testing_stub();
        // The tag row names its project, so the fixture needs one
        // configured.
        workspace.seed_test_project("forge", "/tmp/forge");
        let project_key = workspace.project_key_for_name("forge").expect("seeded project");
        let session_id = "550e8400-e29b-41d4-a716-446655440011";
        let session_key = SessionSlot::worker("TestOrg", "forge", "prompt-driven");
        workspace.insert_live_worker(
            &project_key,
            fake_spawning_entry("prompt-driven", &session_key, true),
        );

        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let path = jsonl_path_for(cfg.path(), cwd.path(), session_id);
        fs::write(&path, "").expect("seed jsonl");

        workspace.apply_worker_tag_or_rollback_with_config_dir(
            &session_key,
            session_id,
            &project_key,
            "prompt-driven",
            &cwd.path().to_string_lossy(),
            false,
            true,
            true,
            cfg.path(),
        );

        // Wait for the StatusChanged emit.
        tokio::time::timeout(Duration::from_secs(2), async {
            while let Some(frame) = rx.recv().await {
                if let SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                {
                    break;
                }
            }
        })
        .await
        .expect("StatusChanged emit within budget");

        let entries = workspace.list_live_workers(&project_key);
        assert_eq!(entries.len(), 1);
        assert!(!entries[0].needs_tag, "needs_tag cleared on successful tag-write");
        assert!(matches!(entries[0].status, forge_primitives::WorkerLiveness::Running));
        let body = fs::read_to_string(&path).expect("read jsonl");
        assert!(body.contains("\"tag\":\"forge:worker:prompt-driven\""));
    }

    /// `retry_worker_tag_opportunistic_with_config_dir` on a worker
    /// whose `needs_tag` is true: when the JSONL is present, the
    /// retry succeeds, the flag is cleared, and a single
    /// `StatusChanged` event fires.
    #[tokio::test]
    async fn opportunistic_retry_clears_flag_when_jsonl_appears() {
        let (workspace, mut rx) = Workspace::testing_stub();
        // The tag row names its project, so the fixture needs one
        // configured.
        workspace.seed_test_project("forge", "/tmp/forge");
        let project_key = workspace.project_key_for_name("forge").expect("seeded project");
        let session_id = "550e8400-e29b-41d4-a716-446655440012";
        let session_key = SessionSlot::worker("TestOrg", "forge", "idle");
        // Pre-state: worker is Running but needs_tag=true (it landed
        // here via the deferred-NotFound branch earlier).
        let mut entry = fake_spawning_entry("idle", &session_key, true);
        entry.status = forge_primitives::WorkerLiveness::Running;
        workspace.insert_live_worker(&project_key, entry);

        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let path = jsonl_path_for(cfg.path(), cwd.path(), session_id);
        fs::write(&path, "").expect("seed jsonl (claude has now written one)");

        workspace.retry_worker_tag_opportunistic_with_config_dir(
            &project_key,
            &session_key,
            session_id,
            "idle",
            &cwd.path().to_string_lossy(),
            false,
            cfg.path(),
        );

        tokio::time::timeout(Duration::from_secs(2), async {
            while let Some(frame) = rx.recv().await {
                if let SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                {
                    break;
                }
            }
        })
        .await
        .expect("StatusChanged within budget");

        let entries = workspace.list_live_workers(&project_key);
        assert!(!entries[0].needs_tag, "needs_tag cleared on opportunistic retry success");
        let body = fs::read_to_string(&path).expect("read jsonl");
        assert!(body.contains("\"tag\":\"forge:worker:idle\""));
    }

    /// #166 regression: when a worker session hits /new, the new
    /// session_id needs its own tag row written to its JSONL.
    /// `session_task::translate_event` now calls
    /// `apply_worker_tag_or_rollback` on EVERY Connected (not just
    /// the first), so the post-/new JSONL gets tagged in lockstep
    /// with the entry's session_key migration. Without this, the
    /// post-/new transcript carries no `forge:worker` tag, so the boot
    /// scan lists it as one of the project's own sessions.
    ///
    /// Workspace-level test: simulate the /new flow by calling the
    /// tagger twice, swapping the WorkerEntry's occupant between calls.
    /// Verify both session_ids' JSONLs land with the tag. The slot does
    /// not move across `/new` - only the occupant the entry carries
    /// does - so both Connecteds name the one slot.
    #[tokio::test]
    async fn worker_tag_re_applied_after_new_session_rekey() {
        let (workspace, mut rx) = Workspace::testing_stub();
        // The tag row names its project, so the fixture needs one
        // configured.
        workspace.seed_test_project("forge", "/tmp/forge");
        let project_key = workspace.project_key_for_name("forge").expect("seeded project");

        // Two distinct session_ids: first Connected, then post-/new.
        let session_id_1 = "550e8400-e29b-41d4-a716-446655440021";
        let session_id_2 = "550e8400-e29b-41d4-a716-446655440022";
        let key_1 = SessionSlot::worker("TestOrg", "forge", "reviewer");

        // Seed the WorkerEntry at the slot the worker was spawned
        // under, which `/new` leaves alone.
        workspace.insert_live_worker(&project_key, fake_spawning_entry("reviewer", &key_1, true));

        let cfg = tempdir().expect("cfg");
        let cwd = tempdir().expect("cwd");
        let path_1 = jsonl_path_for(cfg.path(), cwd.path(), session_id_1);
        fs::write(&path_1, "").expect("seed first jsonl");

        // First Connected: tag the first session's JSONL.
        workspace.apply_worker_tag_or_rollback_with_config_dir(
            &key_1,
            session_id_1,
            &project_key,
            "reviewer",
            &cwd.path().to_string_lossy(),
            false,
            true,
            true,
            cfg.path(),
        );
        tokio::time::timeout(Duration::from_secs(2), async {
            while let Some(frame) = rx.recv().await {
                if let SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                {
                    break;
                }
            }
        })
        .await
        .expect("first StatusChanged within budget");
        let body_1 = fs::read_to_string(&path_1).expect("read first jsonl");
        assert!(
            body_1.contains("\"tag\":\"forge:worker:reviewer\""),
            "first Connected tags the first session's JSONL",
        );

        // Simulate `/new`: the slot does not move, only the occupant
        // the registry entry carries does.
        {
            let mut workers = workspace.live_workers.lock();
            for entry in workers.values_mut().flatten() {
                if entry.slot == key_1 {
                    entry.session_id = Some(forge_primitives::SessionId::new(session_id_2));
                }
            }
        }

        // Seed the second session's JSONL as if claude wrote it on
        // the first turn after /new.
        let path_2 = jsonl_path_for(cfg.path(), cwd.path(), session_id_2);
        fs::write(&path_2, "").expect("seed second jsonl");

        // Second Connected (the /new flow). Without #166's fix the
        // tagger was never called; with the fix it fires
        // unconditionally on every Connected.
        workspace.apply_worker_tag_or_rollback_with_config_dir(
            &key_1,
            session_id_2,
            &project_key,
            "reviewer",
            &cwd.path().to_string_lossy(),
            false,
            true,
            true,
            cfg.path(),
        );
        tokio::time::timeout(Duration::from_secs(2), async {
            while let Some(frame) = rx.recv().await {
                if let SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                {
                    break;
                }
            }
        })
        .await
        .expect("second StatusChanged within budget");

        let body_2 = fs::read_to_string(&path_2).expect("read second jsonl");
        assert!(
            body_2.contains("\"tag\":\"forge:worker:reviewer\""),
            "second Connected (post-/new) tags the new session's JSONL",
        );

        // The first JSONL keeps its tag - re-tagging writes to the
        // new file, not the old one. This guards against accidental
        // first-JSONL overwrite during the re-tag flow.
        let body_1_after = fs::read_to_string(&path_1).expect("read first jsonl");
        assert!(
            body_1_after.contains("\"tag\":\"forge:worker:reviewer\""),
            "first session's tag survives the /new re-tag flow",
        );
    }

    /// #184 regression: when a worker is spawned inside a git repo,
    /// claude's `--worktree <label>` forks the subprocess into
    /// `<repo>/.claude/worktrees/<label>/` and writes the session
    /// JSONL under THAT sanitised path, not the repo root. The
    /// tag-write path must follow the JSONL there.
    ///
    /// Before the fix, `apply_worker_tag_or_rollback_with_config_dir`
    /// passed the repo root to `tag_session_with_retry`, the lookup
    /// missed (different sanitised key), all 30 retries hit NotFound,
    /// and `needs_tag` stayed true forever. On forge restart the
    /// catalog scan found zero tagged worker JSONLs and every worker
    /// spawned fresh.
    ///
    /// Test breaks the existing fixture's "write path = lookup path"
    /// coupling: cwd argument is the repo root, but the JSONL is
    /// seeded at the worktree path's sanitised key.
    #[tokio::test]
    async fn git_repo_worker_tag_lands_under_worktree_path() {
        let (workspace, mut rx) = Workspace::testing_stub();
        // The tag row names its project, so the fixture needs one
        // configured.
        workspace.seed_test_project("repo", "/tmp/repo");
        let project_key = workspace.project_key_for_name("repo").expect("seeded project");
        let session_id = "550e8400-e29b-41d4-a716-446655440099";
        let session_key = SessionSlot::worker("TestOrg", "repo", "debugger");

        // is_git_repo_at_spawn=true is the production shape that
        // triggers claude's --worktree fork.
        let mut entry = fake_spawning_entry("debugger", &session_key, true);
        entry.is_git_repo_at_spawn = true;
        workspace.insert_live_worker(&project_key, entry);

        let cfg = tempdir().expect("cfg");
        let repo_root = tempdir().expect("repo");
        init_worker_worktree(repo_root.path(), "debugger");
        // JSONL lives at the WORKTREE path (matches claude's behaviour
        // under --worktree): <repo>/.claude/worktrees/<label>/.
        let worktree_path = repo_root.path().join(".claude/worktrees/debugger");
        let path = jsonl_path_for(cfg.path(), &worktree_path, session_id);
        fs::write(&path, "").expect("seed jsonl at worktree path");

        // Caller passes the repo root (NOT the worktree path), matching
        // how forge sources the cwd from the project view. The wrapper
        // must compute the worktree-derived cwd internally when
        // is_git_repo_at_spawn is true.
        workspace.apply_worker_tag_or_rollback_with_config_dir(
            &session_key,
            session_id,
            &project_key,
            "debugger",
            &repo_root.path().to_string_lossy(),
            true,
            true,
            true,
            cfg.path(),
        );

        tokio::time::timeout(Duration::from_secs(2), async {
            while let Some(frame) = rx.recv().await {
                if let SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                {
                    break;
                }
            }
        })
        .await
        .expect("StatusChanged within budget");

        let entries = workspace.list_live_workers(&project_key);
        assert_eq!(entries.len(), 1, "worker stays in live_workers after successful tag");
        assert!(
            !entries[0].needs_tag,
            "needs_tag cleared, tag-write found the JSONL at the worktree path"
        );
        let body = fs::read_to_string(&path).expect("read jsonl at worktree path");
        assert!(
            body.contains("\"tag\":\"forge:worker:debugger\""),
            "tag row appended at the worktree-derived JSONL: {body:?}"
        );
    }

    /// #184 regression for the opportunistic-retry path: the
    /// first-turn retry from `handle_deliver_worker_prompt` also
    /// needs to address the worktree-derived JSONL for git-repo
    /// workers. Sibling to `git_repo_worker_tag_lands_under_worktree_path`
    /// Same setup as the apply path, different entry point.
    #[tokio::test]
    async fn git_repo_worker_opportunistic_retry_uses_worktree_path() {
        let (workspace, mut rx) = Workspace::testing_stub();
        // The tag row names its project, so the fixture needs one
        // configured.
        workspace.seed_test_project("repo", "/tmp/repo");
        let project_key = workspace.project_key_for_name("repo").expect("seeded project");
        let session_id = "550e8400-e29b-41d4-a716-446655440100";
        let session_key = SessionSlot::worker("TestOrg", "repo", "debugger");

        // Pre-state: worker is Running (the apply_* path already ran
        // and exhausted into DeferredNotFound). is_git_repo_at_spawn=true.
        let mut entry = fake_spawning_entry("debugger", &session_key, true);
        entry.status = forge_primitives::WorkerLiveness::Running;
        entry.is_git_repo_at_spawn = true;
        workspace.insert_live_worker(&project_key, entry);

        let cfg = tempdir().expect("cfg");
        let repo_root = tempdir().expect("repo");
        let worktree_path = repo_root.path().join(".claude/worktrees/debugger");
        let path = jsonl_path_for(cfg.path(), &worktree_path, session_id);
        fs::write(&path, "").expect("seed jsonl at worktree path (claude has now written)");

        workspace.retry_worker_tag_opportunistic_with_config_dir(
            &project_key,
            &session_key,
            session_id,
            "debugger",
            &repo_root.path().to_string_lossy(),
            true,
            cfg.path(),
        );

        tokio::time::timeout(Duration::from_secs(2), async {
            while let Some(frame) = rx.recv().await {
                if let SessionUpdate::WorkerStatusChanged { action, .. } =
                    std::sync::Arc::unwrap_or_clone(frame.update)
                    && matches!(action, crate::protocol::WorkerStatusAction::StatusChanged)
                {
                    break;
                }
            }
        })
        .await
        .expect("StatusChanged within budget");

        let entries = workspace.list_live_workers(&project_key);
        assert!(
            !entries[0].needs_tag,
            "opportunistic retry found the worktree-path JSONL; needs_tag cleared"
        );
        let body = fs::read_to_string(&path).expect("read jsonl at worktree path");
        assert!(
            body.contains("\"tag\":\"forge:worker:debugger\""),
            "tag row appended at worktree path: {body:?}"
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod worker_respawn_tests {
    use super::*;
    use crate::protocol::{Command, SessionChoice, WorkerSpawnReply};

    /// The `demo` project's lead slot, which the fixtures in this module
    /// boot.
    fn lead_slot() -> SessionSlot {
        SessionSlot::lead("TestOrg", "demo")
    }

    /// A live worker entry for the `demo` project, keyed by the slot the
    /// worker's spawn names - the triple `worker_lookup_for_session`
    /// matches on.
    fn worker_entry(label: &str) -> crate::mcp::workers::types::WorkerEntry {
        crate::mcp::workers::types::WorkerEntry {
            label: label.to_owned(),
            charter: "test".to_owned(),
            slot: SessionSlot::worker("TestOrg", "demo", label),
            session_id: None,
            status: forge_primitives::WorkerLiveness::Running,
            spawned_at: std::time::SystemTime::UNIX_EPOCH,
            spawned_by: lead_slot(),
            needs_tag: false,
            is_git_repo_at_spawn: false,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    /// Seed a project into the stub workspace and hand back the
    /// `LoadedProject` a spawn resolves it to.
    fn seed_project_and_return(ws: &Workspace, name: &str, path: &str) -> LoadedProject {
        ws.seed_test_project(name, path);
        ws.find_project_view_by_name(name).expect("seeded project")
    }

    /// The tool names the per-session `forge` MCP server registers for
    /// `kind`, composed exactly as the spawn path composes them. Read
    /// off the server's debug listing rather than substring-searched in
    /// it, so a description naming a tool cannot answer for the
    /// registration.
    fn forge_tool_surface(
        workspace: &Arc<Workspace>,
        kind: crate::mcp::SessionKind,
    ) -> Vec<String> {
        let server = crate::mcp::build_forge_server(
            crate::mcp::ForgeServerFacades {
                workspace: crate::mcp::peers::facade::ProdWorkspaceFacade::from_arc(workspace),
                worker: crate::mcp::workers::facade::ProdWorkerFacade::from_arc(workspace),
                browser: crate::mcp::browser::facade::ProdBrowserFacade::from_workspace(workspace),
                terminal: crate::mcp::terminal::facade::ProdTerminalFacade::from_workspace(
                    workspace,
                ),
                documents: crate::mcp::documents::facade::ProdDocumentFacade::from_workspace(
                    workspace,
                ),
                review: crate::mcp::review::facade::ProdReviewFacade::from_arc(workspace),
                cron: crate::mcp::cron::facade::ProdCronFacade::from_arc(workspace),
                gotify: crate::mcp::gotify::facade::ProdGotifyFacade::from_arc(workspace),
                slack: crate::mcp::slack::facade::ProdSlackFacade::from_arc(workspace),
                settings: crate::mcp::settings::facade::ProdSettingsFacade::from_arc(workspace),
                vault: None,
                tasks: crate::mcp::tasks::facade::ProdTasksFacade::from_arc(workspace),
                voice: workspace.voice_service(),
                systemone: workspace.systemone.read().as_ref().map(|client| {
                    crate::mcp::systemone::facade::ProdSystemOneFacade::new(std::sync::Arc::clone(
                        client,
                    ))
                    .into_arc()
                }),
            },
            &crate::mcp::McpFamily::all(),
            &SessionSlot::from_str_for_test("caller"),
            kind,
        );
        let debug = format!("{server:?}");
        let (_, tools) = debug.split_once("tools: [").expect("debug lists the tool names");
        let (tools, _) = tools.split_once(']').expect("the tool list is closed");
        tools
            .split(", ")
            .map(|name| name.trim_matches('"').to_owned())
            .filter(|name| !name.is_empty())
            .collect()
    }

    /// The guard refuses a second claim while the first is outstanding.
    /// Holding the claim directly is all this needs - the blocked branch
    /// is unreachable only when claim and release share one call, which
    /// is a property of the callers rather than of the guard.
    #[test]
    fn respawn_guard_refuses_a_second_claim() {
        let (ws, _rx) = Workspace::testing_stub();
        let key = ProjectKey::new("proj");
        assert!(ws.try_claim_respawn(&key), "an unclaimed guard grants");
        assert!(!ws.try_claim_respawn(&key), "a claimed guard refuses");
        ws.release_respawn(&key);
        assert!(ws.try_claim_respawn(&key), "release makes it claimable again");
    }

    /// A worker must not receive the delegation block. It instructs the
    /// reader to call `agents__spawn`, which is lead-only, so a worker
    /// given it would be told to call a tool that refuses it. The lead
    /// half is the control: without it, a helper that did nothing at all
    /// would still satisfy the assertion above. The negative pin keeps
    /// the charter the sole carrier of the delegation default.
    #[test]
    fn only_a_lead_session_gets_the_delegation_block() {
        let mut worker = SessionLaunchSettings::default();
        Workspace::apply_lead_delegation(&mut worker, crate::mcp::SessionKind::Worker);
        assert_eq!(worker.delegation_preamble, None, "a worker gets no delegation block");

        let mut lead = SessionLaunchSettings::default();
        Workspace::apply_lead_delegation(&mut lead, crate::mcp::SessionKind::Lead);
        let preamble = lead.delegation_preamble.expect("a lead does get it");
        assert!(
            preamble.contains("agents__spawn")
                && preamble.contains("always creates the worker in YOUR project")
                && preamble.contains("Workers build; subagents review"),
            "a lead does get it",
        );
        assert!(
            preamble.contains(
                "A work cut - one feature, one issue, one fix - lands whole: one branch, one \
                 review, one look, one merge. Never slice it into pieces that land one after \
                 another, and never show or merge an intermediate step on the way."
            ),
            "the handle and the ban, through the ban's period, are pinned together - the same \
             sentence the conduct block and the charter carry",
        );
        assert!(
            preamble.contains(
                "The look is the one that cut is owed: a feature waits for the user's own look \
                 before merge; a fix merges after the review loop as usual."
            ),
            "the look's scope is pinned",
        );
        assert!(
            preamble.contains(
                "A plan, spec or design the user must review reaches them through \
                 `documents__hand_off` with `reviewable: true`, never as a path in chat"
            ),
            "the document hand-off is how a reviewable plan reaches the user",
        );
        for (clause, why) in [
            (
                "Run independent pieces in parallel, up to the project's capacity",
                "the parallel-by-default headline",
            ),
            ("a merge conflict is not, by itself, a reason to hold a piece", "the conflict rule"),
            ("resolve the conflict and re-run the gates", "its remedy"),
            (
                "Only genuine shared-state ordering serializes: one in-flight migration \
                 sequence, main's merge queue, a release/version line",
                "the shared-state list",
            ),
            ("decide whether the options genuinely differ", "the dispatch cue's scope"),
            (
                "put the enumerated options and the context that bears on them to \
                 systemone__ask_choice when your tools include it",
                "the dispatch cue and its guard",
            ),
            ("without it decide it yourself", "the dispatch fallback"),
            (
                "Either way, report the decision where the work is reported",
                "the dispatch report duty",
            ),
        ] {
            assert!(
                preamble.contains(clause),
                "the delegation preamble does not carry the parallel rule ({why}): {clause}"
            );
        }
        assert!(
            !preamble.contains("doing the work yourself"),
            "the charter, not this block, carries the delegation default",
        );
        // The preamble is lead-facing text, and a lead's launch denies the
        // replaced CLI tools: naming one here sends the lead to a surface
        // it does not have. The charter carries the same test in `spawn`.
        for tool in [
            "CronCreate",
            "CronDelete",
            "CronList",
            "TaskCreate",
            "TaskGet",
            "TaskList",
            "TaskUpdate",
            "SendMessage",
            "ListAgents",
            "Workflow",
            "RemoteTrigger",
        ] {
            assert!(
                !preamble.contains(tool),
                "the delegation preamble must not name the blocked CLI tool {tool}",
            );
        }
    }

    /// A respawn rebuilds both of a lead's blocks. They are stamped at spawn
    /// and the store holds no charter for a lead row, so a `/new`, a
    /// `/resume` or a handoff used to hand back a lead with neither its
    /// mission nor its delegation rules - and a handoff that quietly did
    /// that is the bug this pins. A worker's respawn gets neither: its
    /// charter comes from its own stored row.
    #[test]
    fn a_respawn_rebuilds_a_leads_charter_and_preamble() {
        let (ws, _rx) = Workspace::testing_stub();
        let lead = SessionSlot::lead("TestOrg", "forge");
        let mut settings = SessionLaunchSettings::default();
        ws.stamp_respawn_overrides(&lead, "new-id", &mut settings);
        assert!(
            settings.charter.as_deref().is_some_and(|charter| charter.contains("engineering lead")),
            "the lead's mission survives the respawn: {:?}",
            settings.charter,
        );
        assert!(settings.delegation_preamble.is_some(), "and so do its delegation rules");

        let worker = SessionSlot::worker("TestOrg", "forge", "handoff-cut");
        let mut worker_settings = SessionLaunchSettings::default();
        ws.stamp_respawn_overrides(&worker, "new-id", &mut worker_settings);
        assert!(worker_settings.charter.is_none(), "a worker's charter is its own row's");
        assert!(
            worker_settings.delegation_preamble.is_none(),
            "and a worker is never given the lead-only block",
        );
    }

    /// The role a spawn carries is the role it gets, and the slot's label
    /// comes from the same value - so a worker cannot be handed a worker's
    /// tool surface AND the lead's address. A worker re-spawned by the
    /// boot resume path was classified as Lead while the key's shape was
    /// the only signal, which hands it the lead-only `agents__*` group; the
    /// caller that knows the row is a worker now says so.
    #[test]
    fn a_worker_spawn_carries_its_label_and_a_worker_tool_surface() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = seed_project_and_return(&ws, "forge", "/tmp/role-worker");
        let role = crate::protocol::SpawnRole::Worker {
            label: "implementer".to_owned(),
            wrote_row: true,
            mcp_families: None,
        };

        let slot = Workspace::slot_for_spawn(&role, &project);
        assert_eq!(slot.label(), "implementer", "the slot names the worker");
        let kind = if slot.is_lead() {
            crate::mcp::SessionKind::Lead
        } else {
            crate::mcp::SessionKind::Worker
        };
        assert!(
            !forge_tool_surface(&ws, kind).contains(&"agents__spawn".to_owned()),
            "and a worker's forge server carries no lead-only verb",
        );
    }

    /// Controls for [`a_worker_spawn_carries_its_label_and_a_worker_tool_surface`]:
    /// without a case that answers Lead, a derivation answering Worker for
    /// everything would satisfy it. The shape cases the old prefix test
    /// read are unreachable here by construction - `slot_for_spawn` takes
    /// no key, so a parse cannot be reintroduced without a signature
    /// change - which is the stronger form of that pin.
    #[test]
    fn a_lead_spawn_carries_no_label() {
        let (ws, _rx) = Workspace::testing_stub();
        let project = seed_project_and_return(&ws, "forge", "/tmp/role-lead");

        let slot = Workspace::slot_for_spawn(&crate::protocol::SpawnRole::Lead, &project);
        assert!(slot.is_lead(), "a lead spawn carries the lead label");
    }

    /// A tool surface for each kind, which is what the role gates: this is
    /// the lead half of the pair above, and it is the control that stops a
    /// derivation answering Worker for everything from satisfying the
    /// worker case while stripping the lead-only verbs from every lead.
    #[test]
    fn a_lead_tool_surface_keeps_its_lead_only_verbs() {
        let (ws, _rx) = Workspace::testing_stub();
        assert!(
            forge_tool_surface(&ws, crate::mcp::SessionKind::Lead)
                .contains(&"agents__spawn".to_owned()),
            "a lead keeps the verbs only a lead may call",
        );
    }

    #[test]
    fn force_new_respawn_dispatches_workers_fresh() {
        // A force-new lead came up fresh, so its workers do too: every
        // one dispatches with resume_existing = None.
        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.seed_test_project("data-modules", "/tmp/force-new-data-modules");
        let key = workspace.project_key_for_name("data-modules").expect("seeded project");
        seed_worker_row(&workspace, &key, "steward");
        workspace.enable_test_dispatch_intercept();
        workspace.respawn_workers_for_lead(
            &SessionSlot::from_str_for_test("lead-uuid"),
            key,
            true, // force_new: the workers come up fresh, like their lead
        );

        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, "force-new still spawns the stored worker");
        if let Command::SpawnWorker { resume_existing, .. } = spawns[0] {
            assert!(resume_existing.is_none(), "force_new => worker spawns fresh (no resume)");
        }
    }

    /// A stub carrying one `proj-x` project (org `TestOrg`, path
    /// `/tmp/proj-x`) over an empty store, plus the key that project
    /// resolves under. The store is what the re-spawn wave reads, so a
    /// test expecting a resume writes the label's row through
    /// `record_session_id`. The tempdir must outlive the caller.
    fn stub_with_worker_store() -> (Arc<Workspace>, ProjectKey, tempfile::TempDir) {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("proj-x", "/tmp/proj-x");
        let dir = tempfile::tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let key = ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(
            Some("/tmp/proj-x"),
        ));
        (workspace, key, dir)
    }

    /// A `sessions` row for a `proj-x` worker: the shape the re-spawn
    /// wave reads. `session_id` is absent unless a test writes one
    /// through `record_session_id`, which is what makes the row resume
    /// rather than re-deliver its kick.
    fn worker_row(label: &str, kick: Option<&str>) -> crate::store::sessions::SessionRecord {
        crate::store::sessions::SessionRecord {
            org: "TestOrg".to_owned(),
            project: "proj-x".to_owned(),
            label: label.to_owned(),
            session_id: None,
            charter: Some(format!("dynamic charter for {label}")),
            kick: kick.map(str::to_owned),
            resume_kick: None,
            interactive: Some(false),
            seat_state: None,
            is_git_repo: None,
            mcp_families: None,
            cwd: None,
        }
    }

    /// `proj-x` is a real git repo and `proj-y` is not, so the four
    /// seeded rows below cut across the two axes the skip must not
    /// confuse: whether the ROW says its worker runs in a worktree, and
    /// whether the project path looks like a repo on disk. The two
    /// disagreeing rows are the point - a predicate inferring gitness
    /// from the filesystem gets both of them wrong.
    fn seed_worktree_fixture(
        workspace: &Arc<Workspace>,
    ) -> (ProjectKey, ProjectKey, tempfile::TempDir, tempfile::TempDir) {
        let repo = tempfile::tempdir().expect("git project dir");
        run_git_in(repo.path(), &["init", "-q"]);
        let plain = tempfile::tempdir().expect("non-git project dir");
        workspace.seed_test_project("proj-x", repo.path().to_str().expect("utf8 repo path"));
        workspace.seed_test_project("proj-y", plain.path().to_str().expect("utf8 plain path"));
        // Only `present`'s worktree stands; the other three are gone.
        std::fs::create_dir_all(repo.path().join(".claude").join("worktrees").join("present"))
            .expect("create the surviving worktree");

        let proj_x = workspace.project_key_for_name("proj-x").expect("seeded project");
        let proj_y = workspace.project_key_for_name("proj-y").expect("seeded project");
        let seeded: [(&ProjectKey, &str, bool); 4] = [
            // A git worker whose worktree is gone: the defect.
            (&proj_x, "stranded", true),
            // Its sibling whose worktree stands.
            (&proj_x, "present", true),
            // Runs in the project root, so it has no worktree to lose -
            // even though the project path IS a repo with a `.git`.
            (&proj_x, "rooted", false),
            // Says it runs in a worktree, in a project with no `.git`
            // anywhere. The row decides, not the disk.
            (&proj_y, "ghostworktree", true),
        ];
        for (key, label, is_git) in seeded {
            workspace
                .record_worker_row(
                    key,
                    label,
                    &format!("{label}-uuid"),
                    "c",
                    None,
                    None,
                    false,
                    crate::mcp::workers::types::WorkerTree { is_git_repo: is_git, cwd: None },
                    None,
                )
                .expect("seed the row this wave re-spawns");
        }
        // A row whose spawn never got an id. The wave re-spawns it FRESH,
        // which runs in the project root and passes `--worktree`, so
        // claude creates the worktree itself and there is nothing missing
        // for it to fail on.
        let guard = workspace.db.lock();
        crate::store::sessions::put(
            guard.as_ref().expect("db installed"),
            &crate::store::sessions::SessionRecord {
                org: "TestOrg".to_owned(),
                project: "proj-x".to_owned(),
                label: "unstarted".to_owned(),
                session_id: None,
                charter: Some("c".to_owned()),
                kick: None,
                resume_kick: None,
                interactive: Some(false),
                seat_state: None,
                is_git_repo: Some(true),
                mcp_families: None,
                cwd: None,
            },
        )
        .expect("seed the id-less row");
        drop(guard);
        (proj_x, proj_y, repo, plain)
    }

    /// A worker whose worktree is gone is re-spawned on every boot and
    /// fails every time, forever. The wave skips it, and only it.
    #[test]
    fn boot_respawn_skips_a_row_whose_worktree_is_gone() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        let db_dir = tempfile::tempdir().expect("db dir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        let (proj_x, proj_y, _repo, _plain) = seed_worktree_fixture(&workspace);

        for key in [&proj_x, &proj_y] {
            // The wave reads the rows the store holds, not a hand-made
            // shape, so this also pins that the row carries the flag.
            let rows = workspace.worker_rows_for_project(key);
            workspace.dispatch_worker_respawns(&lead_slot(), key, &rows, false);
        }

        let spawned: Vec<String> = workspace
            .drain_test_dispatch_buffer()
            .into_iter()
            .map(|cmd| match cmd {
                Command::SpawnWorker { label, .. } => label,
                other => panic!("expected SpawnWorker, got {other:?}"),
            })
            .collect();
        assert!(
            !spawned.contains(&"stranded".to_owned()),
            "a worker whose worktree is gone must not be re-spawned - the spawn cannot \
             enter its cwd and would fail on every boot forever; spawned {spawned:?}",
        );
        assert!(
            !spawned.contains(&"ghostworktree".to_owned()),
            "the skip must follow the row's recorded gitness, not a `.git` on disk: \
             this row says worktree and the project path has no repo; spawned {spawned:?}",
        );
        assert!(
            spawned.contains(&"present".to_owned()),
            "a worker whose worktree stands must still re-spawn; spawned {spawned:?}",
        );
        assert!(
            spawned.contains(&"rooted".to_owned()),
            "a worker whose row says it runs in the project root must still re-spawn, \
             even though that project holds a `.git`; spawned {spawned:?}",
        );
        assert!(
            spawned.contains(&"unstarted".to_owned()),
            "a row with no stored id re-spawns FRESH and creates its own worktree, so \
             the missing one must not strand it; spawned {spawned:?}",
        );

        // Skipping is not deleting. The row is the only handle on the
        // worker, so a restored worktree is what brings it back.
        let kept = |key: &ProjectKey| -> Vec<String> {
            workspace.worker_rows_for_project(key).into_iter().map(|r| r.label).collect()
        };
        assert!(
            kept(&proj_x).contains(&"stranded".to_owned())
                && kept(&proj_y).contains(&"ghostworktree".to_owned()),
            "a skipped row must stay in the store, or the restore path this promises is \
             gone; kept {:?} / {:?}",
            kept(&proj_x),
            kept(&proj_y),
        );
    }

    /// The launchpad renders every persisted worker row, so a row the
    /// wave skips would still be offered as a worker - which is the
    /// visible half of the same defect. It must not reach the pane.
    ///
    /// Only the skips are asserted here. Both sites call
    /// `worker_row_can_start`, so an over-skip regression fails the boot
    /// wave's test above; what this one pins is that this site calls the
    /// predicate at all.
    #[test]
    fn launchpad_does_not_offer_a_row_whose_worktree_is_gone() {
        let (workspace, _rx) = Workspace::testing_stub();
        let db_dir = tempfile::tempdir().expect("db dir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        let (proj_x, _proj_y, _repo, _plain) = seed_worktree_fixture(&workspace);

        let offered = workspace.worker_labels_by_project();
        let labels = offered.get(&proj_x).cloned().unwrap_or_default();
        assert!(
            !labels.contains(&"stranded".to_owned()),
            "a worker whose worktree is gone must not be offered by the launchpad; \
             offered {labels:?}",
        );
        assert!(
            !labels.contains(&"ghostworktree".to_owned()),
            "the launchpad must read the row's gitness, not the project's filesystem; \
             offered {labels:?}",
        );
    }

    /// The interactive flag rides the subprocess CLI args, so a
    /// re-spawn that dropped it would take `AskUserQuestion` away from
    /// a worker mid-conversation on the first forge restart - and give
    /// it to one that was never meant to have it. The family selection
    /// rides the same row for the same reason.
    #[test]
    fn dispatch_worker_respawns_carries_interactive_from_the_row() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.seed_test_project("proj-x", "/tmp/proj-x");
        let project_key = workspace.project_key_for_name("proj-x").expect("seeded project");
        let mut talkative = worker_row("talkative", None);
        talkative.interactive = Some(true);
        talkative.mcp_families = Some(vec!["cron".to_owned()]);
        let dynamic = vec![talkative, worker_row("quiet", None)];

        workspace.dispatch_worker_respawns(
            &SessionSlot::from_str_for_test("new-lead"),
            &project_key,
            &dynamic,
            false,
        );

        for cmd in workspace.drain_test_dispatch_buffer() {
            let Command::SpawnWorker {
                label, interactive, from_boot_respawn, mcp_families, ..
            } = cmd
            else {
                panic!("expected SpawnWorker");
            };
            assert!(
                from_boot_respawn,
                "a boot re-spawn must stay exempt from the worker cap; flipping this \
                 strands persisted rows on restart with the refusal dropped unheard"
            );
            match label.as_str() {
                "talkative" => {
                    assert!(interactive, "an interactive row re-spawns interactive");
                    assert_eq!(
                        mcp_families,
                        Some(vec!["cron".to_owned()]),
                        "the row's family selection rides the re-spawn",
                    );
                }
                "quiet" => {
                    assert!(!interactive, "a non-interactive row re-spawns non-interactive");
                    assert_eq!(mcp_families, None, "a row naming none re-spawns unnarrowed");
                }
                other => panic!("unexpected label {other}"),
            }
        }
    }

    /// Re-spawn resumes by the id the store holds: a worker whose label
    /// has one resumes and takes the forge restart note as its kick; one
    /// without re-delivers its stored kick.
    #[test]
    fn dispatch_worker_respawns_kicks_only_what_was_left_mid_turn() {
        use crate::store::sessions::SeatState;

        let (workspace, project_key, _dir) = stub_with_worker_store();
        workspace.enable_test_dispatch_intercept();
        let mut dynamic = vec![
            worker_row("reviewer", Some("original kick")),
            worker_row("scratch", Some("start scratch")),
            worker_row("idle", None),
            worker_row("parked", Some("never delivered")),
        ];
        // The reviewer was mid-turn when forge stopped; the parked worker
        // was not, so its resume must deliver nothing.
        dynamic[0].seat_state = Some(SeatState::InTurn);
        dynamic[3].seat_state = Some(SeatState::Idle);
        workspace.record_session_id("TestOrg", "proj-x", "reviewer", "reviewer-uuid");
        workspace.record_session_id("TestOrg", "proj-x", "parked", "parked-uuid");

        workspace.dispatch_worker_respawns(
            &SessionSlot::from_str_for_test("new-lead"),
            &project_key,
            &dynamic,
            false,
        );

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert_eq!(dispatched.len(), 4, "one SpawnWorker per persisted dynamic worker");
        for cmd in dispatched {
            let Command::SpawnWorker {
                label,
                charter,
                resume_existing,
                kick,
                spawned_by,
                project_key: pk,
                ..
            } = cmd
            else {
                panic!("expected SpawnWorker");
            };
            assert_eq!(
                spawned_by,
                SessionSlot::from_str_for_test("new-lead"),
                "re-parented to the current lead's slot",
            );
            assert_eq!(pk, project_key);
            assert_eq!(charter, format!("dynamic charter for {label}"), "charter from the DB row");
            match label.as_str() {
                "reviewer" => {
                    assert_eq!(
                        resume_existing.as_deref(),
                        Some("reviewer-uuid"),
                        "a stored id resumes"
                    );
                    assert_eq!(
                        kick.as_deref(),
                        Some(DYNAMIC_WORKER_RESTART_NOTE),
                        "resume delivers the forge restart note, not the stored kick",
                    );
                }
                "scratch" => {
                    assert!(resume_existing.is_none(), "no stored id -> fresh");
                    assert_eq!(
                        kick.as_deref(),
                        Some("start scratch"),
                        "fresh re-delivers the stored kick"
                    );
                }
                "idle" => {
                    assert!(resume_existing.is_none());
                    assert!(kick.is_none(), "fresh with no stored kick stays kickless");
                }
                "parked" => {
                    assert_eq!(
                        resume_existing.as_deref(),
                        Some("parked-uuid"),
                        "a stored id resumes",
                    );
                    assert!(
                        kick.is_none(),
                        "a worker that was idle when it stopped is resumed with nothing \
                         delivered; its kick stays on the row for a future fresh spawn",
                    );
                }
                other => panic!("unexpected label {other}"),
            }
        }
    }

    /// The restart note is the first turn a resumed worker reads, and a
    /// brief in its history can carry an earlier loss's clock. Pinned so the
    /// note names the clock and the schedule list as the authority.
    #[test]
    fn the_restart_note_marks_a_briefs_timestamps_unverified() {
        assert!(
            DYNAMIC_WORKER_RESTART_NOTE.contains(
                "If the history's timestamps disagree with the clock and the live schedules"
            ),
            "the note sends a resumed worker to the clock and the schedules",
        );
        assert!(
            DYNAMIC_WORKER_RESTART_NOTE.contains("believe the clock and the schedules"),
            "the note names which side wins, not only that they may disagree",
        );
        assert!(
            DYNAMIC_WORKER_RESTART_NOTE.contains("still do the concrete asks"),
            "the note keeps the brief's asks, which are usually right",
        );
    }

    /// The lead restart note is the first turn a boot-resumed lead reads.
    /// Pinned so it sends the lead to the handoff and the board before it
    /// acts, keeps the history conditional (a refused resume falls back to
    /// a fresh one), warns that a message sent before the restart may have
    /// been lost, and goes to the clock over a stale history.
    #[test]
    fn the_lead_restart_note_names_the_handoff_the_board_and_the_clock() {
        assert!(LEAD_RESTART_NOTE.contains("forge restarted"), "the note says what happened");
        assert!(
            LEAD_RESTART_NOTE.contains("handoff.md` in the project's memory directory"),
            "the note names where the handoff lives, not only its filename",
        );
        assert!(
            LEAD_RESTART_NOTE.contains("task board before acting"),
            "the note sends the lead to the board before it acts",
        );
        assert!(
            LEAD_RESTART_NOTE.contains("they say what was in flight"),
            "the note names the handoff and the board as the source, not the history",
        );
        assert!(
            LEAD_RESTART_NOTE.contains("Continue that work and do not restart what is finished"),
            "the note tells the lead to carry on and not redo finished work",
        );
        assert!(
            LEAD_RESTART_NOTE.contains("treat it as the record of this seat's last run"),
            "a history that IS present is named as this seat's own record",
        );
        assert!(
            LEAD_RESTART_NOTE.contains("If a prior conversation is in the history above"),
            "the history is conditional, so the note stays true over a fresh fallback",
        );
        assert!(
            LEAD_RESTART_NOTE.contains(
                "The last turn was interrupted, so its final tool call may not have completed"
            ) && LEAD_RESTART_NOTE.contains("check the state before continuing"),
            "the note says why the seat is reading it and what the interruption may have left \
             half-done",
        );
        assert!(
            LEAD_RESTART_NOTE.contains(
                "Anything you sent before the restart may not have arrived; confirm it did \
                 before relying on it"
            ),
            "the note warns that an outbound message may have died with the restart",
        );
        assert!(
            LEAD_RESTART_NOTE.contains(
                "If the history's timestamps disagree with the clock and the live schedules, \
                 believe the clock and the schedules"
            ),
            "the note names the whole condition and which side wins",
        );
    }

    /// A boot spawn's restart note is delivered only when the spawn
    /// carries a stored id to resume: a first boot, or `--new`, sends
    /// nothing even though the boot wave asked for the note.
    #[test]
    fn a_resume_kick_reaches_only_a_spawn_with_a_stored_id() {
        let note = || Some("continue where you left off".to_owned());
        assert_eq!(
            resume_kick_for(true, note()),
            note(),
            "a spawn with a stored id takes the note",
        );
        assert!(resume_kick_for(false, note()).is_none(), "a first boot delivers none");
        assert!(
            resume_kick_for(true, None).is_none(),
            "and a caller that asked for no note gets none",
        );
    }

    /// A row carrying its own `resume_kick` takes that text on resume
    /// instead of the generic restart note. The fresh-spawn path is
    /// untouched by it: no stored id still means the stored kick.
    #[test]
    fn dispatch_worker_respawns_prefers_the_rows_resume_kick() {
        let (workspace, project_key, _dir) = stub_with_worker_store();
        workspace.enable_test_dispatch_intercept();
        let mut steward = worker_row("steward", Some("original kick"));
        steward.resume_kick = Some("Re-read the taste notes, then drain both queues.".to_owned());
        // Mid-turn when forge stopped, so its resume is the one that gets a
        // kick; the row's own `resume_kick` is preferred to the generic note.
        steward.seat_state = Some(crate::store::sessions::SeatState::InTurn);
        let mut fresh = worker_row("fresh", Some("original kick"));
        fresh.resume_kick = Some("never delivered: this one has no stored id".to_owned());
        let dynamic = vec![steward, fresh];
        workspace.record_session_id("TestOrg", "proj-x", "steward", "steward-uuid");

        workspace.dispatch_worker_respawns(
            &SessionSlot::from_str_for_test("new-lead"),
            &project_key,
            &dynamic,
            false,
        );

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert_eq!(dispatched.len(), 2);
        for cmd in dispatched {
            let Command::SpawnWorker { label, kick, .. } = cmd else {
                panic!("expected SpawnWorker");
            };
            match label.as_str() {
                "steward" => assert_eq!(
                    kick.as_deref(),
                    Some("Re-read the taste notes, then drain both queues."),
                    "a resuming worker with its own resume_kick gets that, not the generic note",
                ),
                "fresh" => assert_eq!(
                    kick.as_deref(),
                    Some("original kick"),
                    "a fresh re-spawn still takes the stored kick",
                ),
                other => panic!("unexpected label {other}"),
            }
        }
    }

    /// A persisted worker re-spawns on lead reconnect, carrying the
    /// row's own charter.
    #[test]
    fn catalog_scan_respawns_persisted_worker() {
        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"),
        );
        let project_path = dir.path().join("catalog-scan-respawn");
        std::fs::create_dir_all(&project_path).expect("create the project dir");
        workspace.seed_test_project("data-modules", &project_path.to_string_lossy());
        let project_key = workspace.project_key_for_name("data-modules").expect("seeded project");
        workspace
            .record_worker_row(
                &project_key,
                "scratch",
                "scratch-test-id",
                "resume the scratch task",
                Some("go"),
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the persisted worker this test re-spawns");
        workspace.enable_test_dispatch_intercept();

        // No tokio runtime in a plain #[test] -> the sync fallback path.
        workspace.respawn_workers_for_lead(
            &SessionSlot::from_str_for_test("lead-uuid"),
            project_key,
            false,
        );

        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, "the persisted worker re-spawns on lead reconnect");
        if let Command::SpawnWorker { label, charter, .. } = spawns[0] {
            assert_eq!(label, "scratch");
            assert_eq!(charter, "resume the scratch task", "charter comes from the DB row");
        }
    }

    /// A dynamic worker whose row was deleted (despawn / close) does NOT
    /// re-spawn on the next lead reconnect.
    #[test]
    fn catalog_scan_skips_deleted_dynamic_worker() {
        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.seed_test_project("data-modules", "/tmp/catalog-scan-deleted");
        let project_key = workspace.project_key_for_name("data-modules").expect("seeded project");
        // Expect rather than discard: a silent write failure would leave
        // nothing to delete and the negative assertion would hold for the
        // wrong reason.
        workspace
            .record_worker_row(
                &project_key,
                "scratch",
                "scratch-test-id",
                "c",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("write the row this test then deletes");
        workspace.delete_worker_row(&project_key, "scratch").expect("delete the row");
        workspace.enable_test_dispatch_intercept();

        workspace.respawn_workers_for_lead(
            &SessionSlot::from_str_for_test("lead-uuid"),
            project_key,
            false,
        );

        let dispatched = workspace.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().all(|c| !matches!(c, Command::SpawnWorker { .. })),
            "a deleted dynamic worker must not re-spawn",
        );
    }

    /// The id the fixture writes into the label's transcript, which is not
    /// the id its row holds: an assertion on a resolved id says which of
    /// the two answered.
    const TRANSCRIPT_ONLY_ID: &str = "660e8400-e29b-41d4-a716-4466554400aa";

    /// Two fixed seconds for a test that reads the newest transcript:
    /// the later one has to be the test's own write whatever the clock's
    /// granularity is.
    const TRANSCRIPT_OLDER_SECS: u64 = 1_700_000_000;
    const TRANSCRIPT_NEWER_SECS: u64 = 1_700_000_001;

    /// Boot a real workspace over a one-project forge.toml and give the
    /// `steward` label both of the pointers a session can be found by: the
    /// row, which the boot wave reads and which answers the MCP resume
    /// while it is there, and a tagged transcript in the project root's
    /// directory, which the MCP resume falls back to once the row is gone.
    /// The project is not a git repo, so the worker runs in the project
    /// root. Returns the workspace plus the project's key and path, and
    /// the id the row holds.
    ///
    /// Both tempdirs must outlive the caller.
    fn resumable_worker_fixture(
        project: &tempfile::TempDir,
        cfg: &tempfile::TempDir,
    ) -> (Arc<Workspace>, crate::target::ProjectKey, PathBuf, String) {
        let project_path = project.path().to_string_lossy().replace('\\', "/");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]
[[orgs.projects]]
name = "demo"
path = "{project_path}"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#
            ),
        )
        .expect("write forge.toml");

        // The id the store holds for the label is what the re-spawn wave
        // resumes onto, so the fixture writes that row.
        let session_id = "550e8400-e29b-41d4-a716-446655440099";
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let view = ws.list_projects().into_iter().find(|v| v.name == "demo").expect("project");
        ws.record_worker_row(
            &view.key,
            "steward",
            session_id,
            "mind the queues",
            None,
            None,
            false,
            // `demo` is not a git repo, so the worker runs in the project
            // root and has no worktree the wave must find.
            crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
            None,
        )
        .expect("the row the re-spawn wave resumes onto");
        write_tagged_transcript(cfg, &view.path, TRANSCRIPT_ONLY_ID, "steward");
        ws.enable_test_dispatch_intercept();
        (ws, view.key.clone(), view.path.clone(), session_id.to_owned())
    }

    /// Poll the intercept buffer until a SpawnWorker lands or the
    /// deadline passes; the dispatch happens in a spawned task after an
    /// async catalog scan.
    async fn await_spawn_worker(ws: &Arc<Workspace>) -> Vec<Command> {
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
        while std::time::Instant::now() < deadline {
            let dispatched = ws.drain_test_dispatch_buffer();
            if dispatched.iter().any(|c| matches!(c, Command::SpawnWorker { .. })) {
                return dispatched;
            }
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }
        Vec::new()
    }

    /// The async arm: under a runtime the wave runs off the event loop
    /// and re-spawns the worker onto the id the store holds for it.
    #[tokio::test]
    async fn respawn_workers_resumes_a_worker_onto_its_stored_id() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, _path, session_id) = resumable_worker_fixture(&project, &cfg);

        ws.respawn_workers_for_lead(&lead_slot(), key, false);

        let dispatched = await_spawn_worker(&ws).await;
        let spawns: Vec<&Command> =
            dispatched.iter().filter(|c| matches!(c, Command::SpawnWorker { .. })).collect();
        assert_eq!(spawns.len(), 1, "the persisted row dispatches one SpawnWorker");
        let Command::SpawnWorker { label, resume_existing, .. } = spawns[0] else {
            panic!("expected SpawnWorker");
        };
        assert_eq!(label, "steward");
        assert_eq!(
            resume_existing.as_deref(),
            Some(session_id.as_str()),
            "the wave resumes the worker onto the id the store holds",
        );
    }

    /// A despawn must still stop the revival. The transcript outlives the
    /// despawn, so a boot wave that went looking for labels on disk would
    /// bring back a worker the user closed.
    #[tokio::test]
    async fn a_despawned_labels_transcript_revives_nothing_at_boot() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, _path, _session_id) = resumable_worker_fixture(&project, &cfg);
        assert!(
            ws.delete_worker_row(&key, "steward").expect("delete the row"),
            "fixture precondition: the despawn took the row",
        );

        ws.respawn_workers_for_lead(&lead_slot(), key, false);

        let dispatched = await_spawn_worker(&ws).await;
        assert!(
            dispatched.iter().all(|c| !matches!(c, Command::SpawnWorker { .. })),
            "the tagged transcript the despawn left is not a reason to bring the worker back",
        );
    }

    /// The MCP path is the only one leads spawn through; its
    /// `from_boot_respawn` must stay false or the cap silently stops
    /// governing exactly the spawns the cap exists for.
    #[tokio::test]
    async fn mcp_spawn_carries_from_boot_respawn_false() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, _path, _session_id) = resumable_worker_fixture(&project, &cfg);
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        // The intercept swallows the command and holds its reply sender,
        // so the facade's await only resolves once the buffer is
        // drained below - which is also where the assertion target
        // comes from.
        let spawner = tokio::spawn(async move {
            let _ = facade
                .spawn_worker(
                    &lead_slot(),
                    "reviewer".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    false,
                    None,
                    None,
                )
                .await;
        });
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
        let from_boot_respawn = loop {
            let drained = ws.drain_test_dispatch_buffer();
            if let Some(from_boot_respawn) = drained.iter().find_map(|cmd| match cmd {
                Command::SpawnWorker { from_boot_respawn, .. } => Some(*from_boot_respawn),
                _ => None,
            }) {
                break from_boot_respawn;
            }
            assert!(
                std::time::Instant::now() < deadline,
                "the MCP spawn never dispatched a SpawnWorker"
            );
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        };
        spawner.await.expect("facade task joins");
        assert!(!from_boot_respawn, "the MCP path is cap-governed, never boot-exempt");
    }

    /// The MCP resume-spawn resolves the label's prior session and
    /// threads it into `Command::SpawnWorker.resume_existing` - the exact
    /// argument the boot re-spawn path fills. The row answers while it is
    /// there, so the id it holds is the one that arrives, not the one in
    /// the label's transcript.
    #[tokio::test]
    async fn mcp_spawn_with_resume_session_threads_the_resolved_session() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, _path, session_id) = resumable_worker_fixture(&project, &cfg);
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resume_existing = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "steward" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("the resume spawn dispatched");
        // The drain above dropped the command's reply sender, so the
        // facade's await resolves to a DispatchFailed we do not assert on.
        let _ = spawner.await.expect("facade task joins");

        assert_eq!(
            resume_existing.as_deref(),
            Some(session_id.as_str()),
            "the facade resumes the id the store holds for the label"
        );
    }

    /// A `resume_session` spawn for a label with nothing to resume starts
    /// a new session rather than refusing: the caller asked for old
    /// context and has to be told it did not get it, but a fresh worker
    /// is usually what it wanted anyway.
    #[tokio::test]
    async fn mcp_spawn_resume_without_prior_session_starts_fresh() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, worktree) = git_worker_fixture(&project, &cfg, "never-used");
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "never-used".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resume_existing = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "never-used" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("a label with no prior session still spawns");
        let _ = spawner.await.expect("facade task joins");

        assert!(resume_existing.is_none(), "there was nothing to resume, so the session is fresh");
        assert!(
            worktree.exists(),
            "the worktree the ensure minted is the directory the fresh session runs in",
        );
    }

    /// A one-commit git repo as the project plus a workspace booted over
    /// a one-project forge.toml naming it. Returns the workspace, the
    /// project's key, and the label's worktree path (not created).
    fn git_worker_fixture(
        project: &tempfile::TempDir,
        cfg: &tempfile::TempDir,
        label: &str,
    ) -> (Arc<Workspace>, crate::target::ProjectKey, PathBuf) {
        let project_path = project.path().to_string_lossy().replace('\\', "/");
        run_git_in(project.path(), &["init", "-q"]);
        run_git_in(project.path(), &["config", "user.email", "t@example.com"]);
        run_git_in(project.path(), &["config", "user.name", "Test"]);
        run_git_in(project.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(project.path().join("README.md"), "seed").expect("write seed");
        run_git_in(project.path(), &["add", "."]);
        run_git_in(project.path(), &["commit", "-q", "-m", "init"]);

        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]
[[orgs.projects]]
name = "demo"
path = "{project_path}"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            ),
        )
        .expect("write forge.toml");

        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let key =
            ws.list_projects().into_iter().find(|v| v.name == "demo").expect("project").key.clone();
        let worktree = project.path().join(".claude").join("worktrees").join(label);
        (ws, key, worktree)
    }

    /// The regression this change exists for: a despawn deletes the
    /// store row, and the row used to be the only pointer to the session
    /// the label resumes onto. The transcript survives the despawn.
    #[tokio::test]
    async fn a_despawned_label_resolves_from_its_transcripts() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        std::fs::create_dir_all(&worktree).expect("worktree dir");
        write_tagged_transcript(&cfg, &worktree, "aaaa", "steward");
        let _store = seed_stored_session(&ws, "steward", "bbbb");
        assert!(
            ws.delete_worker_row(&key, "steward").expect("delete the row"),
            "fixture precondition: the despawn took the row the label used to be found by",
        );

        let found = ws
            .resolve_worker_resume_session("TestOrg", "demo", &worktree, "steward")
            .expect("lookup");
        assert_eq!(
            found,
            ResumeTarget::Found { session_id: "aaaa".to_owned(), restamp: true },
            "the label resolves to its newest transcript, which is what a despawn leaves behind; \
             a pre-field row is flagged for stamping",
        );
    }

    /// The row is authoritative while it exists: a worker already
    /// registered opens from it even where the directory holds a newer
    /// tagged session. The transcripts are the recovery path for a row
    /// that is gone, not the primary.
    #[tokio::test]
    async fn a_registered_labels_row_wins_over_its_transcripts() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        std::fs::create_dir_all(&worktree).expect("worktree dir");
        write_tagged_transcript(&cfg, &worktree, "aaaa", "steward");
        let _store = seed_stored_session(&ws, "steward", "bbbb");

        let found = ws
            .resolve_worker_resume_session("TestOrg", "demo", &worktree, "steward")
            .expect("lookup");
        assert_eq!(
            found,
            ResumeTarget::Found { session_id: "bbbb".to_owned(), restamp: false },
            "the row the label is registered under is what it opens as",
        );
    }

    /// A directory that is there but cannot be read is a failure, not an
    /// absence: a caller told to start fresh would be told a resume
    /// happened on an answer the lookup never gave.
    #[tokio::test]
    async fn an_unreadable_transcript_directory_is_a_failure_not_an_absence() {
        use std::os::unix::fs::PermissionsExt as _;

        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        std::fs::create_dir_all(&worktree).expect("worktree dir");
        write_tagged_transcript(&cfg, &worktree, "aaaa", "steward");
        let dir = worker_transcript_dir(&cfg, &worktree);
        std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o000)).expect("chmod");
        let found = ws.resolve_worker_resume_session("TestOrg", "demo", &worktree, "steward");
        std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o755)).expect("chmod back");

        let error = found.expect_err("a directory that cannot be read is not an absence");
        assert!(
            error.to_string().contains(&dir.to_string_lossy().to_string()),
            "the failure names the directory it could not read: {error}",
        );
    }

    /// Write a `forge:worker:<label>` tagged transcript under the storage
    /// key of `run_dir` - a worktree, or a project root for a worker with
    /// no worktree of its own - computed while that directory exists, the
    /// way claude names the directory at session time.
    fn write_tagged_transcript(
        cfg: &tempfile::TempDir,
        run_dir: &std::path::Path,
        session_id: &str,
        label: &str,
    ) {
        let worktree_str = run_dir.to_string_lossy().replace('\\', "/");
        let jsonl_dir = worker_transcript_dir(cfg, run_dir);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        std::fs::write(
            jsonl_dir.join(format!("{session_id}.jsonl")),
            format!(
                "{{\"type\":\"user\",\"cwd\":\"{worktree_str}\",\"message\":{{\"content\":\"hi\"}}}}\n\
                 {{\"type\":\"tag\",\"tag\":\"forge:worker:{label}\"}}\n"
            ),
        )
        .expect("write tagged jsonl");
    }

    /// Pin a transcript's mtime to a fixed second, so a test that reads
    /// the newest one does not depend on the clock's granularity.
    fn pin_mtime(cfg: &tempfile::TempDir, run_dir: &std::path::Path, id: &str, secs: u64) {
        let path = worker_transcript_dir(cfg, run_dir).join(format!("{id}.jsonl"));
        let file = std::fs::File::options().write(true).open(&path).expect("open the transcript");
        file.set_modified(std::time::UNIX_EPOCH + std::time::Duration::from_secs(secs))
            .expect("pin the transcript's mtime");
    }

    /// The config-dir directory claude writes `run_dir`'s sessions in.
    fn worker_transcript_dir(cfg: &tempfile::TempDir, run_dir: &std::path::Path) -> PathBuf {
        let run_dir_str = run_dir.to_string_lossy().replace('\\', "/");
        let storage_key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&run_dir_str));
        forge_sdk::projects_dir_for(cfg.path()).join(storage_key)
    }

    /// The attach case is the data-loss guard on a path that still
    /// refuses: the branch predates the spawn and holds the worker's only
    /// copy of its commits, so the rollback removes the worktree it
    /// created and spares the branch.
    #[tokio::test]
    async fn mcp_resume_lookup_failure_keeps_a_pre_existing_branch() {
        use std::os::unix::fs::PermissionsExt as _;

        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        let worktree_str = worktree.to_string_lossy().replace('\\', "/");
        run_git_in(
            project.path(),
            &["worktree", "add", "-q", "-b", "worktree-steward", worktree_str.as_str()],
        );
        std::fs::write(worktree.join("work.txt"), "a worker committed here").expect("write work");
        run_git_in(&worktree, &["add", "."]);
        run_git_in(&worktree, &["commit", "-q", "-m", "real work"]);
        write_tagged_transcript(&cfg, &worktree, "550e8400-e29b-41d4-a716-446655440099", "steward");
        let transcripts = worker_transcript_dir(&cfg, &worktree);
        std::fs::set_permissions(&transcripts, std::fs::Permissions::from_mode(0o000))
            .expect("chmod");
        run_git_in(project.path(), &["worktree", "remove", "--force", worktree_str.as_str()]);
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        // The timeout is the assertion for the other direction: a lookup
        // failure that dispatched instead of returning would sit here
        // waiting on a reply nobody sends, which times out the test
        // rather than failing it with this message.
        let err = tokio::time::timeout(
            std::time::Duration::from_secs(5),
            facade.spawn_worker(
                &lead_slot(),
                "steward".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            ),
        )
        .await
        .expect("a failed lookup returns; it does not dispatch and wait on a reply")
        .expect_err("the label's transcript directory cannot be read");
        std::fs::set_permissions(&transcripts, std::fs::Permissions::from_mode(0o755))
            .expect("chmod back");

        assert!(
            matches!(err, crate::mcp::workers::facade::WorkerSpawnError::ResumeLookupFailed { .. }),
            "an unreadable lookup is reported as a failure, got {err:?}",
        );
        assert!(
            ws.drain_test_dispatch_buffer()
                .iter()
                .all(|c| !matches!(c, Command::SpawnWorker { .. })),
            "a failed lookup spawns nothing",
        );
        assert!(!worktree.exists(), "the attached worktree is rolled back");
        assert!(
            forge_agent::env::worktree::branch_ref_exists(project.path(), "worktree-steward"),
            "the pre-existing branch and its commits survive the refusal"
        );
    }

    /// A refusal from the shared guard (label already live) arrives
    /// after dispatch, so the rollback rides the reply path: the
    /// worktree the ensure step minted is removed and its branch reaped.
    #[tokio::test]
    async fn mcp_label_live_refusal_rolls_back_a_minted_worktree() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        let worktree_str = worktree.to_string_lossy().replace('\\', "/");
        run_git_in(
            project.path(),
            &["worktree", "add", "-q", "-b", "worktree-steward", worktree_str.as_str()],
        );
        write_tagged_transcript(&cfg, &worktree, "550e8400-e29b-41d4-a716-446655440099", "steward");
        run_git_in(project.path(), &["worktree", "remove", "--force", worktree_str.as_str()]);
        run_git_in(project.path(), &["branch", "-D", "worktree-steward"]);
        let _store = seed_stored_session(&ws, "steward", "550e8400-e29b-41d4-a716-446655440099");
        // No dispatch intercept: the label-live refusal must come from
        // the real shared core, which fires before any subprocess spawn.
        ws.insert_live_worker(&key, worker_entry("steward"));
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let err = facade
            .spawn_worker(
                &lead_slot(),
                "steward".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            )
            .await
            .expect_err("the label is already live");
        let crate::mcp::workers::facade::WorkerSpawnError::DispatchFailed { message } = err else {
            panic!("the label-live refusal classifies as DispatchFailed, got {err:?}");
        };
        assert!(message.contains("already live"), "the refusal is the label guard: {message}");
        assert!(!worktree.exists(), "the minted worktree is rolled back");
        assert!(
            !forge_agent::env::worktree::branch_ref_exists(project.path(), "worktree-steward"),
            "the minted branch is reaped"
        );
    }

    /// When the recreation itself cannot happen (the label's branch is
    /// checked out in a second worktree, so `git worktree add` refuses),
    /// the lead gets WorktreeCreationFailed and nothing dispatches - a
    /// log-and-continue mutation here would fall through to a scan the
    /// missing worktree makes misleading.
    #[tokio::test]
    async fn mcp_resume_spawn_surfaces_a_failed_worktree_recreation() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        run_git_in(
            project.path(),
            &["worktree", "add", "-q", "-b", "worktree-steward", "elsewhere"],
        );
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let err = facade
            .spawn_worker(
                &lead_slot(),
                "steward".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            )
            .await
            .expect_err("git cannot check the branch out in a second worktree");
        assert!(
            matches!(
                err,
                crate::mcp::workers::facade::WorkerSpawnError::WorktreeCreationFailed { .. }
            ),
            "the recreation failure surfaces typed, got {err:?}"
        );
        assert!(
            ws.drain_test_dispatch_buffer()
                .iter()
                .all(|c| !matches!(c, Command::SpawnWorker { .. })),
            "the failed recreation stops the spawn before dispatch"
        );
        assert!(!worktree.exists(), "the refused add left no worktree behind");
    }

    /// The motivating shape: a git worker despawned (worktree removed),
    /// then re-spawned with `resume_session`. The facade recreates the
    /// worktree before dispatch, because the transcript lives under the
    /// worktree's storage key and the resumed subprocess needs that cwd.
    ///
    /// The project is reached through a symlink so the two spellings of
    /// its worktree path can never agree by accident: the transcript's
    /// dir was named from the real spelling (existing at write time, so
    /// canonicalised), while a scan that runs without the worktree falls
    /// back to the forge.toml spelling. Recreating before the scan is
    /// what makes the two keys meet; reverted, this test fails on every
    /// platform rather than only where the tempdir root is itself a
    /// symlink.
    #[tokio::test]
    async fn mcp_resume_spawn_recreates_a_despawned_worktree() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        run_git_in(project.path(), &["init", "-q"]);
        run_git_in(project.path(), &["config", "user.email", "t@example.com"]);
        run_git_in(project.path(), &["config", "user.name", "Test"]);
        run_git_in(project.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(project.path().join("README.md"), "seed").expect("write seed");
        run_git_in(project.path(), &["add", "."]);
        run_git_in(project.path(), &["commit", "-q", "-m", "init"]);

        let via_link = project.path().join("via-link");
        std::os::unix::fs::symlink(project.path(), &via_link).expect("symlink project root");
        let project_path = via_link.to_string_lossy().replace('\\', "/");

        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]
[[orgs.projects]]
name = "demo"
path = "{project_path}"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            ),
        )
        .expect("write forge.toml");

        let session_id = "550e8400-e29b-41d4-a716-446655440099".to_owned();
        let worktree = project.path().join(".claude").join("worktrees").join("steward");
        let worktree_str = worktree.to_string_lossy().replace('\\', "/");
        run_git_in(
            project.path(),
            &["worktree", "add", "-q", "-b", "worktree-steward", worktree_str.as_str()],
        );
        // The transcript lives under the worktree's storage key in the
        // config dir's projects tree, so it survives the worktree removal.
        let storage_key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&worktree_str));
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(&storage_key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        std::fs::write(
            jsonl_dir.join(format!("{session_id}.jsonl")),
            format!(
                "{{\"type\":\"user\",\"cwd\":\"{worktree_str}\",\"message\":{{\"content\":\"hi\"}}}}\n\
                 {{\"type\":\"tag\",\"tag\":\"forge:worker:steward\"}}\n"
            ),
        )
        .expect("write tagged jsonl");
        // Despawn: remove the worktree the way a clean despawn does.
        run_git_in(project.path(), &["worktree", "remove", "--force", worktree_str.as_str()]);
        assert!(!worktree.exists(), "fixture precondition: the worktree is gone");

        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let _store = seed_stored_session(&ws, "steward", &session_id);
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resume_existing = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "steward" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("the resume spawn dispatched");
        // Same as above: the drain dropped the reply sender, so the
        // facade's own result is not the assertion target here.
        let _ = spawner.await.expect("facade task joins");

        assert!(worktree.exists(), "the facade recreated the worktree the despawn removed");
        assert_eq!(resume_existing.as_deref(), Some(session_id.as_str()));
    }

    /// A resume on a project that is itself a linked worktree: its
    /// workers' worktrees live under the MAIN checkout (#2460), so the
    /// ensure's repo is the main checkout. A leftover directory there is
    /// cleared through that root; composing the project path refuses it as
    /// outside the project's own `.claude/worktrees` and fails the resume.
    #[tokio::test]
    async fn mcp_resume_clears_a_leftover_under_the_main_checkout_for_a_linked_project() {
        let main = tempfile::tempdir().expect("main dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        run_git_in(main.path(), &["init", "-q"]);
        run_git_in(main.path(), &["config", "user.email", "t@example.com"]);
        run_git_in(main.path(), &["config", "user.name", "Test"]);
        run_git_in(main.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(main.path().join("README.md"), "seed").expect("write seed");
        run_git_in(main.path(), &["add", "."]);
        run_git_in(main.path(), &["commit", "-q", "-m", "init"]);
        let main_root = std::fs::canonicalize(main.path()).expect("canonical main");

        let holder = tempfile::tempdir().expect("holder");
        let linked = holder.path().join("linked");
        let linked_str = linked.to_string_lossy().replace('\\', "/");
        run_git_in(&main_root, &["worktree", "add", "-q", "-b", "linked-project", &linked_str]);

        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]
[[orgs.projects]]
name = "demo"
path = "{linked_str}"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            ),
        )
        .expect("write forge.toml");

        let session_id = "550e8400-e29b-41d4-a716-446655440098".to_owned();
        let worktree = main_root.join(".claude").join("worktrees").join("steward");
        let worktree_str = worktree.to_string_lossy().replace('\\', "/");
        run_git_in(&main_root, &["worktree", "add", "-q", "-b", "worktree-steward", &worktree_str]);
        // The transcript lives under the worktree's storage key in the
        // config dir's projects tree, so it survives the worktree removal.
        let storage_key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&worktree_str));
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(&storage_key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        std::fs::write(
            jsonl_dir.join(format!("{session_id}.jsonl")),
            format!(
                "{{\"type\":\"user\",\"cwd\":\"{worktree_str}\",\"message\":{{\"content\":\"hi\"}}}}\n\
                 {{\"type\":\"tag\",\"tag\":\"forge:worker:steward\"}}\n"
            ),
        )
        .expect("write tagged jsonl");
        // The leftover a failed resume path meets: the registration is
        // gone and an empty directory stands where the worktree was.
        run_git_in(&main_root, &["worktree", "remove", "--force", &worktree_str]);
        std::fs::create_dir_all(&worktree).expect("empty leftover");
        assert!(!worktree.join(".git").exists(), "fixture precondition: no registration left");

        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let _store = seed_stored_session(&ws, "steward", &session_id);
        // The worker's own row names the composed path; the collision
        // check must not read that as another project's claim.
        ws.record_worker_row(
            &ws.list_projects().into_iter().next().expect("project").key,
            "steward",
            &session_id,
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
            None,
        )
        .expect("record the worker's own row");
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resume_existing = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "steward" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("the resume spawn dispatched");
        let _ = spawner.await.expect("facade task joins");

        assert!(
            worktree.join(".git").is_file(),
            "the ensure cleared the leftover under the main checkout and rebuilt a worktree there",
        );
        assert!(
            !linked.join(".claude").join("worktrees").join("steward").exists(),
            "nothing is composed under the project path",
        );
        assert_eq!(resume_existing.as_deref(), Some(session_id.as_str()));
    }

    /// A resume never touches another project's worktree: the refusal comes
    /// before the ensure (which can clear a deregistered leftover, rewrite
    /// a link and record ownership) and before the transcript lookup (which
    /// would adopt that project's conversation). A durable row claims the
    /// tree even with no live entry, after a restart.
    #[tokio::test]
    async fn mcp_resume_refuses_a_worktree_another_project_holds() {
        let holder = tempfile::tempdir().expect("holder");
        let main = holder.path().join("main");
        std::fs::create_dir_all(&main).expect("main dir");
        run_git_in(&main, &["init", "-q"]);
        run_git_in(&main, &["config", "user.email", "t@example.com"]);
        run_git_in(&main, &["config", "user.name", "Test"]);
        run_git_in(&main, &["config", "commit.gpgsign", "false"]);
        std::fs::write(main.join("README.md"), "seed").expect("write seed");
        run_git_in(&main, &["add", "."]);
        run_git_in(&main, &["commit", "-q", "-m", "init"]);
        let main = std::fs::canonicalize(&main).expect("canonical main");
        let linked_a = holder.path().join("proj-a");
        let linked_b = holder.path().join("proj-b");
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "proj-a", linked_a.to_str().expect("utf8")],
        );
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "proj-b", linked_b.to_str().expect("utf8")],
        );
        let cfg = tempfile::tempdir().expect("cfg dir");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[orgs.projects]]\nname = \"proj-b\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                linked_a.display(),
                linked_b.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let key_of = |name: &str| {
            ws.list_projects().into_iter().find(|v| v.name == name).expect("project").key
        };
        let session_id = "550e8400-e29b-41d4-a716-446655440085";
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );
        ws.record_worker_row(
            &key_of("proj-b"),
            "shared",
            session_id,
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
            None,
        )
        .expect("record proj-b's row");

        let shared = main.join(".claude").join("worktrees").join("shared");
        std::fs::create_dir_all(shared.parent().expect("worktrees root")).expect("mkdir");
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-shared", shared.to_str().expect("utf8")],
        );
        // proj-a's worker holds the tree, first as a live seat...
        let entry = crate::mcp::workers::types::WorkerEntry {
            label: "shared".to_owned(),
            charter: "test".to_owned(),
            slot: SessionSlot::worker("TestOrg", "proj-a", "shared"),
            session_id: Some(forge_primitives::SessionId::new(
                "550e8400-e29b-41d4-a716-446655440084".to_owned(),
            )),
            status: forge_primitives::WorkerLiveness::Running,
            spawned_at: std::time::SystemTime::UNIX_EPOCH,
            spawned_by: SessionSlot::lead("TestOrg", "proj-a"),
            needs_tag: false,
            is_git_repo_at_spawn: true,
            cwd: None,
            diagnostic: None,
            kick: None,
        };
        ws.insert_live_worker(&key_of("proj-a"), entry);
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let err = facade
            .spawn_worker(
                &SessionSlot::lead("TestOrg", "proj-b"),
                "shared".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            )
            .await
            .expect_err("a live holder refuses the resume");
        let crate::mcp::workers::facade::WorkerSpawnError::WorktreeCreationFailed { reason } = err
        else {
            panic!("the refusal is the worktree guard: {err:?}");
        };
        assert!(reason.contains("worker 'shared'"), "it names the holder: {reason}");
        assert!(reason.contains("proj-a"), "and its project: {reason}");
        assert!(
            !main.join(".git").join("forge-worktrees").exists(),
            "the refused resume never reached the ensure",
        );

        // ...then only as a durable row: after a restart, before proj-a's
        // lead connects, the row still claims the tree.
        ws.remove_latest_worker(&key_of("proj-a"), "shared");
        ws.record_worker_row(
            &key_of("proj-a"),
            "shared",
            "550e8400-e29b-41d4-a716-446655440084",
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
            None,
        )
        .expect("record proj-a's row");
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let err = facade
            .spawn_worker(
                &SessionSlot::lead("TestOrg", "proj-b"),
                "shared".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            )
            .await
            .expect_err("the durable row refuses the resume");
        let crate::mcp::workers::facade::WorkerSpawnError::WorktreeCreationFailed { reason } = err
        else {
            panic!("the refusal is the worktree guard: {err:?}");
        };
        assert!(reason.contains("proj-a"), "the durable row still names its project: {reason}");
        assert!(
            !main.join(".git").join("forge-worktrees").exists(),
            "and nothing was ensured against the other project's tree",
        );
        assert!(shared.exists(), "the other project's tree is untouched");
    }

    /// A resume in one project never adopts another project's conversation:
    /// both compose the same worktree directory, and a Projects-pane close
    /// deletes the row but leaves the tree and its tagged transcript. The
    /// tag's project field is what tells them apart.
    #[tokio::test]
    async fn mcp_resume_does_not_adopt_another_projects_session() {
        let repo = tempfile::tempdir().expect("repo");
        let main = repo.path().join("main");
        std::fs::create_dir_all(&main).expect("main dir");
        run_git_in(&main, &["init", "-q"]);
        run_git_in(&main, &["config", "user.email", "t@example.com"]);
        run_git_in(&main, &["config", "user.name", "Test"]);
        run_git_in(&main, &["config", "commit.gpgsign", "false"]);
        std::fs::write(main.join("README.md"), "seed").expect("write seed");
        run_git_in(&main, &["add", "."]);
        run_git_in(&main, &["commit", "-q", "-m", "init"]);
        let main = std::fs::canonicalize(&main).expect("canonical main");
        let holder = tempfile::tempdir().expect("holder");
        let linked_a = holder.path().join("proj-a");
        let linked_b = holder.path().join("proj-b");
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "proj-a", linked_a.to_str().expect("utf8")],
        );
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "proj-b", linked_b.to_str().expect("utf8")],
        );
        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[orgs.projects]]\nname = \"proj-b\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                linked_a.display(),
                linked_b.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        // The tree both projects compose, left behind by proj-a's closed
        // worker: its row is gone, the tree and its transcript are not.
        let shared = main.join(".claude").join("worktrees").join("shared");
        std::fs::create_dir_all(shared.parent().expect("worktrees root")).expect("mkdir");
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-shared", shared.to_str().expect("utf8")],
        );
        let shared_str = shared.to_string_lossy().replace('\\', "/");
        let key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&shared_str));
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        let theirs = "550e8400-e29b-41d4-a716-446655440080";
        std::fs::write(
            jsonl_dir.join(format!("{theirs}.jsonl")),
            format!(
                "{{\"type\":\"user\",\"cwd\":\"{shared_str}\"}}\n\
                 {{\"type\":\"tag\",\"tag\":\"forge:worker:shared\",\
                 \"project\":\"TestOrg/proj-a\"}}\n"
            ),
        )
        .expect("write proj-a's tagged transcript");

        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &SessionSlot::lead("TestOrg", "proj-b"),
                    "shared".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resumed = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "shared" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("the resume spawn dispatched");
        let _ = spawner.await.expect("facade task joins");
        assert_eq!(
            resumed, None,
            "proj-b must not adopt proj-a's session from the shared directory",
        );

        // The proxy: proj-b's own tagged transcript IS adopted.
        let mine = "550e8400-e29b-41d4-a716-446655440081";
        std::fs::write(
            jsonl_dir.join(format!("{mine}.jsonl")),
            format!(
                "{{\"type\":\"user\",\"cwd\":\"{shared_str}\"}}\n\
                 {{\"type\":\"tag\",\"tag\":\"forge:worker:shared\",\
                 \"project\":\"TestOrg/proj-b\"}}\n"
            ),
        )
        .expect("write proj-b's tagged transcript");
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &SessionSlot::lead("TestOrg", "proj-b"),
                    "shared".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resumed = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "shared" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("the resume spawn dispatched");
        let _ = spawner.await.expect("facade task joins");
        assert_eq!(
            resumed.as_deref(),
            Some(mine),
            "proj-b's own tagged session is the one resumed",
        );
    }

    /// A pre-field tag row is adopted once and stamped by that adoption:
    /// the second project's resume skips it, and a later unstamped row in
    /// a directory two projects compose is refused as ambiguous instead
    /// of being handed to either.
    #[tokio::test]
    async fn a_pre_field_transcript_is_adopted_once_and_stamped() {
        let repo = tempfile::tempdir().expect("repo");
        let main = repo.path().join("main");
        std::fs::create_dir_all(&main).expect("main dir");
        run_git_in(&main, &["init", "-q"]);
        run_git_in(&main, &["config", "user.email", "t@example.com"]);
        run_git_in(&main, &["config", "user.name", "Test"]);
        run_git_in(&main, &["config", "commit.gpgsign", "false"]);
        std::fs::write(main.join("README.md"), "seed").expect("write seed");
        run_git_in(&main, &["add", "."]);
        run_git_in(&main, &["commit", "-q", "-m", "init"]);
        let main = std::fs::canonicalize(&main).expect("canonical main");
        let holder = tempfile::tempdir().expect("holder");
        let linked_a = holder.path().join("proj-a");
        let linked_b = holder.path().join("proj-b");
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "proj-a", linked_a.to_str().expect("utf8")],
        );
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "proj-b", linked_b.to_str().expect("utf8")],
        );
        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                linked_a.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        let shared = main.join(".claude").join("worktrees").join("shared");
        std::fs::create_dir_all(shared.parent().expect("worktrees root")).expect("mkdir");
        run_git_in(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-shared", shared.to_str().expect("utf8")],
        );
        let shared_str = shared.to_string_lossy().replace('\\', "/");
        let key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&shared_str));
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        let theirs = "550e8400-e29b-41d4-a716-446655440082";
        let unstamped = format!(
            "{{\"type\":\"user\",\"cwd\":\"{shared_str}\"}}\n\
             {{\"type\":\"tag\",\"tag\":\"forge:worker:shared\"}}\n"
        );
        std::fs::write(jsonl_dir.join(format!("{theirs}.jsonl")), &unstamped)
            .expect("write the pre-field transcript");

        let resume_as = |project: &'static str| {
            let ws = Arc::clone(&ws);
            async move {
                ws.enable_test_dispatch_intercept();
                let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
                let spawner = tokio::spawn(async move {
                    facade
                        .spawn_worker(
                            &SessionSlot::lead("TestOrg", project),
                            "shared".to_owned(),
                            "charter".to_owned(),
                            None,
                            None,
                            false,
                            true,
                            None,
                            None,
                        )
                        .await
                });
                let resumed = poll_spawn_worker_field(&ws, |cmd| match cmd {
                    Command::SpawnWorker { label, resume_existing, .. } if label == "shared" => {
                        Some(resume_existing.clone())
                    }
                    _ => None,
                })
                .await;
                let _ = spawner.await.expect("facade task joins");
                resumed
            }
        };

        // One project composes the directory, so the pre-field row is
        // adopted - and stamped by that adoption.
        let resumed = resume_as("proj-a").await.expect("dispatched");
        assert_eq!(resumed.as_deref(), Some(theirs), "the pre-field row is adopted once");
        let body = std::fs::read_to_string(jsonl_dir.join(format!("{theirs}.jsonl")))
            .expect("read the stamped transcript");
        assert!(
            body.contains("\"project\":\"TestOrg/proj-a\""),
            "the adoption stamped the row: {body:?}",
        );

        // A second project composing the same directory now sees the
        // stamped row as proj-a's and starts fresh.
        ws.seed_test_project("proj-b", &linked_b.to_string_lossy());
        let resumed = resume_as("proj-b").await.expect("dispatched");
        assert_eq!(resumed, None, "the stamped row is not the second project's to adopt");

        // An unstamped row in the now-shared directory is ambiguous: the
        // resume is refused rather than handed to either project.
        let newer = "550e8400-e29b-41d4-a716-446655440083";
        std::fs::write(jsonl_dir.join(format!("{newer}.jsonl")), &unstamped)
            .expect("write another pre-field transcript");
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &SessionSlot::lead("TestOrg", "proj-b"),
                    "shared".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        // A refusal returns without dispatching; a dispatch would block
        // on the intercept, so the timeout is the fail-fast guard.
        let err = tokio::time::timeout(std::time::Duration::from_secs(5), spawner)
            .await
            .expect("the refusal returns without dispatching")
            .expect("facade task joins")
            .expect_err("an ambiguous pre-field row is refused");
        let crate::mcp::workers::facade::WorkerSpawnError::ResumeLookupFailed { message, .. } = err
        else {
            panic!("the refusal is the lookup: {err:?}");
        };
        assert!(message.contains("predates project tags"), "the refusal says why: {message}");
    }

    /// A stamp that fails after the ensure undoes the worktree it minted,
    /// so a refused adoption strands neither worktree nor branch.
    #[tokio::test]
    async fn a_failed_stamp_discards_the_worktree_the_resume_minted() {
        let repo = tempfile::tempdir().expect("repo");
        let main = repo.path().join("main");
        std::fs::create_dir_all(&main).expect("main dir");
        run_git_in(&main, &["init", "-q"]);
        run_git_in(&main, &["config", "user.email", "t@example.com"]);
        run_git_in(&main, &["config", "user.name", "Test"]);
        run_git_in(&main, &["config", "commit.gpgsign", "false"]);
        std::fs::write(main.join("README.md"), "seed").expect("write seed");
        run_git_in(&main, &["add", "."]);
        run_git_in(&main, &["commit", "-q", "-m", "init"]);
        let main = std::fs::canonicalize(&main).expect("canonical main");
        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"demo\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                main.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        let shared = main.join(".claude").join("worktrees").join("shared");
        let shared_str = shared.to_string_lossy().replace('\\', "/");
        let key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&shared_str));
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        let theirs = "550e8400-e29b-41d4-a716-446655440084";
        let transcript = jsonl_dir.join(format!("{theirs}.jsonl"));
        std::fs::write(
            &transcript,
            format!(
                "{{\"type\":\"user\",\"cwd\":\"{shared_str}\"}}\n\
                 {{\"type\":\"tag\",\"tag\":\"forge:worker:shared\"}}\n"
            ),
        )
        .expect("write the pre-field transcript");
        let mut perms = std::fs::metadata(&transcript).expect("stat").permissions();
        perms.set_readonly(true);
        std::fs::set_permissions(&transcript, perms).expect("make the transcript read-only");

        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let err = tokio::time::timeout(
            std::time::Duration::from_secs(10),
            facade.spawn_worker(
                &SessionSlot::lead("TestOrg", "demo"),
                "shared".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            ),
        )
        .await
        .expect("the refused spawn returns")
        .expect_err("a transcript that cannot be stamped refuses the resume");
        let crate::mcp::workers::facade::WorkerSpawnError::DispatchFailed { message } = err else {
            panic!("the refusal is the stamp: {err:?}");
        };
        assert!(
            message.contains("stamping the adopted transcript's project failed"),
            "the refusal names the stamp: {message}",
        );
        assert!(!shared.exists(), "the ensure's worktree was discarded with the refusal");
    }

    /// The transcript lookup keys a directory by its sanitised path, so
    /// two non-git projects at `a-b` and `a/b` read the same transcripts.
    /// A pre-field tag there is not known to be either project's, so both
    /// refuse it instead of the first adopter taking the other's
    /// conversation.
    #[tokio::test]
    async fn colliding_transcript_keys_refuse_a_pre_field_adoption_in_both_projects() {
        let holder = tempfile::tempdir().expect("holder");
        let a_dir = holder.path().join("a-b");
        let b_dir = holder.path().join("a").join("b");
        std::fs::create_dir_all(&a_dir).expect("a-b dir");
        std::fs::create_dir_all(&b_dir).expect("a/b dir");
        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[orgs.projects]]\nname = \"proj-b\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                a_dir.display(),
                b_dir.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        let a_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &a_dir.to_string_lossy(),
        ));
        let b_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &b_dir.to_string_lossy(),
        ));
        assert_eq!(a_key, b_key, "the fixture's two roots sanitise to one transcript key");
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(&a_key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        let theirs = "550e8400-e29b-41d4-a716-446655440090";
        std::fs::write(
            jsonl_dir.join(format!("{theirs}.jsonl")),
            "{\"type\":\"user\",\"cwd\":\"/somewhere\"}\n\
             {\"type\":\"tag\",\"tag\":\"forge:worker:shared\"}\n",
        )
        .expect("write the pre-field transcript");

        let resume = |project: &'static str| {
            let ws = Arc::clone(&ws);
            async move {
                let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
                tokio::time::timeout(
                    std::time::Duration::from_secs(5),
                    facade.spawn_worker(
                        &SessionSlot::lead("TestOrg", project),
                        "shared".to_owned(),
                        "charter".to_owned(),
                        None,
                        None,
                        false,
                        true,
                        None,
                        None,
                    ),
                )
                .await
                .expect("the spawn returns")
            }
        };

        for project in ["proj-a", "proj-b"] {
            let err = match resume(project).await {
                Ok(reply) => panic!("{project} adopted the colliding transcript: {reply:?}"),
                Err(err) => err,
            };
            let crate::mcp::workers::facade::WorkerSpawnError::ResumeLookupFailed {
                message, ..
            } = err
            else {
                panic!("{project}'s refusal is the lookup: {err:?}");
            };
            assert!(
                message.contains("predates project tags"),
                "{project} refuses the ambiguous row: {message}",
            );
        }
    }

    /// Two git projects whose composed worker trees sanitise to one key
    /// (`a-b` and `a/b`) read the same transcripts, so a pre-field tag
    /// there is ambiguous and both refuse it.
    #[tokio::test]
    async fn colliding_worktree_keys_refuse_a_pre_field_adoption_in_both_git_projects() {
        let holder = tempfile::tempdir().expect("holder");
        let a_dir = holder.path().join("a-b");
        let b_dir = holder.path().join("a").join("b");
        for dir in [&a_dir, &b_dir] {
            std::fs::create_dir_all(dir).expect("project dir");
            run_git_in(dir, &["init", "-q"]);
            run_git_in(dir, &["config", "user.email", "t@example.com"]);
            run_git_in(dir, &["config", "user.name", "Test"]);
            run_git_in(dir, &["config", "commit.gpgsign", "false"]);
            std::fs::write(dir.join("README.md"), "seed").expect("write seed");
            run_git_in(dir, &["add", "."]);
            run_git_in(dir, &["commit", "-q", "-m", "init"]);
        }
        let a_dir = std::fs::canonicalize(&a_dir).expect("canonical a-b");
        let b_dir = std::fs::canonicalize(&b_dir).expect("canonical a/b");
        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[orgs.projects]]\nname = \"proj-b\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                a_dir.display(),
                b_dir.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        let a_run = a_dir.join(".claude").join("worktrees").join("shared");
        let b_run = b_dir.join(".claude").join("worktrees").join("shared");
        let a_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &a_run.to_string_lossy(),
        ));
        let b_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &b_run.to_string_lossy(),
        ));
        assert_eq!(a_key, b_key, "the composed worktrees sanitise to one transcript key");
        let jsonl_dir = forge_sdk::projects_dir_for(cfg.path()).join(&a_key);
        std::fs::create_dir_all(&jsonl_dir).expect("jsonl dir");
        let theirs = "550e8400-e29b-41d4-a716-446655440091";
        std::fs::write(
            jsonl_dir.join(format!("{theirs}.jsonl")),
            "{\"type\":\"user\",\"cwd\":\"/somewhere\"}\n\
             {\"type\":\"tag\",\"tag\":\"forge:worker:shared\"}\n",
        )
        .expect("write the pre-field transcript");

        let resume = |project: &'static str| {
            let ws = Arc::clone(&ws);
            async move {
                let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
                tokio::time::timeout(
                    std::time::Duration::from_secs(15),
                    facade.spawn_worker(
                        &SessionSlot::lead("TestOrg", project),
                        "shared".to_owned(),
                        "charter".to_owned(),
                        None,
                        None,
                        false,
                        true,
                        None,
                        None,
                    ),
                )
                .await
                .expect("the spawn returns")
            }
        };

        for project in ["proj-a", "proj-b"] {
            let err = match resume(project).await {
                Ok(reply) => panic!("{project} adopted the colliding transcript: {reply:?}"),
                Err(err) => err,
            };
            let crate::mcp::workers::facade::WorkerSpawnError::ResumeLookupFailed {
                message, ..
            } = err
            else {
                panic!("{project}'s refusal is the lookup: {err:?}");
            };
            assert!(
                message.contains("predates project tags"),
                "{project} refuses the ambiguous row: {message}",
            );
        }
    }

    /// A git project whose checkout path collides with a non-git
    /// project's root does not read that root's transcripts: its worker
    /// runs under `.claude/worktrees`, so it is not counted as composing
    /// the directory.
    #[tokio::test]
    async fn a_colliding_git_checkout_is_not_counted_as_composing() {
        let holder = tempfile::tempdir().expect("holder");
        let a_dir = holder.path().join("a-b");
        let b_dir = holder.path().join("a").join("b");
        std::fs::create_dir_all(&a_dir).expect("a-b dir");
        std::fs::create_dir_all(&b_dir).expect("a/b dir");
        run_git_in(&b_dir, &["init", "-q"]);
        let a_dir = std::fs::canonicalize(&a_dir).expect("canonical a-b");
        let b_dir = std::fs::canonicalize(&b_dir).expect("canonical a/b");
        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[orgs.projects]]\nname = \"proj-b\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                a_dir.display(),
                b_dir.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        assert_eq!(
            ws.projects_composing(&a_dir, "shared"),
            vec![("TestOrg".to_owned(), "proj-a".to_owned())],
            "the git checkout that only shares the sanitised key is not counted",
        );
    }

    /// A worker directory that is gone still names the project whose
    /// worktree it was, even when the tag row spells the root through a
    /// symlink: nothing below the root exists, so nothing can be
    /// canonicalised, and both sides have to resolve the same existing
    /// prefix to compare equal.
    #[tokio::test]
    async fn a_gone_worker_dir_behind_a_symlink_still_names_its_project() {
        let holder = tempfile::tempdir().expect("holder");
        let real = holder.path().join("real");
        let project = real.join("proj");
        std::fs::create_dir_all(&project).expect("project dir");
        run_git_in(&project, &["init", "-q"]);
        let link = holder.path().join("link");
        std::os::unix::fs::symlink(&real, &link).expect("symlink");

        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                project.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        let gone = link.join("proj").join(".claude/worktrees/shared");
        assert!(!gone.exists(), "the worker's tree is gone, which is the case under test");
        assert_eq!(
            ws.projects_composing(&gone, "shared"),
            vec![("TestOrg".to_owned(), "proj-a".to_owned())],
            "a gone worker dir behind a symlink names its project",
        );
    }

    /// The other comparison is the sanitised key, and it is built from the
    /// resolved spelling: a run directory that resolves to a different path
    /// from the project's worker directory but sanitises to the same key
    /// still names the project.
    #[tokio::test]
    async fn a_sanitised_key_names_its_project_from_the_resolved_spelling() {
        let holder = tempfile::tempdir().expect("holder");
        let real = holder.path().join("real");
        let project = real.join("a-b");
        std::fs::create_dir_all(&project).expect("project dir");
        run_git_in(&project, &["init", "-q"]);
        // The run dir's existing ancestor: its last components are gone, so
        // only the prefix can be canonicalised.
        std::fs::create_dir_all(real.join("a")).expect("the run dir's existing ancestor");
        let link = holder.path().join("link");
        std::os::unix::fs::symlink(&real, &link).expect("symlink");

        let cfg = tempfile::tempdir().expect("cfg");
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                "[[orgs]]\nname = \"TestOrg\"\naccounts = [\"acct-a\"]\n\
                 [[orgs.projects]]\nname = \"proj-a\"\npath = \"{}\"\n\
                 [[accounts]]\ndisplay_name = \"acct-a\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n",
                project.display()
            ),
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let store = tempfile::tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );

        // Resolves to `real/a/b/.claude/worktrees/shared`, which sanitises to
        // the same key as the project's `real/a-b/.claude/worktrees/shared`.
        // Both paths are far under the 200-character sanitise cap, so the key
        // is the plain substitution rather than a truncated-and-hashed one.
        let gone = link.join("a/b").join(".claude/worktrees/shared");
        assert!(!gone.exists(), "the run directory is gone, which is the case under test");
        assert_eq!(
            ws.projects_composing(&gone, "shared"),
            vec![("TestOrg".to_owned(), "proj-a".to_owned())],
            "a sanitised key from the resolved spelling names its project",
        );
    }

    /// The mirror of the recreation case: the row says the worker runs in
    /// the project root, and the project is a repo. The ensure has to read
    /// the ROW, as the spawn does, or it mints a worktree the resumed
    /// session will not run in and nothing will clean up.
    #[tokio::test]
    async fn mcp_resume_does_not_ensure_a_worktree_the_row_does_not_use() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        let session_id = "550e8400-e29b-41d4-a716-446655440099";
        let dir = tempfile::tempdir().expect("tempdir");
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        ws.record_worker_row(
            &key,
            "steward",
            session_id,
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
            None,
        )
        .expect("seed the row that disagrees with the disk");
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, .. } if label == "steward" => Some(()),
            _ => None,
        })
        .await
        .expect("the resume spawn dispatched");
        let _ = spawner.await.expect("facade task joins");

        assert!(
            !worktree.exists(),
            "the ensure must follow the row's recorded gitness, not probe the project: \
             this row runs in the project root, so no worktree belongs here",
        );
    }

    /// The sequence the regression turned on: a worker spawns - the row
    /// the spawn handler writes and the transcript claude writes in the
    /// worktree are what it leaves behind - then it is despawned, row
    /// deleted and worktree gone. The transcript is not the despawn's to
    /// remove, so the label spawns again onto the session it ran under.
    #[tokio::test]
    async fn a_despawned_label_spawns_again_onto_its_session() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, worktree) = git_worker_fixture(&project, &cfg, "steward");
        let worktree_str = worktree.to_string_lossy().replace('\\', "/");
        let session_id = "550e8400-e29b-41d4-a716-446655440099";
        run_git_in(
            project.path(),
            &["worktree", "add", "-q", "-b", "worktree-steward", worktree_str.as_str()],
        );
        write_tagged_transcript(&cfg, &worktree, session_id, "steward");
        let _store = seed_stored_session(&ws, "steward", session_id);
        assert!(ws.delete_worker_row(&key, "steward").expect("delete the row"));
        run_git_in(project.path(), &["worktree", "remove", "--force", worktree_str.as_str()]);
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let Command::SpawnWorker { resume_existing, mcp_families, return_to, .. } =
            take_dispatched_spawn_worker(&ws).await
        else {
            panic!("expected the resume to dispatch a SpawnWorker");
        };
        assert_eq!(
            resume_existing.as_deref(),
            Some(session_id),
            "the label resumes the session its transcript still names",
        );
        // The row is gone (that is what the despawn did), so the spawn
        // legitimately carries no selection: every family.
        assert_eq!(mcp_families, None, "no row means no narrowing");
        // Answer the way `handle_spawn_worker` does for a resume; what
        // the assertion below reads is the facade's own mapping of it,
        // which reports a fallback for a resume that found nothing.
        return_to
            .expect("a dispatch off the workspace's own bus carries a reply channel")
            .send(Ok(WorkerSpawnReply {
                session_id: session_id.to_owned(),
                tag: forge_primitives::worker_tag("steward"),
                mcp_families: None,
                rate_limited_account: None,
                durability_warning: None,
                worktree: None,
                session_choice: SessionChoice::Resumed,
            }))
            .expect("the facade is awaiting its reply");
        let reply = spawner.await.expect("facade task joins").expect("the resume is not an error");

        assert_eq!(
            reply.session_choice,
            SessionChoice::Resumed,
            "a resume that found its session reports the resume, not a fallback",
        );
        assert!(worktree.exists(), "and lands back in the worktree the despawn removed");
    }

    /// A worker in a project that is not a git repo runs in the project
    /// root, so its sessions live in the project's own transcript
    /// directory - the one holding every session that ever ran there.
    /// The label's tag is what picks its own out of that, once the row a
    /// despawn deleted is gone.
    #[tokio::test]
    async fn a_despawned_non_git_label_spawns_again_onto_its_session() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, project_path, session_id) = resumable_worker_fixture(&project, &cfg);
        write_tagged_transcript(&cfg, &project_path, &session_id, "steward");
        // Newer, and not this label's: the directory is shared, so
        // newest-in-directory would hand the lead's own work to the
        // worker.
        write_tagged_transcript(
            &cfg,
            &project_path,
            "550e8400-e29b-41d4-a716-4466554400ff",
            "lead",
        );
        // The pick is by mtime, and a tie goes to the greater session id.
        // Pin the two, so "the test's is newer" is a fact of the fixture
        // rather than of the filesystem's clock granularity: on a coarse
        // one both writes land in the same tick, and the tie then hands
        // the win to the fixture's `660e...` over the test's `550e...`.
        pin_mtime(&cfg, &project_path, TRANSCRIPT_ONLY_ID, TRANSCRIPT_OLDER_SECS);
        pin_mtime(&cfg, &project_path, &session_id, TRANSCRIPT_NEWER_SECS);
        assert!(ws.delete_worker_row(&key, "steward").expect("delete the row"));
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let resumed = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { label, resume_existing, .. } if label == "steward" => {
                Some(resume_existing.clone())
            }
            _ => None,
        })
        .await
        .expect("the despawned label spawns again");
        let _ = spawner.await.expect("facade task joins");

        assert_eq!(
            resumed.as_deref(),
            Some(session_id.as_str()),
            "the label resumes its own session, not the newest one in the directory",
        );
    }

    /// The other half: a resume with nothing to resume starts fresh, and
    /// the reply the tool renders says which happened - a caller that
    /// asked for old context is never left believing it got some.
    #[tokio::test]
    async fn a_resume_with_nothing_to_resume_reports_a_fresh_session() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, _worktree) = git_worker_fixture(&project, &cfg, "ghost");
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "ghost".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });
        let Command::SpawnWorker { resume_existing, return_to, .. } =
            take_dispatched_spawn_worker(&ws).await
        else {
            panic!("expected the fallback to dispatch a SpawnWorker");
        };
        assert!(resume_existing.is_none(), "nothing to resume, so the session is fresh");
        // Answer the way `handle_spawn_worker` does for a spawn carrying
        // no `resume_existing`, which is what a fallback dispatches -
        // whatever flag the caller passed. Whether it asked to resume and
        // found nothing is known only to the facade, which restates it.
        return_to
            .expect("a dispatch off the workspace's own bus carries a reply channel")
            .send(Ok(WorkerSpawnReply {
                session_id: "fresh-session-uuid".into(),
                tag: forge_primitives::worker_tag("ghost"),
                mcp_families: None,
                rate_limited_account: None,
                durability_warning: None,
                worktree: None,
                session_choice: SessionChoice::Fresh,
            }))
            .expect("the facade is awaiting its reply");
        let reply =
            spawner.await.expect("facade task joins").expect("the fallback is not an error");

        assert_eq!(
            reply.session_choice,
            SessionChoice::FreshWithoutPrior,
            "a resume that found nothing reports the fallback, not a plain fresh spawn",
        );
    }

    /// The third outcome, one arm over from the fallback: a spawn that
    /// never asked to resume reports a plain fresh session, so a lead that
    /// set no flag is not told a lookup found nothing.
    #[tokio::test]
    async fn a_spawn_without_the_flag_reports_a_plain_fresh_session() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _key, _worktree) = git_worker_fixture(&project, &cfg, "ghost");
        ws.enable_test_dispatch_intercept();
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);

        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "ghost".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    false,
                    None,
                    None,
                )
                .await
        });
        let Command::SpawnWorker { resume_existing, return_to, .. } =
            take_dispatched_spawn_worker(&ws).await
        else {
            panic!("expected the plain spawn to dispatch a SpawnWorker");
        };
        assert!(resume_existing.is_none(), "the flag was not set, so nothing is resumed");
        return_to
            .expect("a dispatch off the workspace's own bus carries a reply channel")
            .send(Ok(WorkerSpawnReply {
                session_id: "fresh-session-uuid".into(),
                tag: forge_primitives::worker_tag("ghost"),
                mcp_families: None,
                rate_limited_account: None,
                durability_warning: None,
                worktree: None,
                session_choice: SessionChoice::Fresh,
            }))
            .expect("the facade is awaiting its reply");
        let reply = spawner.await.expect("facade task joins").expect("the spawn is not an error");

        assert_eq!(
            reply.session_choice,
            SessionChoice::Fresh,
            "a spawn that never asked to resume is not a resume that found nothing",
        );
    }

    /// The first `SpawnWorker` a facade dispatched, taken whole so the
    /// test can answer its reply channel the way the spawn handler would.
    async fn take_dispatched_spawn_worker(ws: &Arc<Workspace>) -> Command {
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
        loop {
            if let Some(cmd) = ws
                .drain_test_dispatch_buffer()
                .into_iter()
                .find(|c| matches!(c, Command::SpawnWorker { .. }))
            {
                return cmd;
            }
            assert!(std::time::Instant::now() < deadline, "no SpawnWorker was dispatched");
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }
    }

    fn run_git_in(dir: &std::path::Path, args: &[&str]) {
        let status = std::process::Command::new("git")
            .args(args)
            .current_dir(dir)
            .status()
            .expect("spawn git");
        assert!(status.success(), "git {args:?} failed in {dir:?}");
    }

    /// Record `id` as the store's answer for `label` in the `demo`
    /// project. A resume reads the store, so a test that expects one has
    /// to put the id there; `new_for_test` boots without a store, so
    /// this installs one. The tempdir must outlive the caller.
    fn seed_stored_session(ws: &Arc<Workspace>, label: &str, id: &str) -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        ws.install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        ws.record_session_id("TestOrg", "demo", label, id);
        dir
    }

    /// Poll the intercept buffer until `pick` matches a SpawnWorker or
    /// the deadline passes; the dispatch happens inside the facade's
    /// awaited dispatch and the buffer holds the command until drained.
    async fn poll_spawn_worker_field<T>(
        ws: &Arc<Workspace>,
        pick: impl Fn(&Command) -> Option<T>,
    ) -> Option<T> {
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
        loop {
            let drained = ws.drain_test_dispatch_buffer();
            let picked = drained.iter().find_map(&pick);
            if picked.is_some() {
                return picked;
            }
            if std::time::Instant::now() >= deadline {
                return None;
            }
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }
    }

    /// D7: a resume that states no tree resumes the one the ROW records.
    /// The subprocess has to start where the JSONL lives, and for a
    /// worker the spawn pointed at another repository that is its own
    /// tree - the project's path would send the resume looking under a
    /// directory nothing was ever written to.
    #[tokio::test]
    async fn a_resume_without_a_stated_cwd_adopts_the_rows_tree() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        run_git_in(project.path(), &["init", "-q"]);
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]
[[orgs.projects]]
name = "demo"
path = "{}"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                project.path().to_string_lossy().replace('\\', "/")
            ),
        )
        .expect("write forge.toml");

        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let view = ws.list_projects().into_iter().find(|v| v.name == "demo").expect("project");
        let _store = seed_stored_session(&ws, "steward", "550e8400-e29b-41d4-a716-446655440099");
        // The tree the spawn resolved: a second repository, with the
        // worktree claude's `--worktree` would have forked there.
        let sibling = tempfile::tempdir().expect("sibling repo");
        run_git_in(sibling.path(), &["init", "-q"]);
        run_git_in(sibling.path(), &["config", "commit.gpgsign", "false"]);
        let root = std::fs::canonicalize(sibling.path()).expect("canonical sibling");
        ws.seed_test_worker_row_at(&view.key, "steward", &root.to_string_lossy(), true);
        let worktree = root.join(".claude").join("worktrees").join("steward");
        run_git_in(
            &root,
            &["worktree", "add", "-q", "-b", "worktree-steward", worktree.to_str().expect("utf8")],
        );
        ws.enable_test_dispatch_intercept();

        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    None,
                )
                .await
        });

        let dispatched = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { cwd, .. } => Some(cwd.clone()),
            _ => None,
        })
        .await;
        assert_eq!(
            dispatched.flatten().as_deref(),
            Some(root.to_string_lossy().as_ref()),
            "the resume carries the row's tree, not the project's",
        );
        spawner.abort();
    }

    /// A resume that states a DIFFERENT tree than the row's is refused
    /// rather than started: claude finds a conversation by the project
    /// key derived from the directory it runs in, so a moved resume dies
    /// "No conversation found" - the history is keyed to its tree, and a
    /// worker moves trees only by being despawned and spawned fresh.
    #[tokio::test]
    async fn a_resume_stating_a_different_tree_is_refused() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        run_git_in(project.path(), &["init", "-q"]);
        let forge_dir = cfg.path().join("forge");
        std::fs::create_dir_all(&forge_dir).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            format!(
                r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]
[[orgs.projects]]
name = "demo"
path = "{}"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                project.path().to_string_lossy().replace('\\', "/")
            ),
        )
        .expect("write forge.toml");

        let ws = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("boot"));
        let view = ws.list_projects().into_iter().find(|v| v.name == "demo").expect("project");
        let _store = seed_stored_session(&ws, "steward", "550e8400-e29b-41d4-a716-446655440099");
        // The row the history lives under: its own repository.
        let home_tree = tempfile::tempdir().expect("worker tree");
        run_git_in(home_tree.path(), &["init", "-q"]);
        let home_root = std::fs::canonicalize(home_tree.path()).expect("canonical home");
        ws.seed_test_worker_row_at(&view.key, "steward", &home_root.to_string_lossy(), true);
        // A different tree the caller asks the resume to move to.
        let other = tempfile::tempdir().expect("other tree");
        run_git_in(other.path(), &["init", "-q"]);
        let other_root = std::fs::canonicalize(other.path()).expect("canonical other");
        ws.enable_test_dispatch_intercept();

        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&ws);
        // The timeout is the assertion for the other direction: a
        // resume that dispatched instead of refusing would sit here
        // waiting on a reply nobody sends, which times out the test
        // rather than failing it with this message.
        let error = tokio::time::timeout(
            std::time::Duration::from_secs(5),
            facade.spawn_worker(
                &lead_slot(),
                "steward".to_owned(),
                "charter".to_owned(),
                None,
                None,
                false,
                true,
                None,
                Some(other_root.to_string_lossy().into_owned()),
            ),
        )
        .await
        .expect("the refusal answers without dispatching")
        .expect_err("a resume cannot move the worker's tree");

        let crate::mcp::workers::facade::WorkerSpawnError::DispatchFailed { message } = error
        else {
            panic!("the refusal is a dispatch failure");
        };
        assert!(
            message.contains("history"),
            "the refusal says why the tree cannot move: {message}",
        );
        assert!(
            ws.drain_test_dispatch_buffer().is_empty(),
            "nothing was dispatched for a refused resume",
        );

        // The control, and the arm a guard that refused every stated tree
        // would break: a resume stating the row's OWN tree is accepted, and
        // dispatches with that tree.
        let stated = home_root.to_string_lossy().into_owned();
        let spawner = tokio::spawn(async move {
            facade
                .spawn_worker(
                    &lead_slot(),
                    "steward".to_owned(),
                    "charter".to_owned(),
                    None,
                    None,
                    false,
                    true,
                    None,
                    Some(stated),
                )
                .await
        });
        let dispatched = poll_spawn_worker_field(&ws, |cmd| match cmd {
            Command::SpawnWorker { cwd, .. } => Some(cwd.clone()),
            _ => None,
        })
        .await;
        assert_eq!(
            dispatched.flatten().as_deref(),
            Some(home_root.to_string_lossy().as_ref()),
            "a resume stating the tree the history lives in is accepted and carries it",
        );
        spawner.abort();
    }

    /// `--new`: the same fixture comes up fresh, so the worker that
    /// WOULD have resumed spawns fresh. Paired with the resume test
    /// deliberately - against a fixture with nothing stored both arms
    /// yield None and the branch is unobservable.
    #[tokio::test]
    async fn force_new_spawns_fresh_the_worker_the_scan_would_have_resumed() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, key, _path, _session_id) = resumable_worker_fixture(&project, &cfg);

        ws.respawn_workers_for_lead(&lead_slot(), key, true);

        let dispatched = await_spawn_worker(&ws).await;
        let spawns: Vec<&Command> =
            dispatched.iter().filter(|c| matches!(c, Command::SpawnWorker { .. })).collect();
        assert_eq!(spawns.len(), 1, "force_new still spawns the persisted worker");
        let Command::SpawnWorker { resume_existing, .. } = spawns[0] else {
            panic!("expected SpawnWorker");
        };
        assert!(
            resume_existing.is_none(),
            "force_new skips the scan, so a resumable worker still spawns fresh",
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]
mod async_worker_spawn_failure_tests {
    use super::*;
    use crate::mcp::workers::types::WorkerEntry;
    use forge_agent::client::SpawnFailureKind;

    fn fake_worker(label: &str, worker_key: &str, lead_id: &str, is_git: bool) -> WorkerEntry {
        WorkerEntry {
            label: label.to_owned(),
            charter: "test".to_owned(),
            slot: SessionSlot::from_str_for_test(worker_key),
            session_id: None,
            status: forge_primitives::WorkerLiveness::Spawning,
            spawned_at: std::time::SystemTime::UNIX_EPOCH,
            spawned_by: SessionSlot::from_str_for_test(lead_id),
            needs_tag: true,
            is_git_repo_at_spawn: is_git,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    /// Seed the workspace pool with a stub Agent so the notice
    /// dispatch's `pool.lock().contains_key(&lead_key)` lead-
    /// resolution check passes. Mirrors the `install_fake_session_task`
    /// helper used by the migration tests.
    fn install_lead_in_pool(workspace: &Arc<Workspace>, lead_id: &str) -> SessionSlot {
        let key = SessionSlot::from_str_for_test(lead_id);
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        workspace.pool.lock().insert(
            key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        key
    }

    /// Pins the lookup predicate the Connected catalog-mirror guard (in
    /// session_task) depends on: worker_lookup_for_session keyed by the
    /// worker's own id resolves a seeded worker (so its tag-less mirror
    /// is skipped) and not a lead/regular session. The guard's
    /// end-to-end skip is exercised in production.
    #[test]
    fn worker_lookup_drives_catalog_mirror_skip() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        workspace.insert_live_worker(
            &project_key,
            fake_worker("reviewer", worker_key, "lead-uuid", false),
        );
        assert!(
            workspace
                .worker_lookup_for_session(&SessionSlot::from_str_for_test(worker_key))
                .is_some(),
            "seeded worker must be detected so its tag-less catalog mirror is skipped"
        );
        assert!(
            workspace
                .worker_lookup_for_session(&SessionSlot::from_str_for_test("lead-uuid"))
                .is_none(),
            "the lead is not a live worker, so it is still mirrored into the catalog"
        );
    }

    /// #146: async worktree-creation failure → notice envelope
    /// dispatched to the lead's chat AND the WorkerEntry rolled
    /// back. Verifies both effects in one go.
    #[tokio::test]
    async fn async_failure_with_worktree_classification_dispatches_notice_and_rolls_back() {
        let (workspace, mut update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();

        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let lead_id = "lead-uuid";
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, lead_id, true));
        let lead_key = install_lead_in_pool(&workspace, lead_id);
        // The ConnectionFailed arm records the failure before this handler
        // runs, and the rollback deletes the row it would have drawn.
        let worker_slot = SessionSlot::from_str_for_test(worker_key);
        workspace.record_spawn_failure_for_test(&worker_slot, "the subprocess exited");

        let handled = workspace.handle_async_worker_spawn_failure(
            &worker_slot,
            "fatal: 'reviewer' is already used by worktree at /a/b/c",
            SpawnFailureKind::Unclassified,
        );
        assert!(handled, "async worker failure path must consume the failure");

        // Notice dispatched via Command::Prompt to the lead's key.
        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, "exactly one WorkerSpawnFailedNotice envelope");
        if let Command::Prompt { key, text, .. } | Command::PromptUnder { key, text, .. } =
            prompts[0]
        {
            assert_eq!(*key, lead_key, "notice targets the lead session id");
            assert!(text.starts_with("[Worker 'reviewer' spawn failed"));
            assert!(text.contains("already used by worktree"));
        }
        // And the echo a view draws: the CLI does not paint a prompt it was
        // handed on stdin, so without this the page shows nothing at all.
        let echoed = std::iter::from_fn(|| update_rx.try_recv().ok()).any(|frame| {
            matches!(
                std::sync::Arc::unwrap_or_clone(frame.update),
                SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. }
                    if key == lead_key
                        && matches!(wrapped.kind, WrappedKind::WorkerSpawnFailedNotice)
            )
        });
        assert!(echoed, "the notice reaches the chat as the update a view draws");

        // WorkerEntry rolled back: live_workers is empty.
        assert!(
            workspace.list_live_workers(&project_key).is_empty(),
            "WorkerEntry removed on async failure",
        );
        assert_eq!(
            workspace.spawn_failure(&worker_slot),
            None,
            "the failure record goes with the row the rollback deletes",
        );
    }

    /// #146 + #245 Layer C: async failure with a non-worktree-classified
    /// message must NOT dispatch a lead-notice; the entry transitions to
    /// `WorkerLiveness::Failed` with the message as diagnostic, so the
    /// user sees the failure surfaced on the row rather than the worker
    /// silently vanishing.
    #[tokio::test]
    async fn async_failure_without_worktree_classification_transitions_to_failed() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();

        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let lead_id = "lead-uuid";
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, lead_id, true));
        install_lead_in_pool(&workspace, lead_id);

        let handled = workspace.handle_async_worker_spawn_failure(
            &SessionSlot::from_str_for_test(worker_key),
            "agent spawn failed: subprocess exited with code 2",
            SpawnFailureKind::Unclassified,
        );
        assert!(handled);

        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(), "non-worktree classifier outcome must NOT dispatch a notice");
        let entries = workspace.list_live_workers(&project_key);
        assert_eq!(entries.len(), 1, "non-worktree failure keeps the entry visible");
        assert!(
            matches!(entries[0].status, forge_primitives::WorkerLiveness::Failed),
            "non-worktree failure transitions to Failed; got {:?}",
            entries[0].status,
        );
        assert_eq!(
            entries[0].diagnostic.as_deref(),
            Some("agent spawn failed: subprocess exited with code 2"),
            "diagnostic captures the ConnectionFailed message",
        );
    }

    /// #146: non-worker session_key (e.g. a lead failure) returns
    /// false and changes nothing - the caller's existing
    /// ConnectionFailed flow proceeds unchanged.
    #[tokio::test]
    async fn async_failure_on_non_worker_session_is_no_op() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        let unknown = SessionSlot::from_str_for_test("not-a-worker");
        let handled = workspace.handle_async_worker_spawn_failure(
            &unknown,
            "some unrelated error",
            SpawnFailureKind::Unclassified,
        );
        assert!(!handled);
        assert!(workspace.drain_test_dispatch_buffer().is_empty());
    }

    /// #146: double-fire safety - a second ConnectionFailed for the
    /// same worker (after the first call removed its WorkerEntry on
    /// the WORKTREE-classified path) must be a no-op rather than
    /// re-dispatching the notice.
    ///
    /// The message used here MUST classify as worktree-creation
    /// failure - that's the path that still removes the entry under
    /// #245 Layer C. The non-worktree path transitions to Failed
    /// instead of removing, so it wouldn't exercise the
    /// double-fire-after-removal semantics this test is pinning.
    /// `classify_worker_spawn_failure` validates the predicate
    /// upfront so a future rewording that breaks the contract
    /// surfaces here instead of as a confusing failure further down.
    #[tokio::test]
    async fn async_failure_double_fire_is_no_op() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();

        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let lead_id = "lead-uuid";
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, lead_id, true));
        install_lead_in_pool(&workspace, lead_id);

        let session_key = SessionSlot::from_str_for_test(worker_key);
        let worktree_msg = "fatal: 'reviewer' is already used by worktree at /a";
        // Pin the test's premise: this message must classify as
        // WorktreeCreationFailed so we exercise the remove-then-no-op
        // path. If a future change to the classifier breaks this
        // assumption, the test below would change shape (transition-
        // to-Failed isn't a no-op on re-fire).
        assert!(
            matches!(
                crate::mcp::workers::facade::classify_worker_spawn_failure(
                    worktree_msg,
                    true,
                    SpawnFailureKind::Unclassified,
                ),
                crate::mcp::workers::facade::WorkerSpawnError::WorktreeCreationFailed { .. },
            ),
            "test fixture must classify as worktree failure to exercise the removal path",
        );

        assert!(workspace.handle_async_worker_spawn_failure(
            &session_key,
            worktree_msg,
            SpawnFailureKind::Unclassified
        ));
        let _ = workspace.drain_test_dispatch_buffer();

        // Second call: WorkerEntry already gone, returns false, no
        // new dispatch.
        assert!(!workspace.handle_async_worker_spawn_failure(
            &session_key,
            worktree_msg,
            SpawnFailureKind::Unclassified
        ));
        assert!(workspace.drain_test_dispatch_buffer().is_empty());
    }

    fn install_db(workspace: &Arc<Workspace>) -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        workspace
            .install_db_for_test(crate::store::Db::open(&dir.path().join("db.redb")).expect("db"));
        dir
    }

    /// The labels with a persisted row in `project_key`. The store is
    /// keyed by `(org, name, label)`, so the key has to resolve before
    /// the rows can be read.
    fn persisted_labels(workspace: &Arc<Workspace>, project_key: &ProjectKey) -> Vec<String> {
        let project = workspace.project_for_key(project_key).expect("seeded project");
        let guard = workspace.db.lock();
        crate::store::sessions::list_for_project(
            guard.as_ref().expect("db"),
            &project.org,
            &project.name,
        )
        .expect("list")
        .into_iter()
        .map(|w| w.label)
        .collect()
    }

    /// #2: a worktree-creation failure is a hard removal (the worker
    /// never started), so it deletes the persisted dynamic-worker row -
    /// otherwise the row zombie-re-spawns every restart despite a
    /// visibly-failed spawn. Also mirrors the tag-rollback arm's
    /// `release_session`: the pool entry + command sender must not leak
    /// per failed fresh spawn.
    #[tokio::test]
    async fn worktree_failure_deletes_persisted_dynamic_worker_row() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let _dir = install_db(&workspace);
        workspace.enable_test_dispatch_intercept();

        workspace.seed_test_project("proj-x", "/tmp/worktree-failure-proj");
        let project_key = workspace.project_key_for_name("proj-x").expect("seeded project");
        let worker_key = "worker-uuid";
        let lead_id = "lead-uuid";
        seed_worker_row(&workspace, &project_key, "reviewer");
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, lead_id, true));
        install_lead_in_pool(&workspace, lead_id);

        let session_key = SessionSlot::from_str_for_test(worker_key);
        let (handle, _agent_rx) = Workspace::testing_stub_handle();
        let (cmd_tx, _cmd_rx) = mpsc::unbounded_channel::<Command>();
        workspace.pool.lock().insert(
            session_key.clone(),
            PooledAgent {
                handle: Arc::new(handle),
                account: AccountKey("test".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "pooled-session".to_owned(),
            },
        );
        workspace.command_senders.lock().insert(session_key.clone(), cmd_tx);

        let worktree_msg = "fatal: 'reviewer' is already used by worktree at /a";
        assert!(workspace.handle_async_worker_spawn_failure(
            &session_key,
            worktree_msg,
            SpawnFailureKind::Unclassified
        ));

        assert!(
            persisted_labels(&workspace, &project_key).is_empty(),
            "worktree-failure hard removal deletes the persisted row",
        );
        assert!(
            !workspace.pool.lock().contains_key(&session_key)
                && !workspace.command_senders.lock().contains_key(&session_key),
            "the failed spawn's session registrations are released",
        );
    }

    /// A worktree-creation failure never got a worktree, so the
    /// `Removed` event the close toast is built from must not report one
    /// intact - `Intact` is the arm that names a path, and there is
    /// nothing at that path to preserve. The worker is a GIT worker,
    /// the only case that could report `Intact` at all.
    #[tokio::test]
    async fn worktree_creation_failure_reports_no_worktree_to_preserve() {
        let (workspace, mut update_rx) = Workspace::testing_stub();

        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let lead_id = "lead-uuid";
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, lead_id, true));
        install_lead_in_pool(&workspace, lead_id);

        let session_key = SessionSlot::from_str_for_test(worker_key);
        let worktree_msg = "Error creating worktree: failed to resolve base branch";
        // The call below returns true on either classifier outcome, so
        // only this pins which path ran: the other transitions to
        // Failed and emits no Removed event at all.
        assert!(
            matches!(
                crate::mcp::workers::facade::classify_worker_spawn_failure(
                    worktree_msg,
                    true,
                    SpawnFailureKind::Unclassified,
                ),
                crate::mcp::workers::facade::WorkerSpawnError::WorktreeCreationFailed { .. },
            ),
            "the fixture must drive a real worktree-creation failure",
        );
        assert!(workspace.handle_async_worker_spawn_failure(
            &session_key,
            worktree_msg,
            SpawnFailureKind::Unclassified
        ));

        let mut dispositions = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::WorkerStatusChanged { action, worktree, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && action == crate::protocol::WorkerStatusAction::Removed
            {
                dispositions.push(worktree);
            }
        }
        assert_eq!(
            dispositions,
            vec![crate::protocol::WorktreeDisposition::Absent],
            "a worktree that failed to be created must not be reported preserved",
        );
    }

    /// #2: a non-worktree failure transitions the worker to Failed
    /// (visible) and KEEPS its row, so it re-spawns on the next restart
    /// to recover or re-fail visibly.
    #[tokio::test]
    async fn transition_to_failed_keeps_persisted_dynamic_worker_row() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let _dir = install_db(&workspace);

        workspace.seed_test_project("proj-x", "/tmp/transition-failed-proj");
        let project_key = workspace.project_key_for_name("proj-x").expect("seeded project");
        let worker_key = "worker-uuid";
        seed_worker_row(&workspace, &project_key, "reviewer");
        // Non-git worker + a generic message classifies as DispatchFailed,
        // driving the transition-to-Failed (visible) path.
        workspace.insert_live_worker(
            &project_key,
            fake_worker("reviewer", worker_key, "lead-uuid", false),
        );

        let session_key = SessionSlot::from_str_for_test(worker_key);
        assert!(workspace.handle_async_worker_spawn_failure(
            &session_key,
            "subprocess exited with code 2",
            SpawnFailureKind::Unclassified,
        ));

        assert_eq!(
            persisted_labels(&workspace, &project_key),
            vec!["reviewer".to_owned()],
            "a Failed-but-visible worker keeps its row for re-spawn",
        );
    }

    /// #245 Layer C test gap 12 + 11: direct unit coverage for
    /// [`transition_worker_to_failed`].
    ///
    /// Covers:
    /// - First call flips status + records diagnostic
    /// - Second call with identical diagnostic is a no-op (no
    ///   extra event emission)
    /// - Second call with a NEW diagnostic re-emits + records new
    ///   diagnostic
    /// - needs_tag is cleared on transition
    #[tokio::test]
    async fn transition_worker_to_failed_idempotent_for_identical_diagnostic() {
        let (workspace, mut update_rx) = Workspace::testing_stub();
        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let session_key = SessionSlot::from_str_for_test(worker_key);
        // Worker starts Spawning + needs_tag = true (mirrors
        // fresh-spawn state pre-Connected).
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, "lead", true));

        // First call: flips to Failed, records diagnostic, clears
        // needs_tag, emits WorkerStatusChanged.
        transition_worker_to_failed(
            &workspace,
            &project_key,
            &session_key,
            Some("spawn failed".to_owned()),
        );

        let entries = workspace.list_live_workers(&project_key);
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].status, forge_primitives::WorkerLiveness::Failed);
        assert_eq!(entries[0].diagnostic.as_deref(), Some("spawn failed"));
        assert!(!entries[0].needs_tag, "needs_tag must be cleared on Failed transition");

        // Drain the first event so the next assertion is unambiguous.
        let _ = update_rx.try_recv().expect("first transition emitted event");

        // Second call with identical diagnostic: no-op, no new event.
        transition_worker_to_failed(
            &workspace,
            &project_key,
            &session_key,
            Some("spawn failed".to_owned()),
        );
        let second_event = update_rx.try_recv();
        assert!(
            second_event.is_err(),
            "identical diagnostic re-fire must NOT emit a new event; got {second_event:?}",
        );

        // Third call with NEW diagnostic: re-emits + records new text.
        transition_worker_to_failed(
            &workspace,
            &project_key,
            &session_key,
            Some("more specific reason".to_owned()),
        );
        let third_event = update_rx.try_recv();
        assert!(third_event.is_ok(), "fresh diagnostic must re-emit");
        let entries = workspace.list_live_workers(&project_key);
        assert_eq!(entries[0].diagnostic.as_deref(), Some("more specific reason"));
    }

    /// handle_async_worker_spawn_failure drops whatever was parked for the
    /// worker whose spawn died, and the message in it is acknowledged back
    /// to its sender: a spawn that never connected has no session left to
    /// deliver it to, and nothing re-delivers it later.
    #[tokio::test]
    async fn async_worker_spawn_failure_acknowledges_the_parked_message() {
        use crate::mcp::peers::types::{MessageId, WrappedKind, WrappedPrompt};
        let (workspace, mut update_rx) = Workspace::testing_stub();
        let project_key = ProjectKey::new("proj-x");
        let worker_key = "builder-uuid";
        let session_key = SessionSlot::from_str_for_test(worker_key);
        workspace
            .insert_live_worker(&project_key, fake_worker("builder", worker_key, "lead", true));
        workspace.enable_test_dispatch_intercept();

        let sender = SessionSlot::from_str_for_test("sender-proj");
        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: "ready?".to_owned(),
            },
        );

        workspace.handle_async_worker_spawn_failure(
            &session_key,
            "resume failed: boom",
            SpawnFailureKind::Unclassified,
        );

        let mut echo = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
            {
                echo = Some((key, wrapped));
            }
        }
        let (key, notice) = echo.expect("the parked message is acknowledged to its sender");
        assert_eq!(key, sender, "on the sender's slot");
        assert!(
            matches!(notice.kind, WrappedKind::DeliveryFailureNotice),
            "as a delivery failure, not a peer message"
        );
        assert!(
            workspace.take_parked_for_slot(&session_key).peer.is_empty(),
            "and the bucket is gone, so nothing re-delivers it"
        );
    }

    /// #245 Layer C test gap 11: a worker that flipped to Failed
    /// then transitions back to Running (e.g. a successful resume
    /// after the user fixed the underlying problem) must clear the
    /// stale diagnostic field. Without this, the Projects pane
    /// would render a healthy Running worker with a phantom
    /// failure sub-row underneath.
    #[tokio::test]
    async fn transition_worker_to_running_clears_prior_failed_diagnostic() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let session_key = SessionSlot::from_str_for_test(worker_key);
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, "lead", true));

        // Flip to Failed with a diagnostic.
        transition_worker_to_failed(
            &workspace,
            &project_key,
            &session_key,
            Some("connection refused".to_owned()),
        );
        assert_eq!(
            workspace.list_live_workers(&project_key)[0].diagnostic.as_deref(),
            Some("connection refused"),
        );

        // Transition back to Running. Diagnostic must clear.
        transition_worker_to_running(
            &workspace,
            &project_key,
            &session_key,
            TagWriteResult::Succeeded,
        );
        let entry = &workspace.list_live_workers(&project_key)[0];
        assert_eq!(entry.status, forge_primitives::WorkerLiveness::Running);
        assert!(
            entry.diagnostic.is_none(),
            "diagnostic must clear when worker transitions back to Running; got {:?}",
            entry.diagnostic,
        );
    }

    /// #146: lead-session-gone path - the worker was spawned by a
    /// lead session that has since been released (e.g. /new flow).
    /// Notice dispatch is skipped (warn-logged) but the WorkerEntry
    /// still rolls back.
    #[tokio::test]
    async fn async_failure_when_lead_session_gone_drops_notice_but_rolls_back() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();

        let project_key = ProjectKey::new("proj-x");
        let worker_key = "worker-uuid";
        let lead_id = "lead-gone-uuid";
        workspace
            .insert_live_worker(&project_key, fake_worker("reviewer", worker_key, lead_id, true));
        // DELIBERATELY skip install_lead_in_pool - lead is "gone".

        let handled = workspace.handle_async_worker_spawn_failure(
            &SessionSlot::from_str_for_test(worker_key),
            "fatal: 'reviewer' is already used by worktree at /a",
            SpawnFailureKind::Unclassified,
        );
        assert!(handled, "still consumes the failure even when lead is gone");

        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(), "no notice dispatched when lead session is gone");
        assert!(
            workspace.list_live_workers(&project_key).is_empty(),
            "WorkerEntry still rolls back even when notice is dropped",
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used)]
mod git_scan_cwd_tests {
    use super::*;
    use crate::mcp::workers::types::WorkerEntry;
    use forge_primitives::WorkerLiveness;
    use forge_primitives::document::DocumentHandOffEnding;
    use std::time::SystemTime;

    fn worker_entry(label: &str, session_key: &SessionSlot, is_git: bool) -> WorkerEntry {
        WorkerEntry {
            label: label.into(),
            charter: "test charter".into(),
            slot: session_key.clone(),
            session_id: None,
            status: WorkerLiveness::Running,
            spawned_at: SystemTime::UNIX_EPOCH,
            spawned_by: SessionSlot::from_str_for_test("lead-uuid"),
            needs_tag: false,
            is_git_repo_at_spawn: is_git,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    /// Seed a project + a worker for it. Returns the project_root
    /// path the project_key derives from, and the worker's session
    /// key for the caller to drive `git_scan_cwd_for_session`.
    fn seed_project_and_worker(
        ws: &Arc<Workspace>,
        project_name: &str,
        project_root: &str,
        worker_label: &str,
        worker_session: &str,
        is_git: bool,
    ) -> (std::path::PathBuf, SessionSlot) {
        ws.seed_test_project(project_name, project_root);
        let project_key = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(project_root)),
        );
        let session_key = SessionSlot::from_str_for_test(worker_session);
        ws.insert_live_worker(&project_key, worker_entry(worker_label, &session_key, is_git));
        (std::path::PathBuf::from(project_root), session_key)
    }

    #[test]
    fn git_scan_cwd_resolves_worktree_when_cwd_raw_is_project_root() {
        // Fresh-spawn path: `cwd_raw` is the project root (the value
        // claude sends in `AgentEvent::Connected.cwd` before it
        // chdirs into the worktree). The function must compose
        // `<project_root>/.claude/worktrees/<label>` for git workers.
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            "/tmp/test-forge-fresh",
            "implementer",
            "worker-uuid-fresh",
            true,
        );
        let resolved = ws.git_scan_cwd_for_session(&session_key, &project_root);
        assert_eq!(
            resolved,
            project_root.join(".claude/worktrees").join("implementer"),
            "fresh-spawn cwd_raw must resolve to the worktree path"
        );
    }

    #[test]
    fn git_scan_cwd_resolves_worktree_when_cwd_raw_is_already_worktree_path() {
        // Resumed-worker path: `cwd_raw` is already
        // `<project_root>/.claude/worktrees/<label>` because the
        // catalog row was written after claude chdir'd. Old behavior
        // composed `worker_tag_dir(cwd_raw, label, true)` and doubled
        // the suffix - new behavior anchors on the project_key, so
        // both inputs converge on the same final path.
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            "/tmp/test-forge-resume",
            "implementer",
            "worker-uuid-resume",
            true,
        );
        let already_worktree = project_root.join(".claude/worktrees").join("implementer");
        let resolved = ws.git_scan_cwd_for_session(&session_key, &already_worktree);
        assert_eq!(
            resolved, already_worktree,
            "resume cwd_raw must NOT double the worktree suffix"
        );
    }

    #[test]
    fn git_scan_cwd_returns_cwd_unchanged_for_lead_session() {
        // Non-worker sessions take the fall-through branch and the
        // raw cwd survives unchanged. No `live_workers` entry exists
        // for the lead.
        let (ws, _rx) = Workspace::testing_stub();
        ws.seed_test_project("forge", "/tmp/test-forge-lead");
        let lead_key = SessionSlot::from_str_for_test("lead-uuid");
        let lead_cwd = std::path::PathBuf::from("/tmp/test-forge-lead");
        let resolved = ws.git_scan_cwd_for_session(&lead_key, &lead_cwd);
        assert_eq!(resolved, lead_cwd, "lead sessions must get cwd_raw unchanged");
    }

    #[test]
    fn git_scan_cwd_returns_cwd_unchanged_for_non_git_worker() {
        // Non-git workers don't have a worktree fork; they run in
        // the project root itself. Returning cwd_raw unchanged
        // matches the pre-fix behavior for this case.
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            "/tmp/test-forge-nongit",
            "researcher",
            "worker-uuid-nongit",
            false,
        );
        let resolved = ws.git_scan_cwd_for_session(&session_key, &project_root);
        assert_eq!(resolved, project_root, "non-git worker must use cwd_raw unchanged");
    }

    // ---------------------------------------------------------------
    // #245 Layer B: resume_cwd_for_slot falls back to the owning
    // worker's project_root when the catalog has no recorded cwd.
    // Without this, claude --resume inherits the forge binary's
    // process cwd and derives the JSONL location against the wrong
    // git root (the bug documented in #245).
    // ---------------------------------------------------------------

    #[test]
    fn resume_cwd_for_slot_returns_worktree_for_git_worker_with_no_catalog_cwd() {
        // Git-repo worker (the data-modules babysitter / librarian
        // case from #245). Layer B composes the worker's worktree
        // path so claude resolves the JSONL on the first try -
        // passing just the project root would make claude look under
        // the wrong sanitised dir and surface "No conversation
        // found".
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "data-modules",
            "/tmp/test-data-modules",
            "babysitter",
            "worker-uuid-hub",
            true,
        );
        let resolved = ws.resume_cwd_for_slot(&session_key);
        assert_eq!(
            resolved,
            project_root.join(".claude/worktrees/babysitter").to_string_lossy(),
            "git-repo worker resume cwd must compose the worktree path via worker_tag_dir",
        );
    }

    #[test]
    fn resume_cwd_for_slot_returns_project_root_for_non_git_worker() {
        // Non-git project: worker_tag_dir leaves the path as the
        // project root, so the fallback returns the root verbatim.
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "non-git-proj",
            "/tmp/test-non-git",
            "implementer",
            "worker-uuid-non-git",
            false,
        );
        let resolved = ws.resume_cwd_for_slot(&session_key);
        assert_eq!(
            resolved,
            project_root.to_string_lossy(),
            "non-git worker resume cwd must equal the project root (no worktree subdir)",
        );
    }

    #[test]
    fn resume_cwd_for_slot_returns_empty_for_unknown_session() {
        // Non-worker, non-catalog session - the function returns
        // empty string and lets the bridge surface ConnectionFailed
        // (current behaviour for genuinely-orphan sessions).
        let (ws, _rx) = Workspace::testing_stub();
        let unknown = SessionSlot::from_str_for_test("not-a-known-session");
        assert_eq!(ws.resume_cwd_for_slot(&unknown), "");
    }

    #[test]
    fn cwd_for_session_resolves_a_git_worker_with_no_catalog_row() {
        // The catalog holds no worker rows at all (the boot scan hides
        // worker-tagged sessions; the Connected handler skips the
        // mirror for workers), so every worker resolves through the
        // registry - not just a resume.
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "gateway-backend",
            "/tmp/test-gateway-cwd",
            "pyth-review-fixes",
            "worker-uuid-cwd",
            true,
        );
        assert_eq!(
            ws.cwd_for_session(&session_key).as_deref(),
            project_root.join(".claude/worktrees/pyth-review-fixes").to_str(),
        );
    }

    /// A worker the spawn pointed at another tree reads back to THAT
    /// tree, not the project's: the seat's cwd, the resume cwd and the
    /// git scan all compose from the root the spawn resolved. Composing
    /// from the project path instead would put the worker's branch, its
    /// files and its resumed JSONL under a directory the worker never
    /// ran in.
    #[test]
    fn a_cwd_workers_read_backs_compose_its_own_tree() {
        let (ws, _rx) = Workspace::testing_stub();
        let (_project_root, session_key) = seed_project_and_worker(
            &ws,
            "playground",
            "/tmp/test-playground",
            "nazar-hand",
            "worker-uuid-nazar",
            true,
        );
        let project_key = ws.project_key_for_name("playground").expect("seeded project");
        let root = std::path::PathBuf::from("/tmp/test-nazar");
        let mut entry = worker_entry("nazar-hand", &session_key, true);
        entry.cwd = Some(root.clone());
        ws.remove_latest_worker(&project_key, "nazar-hand");
        ws.insert_live_worker(&project_key, entry);
        let tree = root.join(".claude/worktrees/nazar-hand");

        assert_eq!(
            ws.cwd_for_session(&session_key).as_deref(),
            tree.to_str(),
            "the seat's tree is the worker's own, not the project's",
        );
        assert_eq!(
            ws.git_scan_cwd_for_session(&session_key, std::path::Path::new("/tmp/test-playground")),
            tree,
            "the branch and file counts read the worker's tree",
        );
        assert_eq!(
            ws.resume_cwd_for_slot(&session_key),
            tree.to_string_lossy(),
            "and a resume lands where the JSONL lives",
        );

        // A non-git tree is its own directory, no worktree composed.
        let plain_root = std::path::PathBuf::from("/tmp/test-plain");
        let mut plain = worker_entry("nazar-hand", &session_key, false);
        plain.cwd = Some(plain_root.clone());
        ws.remove_latest_worker(&project_key, "nazar-hand");
        ws.insert_live_worker(&project_key, plain);
        assert_eq!(
            ws.cwd_for_session(&session_key).as_deref(),
            plain_root.to_str(),
            "a non-git worker's own directory is the tree itself",
        );
    }

    /// The launchpad asks about the ROW's tree, not the project's: a
    /// worker pointed at another directory is offered on whether that
    /// directory's worktree is there. The project's own worktree stands
    /// in this fixture, so a launchpad reading the project path would
    /// offer a row the boot wave would skip.
    #[test]
    fn the_launchpad_asks_about_the_rows_own_tree() {
        let (workspace, _rx) = Workspace::testing_stub();
        let db_dir = tempfile::tempdir().expect("db dir");
        workspace.install_db_for_test(
            crate::store::Db::open(&db_dir.path().join("db.redb")).expect("open db"),
        );
        let repo = tempfile::tempdir().expect("git project dir");
        let status = std::process::Command::new("git")
            .args(["init", "-q"])
            .current_dir(repo.path())
            .status()
            .expect("spawn git");
        assert!(status.success(), "git init");
        workspace.seed_test_project("proj-x", repo.path().to_str().expect("utf8 repo path"));
        let proj_x = workspace.project_key_for_name("proj-x").expect("seeded project");
        // The project's own worktree stands, so the project path answers
        // "there is one" for anything that asks it.
        std::fs::create_dir_all(repo.path().join(".claude").join("worktrees").join("at-home"))
            .expect("create the project worktree");

        let gone = tempfile::tempdir().expect("worker tree dir");
        let gone_root = std::fs::canonicalize(gone.path()).expect("canonical");
        workspace.seed_test_worker_row_at(&proj_x, "moved", &gone_root.to_string_lossy(), true);
        workspace.seed_test_worker_row_at(
            &proj_x,
            "at-home",
            repo.path().to_str().expect("utf8 repo path"),
            true,
        );

        let offered = workspace.worker_labels_by_project();
        let labels = offered.get(&proj_x).cloned().unwrap_or_default();
        assert!(
            !labels.contains(&"moved".to_owned()),
            "a worker whose own tree has no worktree must not be offered, however the project \
             looks; offered {labels:?}",
        );
        assert!(
            labels.contains(&"at-home".to_owned()),
            "and the project's own worker is still offered; offered {labels:?}",
        );
    }

    /// A hand-off reads the document out of the seat's OWN tree, asks the
    /// seat's clients to open it with the resolved path, and **parks until
    /// the reader answers** - the finish is what releases the call, and the
    /// answer carries what it filed.
    #[tokio::test]
    async fn a_document_hand_off_parks_on_the_ask_and_answers_with_the_ending() {
        let dir = tempfile::tempdir().expect("tempdir");
        let root = dir.path().to_str().expect("utf8").to_owned();
        let (ws, mut updates) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            &root,
            "implementer",
            "worker-uuid-hand-off",
            true,
        );
        let cwd = project_root.join(".claude/worktrees/implementer");
        std::fs::create_dir_all(cwd.join("docs")).expect("the worktree");
        std::fs::write(cwd.join("docs/readme.md"), b"# hi\n").expect("the document");
        // The read answers the CANONICAL path (the `/var` -> `/private/var`
        // case on this machine), which is what a viewer deep-links by.
        let expected = cwd.canonicalize().expect("canonical").join("docs/readme.md");
        ws.note_client_attached();

        let handed = {
            let ws = Arc::clone(&ws);
            let seat = session_key.clone();
            tokio::spawn(async move { ws.hand_off_document(&seat, "docs/readme.md", true).await })
        };
        // The ask crosses, carrying the id the answer will name.
        let ask = tokio::time::timeout(std::time::Duration::from_secs(5), async {
            loop {
                match updates
                    .recv()
                    .await
                    .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                {
                    Some(SessionUpdate::DocumentHandOffPending {
                        id, path, reviewable, ..
                    }) => {
                        break (id, path, reviewable);
                    }
                    Some(_) => {}
                    None => panic!("the stream ended before the ask"),
                }
            }
        })
        .await
        .expect("the ask reaches the seat's stream");
        assert_eq!(ask.1, expected.to_string_lossy(), "with the resolved path - the address");
        assert!(ask.2, "and the flag the hand-off passed");

        assert!(ws.resolve_document_hand_off(
            ask.0,
            &session_key,
            DocumentHandOffEnding::Approve { review_id: Some("r-1".to_owned()), note: None },
        ));

        let (resolved, ending) = handed.await.expect("the task joins").expect("the hand-off lands");
        assert_eq!(resolved, expected.to_string_lossy(), "answered with the resolved path");
        assert_eq!(
            ending,
            DocumentHandOffEnding::Approve { review_id: Some("r-1".to_owned()), note: None }
        );
        assert!(
            std::iter::from_fn(|| updates.try_recv().ok()).any(|frame| matches!(
                &*frame.update,
                SessionUpdate::DocumentHandOffResolved { id, .. } if *id == ask.0
            )),
            "and the resolution crosses, so a view that did not answer closes its ask",
        );
    }

    /// A refused read raises nothing, parks on nothing, and answers the
    /// read's own sentence.
    #[tokio::test]
    async fn a_refused_document_hand_off_raises_nothing() {
        let dir = tempfile::tempdir().expect("tempdir");
        let root = dir.path().to_str().expect("utf8").to_owned();
        let (ws, mut updates) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            &root,
            "implementer",
            "worker-uuid-hand-off-refused",
            true,
        );
        let cwd = project_root.join(".claude/worktrees/implementer");
        std::fs::create_dir_all(&cwd).expect("the worktree");

        let refused = ws
            .hand_off_document(&session_key, "gone.md", false)
            .await
            .expect_err("nothing to read");

        assert!(refused.contains("no document at"), "{refused}");
        assert!(
            std::iter::from_fn(|| updates.try_recv().ok()).all(|frame| !matches!(
                &*frame.update,
                SessionUpdate::DocumentHandOffPending { .. }
            )),
            "a refusal is not a hand-off",
        );
    }

    /// **A hand-off claims an open only where something can draw it.** With
    /// no client attached, the ask would cross the fan-out and reach nothing
    /// that draws a document viewer - so the tool refuses with
    /// the reason instead of parking on an ask nothing can draw. A client
    /// attaching (the transport notes each connection) is what makes the
    /// same hand-off land, and its leaving takes the claim back.
    #[tokio::test]
    async fn a_hand_off_claims_an_open_only_with_a_client_attached() {
        let dir = tempfile::tempdir().expect("tempdir");
        let root = dir.path().to_str().expect("utf8").to_owned();
        let (ws, mut updates) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            &root,
            "implementer",
            "worker-uuid-hand-off-gate",
            true,
        );
        let cwd = project_root.join(".claude/worktrees/implementer");
        std::fs::create_dir_all(cwd.join("docs")).expect("the worktree");
        std::fs::write(cwd.join("docs/readme.md"), b"# hi\n").expect("the document");

        let refused = ws
            .hand_off_document(&session_key, "docs/readme.md", false)
            .await
            .expect_err("no client, so nothing to open on");
        assert_eq!(refused, crate::documents::NO_VIEWER_CLIENT, "the refusal is the named one");
        assert!(
            std::iter::from_fn(|| updates.try_recv().ok()).all(|frame| !matches!(
                &*frame.update,
                SessionUpdate::DocumentHandOffPending { .. }
            )),
            "and nothing was asked of the terminal",
        );

        ws.note_client_attached();
        let handed = {
            let ws = Arc::clone(&ws);
            let seat = session_key.clone();
            tokio::spawn(async move { ws.hand_off_document(&seat, "docs/readme.md", false).await })
        };
        let ask = tokio::time::timeout(std::time::Duration::from_secs(5), async {
            loop {
                match updates
                    .recv()
                    .await
                    .map(|frame| std::sync::Arc::unwrap_or_clone(frame.update))
                {
                    Some(SessionUpdate::DocumentHandOffPending { id, .. }) => break id,
                    Some(_) => {}
                    None => panic!("the stream ended before the ask"),
                }
            }
        })
        .await
        .expect("an attached client is what the hand-off waits for");
        ws.resolve_document_hand_off(
            ask,
            &session_key,
            DocumentHandOffEnding::Approve { review_id: None, note: None },
        );
        handed.await.expect("the task joins").expect("and the park releases");

        ws.note_client_detached();
        let refused = ws
            .hand_off_document(&session_key, "docs/readme.md", false)
            .await
            .expect_err("the client left, so the open is unclaimed again");
        assert_eq!(refused, crate::documents::NO_VIEWER_CLIENT);
    }

    /// **A document deleted between the hand-off and a later open of its
    /// stable address refuses as missing - and its threads still read, with
    /// their captured lines.** The store was never about the file: deleting
    /// the document cannot touch what was written against it, which is what
    /// keeps a thread reachable from the review record after the file it
    /// reviewed is gone.
    #[tokio::test]
    async fn a_deleted_document_refuses_and_its_threads_still_read() {
        use forge_primitives::review::{
            ReviewAnchor, ReviewAuthor, ReviewComment, ReviewSide, ReviewStatus, ReviewThread,
        };

        let dir = tempfile::tempdir().expect("tempdir");
        let root = dir.path().to_str().expect("utf8").to_owned();
        let (ws, _updates) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "forge",
            &root,
            "implementer",
            "worker-uuid-hand-off-deleted",
            true,
        );
        let cwd = project_root.join(".claude/worktrees/implementer");
        std::fs::create_dir_all(cwd.join("docs")).expect("the worktree");
        let document = cwd.join("docs/plan.md");
        std::fs::write(&document, b"# plan\n").expect("the document");
        let resolved = cwd.canonicalize().expect("canonical").join("docs/plan.md");
        let scope = forge_primitives::review::doc_scope_ref(&resolved.to_string_lossy());
        assert!(
            ws.upsert_review_thread(
                "forge",
                &scope,
                ReviewThread {
                    id: "d1".to_owned(),
                    anchor: ReviewAnchor {
                        path: resolved.to_string_lossy().into_owned(),
                        side: ReviewSide::New,
                        line: 1,
                        content_hash: 7,
                        context: vec!["# plan".to_owned()],
                        base_ref: scope.clone(),
                    },
                    comments: vec![ReviewComment {
                        author: ReviewAuthor::User,
                        text: "one line, please".to_owned(),
                        at: String::new(),
                        review_id: None,
                    }],
                    status: ReviewStatus::Open,
                    created_at: String::new(),
                    updated_at: String::new(),
                    commit: None,
                },
            ),
            "the thread was stored",
        );

        std::fs::remove_file(&document).expect("the deletion");

        let refused = ws
            .hand_off_document(&session_key, "docs/plan.md", false)
            .await
            .expect_err("the stable address now refuses");
        assert!(refused.contains("no document at"), "and says what it met: {refused}");

        let threads = ws.load_review_threads("forge", &scope).expect("the scope still reads");
        assert_eq!(threads.len(), 1, "the deletion cannot touch the document's threads");
        assert_eq!(
            threads[0].anchor.context,
            vec!["# plan".to_owned()],
            "with their captured lines kept",
        );
    }

    /// The project-root arm answers LEADS ONLY. `seed_project_and_worker`
    /// cannot show this: its slot names no loaded project, so
    /// `project_for_slot` misses and BOTH arms fall through to the
    /// registry's answer - which is how the shadowing regression passed
    /// every existing cwd test. The slot has to name a loaded project for
    /// the two arms to disagree, and the wrong one here sends a git
    /// worker's resume to the project root while its JSONL sits under
    /// the worktree (#245 Layer B).
    #[test]
    fn a_worker_slot_does_not_resolve_to_its_project_root() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        let view =
            ws.list_projects().into_iter().find(|v| v.name == "forge").expect("fixture project");
        let slot = SessionSlot::worker(&view.org, &view.name, "implementer");
        ws.insert_live_worker(&view.key, worker_entry("implementer", &slot, true));

        let resolved = ws.cwd_for_session(&slot);
        let expected = view.path.join(".claude/worktrees/implementer");
        assert_eq!(
            resolved.as_deref(),
            expected.to_str(),
            "the registry composes the worktree; the project root must not shadow it",
        );
    }

    /// The other arm of the same lookup, pinned next to it so the pair
    /// says what the split is: a lead's cwd IS its project root, read
    /// from the slot rather than from the catalog, because the catalog is
    /// keyed by the id the CLI adopted and `/new` replaces that.
    #[test]
    fn a_lead_slot_resolves_to_its_project_root() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        let view =
            ws.list_projects().into_iter().find(|v| v.name == "forge").expect("fixture project");

        let resolved = ws.cwd_for_session(&SessionSlot::lead(&view.org, &view.name));
        assert_eq!(resolved.as_deref(), view.path.to_str(), "a lead runs in its project root");
    }

    #[test]
    fn cwd_for_session_is_none_when_the_workers_project_is_not_loaded() {
        // The contradiction the WARN names: the registry knows the
        // worker's project_key and label, but no loaded project
        // matches that key, so no path can be composed. Unreachable
        // while forge.toml and `live_workers` agree.
        let (ws, _rx) = Workspace::testing_stub();
        let session_key = SessionSlot::from_str_for_test("worker-uuid-orphan");
        ws.insert_live_worker(
            &ProjectKey::new("stale-key".to_owned()),
            worker_entry("implementer", &session_key, true),
        );
        assert!(ws.cwd_for_session(&session_key).is_none());
    }

    /// The cwd read is not a catalog read any more: a slot that names
    /// no declared project resolves through the worker registry, and a
    /// catalog row for the same session carrying a different cwd is not
    /// consulted at all. Seeding BOTH with different paths is what makes
    /// the two rules distinguishable - under the old catalog-first
    /// precedence the row's path was the one that won.
    #[test]
    fn resume_cwd_for_slot_ignores_a_catalog_row_carrying_another_cwd() {
        let (ws, _rx) = Workspace::testing_stub();
        let session_id = "shared-session-uuid";
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "precedence-proj",
            "/tmp/test-precedence",
            "implementer",
            session_id,
            true,
        );
        // A catalog row for the same session, pointing somewhere else:
        // it is not a cwd source for this lookup.
        ws.record_connected_session("/tmp/test-precedence-catalog-cwd", session_id, None);
        let resolved = ws.resume_cwd_for_slot(&session_key);
        assert_eq!(
            resolved,
            project_root.join(".claude/worktrees/implementer").to_string_lossy(),
            "the worker registry decides the cwd; the catalog row is not read",
        );
    }

    /// Read/pick consistency: the cwd `resume_cwd_for_slot` hands
    /// `claude --resume` for a git worker encodes to the SAME storage
    /// key `build_resume_map_from_sessions` scopes candidates to (both
    /// go through `project_key_for_directory(worker_tag_dir(...))`), so
    /// a picked session always lives in the dir the resume read looks
    /// under - the pick and the read can't diverge the way the head-read
    /// cwd allowed.
    #[test]
    fn git_worker_resume_cwd_encodes_to_scoped_storage_key() {
        let (ws, _rx) = Workspace::testing_stub();
        let (project_root, session_key) = seed_project_and_worker(
            &ws,
            "playground",
            "/tmp/test-playground-consistency",
            "gpt-tutor",
            "worker-uuid-consistency",
            true,
        );
        let read_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &ws.resume_cwd_for_slot(&session_key),
        ));
        let scoped_key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            crate::mcp::workers::types::worker_tag_dir(&project_root, "gpt-tutor", true)
                .to_string_lossy()
                .as_ref(),
        ));
        assert_eq!(
            read_key, scoped_key,
            "resume read dir and resume-map scope key must be the same storage folder",
        );
    }

    // ---------------------------------------------------------------
    // The selection walk and `session_chip_for`. Build a real
    // workspace from the local `make_workspace_dir_246` helper (single
    // account "Stargate", single project "forge") + manually drive the
    // loading state via account_pool().set_*().
    // ---------------------------------------------------------------

    fn make_workspace_dir_246() -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// Two accounts serving one project's model, in pin order.
    fn make_two_account_workspace_dir() -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["First", "Second"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "First"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Second"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// A project `model` fills the CLI's model slots: all five slot
    /// variables carry that one model on the spawned child.
    #[tokio::test]
    async fn a_project_model_fills_the_cli_model_slots() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let workspace =
            std::sync::Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_gateway_ready(true);
        workspace.seed_test_ready_account("Stargate");
        let handle = workspace
            .get_agent_handle(
                SessionTarget::Default,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("spawn");
        let env = handle.env();
        for var in MODEL_SLOT_VARIABLES {
            assert_eq!(
                env.get(var).map(String::as_str),
                Some("claude-sonnet-5"),
                "{var} carries the project model",
            );
        }
    }

    /// A spawn whose target resolves to no configured project is
    /// refused, naming the session and both ways out. It used to spawn
    /// unregistered, carrying the account's real credential and a
    /// direct base URL - a session the gateway could not see, rotate or
    /// cool, and one whose dir forge.toml does not describe.
    #[tokio::test]
    async fn a_spawn_resolving_to_no_project_is_refused_by_name() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_gateway_ready(true);
        workspace.seed_test_ready_account("Stargate");
        let target = SessionTarget::Session(SessionSlot::from_str_for_test("orphan-uuid"));
        let error = workspace
            .get_agent_handle(
                target,
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .err()
            .expect("a session mapping to no project must not spawn");

        let message = format!("{error}");
        assert!(
            message.contains("orphan-uuid"),
            "the refusal names the session, so the row is identifiable: {message}",
        );
        assert!(message.contains("Add that project"), "and names the way forward: {message}");
        assert!(
            workspace.pool.lock().is_empty(),
            "nothing is pooled, so no unregistered child is running",
        );
    }

    /// `project_would_bind` is what a project row's accounts refusal
    /// reads, so an always-false regression would refuse every project
    /// and nothing else would fail.
    #[tokio::test]
    async fn project_would_bind_tracks_the_walk() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let project = workspace.list_projects().into_iter().next().expect("one project");

        assert!(
            !workspace.project_would_bind(&project.key),
            "an account still resolving is nothing the walk can pick",
        );

        workspace.seed_test_ready_account("Stargate");
        assert!(
            workspace.project_would_bind(&project.key),
            "a ready account declaring the project's model is what a spawn lands on",
        );

        workspace.seed_test_account_state("Stargate", forge_gateway::LoadingState::Bailed);
        assert!(
            workspace.project_would_bind(&project.key),
            "a bailed account is still picked when nothing else declares the model, \
             so the row stays clickable",
        );

        // Agent-cooling, which is the one settled state the walk refuses:
        // it is what draws a project row's refusal on a project that does
        // declare a model.
        workspace.seed_test_ready_account("Stargate");
        let an_hour_out = std::time::SystemTime::now()
            .duration_since(std::time::SystemTime::UNIX_EPOCH)
            .expect("clock after the epoch")
            .as_secs()
            + 3600;
        workspace.gateway.report_probe_limit(&AccountKey("Stargate".to_owned()), Some(an_hour_out));
        assert!(
            !workspace.project_would_bind(&project.key),
            "every declaring account cooling is nothing to spawn on, so the row blocks",
        );
    }

    /// The spawn's notice: an account the walk had to take while
    /// saturated or bailed comes back named, one with room does not, so
    /// the tool result carries a notice exactly when there is something
    /// to warn about.
    #[tokio::test]
    async fn a_degraded_account_is_named_and_an_account_with_room_is_not() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let key = AccountKey("Stargate".to_owned());

        workspace.account_pool().set_usage(&key, usage_at(100.0));
        assert_eq!(
            workspace.degraded_account_name("Stargate").as_deref(),
            Some("Stargate"),
            "a saturated account is named, so the spawn warns the worker may throttle",
        );

        workspace.account_pool().set_usage(&key, usage_at(10.0));
        assert_eq!(
            workspace.degraded_account_name("Stargate"),
            None,
            "an account with room is not named, so the result carries no notice",
        );

        workspace.account_pool().set_loading(&key, forge_gateway::LoadingState::Bailed);
        assert_eq!(
            workspace.degraded_account_name("Stargate").as_deref(),
            Some("Stargate"),
            "a bailed account is named too",
        );
    }

    /// Two accounts and a project that declares no model, which is the
    /// fixture for `apply_project_model`'s absent-model case.
    fn make_workspace_dir_lead_and_worker() -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Alpha", "Beta"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Alpha"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Beta"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// The probe-glue edge: record_usage_success with any window at
    /// the cap reports the gateway, which rotates every session bound
    /// to that account. A probe under the cap reports nothing.
    #[tokio::test]
    async fn record_usage_success_reports_probe_exhaustion_to_the_gateway() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let pool = workspace.account_pool();
        pool.set_usage(&AccountKey("Stargate".to_owned()), usage_at(10.0));
        workspace.gateway.bindings.bind("Org", "forge", "s1", AccountKey("Stargate".to_owned()));
        workspace.record_usage_success(&AccountKey("Stargate".to_owned()), usage_at(100.0));
        assert!(
            workspace.gateway.bindings.binding_for("Org", "forge", "s1").is_none(),
            "a probe verdict at the cap rotates the bound session",
        );

        workspace.gateway.bindings.bind("Org", "forge", "s2", AccountKey("Stargate".to_owned()));
        workspace.record_usage_success(&AccountKey("Stargate".to_owned()), usage_at(10.0));
        assert!(
            workspace.gateway.bindings.binding_for("Org", "forge", "s2").is_some(),
            "a probe under the cap rotates nothing",
        );
    }

    /// A write to the pool is announced.
    ///
    /// The home's account card is a snapshot field with no stream of its own:
    /// the per-account loading state, the settled flag and the listener's
    /// readiness all move without any seat's news, so a page that read them
    /// once drew `0 ready, probing` for the life of the connection while the
    /// pool had been ready for minutes. Nothing else in the stream says the
    /// pool moved, so the announcement is the only way a subscriber hears it.
    #[tokio::test]
    async fn a_probe_that_writes_the_pool_announces_it() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut updates = workspace.subscribe_answerer();
        // The boot backlog, so what the assertion reads is this call's news
        // rather than something emitted before it.
        while updates.try_recv().is_ok() {}

        workspace.record_usage_success(&AccountKey("Stargate".to_owned()), usage_at(10.0));

        let frame = std::iter::from_fn(|| updates.try_recv().ok())
            .find(|frame| matches!(&*frame.update, SessionUpdate::AccountsChanged { .. }))
            .expect("a probe that wrote the pool announced nothing");
        let SessionUpdate::AccountsChanged { accounts } =
            std::sync::Arc::unwrap_or_clone(frame.update)
        else {
            unreachable!("the predicate above selected this variant")
        };
        // The frame and the snapshot's field are one builder, so a client that
        // folds it draws what a client that reads the home draws.
        assert_eq!(
            accounts,
            workspace.account_pool_view(),
            "the announcement carried a different pool than the snapshot states",
        );
        assert_eq!(accounts.loading.len(), 1, "the pool's configured account is in the frame");
        assert_eq!(accounts.loading[0].display_name, "Stargate");
        assert!(
            accounts.usage[0].snapshot.is_some(),
            "the usage row carries the snapshot the poll wrote",
        );
    }

    /// The pool pairs each account's loading row with its own usage row.
    ///
    /// Two accounts with different figures: a builder keyed off the wrong
    /// name would hand one account the other's usage, and the band card and
    /// the rail chip would draw the wrong account's numbers.
    #[tokio::test]
    async fn the_pool_view_pairs_each_account_with_its_own_usage() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["A", "B"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "A"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "B"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));

        workspace.record_usage_success(&AccountKey("A".to_owned()), usage_at(10.0));
        workspace.record_usage_success(&AccountKey("B".to_owned()), usage_at(20.0));

        let pool = workspace.account_pool_view();
        let loading: Vec<&str> = pool.loading.iter().map(|row| row.display_name.as_str()).collect();
        assert_eq!(loading, ["A", "B"], "the loading rows keep declaration order");
        let usage: Vec<(&str, Option<f64>)> = pool
            .usage
            .iter()
            .map(|row| {
                (
                    row.display_name.as_str(),
                    row.snapshot
                        .as_ref()
                        .and_then(forge_primitives::usage::UsageSnapshot::five_hour_util),
                )
            })
            .collect();
        assert_eq!(
            usage,
            [("A", Some(10.0)), ("B", Some(20.0))],
            "each account carries its own snapshot",
        );
    }

    /// A poll that found the pool as it already stood announces nothing.
    ///
    /// **`fetched_at` moves on every probe**, so a comparison against the
    /// whole snapshot makes every poll news: six idle accounts then send six
    /// pool frames a minute for figures nobody changed. What is news is the
    /// pool's loading state or its usage, and a probe that moved either still
    /// announces.
    #[tokio::test]
    async fn a_probe_announces_only_a_pool_that_moved() {
        fn announced(updates: &mut tokio::sync::mpsc::UnboundedReceiver<SeatUpdate>) -> usize {
            std::iter::from_fn(|| updates.try_recv().ok())
                .filter(|frame| matches!(&*frame.update, SessionUpdate::AccountsChanged { .. }))
                .count()
        }

        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut updates = workspace.subscribe_answerer();
        while updates.try_recv().is_ok() {}

        let key = AccountKey("Stargate".to_owned());
        let first = usage_at(10.0);
        workspace.record_usage_success(&key, first.clone());
        assert_eq!(announced(&mut updates), 1, "the loading transition is news");

        let mut later = first.clone();
        later.fetched_at = first.fetched_at + std::time::Duration::from_secs(60);
        workspace.record_usage_success(&key, later);
        assert_eq!(announced(&mut updates), 0, "an unchanged pool is no news");

        workspace.record_usage_success(&key, usage_at(11.0));
        assert_eq!(announced(&mut updates), 1, "a window that moved is news");
    }

    /// A probe that moves only the pool's loading state is news, even when
    /// its figures match the ones already held.
    ///
    /// The pool can hold a snapshot while an account is still `Loading` -
    /// the cache seeds usage before anything settles the state - and a poll
    /// that is what moves it to `Ready` changes nothing else. Without the
    /// loading clause the card keeps `0 ready, probing` until something else
    /// moves.
    #[tokio::test]
    async fn a_probe_that_only_settles_the_loading_state_is_news() {
        use forge_gateway::LoadingState;

        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut updates = workspace.subscribe_answerer();
        while updates.try_recv().is_ok() {}
        let key = AccountKey("Stargate".to_owned());

        let cached = usage_at(10.0);
        workspace.accounts.set_usage(&key, cached.clone());
        workspace.accounts.set_loading(&key, LoadingState::Loading);

        let mut same = cached;
        same.fetched_at += std::time::Duration::from_secs(60);
        workspace.record_usage_success(&key, same);

        let announced = std::iter::from_fn(|| updates.try_recv().ok())
            .filter(|frame| matches!(&*frame.update, SessionUpdate::AccountsChanged { .. }))
            .count();
        assert_eq!(announced, 1, "the Loading -> Ready move was not announced");
    }

    /// A success after a transient failure is news even when its figures
    /// match the ones held.
    ///
    /// The loading row carries the last probe failure and its hold-down, and
    /// a clean probe clears both. With the usage identical that is the only
    /// change in the pool, so a comparison that looks at the figures alone
    /// drops the read and leaves a client drawing a failure the pool no
    /// longer holds.
    #[tokio::test]
    async fn a_probe_after_a_failure_is_news_even_when_the_figures_match() {
        use forge_gateway::UsageFetchStatus;

        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut updates = workspace.subscribe_answerer();
        while updates.try_recv().is_ok() {}
        let key = AccountKey("Stargate".to_owned());

        let held = usage_at(10.0);
        workspace.accounts.set_usage(&key, held.clone());
        workspace.accounts.set_last_error(
            &key,
            UsageFetchStatus::RateLimited,
            Some(std::time::Duration::from_secs(120)),
        );

        let mut same = held;
        same.fetched_at += std::time::Duration::from_secs(60);
        workspace.record_usage_success(&key, same);

        let announced = std::iter::from_fn(|| updates.try_recv().ok())
            .filter(|frame| matches!(&*frame.update, SessionUpdate::AccountsChanged { .. }))
            .count();
        assert_eq!(announced, 1, "the cleared probe failure was not announced");
    }

    /// An org whose primaries cannot serve the project's model and whose
    /// fallback can: the walk reaches the fallback because the primaries
    /// declare nothing it serves.
    fn make_workspace_dir_fallback_only_model() -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Personal"]
fallback_accounts = ["OpenRouter-TM"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "deepseek-v4.1-flash"

[[accounts]]
display_name = "Personal"
token = "t"
models = ["claude-opus-5"]
provider = "anthropic"

[[accounts]]
display_name = "OpenRouter-TM"
token = "t"
models = ["deepseek-v4.1-flash"]
provider = "openrouter"
base_url = "https://openrouter.ai/api"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// Two primaries where only the second serves the project's model.
    fn make_workspace_dir_model_split() -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            forge_toml_path(dir.path()),
            r#"
[[orgs]]
name = "Default"
accounts = ["Personal", "OpenRouter-TM"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "deepseek-v4.1-flash"

[[accounts]]
display_name = "Personal"
token = "t"
models = ["claude-opus-5"]
provider = "anthropic"

[[accounts]]
display_name = "OpenRouter-TM"
token = "t"
models = ["deepseek-v4.1-flash"]
provider = "openrouter"
base_url = "https://openrouter.ai/api"
"#,
        )
        .expect("write forge.toml");
        dir
    }

    /// The project's model is served only by a fallback account: the walk
    /// reaches it, so the session lands on the declaring account rather
    /// than on a primary that cannot serve it.
    #[tokio::test]
    async fn a_model_declaring_project_spawns_on_the_fallback_that_serves_it() {
        let dir = make_workspace_dir_fallback_only_model();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let pool = workspace.account_pool();
        pool.set_usage(&AccountKey("Personal".to_owned()), usage_at(10.0));
        pool.set_usage(&AccountKey("OpenRouter-TM".to_owned()), usage_at(10.0));
        let handle = workspace
            .get_agent_handle(
                SessionTarget::Named("forge".to_owned()),
                SessionLaunchSettings::default(),
                &crate::protocol::SpawnRole::Lead,
            )
            .expect("the declaring fallback serves the spawn");
        assert_eq!(
            handle.display_name().as_deref(),
            Some("OpenRouter-TM"),
            "the spawn lands on the account that declares the project's model",
        );
    }

    /// The spawn pins the project's canonical model into the launch
    /// settings - which is how the session's model reaches the CLI - and
    /// a project that declares no model leaves the caller's pin alone.
    #[test]
    fn the_project_model_is_pinned_into_the_launch_settings() {
        let dir = make_workspace_dir_model_split();
        let config = crate::config::load_from_dir(dir.path()).expect("load");
        let project = config.projects.iter().find(|p| p.name == "forge").expect("forge project");
        let mut settings = SessionLaunchSettings {
            settings: Some(serde_json::json!({"effortLevel": "max", "model": "opus"})),
            ..SessionLaunchSettings::default()
        };
        apply_project_model(Some(project), &mut settings);
        let document = settings.settings.expect("document");
        assert_eq!(
            document["model"],
            serde_json::json!("deepseek-v4.1-flash"),
            "the canonical model replaces the caller's pin",
        );
        assert_eq!(
            document["effortLevel"],
            serde_json::json!("max"),
            "the other settings keys survive the pin",
        );

        let bare_dir = make_workspace_dir_lead_and_worker();
        let bare_config = crate::config::load_from_dir(bare_dir.path()).expect("load");
        let mut bare_settings = SessionLaunchSettings {
            settings: Some(serde_json::json!({"model": "opus"})),
            ..SessionLaunchSettings::default()
        };
        apply_project_model(bare_config.projects.first(), &mut bare_settings);
        assert_eq!(
            bare_settings.settings.expect("document")["model"],
            serde_json::json!("opus"),
            "a project that declares no model leaves the caller's pin alone",
        );
    }

    /// The refusal is a stated requirement: it names the project, the
    /// model, the org and the accounts considered.
    #[test]
    fn the_refusal_names_the_project_model_org_and_accounts_considered() {
        let error = WorkspaceError::NoAccountServesProjectModel {
            project: "steve".to_owned(),
            org: "Busytools".to_owned(),
            model: "glm-5.3-flash".to_owned(),
            accounts: "Zai, Personal".to_owned(),
        };
        let message = error.to_string();
        for needle in ["steve", "glm-5.3-flash", "Busytools", "Zai, Personal"] {
            assert!(message.contains(needle), "the refusal must name {needle}: {message}");
        }
    }

    fn usage_at(five_hour_util: f64) -> forge_primitives::usage::UsageSnapshot {
        forge_primitives::usage::UsageSnapshot {
            source: forge_primitives::usage::UsageSourceKind::Oauth,
            fetched_at: std::time::SystemTime::UNIX_EPOCH,
            five_hour: Some(forge_primitives::usage::UsageWindow {
                utilization: five_hour_util,
                resets_at: Some(
                    std::time::SystemTime::now() + std::time::Duration::from_secs(3600),
                ),
                reset_description: None,
                status: None,
            }),
            seven_day: None,
            seven_day_opus: None,
            seven_day_sonnet: None,
            extra_usage: None,
            spend: None,
            balance: None,
        }
    }

    #[tokio::test]
    async fn a_chip_needs_an_account_the_walk_can_find() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config_arc().projects[0].path.to_string_lossy().as_ref(),
            )));
        assert!(
            workspace.session_chip_for(&project_key).is_none(),
            "nothing is Ready yet, so the walk finds no account to chip with",
        );
    }

    #[tokio::test]
    async fn session_chip_for_normal_branch_for_ready_account() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.account_pool().set_usage(
            &AccountKey("Stargate".to_owned()),
            forge_primitives::usage::UsageSnapshot {
                source: forge_primitives::usage::UsageSourceKind::Oauth,
                fetched_at: std::time::SystemTime::UNIX_EPOCH,
                // 5h window not at cap -> Normal branch.
                five_hour: Some(forge_primitives::usage::UsageWindow {
                    utilization: 30.0,
                    resets_at: Some(
                        std::time::SystemTime::now() + std::time::Duration::from_secs(3600),
                    ),
                    reset_description: None,
                    status: None,
                }),
                seven_day: None,
                seven_day_opus: None,
                seven_day_sonnet: None,
                extra_usage: None,
                spend: None,
                balance: None,
            },
        );
        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config_arc().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace.session_chip_for(&project_key).expect("chip");
        assert_eq!(chip.state, SessionChipState::Normal);
        assert_eq!(chip.account_name, "Stargate");
    }

    #[tokio::test]
    async fn session_chip_for_at_cap_branch() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.account_pool().set_usage(
            &AccountKey("Stargate".to_owned()),
            forge_primitives::usage::UsageSnapshot {
                source: forge_primitives::usage::UsageSourceKind::Oauth,
                fetched_at: std::time::SystemTime::UNIX_EPOCH,
                // 5h window at 100% with future resets_at -> AtCap branch.
                five_hour: Some(forge_primitives::usage::UsageWindow {
                    utilization: 100.0,
                    resets_at: Some(
                        std::time::SystemTime::now() + std::time::Duration::from_secs(3600),
                    ),
                    reset_description: None,
                    status: None,
                }),
                seven_day: None,
                seven_day_opus: None,
                seven_day_sonnet: None,
                extra_usage: None,
                spend: None,
                balance: None,
            },
        );
        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config_arc().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace.session_chip_for(&project_key).expect("chip");
        assert_eq!(chip.state, SessionChipState::AtCap);
    }

    #[tokio::test]
    async fn session_chip_for_at_cap_on_weekly_window() {
        // A weekly (7-day) cap alone, 5h window clear, must still flag
        // the chip AtCap - saturation is any-window, not 5h-only.
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.account_pool().set_usage(
            &AccountKey("Stargate".to_owned()),
            forge_primitives::usage::UsageSnapshot {
                source: forge_primitives::usage::UsageSourceKind::Oauth,
                fetched_at: std::time::SystemTime::UNIX_EPOCH,
                five_hour: None,
                seven_day: Some(forge_primitives::usage::UsageWindow {
                    utilization: 100.0,
                    resets_at: Some(
                        std::time::SystemTime::now() + std::time::Duration::from_secs(86_400),
                    ),
                    reset_description: None,
                    status: None,
                }),
                seven_day_opus: None,
                seven_day_sonnet: None,
                extra_usage: None,
                spend: None,
                balance: None,
            },
        );
        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config_arc().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace.session_chip_for(&project_key).expect("chip");
        assert_eq!(chip.state, SessionChipState::AtCap);
    }

    /// **A chip resolves while the walk refuses.** A cooling account is the
    /// one a spawn would land on once its window lifts, so the read names
    /// it and says it is rate-limited; the walk and the spawn refusal are
    /// untouched.
    #[tokio::test]
    async fn session_chip_for_names_the_cooling_account() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let key = AccountKey("Stargate".to_owned());
        workspace.account_pool().set_usage(&key, usage_at(100.0));
        let reset_at = std::time::SystemTime::now()
            .duration_since(std::time::SystemTime::UNIX_EPOCH)
            .expect("the test clock is past the epoch")
            .as_secs()
            + 3600;
        workspace.gateway.report_probe_limit(&key, Some(reset_at));

        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config.read().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace
            .session_chip_for(&project_key)
            .expect("the read names the account a spawn would land on");
        assert_eq!(chip.account_name, "Stargate");
        assert_eq!(chip.state, SessionChipState::RateLimited);

        assert!(
            matches!(
                workspace.gateway.select_for("Default", "claude-sonnet-5"),
                Err(forge_gateway::SelectFailure::BudgetExhausted { .. }),
            ),
            "the read surface must not have made the cooling account selectable",
        );
    }

    /// **With two cooling accounts the chip follows the thaw, not pin
    /// order.** The first spawn after the cooldowns lift lands on the
    /// account whose reset is soonest, so that is the one whose windows and
    /// reset the footer must state.
    #[tokio::test]
    async fn session_chip_for_names_the_cooling_account_that_thaws_first() {
        let dir = make_two_account_workspace_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let first = AccountKey("First".to_owned());
        let second = AccountKey("Second".to_owned());
        workspace.account_pool().set_usage(&first, usage_at(42.0));
        workspace.account_pool().set_usage(&second, usage_at(100.0));
        let now = std::time::SystemTime::now()
            .duration_since(std::time::SystemTime::UNIX_EPOCH)
            .expect("the test clock is past the epoch")
            .as_secs();
        workspace.gateway.report_probe_limit(&first, Some(now + 2 * 3600));
        workspace.gateway.report_probe_limit(&second, Some(now + 10 * 60));

        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config.read().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace
            .session_chip_for(&project_key)
            .expect("the read names the account a spawn would land on");
        assert_eq!(
            chip.account_name, "Second",
            "the chip named the first-pinned account instead of the one that thaws first",
        );
        assert_eq!(chip.state, SessionChipState::RateLimited);
    }

    #[tokio::test]
    async fn session_chip_for_bailed_branch() {
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // Snapshot first, then bail: the walk reads the loading state,
        // so a chip needs the account first made pickable.
        workspace.account_pool().set_usage(
            &AccountKey("Stargate".to_owned()),
            forge_primitives::usage::UsageSnapshot {
                source: forge_primitives::usage::UsageSourceKind::Oauth,
                fetched_at: std::time::SystemTime::UNIX_EPOCH,
                five_hour: None,
                seven_day: None,
                seven_day_opus: None,
                seven_day_sonnet: None,
                extra_usage: None,
                spend: None,
                balance: None,
            },
        );
        // Now flip to Bailed on an auth failure - the red class.
        workspace
            .account_pool()
            .set_loading(&AccountKey("Stargate".to_owned()), forge_gateway::LoadingState::Bailed);
        workspace.account_pool().set_last_error(
            &AccountKey("Stargate".to_owned()),
            forge_gateway::UsageFetchStatus::Unauthorized,
            None,
        );
        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config_arc().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace.session_chip_for(&project_key).expect("chip");
        assert_eq!(chip.state, SessionChipState::Bailed);
    }

    #[tokio::test]
    async fn session_chip_for_degraded_branch() {
        // A Bailed account with no auth class recorded - the
        // shape-drift settle, or a rate limit - is the warning-yellow
        // Degraded chip, the same split the account rows render.
        let dir = make_workspace_dir_246();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.account_pool().set_usage(
            &AccountKey("Stargate".to_owned()),
            forge_primitives::usage::UsageSnapshot {
                source: forge_primitives::usage::UsageSourceKind::Oauth,
                fetched_at: std::time::SystemTime::UNIX_EPOCH,
                five_hour: None,
                seven_day: None,
                seven_day_opus: None,
                seven_day_sonnet: None,
                extra_usage: None,
                spend: None,
                balance: None,
            },
        );
        workspace
            .account_pool()
            .set_loading(&AccountKey("Stargate".to_owned()), forge_gateway::LoadingState::Bailed);
        let project_key =
            ProjectKey::new(forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
                workspace.config_arc().projects[0].path.to_string_lossy().as_ref(),
            )));
        let chip = workspace.session_chip_for(&project_key).expect("chip");
        assert_eq!(chip.state, SessionChipState::Degraded);
    }

    /// One transcript under the storage key of `run_dir`, tagged for `label`
    /// when there is one, with its mtime pinned to `secs` so the newest-first
    /// order is a fact rather than the clock's granularity.
    fn write_picker_transcript(
        cfg: &tempfile::TempDir,
        run_dir: &std::path::Path,
        id: &str,
        label: Option<&str>,
        secs: u64,
    ) {
        let run_dir = run_dir.to_string_lossy().replace('\\', "/");
        let key = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&run_dir));
        let dir = forge_sdk::projects_dir_for(cfg.path()).join(key);
        std::fs::create_dir_all(&dir).expect("transcript dir");
        let tag = label
            .map(|label| format!("{{\"type\":\"tag\",\"tag\":\"forge:worker:{label}\"}}\n"))
            .unwrap_or_default();
        let body = format!(
            "{{\"type\":\"user\",\"cwd\":\"{run_dir}\",\"message\":{{\"content\":\"session {id}\"}}}}\n{tag}"
        );
        let path = dir.join(format!("{id}.jsonl"));
        std::fs::write(&path, body).expect("write transcript");
        let file = std::fs::File::options().write(true).open(&path).expect("open the transcript");
        file.set_modified(std::time::UNIX_EPOCH + std::time::Duration::from_secs(secs))
            .expect("pin the transcript's mtime");
    }

    /// A worker's list is only what its own label ran, and only in the
    /// directory its resume runs in: another worker's transcript and an
    /// untagged one in the same worktree are both out.
    #[tokio::test]
    async fn resume_sessions_of_a_worker_are_only_its_own_labels() {
        let project = tempfile::tempdir().expect("project dir");
        let cfg = tempfile::tempdir().expect("cfg dir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(cfg.path().to_owned());
        let root = project.path().to_string_lossy().replace('\\', "/");
        ws.seed_test_project("demo", &root);
        let seat = SessionSlot::worker("TestOrg", "demo", "alpha");
        let project_key = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&root)),
        );
        ws.insert_live_worker(&project_key, worker_entry("alpha", &seat, true));
        let worktree = project.path().join(".claude/worktrees/alpha");
        std::fs::create_dir_all(&worktree).expect("worktree dir");
        write_picker_transcript(&cfg, &worktree, "alpha-new", Some("alpha"), 1_700_000_200);
        write_picker_transcript(&cfg, &worktree, "alpha-old", Some("alpha"), 1_700_000_100);
        write_picker_transcript(&cfg, &worktree, "beta", Some("beta"), 1_700_000_300);
        write_picker_transcript(&cfg, &worktree, "untagged", None, 1_700_000_400);
        // The same label's run from another tree, which `--resume` from this
        // seat's directory cannot find at all.
        let elsewhere = project.path().join("elsewhere");
        std::fs::create_dir_all(&elsewhere).expect("another tree");
        write_picker_transcript(&cfg, &elsewhere, "elsewhere", Some("alpha"), 1_700_000_500);

        let found = ws.resumable_sessions(&seat).await;

        assert_eq!(
            found.iter().map(|info| info.session_id.as_str()).collect::<Vec<_>>(),
            ["alpha-new", "alpha-old"],
            "its own label's runs in its own directory, newest first, and nothing else",
        );
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used)]
mod kick_dispatcher_tests {
    //! Cover for `start_kick_dispatcher` plus `enqueue_kick` (#259).
    //!
    //! Tests observe via `command_intercept` (`enable_test_dispatch_intercept`
    //! plus `drain_test_dispatch_buffer`); the drainer calls
    //! `Workspace::dispatch_forged_prompt` for each `KickRequest`, which the
    //! intercept buffer captures verbatim and whose prompt frame the update
    //! stream carries.
    //!
    //! Time is paused (`start_paused = true`) so the drainer's
    //! `tokio::time::sleep(KICK_DISPATCH_INTERVAL)` advances only when
    //! the test explicitly advances the clock. Without that, the
    //! drainer would race the assertions in real time.
    use super::*;
    use crate::protocol::Command;
    use std::time::Duration;

    /// A drained kick draws the words it sends the worker.
    ///
    /// They reach the model on stdin and the CLI does not echo them, so the
    /// frame is the only thing a view can draw them from - and reverting the
    /// drainer to the delivery path leaves every dispatch-side test in here
    /// green, which is why this one asserts the frame.
    #[tokio::test(start_paused = true)]
    async fn a_drained_kick_draws_its_words() {
        let (workspace, mut update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();

        let key = sk("draws");
        workspace
            .enqueue_kick(KickRequest { slot: key.clone(), prompt_body: "get on with it".into() });
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;

        let mut echoed = None;
        while let Ok(frame) = update_rx.try_recv() {
            if let crate::protocol::SessionUpdate::ChatAppended { key: addressed, msg, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && addressed == key
            {
                echoed = Some(msg);
            }
        }
        let frame = echoed;
        let Some(Message::User { message, .. }) = frame else {
            panic!("a drained kick draws the words the worker received")
        };
        assert!(
            matches!(
                message.content.first(),
                Some(forge_primitives::ContentBlock::Text { text, .. }) if text == "get on with it"
            ),
            "the frame carries the kick's prose: {message:?}",
        );
    }

    /// Helper: a session key for kick tests.
    fn sk(name: &str) -> SessionSlot {
        SessionSlot::from_str_for_test(format!("kick-test-{name}"))
    }

    /// Helper: assert the intercept buffer's Prompt commands match
    /// `expected` SessionSlots in order. Filters out any non-Prompt
    /// commands the dispatch path might queue.
    fn assert_dispatched_kick_keys(
        workspace: &Arc<Workspace>,
        expected: &[SessionSlot],
        context: &str,
    ) {
        let dispatched = workspace.drain_test_dispatch_buffer();
        let keys: Vec<SessionSlot> = dispatched
            .into_iter()
            .filter_map(|c| match c {
                Command::Prompt { key, .. } | Command::PromptUnder { key, .. } => Some(key),
                _ => None,
            })
            .collect();
        assert_eq!(keys, expected.to_vec(), "{context}: dispatched keys mismatch");
    }

    /// First-kick latency is zero (drainer pulls immediately), and
    /// the SECOND kick waits `KICK_DISPATCH_INTERVAL` before firing.
    /// Pinning the stagger interval prevents a regression where the
    /// drainer sleeps before its first send (which would be a
    /// straightforward off-by-one bug given the loop's structure).
    #[tokio::test(start_paused = true)]
    async fn dispatcher_fires_first_kick_immediately_then_staggers() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();

        let a = sk("a");
        let b = sk("b");
        workspace.enqueue_kick(KickRequest { slot: a.clone(), prompt_body: "kick a".into() });
        workspace.enqueue_kick(KickRequest { slot: b.clone(), prompt_body: "kick b".into() });

        // Yield once so the drainer task gets a turn; it should fire
        // the first kick before sleeping. With paused time the sleep
        // doesn't advance, so the SECOND kick stays pending.
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;
        assert_dispatched_kick_keys(&workspace, std::slice::from_ref(&a), "after first yield");

        // Advance time past the interval; drainer wakes, fires the
        // second kick, then sleeps again with the queue now empty.
        tokio::time::advance(KICK_DISPATCH_INTERVAL).await;
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;
        assert_dispatched_kick_keys(&workspace, std::slice::from_ref(&b), "after interval advance");
    }

    /// Multi-worker burst: 7 simultaneous enqueues produce exactly
    /// one dispatch per interval, all 7 dispatched after 6 advances.
    /// Mirrors the issue's reproduction shape (forge boot with 5+
    /// team workers).
    #[tokio::test(start_paused = true)]
    async fn dispatcher_staggers_seven_simultaneous_kicks_one_per_interval() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();

        let keys: Vec<SessionSlot> = (0..7).map(|i| sk(&format!("worker-{i}"))).collect();
        for key in &keys {
            workspace.enqueue_kick(KickRequest {
                slot: key.clone(),
                prompt_body: format!("kick {}", key.display()),
            });
        }

        // First kick fires before any sleep.
        tokio::task::yield_now().await;
        tokio::task::yield_now().await;
        assert_dispatched_kick_keys(&workspace, &keys[0..1], "boot tick");

        // Six more intervals → six more kicks → all 7 dispatched.
        for i in 1..7 {
            tokio::time::advance(KICK_DISPATCH_INTERVAL).await;
            tokio::task::yield_now().await;
            tokio::task::yield_now().await;
            assert_dispatched_kick_keys(
                &workspace,
                &keys[i..=i],
                &format!("after interval advance {i}"),
            );
        }
    }

    /// `start_kick_dispatcher` is idempotent: a second call after the
    /// receiver has been taken finds the slot empty and no-ops. A
    /// regression that spawns two drainers would fire each kick TWICE
    /// (both drainers would race for the same receiver - actually
    /// only the first would get the item due to mpsc semantics, but
    /// the SECOND drainer would burn task slots forever waiting on
    /// an empty channel). Pin by counting dispatches against a known
    /// queue.
    #[tokio::test(start_paused = true)]
    async fn start_kick_dispatcher_is_idempotent() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        workspace.enable_test_dispatch_intercept();
        workspace.start_kick_dispatcher();
        workspace.start_kick_dispatcher(); // no-op second call

        workspace.enqueue_kick(KickRequest { slot: sk("only"), prompt_body: "k".into() });
        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, "second start_kick_dispatcher must not duplicate dispatches");
    }

    /// `enqueue_kick` after workspace drop is logged but doesn't
    /// panic. The channel's sender is held on `Workspace`, so dropping
    /// the workspace closes the channel; the drainer (if still alive)
    /// exits its recv loop. Verifying the no-panic shape protects the
    /// shutdown-race window where a final Connected event might queue
    /// a kick after the drop began.
    ///
    /// We don't drop the Arc here (testing_stub gives one out and the
    /// test holds it for the duration). What we DO verify: `enqueue_kick`
    /// returns successfully when the dispatcher hasn't been started -
    /// the message just sits in the channel until either the drainer
    /// is started or the workspace is dropped. Either way, no panic.
    #[tokio::test]
    async fn enqueue_kick_without_dispatcher_started_does_not_panic() {
        let (workspace, _update_rx) = Workspace::testing_stub();
        // Note: NOT calling start_kick_dispatcher.
        workspace.enqueue_kick(KickRequest { slot: sk("orphan"), prompt_body: "k".into() });
        // No assertion target other than "we got here without panicking".
        // A future change that makes enqueue_kick require a started
        // dispatcher would fail this test.
        let _ = Duration::from_millis(0); // touch Duration to keep the use site live
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used)]
mod catalog_scan_tests {
    use super::*;
    use crate::protocol::Command;
    use forge_agent::client::SessionLaunchSettings;
    use std::fs;
    use tempfile::tempdir;

    const LEAD_UUID: &str = "00000000-0000-4000-8000-000000000001";
    const WORKER_UUID: &str = "00000000-0000-4000-8000-000000000002";

    /// One project rooted inside the tempdir plus a transcript whose
    /// head carries that cwd, so the scan groups the session under the
    /// project's key the same way boot did.
    fn scan_fixture_dir() -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        let project_path = dir.path().join("proj");
        let toml = format!(
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]
[[orgs.projects]]
name = "proj"
path = "{}"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            project_path.display()
        );
        fs::write(forge_toml_path(dir.path()), toml).expect("write forge.toml");
        write_session_fixture(dir.path(), &project_path.display().to_string(), LEAD_UUID, None);
        dir
    }

    fn write_session_fixture(
        config_dir: &std::path::Path,
        project_path: &str,
        session_id: &str,
        tag: Option<&str>,
    ) {
        let key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(project_path));
        let project_dir = config_dir.join("projects").join(key);
        fs::create_dir_all(&project_dir).expect("project dir");
        let mut body = format!(
            "{{\"type\":\"user\",\"timestamp\":\"2026-09-05T00:00:00.000Z\",\"cwd\":\"{project_path}\",\"message\":{{\"content\":\"opening prompt\"}}}}\n"
        );
        if let Some(tag) = tag {
            body = format!(
                "{body}{{\"type\":\"tag\",\"tag\":\"{tag}\",\"sessionId\":\"{session_id}\"}}\n"
            );
        }
        fs::write(project_dir.join(format!("{session_id}.jsonl")), body).expect("write jsonl");
    }

    /// A spawn does not park on the background catalog scan. It reaches
    /// the pool immediately against an unloaded catalog, keyed by an id
    /// forge minted rather than the lead transcript that catalog holds -
    /// the store is the resume source now, and it is empty here.
    #[tokio::test]
    async fn a_spawn_before_the_scan_does_not_wait_for_it() {
        let dir = scan_fixture_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_gateway_ready(true);
        workspace.seed_test_ready_account("Stargate");
        assert!(!workspace.catalog_ready(), "new_for_test leaves the scan unstarted");

        workspace
            .dispatch(Command::SpawnProject {
                project_name: "proj".to_owned(),
                launch_settings: SessionLaunchSettings::default(),
            })
            .expect("dispatch");

        let keys: Vec<String> =
            workspace.pool.lock().keys().map(forge_primitives::SessionSlot::display).collect();
        assert_eq!(keys.len(), 1, "the spawn reached the pool without waiting for the scan");
        assert_ne!(
            keys[0], LEAD_UUID,
            "and keys to an id forge minted, not the catalog's lead transcript",
        );
    }

    /// The background scan swaps the catalog in and announces it: the
    /// update arrives, readiness flips, and the default catalog hides
    /// worker-tagged sessions exactly as the synchronous scan did.
    #[tokio::test]
    async fn catalog_scan_reports_loaded_and_fills_project_views() {
        let dir = scan_fixture_dir();
        write_session_fixture(
            dir.path(),
            &dir.path().join("proj").display().to_string(),
            WORKER_UUID,
            Some("forge:worker:implementer"),
        );
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut update_rx = workspace.subscribe_answerer();
        assert!(workspace.list_projects()[0].sessions.is_empty(), "catalog starts empty");

        workspace.start_catalog_scan();

        let update = tokio::time::timeout(Duration::from_secs(5), update_rx.recv())
            .await
            .expect("scan finishes")
            .expect("channel open");
        assert!(
            matches!(&*update.update, SessionUpdate::CatalogLoaded),
            "expected CatalogLoaded, got {update:?}"
        );
        assert!(workspace.catalog_ready());

        let projects = workspace.list_projects();
        assert_eq!(projects.len(), 1);
        assert_eq!(
            projects[0].sessions.len(),
            1,
            "worker-tagged sessions stay hidden from the default catalog"
        );
        assert_eq!(projects[0].sessions[0].session.as_str(), LEAD_UUID);
    }

    /// No spawn waits on the boot catalog scan any more: the lead's
    /// resume target comes from the store, so a spawn dispatched against
    /// an unloaded catalog lands immediately, keyed by the project's
    /// lead slot rather than by the lead transcript the catalog holds.
    #[tokio::test]
    async fn a_spawn_does_not_wait_for_the_catalog_scan() {
        let dir = scan_fixture_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        assert!(!workspace.catalog_ready(), "the scan has not landed yet");

        workspace
            .dispatch(Command::SpawnProject {
                project_name: "proj".to_owned(),
                launch_settings: SessionLaunchSettings::default(),
            })
            .expect("dispatch");

        let keys: Vec<String> =
            workspace.pool.lock().keys().map(forge_primitives::SessionSlot::display).collect();
        assert_eq!(keys.len(), 1, "the spawn ran immediately, unparked");
        assert_eq!(
            keys[0], "Default/proj/lead",
            "and keyed by the project's lead slot: the catalog's lead transcript is not a \
             routing key, and the store this spawn reads is empty: {keys:?}",
        );
    }

    /// The boot scan persists a tag-cache row per transcript even when
    /// the config dir is reached through a symlink, and the same pass
    /// prunes a seeded row whose transcript is gone - the prune is part
    /// of the scan, not only of the store fn.
    #[tokio::test]
    async fn boot_scan_warms_the_cache_and_prunes_stale_rows() {
        let real = scan_fixture_dir();
        write_session_fixture(
            real.path(),
            &real.path().join("proj").display().to_string(),
            WORKER_UUID,
            Some("forge:worker:implementer"),
        );
        let link_dir = tempfile::tempdir().expect("tempdir");
        let link = link_dir.path().join("cfg");
        std::os::unix::fs::symlink(real.path(), &link).expect("symlink config dir");

        let workspace = Arc::new(Workspace::new_for_test(link).expect("new"));
        {
            let db = workspace.db.lock();
            crate::store::session_tags::store_all(
                db.as_ref().expect("test db present"),
                &[(
                    "/gone/deleted.jsonl".to_owned(),
                    forge_agent::userdata::catalog::scan::SessionTagScan {
                        tag: None,
                        project: None,
                        scanned_len: 10,
                    },
                )],
            )
            .expect("seed stale row");
        }

        workspace.start_catalog_scan();
        tokio::time::timeout(Duration::from_secs(5), async {
            while !workspace.catalog_ready() {
                tokio::time::sleep(Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("scan finishes");

        let prior = {
            let db = workspace.db.lock();
            crate::store::session_tags::load_all(db.as_ref().expect("test db present"))
                .expect("load persisted cache")
        };
        assert!(!prior.is_empty(), "the boot scan persisted cache rows");

        let after = {
            let db = workspace.db.lock();
            crate::store::session_tags::load_all(db.as_ref().expect("test db present"))
                .expect("reload cache")
        };
        assert!(!after.contains_key("/gone/deleted.jsonl"), "the boot scan pruned the stale row");
    }

    /// The boot scan reaches a tree through an outbound `projects`
    /// symlink when that tree lives elsewhere.
    #[tokio::test]
    async fn boot_scan_reaches_an_outbound_projects_symlink() {
        let cfg = tempdir().expect("cfg tempdir");
        let tree = tempdir().expect("tree tempdir");
        let project_path = cfg.path().join("proj");
        fs::create_dir_all(&project_path).expect("project dir");
        let toml = format!(
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]
[[orgs.projects]]
name = "proj"
path = "{}"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            project_path.display()
        );
        fs::write(forge_toml_path(cfg.path()), toml).expect("write forge.toml");
        write_session_fixture(
            tree.path(),
            &project_path.display().to_string(),
            WORKER_UUID,
            Some("forge:worker:implementer"),
        );
        std::os::unix::fs::symlink(tree.path().join("projects"), cfg.path().join("projects"))
            .expect("outbound projects symlink");

        let workspace = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("new"));
        workspace.start_catalog_scan();
        tokio::time::timeout(Duration::from_secs(5), async {
            while !workspace.catalog_ready() {
                tokio::time::sleep(Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("scan finishes");

        let prior = {
            let db = workspace.db.lock();
            crate::store::session_tags::load_all(db.as_ref().expect("test db present"))
                .expect("load persisted cache")
        };
        assert!(
            prior.keys().any(|key| key.contains("implementer") || !key.is_empty()),
            "the boot scan reached the external tree and persisted cache rows: {prior:?}",
        );
    }

    /// An outbound symlink whose target is not named `projects` still
    /// scans: the walk descends into `<root>/projects`, so a root
    /// derived from the target's parent would miss the tree entirely
    /// and the catalog would sit empty. The derivation falls back to
    /// the config dir, whose `projects` link resolves to the tree.
    #[tokio::test]
    async fn boot_scan_reaches_an_outbound_tree_not_named_projects() {
        let cfg = tempdir().expect("cfg tempdir");
        let tree = tempdir().expect("tree tempdir");
        let project_path = cfg.path().join("proj");
        fs::create_dir_all(&project_path).expect("project dir");
        let toml = format!(
            r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]
[[orgs.projects]]
name = "proj"
path = "{}"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            project_path.display()
        );
        fs::write(forge_toml_path(cfg.path()), toml).expect("write forge.toml");
        write_session_fixture(tree.path(), &project_path.display().to_string(), LEAD_UUID, None);
        // The fixture writes a literal `projects` dir; the layout under
        // test is one that is NOT named that.
        fs::rename(tree.path().join("projects"), tree.path().join("sessions"))
            .expect("rename the tree to an odd name");
        std::os::unix::fs::symlink(tree.path().join("sessions"), cfg.path().join("projects"))
            .expect("outbound projects symlink to an oddly named dir");

        let workspace = Arc::new(Workspace::new_for_test(cfg.path().to_owned()).expect("new"));
        workspace.start_catalog_scan();
        tokio::time::timeout(Duration::from_secs(5), async {
            while !workspace.catalog_ready() {
                tokio::time::sleep(Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("scan finishes");

        let sessions = &workspace.list_projects()[0].sessions;
        assert_eq!(
            sessions.first().map(|s| s.session.as_str()),
            Some(LEAD_UUID),
            "the session behind the oddly named link is in the catalog"
        );
    }

    /// A session recorded live before the scan lands survives the
    /// scan's catalog swap: its transcript may not exist on disk yet,
    /// so the disk-built map absorbs the recorded rows rather than
    /// replacing them.
    #[tokio::test]
    async fn scan_swap_preserves_live_recorded_sessions() {
        let dir = scan_fixture_dir();
        let project_dir = dir.path().join("proj");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));

        workspace.record_connected_session(&project_dir.display().to_string(), "live-uuid", None);
        workspace.start_catalog_scan();
        tokio::time::timeout(Duration::from_secs(5), async {
            while !workspace.catalog_ready() {
                tokio::time::sleep(Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("scan finishes");

        let sessions = &workspace.list_projects()[0].sessions;
        assert!(
            sessions.iter().any(|s| s.session.as_str() == "live-uuid"),
            "the live-recorded session survives the scan swap"
        );
        assert!(
            sessions.iter().any(|s| s.session.as_str() == LEAD_UUID),
            "the on-disk session is present alongside it"
        );
    }

    /// Live-recorded sessions keep their recorded (newest-first) order
    /// at the head of the merged catalog. The Projects pane reads
    /// `sessions.first()` for the row's relative time, so a reversed
    /// head shows the oldest connection's recency.
    #[tokio::test]
    async fn scan_swap_keeps_recorded_sessions_newest_first() {
        let dir = scan_fixture_dir();
        let project_dir = dir.path().join("proj");
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));

        workspace.record_connected_session(&project_dir.display().to_string(), "live-older", None);
        workspace.record_connected_session(&project_dir.display().to_string(), "live-newer", None);
        workspace.start_catalog_scan();
        tokio::time::timeout(Duration::from_secs(5), async {
            while !workspace.catalog_ready() {
                tokio::time::sleep(Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("scan finishes");

        let sessions = &workspace.list_projects()[0].sessions;
        assert_eq!(
            sessions[0].session.as_str(),
            "live-newer",
            "the latest connection leads the project"
        );
        assert_eq!(sessions[1].session.as_str(), "live-older");
        assert_eq!(sessions[2].session.as_str(), LEAD_UUID);
    }

    /// With no tokio runtime there is no scan to await, so readiness
    /// publishes immediately over an empty catalog and spawns fall
    /// through to fresh instead of parking forever.
    #[test]
    fn start_catalog_scan_without_a_runtime_publishes_readiness() {
        let dir = scan_fixture_dir();
        let workspace = Workspace::new_for_test(dir.path().to_owned()).expect("new");

        workspace.start_catalog_scan();

        assert!(workspace.catalog_ready(), "no runtime: readiness publishes immediately");
        assert!(
            workspace.list_projects()[0].sessions.is_empty(),
            "no runtime: no scan ran, the catalog stays empty"
        );
    }

    // ---------------------------------------------------------------
    // `/resume`'s list is what `claude --resume` can find from the
    // directory the seat's own resume runs in.
    // ---------------------------------------------------------------

    /// Run the boot catalog scan and wait for it, so the seat's read takes the
    /// catalog branch rather than the directory's own.
    async fn ready_catalog(workspace: &Arc<Workspace>) {
        let mut updates = workspace.subscribe_answerer();
        workspace.start_catalog_scan();
        loop {
            let update = tokio::time::timeout(std::time::Duration::from_secs(5), updates.recv())
                .await
                .expect("the scan finishes")
                .expect("the stream is open");
            if matches!(&*update.update, SessionUpdate::CatalogLoaded) {
                break;
            }
        }
        assert!(workspace.catalog_ready(), "the scan landed before the read");
    }

    /// Pin a transcript's mtime to a fixed second, so a test that reads the
    /// newest first does not depend on the clock's granularity.
    fn pin_transcript(dir: &tempfile::TempDir, project_path: &str, id: &str, secs: u64) {
        let key =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(project_path));
        let path = dir.path().join("projects").join(key).join(format!("{id}.jsonl"));
        let file = fs::File::options().write(true).open(&path).expect("open the transcript");
        file.set_modified(std::time::UNIX_EPOCH + std::time::Duration::from_secs(secs))
            .expect("pin the transcript's mtime");
    }

    /// A lead's list is its project's own transcripts, newest first, and never
    /// a worker's: a lead's resume runs in the project root, where a non-git
    /// worker's transcript sits too, and picking it would put the lead's turns
    /// into a transcript tagged for that worker.
    ///
    /// **The newest transcript is the SECOND file written**, so a list that
    /// came back in directory order passes only if it also sorts.
    #[tokio::test]
    async fn resume_sessions_of_a_lead_are_its_projects_and_never_its_workers() {
        let dir = scan_fixture_dir();
        let project = dir.path().join("proj");
        let project_path = project.display().to_string();
        write_session_fixture(dir.path(), &project_path, "older", None);
        write_session_fixture(dir.path(), &project_path, WORKER_UUID, Some("forge:worker:alpha"));
        pin_transcript(&dir, &project_path, "older", 1_700_000_200);
        pin_transcript(&dir, &project_path, LEAD_UUID, 1_700_000_100);
        pin_transcript(&dir, &project_path, WORKER_UUID, 1_700_000_300);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));

        let found = workspace.resumable_sessions(&SessionSlot::lead("Default", "proj")).await;

        assert_eq!(
            found.iter().map(|info| info.session_id.as_str()).collect::<Vec<_>>(),
            ["older", LEAD_UUID],
            "the project's own transcripts, newest first, and never a worker's",
        );
        assert_eq!(found[1].summary, "opening prompt", "a row carries the transcript's title");
    }

    /// The list is the sessions a seat can JUMP BACK TO, so the one it is
    /// already on is not one of them: a pick would respawn the seat onto
    /// itself.
    ///
    /// **A newer row is not the occupant**, so an exclusion that drops the
    /// list's head instead of the occupant loses a real jump and fails.
    #[tokio::test]
    async fn resume_sessions_leave_out_the_session_the_seat_is_already_on() {
        let dir = scan_fixture_dir();
        let project = dir.path().join("proj");
        let project_path = project.display().to_string();
        write_session_fixture(dir.path(), &project_path, "newer", None);
        pin_transcript(&dir, &project_path, "newer", 1_700_000_200);
        pin_transcript(&dir, &project_path, LEAD_UUID, 1_700_000_100);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let seat = SessionSlot::lead("Default", "proj");
        workspace.record_session_id("Default", "proj", "lead", LEAD_UUID);

        let found = workspace.resumable_sessions(&seat).await;

        assert_eq!(
            found.iter().map(|info| info.session_id.as_str()).collect::<Vec<_>>(),
            ["newer"],
            "the occupant goes and the newer session survives",
        );
    }

    /// The answer is bounded to the newest 50, which is the list a reader
    /// picks from: the record is re-encoded on every seat open and reread, so
    /// the payload cannot grow with the project's history. The catalog branch
    /// is the one that answers a lead in steady state, so that is the branch
    /// the cap and the worker filter are pinned on: the newest transcript here
    /// is a worker's, and it must be gone before the cap is spent.
    #[tokio::test]
    async fn resume_sessions_are_bounded_to_the_newest_fifty() {
        let dir = scan_fixture_dir();
        let project = dir.path().join("proj");
        let project_path = project.display().to_string();
        for n in 0..60_u64 {
            let id = format!("t{n:02}");
            write_session_fixture(dir.path(), &project_path, &id, None);
            pin_transcript(&dir, &project_path, &id, 1_700_000_000 + n);
        }
        write_session_fixture(dir.path(), &project_path, WORKER_UUID, Some("forge:worker:alpha"));
        pin_transcript(&dir, &project_path, WORKER_UUID, 1_700_000_500);
        pin_transcript(&dir, &project_path, LEAD_UUID, 1_699_999_999);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        ready_catalog(&workspace).await;

        let found = workspace.resumable_sessions(&SessionSlot::lead("Default", "proj")).await;

        assert!(
            found.iter().all(|info| info.session_id != WORKER_UUID),
            "a worker's transcript is never a lead's jump, even as the newest row: {found:?}",
        );
        assert_eq!(found.len(), 50, "the cap is the newest fifty rows");
        assert_eq!(found[0].session_id, "t59", "the newest of the lead's own leads");
        assert_eq!(found[49].session_id, "t10", "and the oldest ten are the ones cut");
        assert!(
            found.iter().all(|info| info.session_id != "t09" && info.session_id != LEAD_UUID),
            "nothing below the fiftieth-newest is carried",
        );
    }

    /// A seat whose project forge has not loaded has nowhere to resume from,
    /// and the list is empty rather than another project's.
    #[tokio::test]
    async fn resume_sessions_of_an_unloaded_project_are_empty() {
        let (workspace, _updates) = Workspace::testing_stub();
        assert!(
            workspace.resumable_sessions(&SessionSlot::lead("TestOrg", "nothing")).await.is_empty(),
            "no loaded project, no cwd, no list",
        );
    }

    /// **A session that has connected but written no turn is not a jump.**
    /// The catalog mirrors every Connected - the boot spawn's own session
    /// included - and that row has no transcript `claude --resume` can find;
    /// offering it lands the seat on "No conversation found" (measured on the
    /// dev stack). The read keeps a catalog row only when its transcript is on
    /// disk, which is the branch a lead takes once the boot scan has landed.
    #[tokio::test]
    async fn resume_sessions_leave_out_a_connected_session_with_no_transcript() {
        let dir = scan_fixture_dir();
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let seat = SessionSlot::lead("Default", "proj");
        ready_catalog(&workspace).await;
        let cwd = workspace.cwd_for_session(&seat).expect("the project's directory");
        workspace.record_connected_session(&cwd, "live-only", Some("new session".to_owned()));

        let found = workspace.resumable_sessions(&seat).await;

        assert!(
            found.iter().all(|info| info.session_id != "live-only"),
            "the catalog's row has no transcript behind it: {found:?}",
        );
        assert_eq!(found.len(), 1, "and the transcript that IS there is still offered");
    }

    /// **A row the catalog mirrored at Connected states a placeholder title.**
    /// The session it names left a transcript behind, so the row is a real
    /// jump - and the picker reads the title off that transcript rather than
    /// offering `new session` for the one session a reader is most likely to
    /// want back.
    #[tokio::test]
    async fn resume_sessions_read_a_live_mirrors_title_from_its_transcript() {
        let dir = scan_fixture_dir();
        let project = dir.path().join("proj");
        let project_path = project.display().to_string();
        write_session_fixture(dir.path(), &project_path, "left-behind", None);
        pin_transcript(&dir, &project_path, "left-behind", 1_700_000_100);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let seat = SessionSlot::lead("Default", "proj");
        ready_catalog(&workspace).await;
        let cwd = workspace.cwd_for_session(&seat).expect("the project's directory");
        workspace.record_connected_session(&cwd, "left-behind", None);

        let found = workspace.resumable_sessions(&seat).await;

        let row = found
            .iter()
            .find(|info| info.session_id == "left-behind")
            .expect("a session that wrote a transcript is a jump");
        assert_eq!(
            row.summary, "opening prompt",
            "the title is the transcript's, not the mirror's placeholder",
        );
    }

    /// **The store is the config dir's.** Two config dirs under one
    /// app-support base open side by side, each on its own file, so neither
    /// collides with the other's lock-backed writer nor inherits its crons,
    /// subscriptions and worker rows.
    #[test]
    fn each_config_dir_opens_its_own_store() {
        let dir = tempdir().expect("tempdir");
        let app_support = dir.path().join("app-support");
        let one = dir.path().join("config-one");
        let two = dir.path().join("config-two");
        // The boot creates the config dir before it opens the store, and the
        // store key is a digest of the canonical path.
        std::fs::create_dir_all(&one).expect("the first config dir");
        std::fs::create_dir_all(&two).expect("the second config dir");

        let first = open_db(&app_support, &one).expect("the first config dir's store");
        let second = open_db(&app_support, &two).expect("the second config dir's own store");

        assert_ne!(
            store_path(&app_support, &one),
            store_path(&app_support, &two),
            "the path carries the config dir, like the lock's",
        );
        assert!(store_path(&app_support, &one).is_file(), "the first store was created");
        assert!(store_path(&app_support, &two).is_file(), "and the second beside it");
        drop((first, second));
    }

    /// **A machine-wide store from before the split is adopted once**, and
    /// only from the default config dir: a scratch or second config dir
    /// booting first must not take the user's state.
    #[test]
    fn the_default_config_dir_adopts_the_machine_wide_store_once() {
        let dir = tempdir().expect("tempdir");
        let app_support = dir.path().join("app-support");
        std::fs::create_dir_all(&app_support).expect("the app-support dir");
        let legacy = app_support.join("db.redb");
        drop(crate::store::Db::open(&legacy).expect("a store at the old path"));
        let home_config = dirs::home_dir().expect("a home dir").join(".claude");
        let target = app_support.join("stores").join("adopted.redb");
        std::fs::create_dir_all(target.parent().expect("the stores dir")).expect("stores dir");

        let outcome = adopt_legacy_store(&app_support, &home_config, &target);

        assert!(matches!(outcome, Adoption::Settled), "the home config dir adopts");
        assert!(target.is_file(), "the default config dir took it");
        assert!(!legacy.exists(), "and the machine-wide path is empty");

        // Once: a target already present is the migration done, so a later
        // legacy file is not looked at again.
        let stray = app_support.join("db.redb");
        std::fs::write(&stray, b"not a store").expect("a stray file");
        let again = adopt_legacy_store(&app_support, &home_config, &target);
        assert!(matches!(again, Adoption::Settled), "nothing is left to do");
        assert!(stray.is_file(), "the once-guard leaves a later legacy file alone");
    }

    /// **A scratch config dir leaves the file alone**, and a temp dir is not
    /// the default one: the adoption predicate answers for the home path and
    /// nothing else.
    #[test]
    fn a_scratch_config_dir_leaves_the_machine_wide_store_alone() {
        let dir = tempdir().expect("tempdir");
        let app_support = dir.path().join("app-support");
        std::fs::create_dir_all(&app_support).expect("the app-support dir");
        let legacy = app_support.join("db.redb");
        drop(crate::store::Db::open(&legacy).expect("a store at the old path"));
        let scratch = dir.path().join("scratch-config");
        let target = app_support.join("stores").join("scratch.redb");
        std::fs::create_dir_all(target.parent().expect("the stores dir")).expect("stores dir");

        let outcome = adopt_legacy_store(&app_support, &scratch, &target);

        assert!(matches!(outcome, Adoption::Settled), "a scratch dir has nothing to adopt");
        assert!(legacy.is_file(), "the user's store stays where it is");
        assert!(!target.exists(), "and no copy was made");
        assert!(!is_default_config_dir(&scratch), "a temp dir is not the default config dir");
        assert!(
            is_default_config_dir(&dirs::home_dir().expect("a home dir").join(".claude")),
            "the home directory's .claude is",
        );
    }

    /// **A store another process holds defers the boot rather than hiding
    /// it.** Opening a fresh store would make the next boot see a target and
    /// never look again, stranding every row; memory-only leaves the retry
    /// for the next boot.
    #[test]
    fn a_machine_wide_store_in_use_defers_the_boot() {
        let dir = tempdir().expect("tempdir");
        let app_support = dir.path().join("app-support");
        std::fs::create_dir_all(&app_support).expect("the app-support dir");
        let legacy = app_support.join("db.redb");
        let held = crate::store::Db::open(&legacy).expect("a store at the old path");
        let home_config = dirs::home_dir().expect("a home dir").join(".claude");
        let target = app_support.join("stores").join("adopted.redb");
        std::fs::create_dir_all(target.parent().expect("the stores dir")).expect("stores dir");

        let outcome = adopt_legacy_store(&app_support, &home_config, &target);

        assert!(matches!(outcome, Adoption::Deferred), "a held store defers the boot");
        assert!(!target.exists(), "nothing was moved in");
        assert!(legacy.is_file(), "and the owner still has its file where it was");
        drop(held);
    }

    /// **The boot adopts through `open_db` itself**, not only through the
    /// helper: the home config dir's first boot moves the legacy store in
    /// and opens it. Wiring the adoption out of `open_db` would create a
    /// fresh target first, and every later boot would never look again.
    #[test]
    fn open_db_adopts_the_machine_wide_store_for_the_home_config_dir() {
        let dir = tempdir().expect("tempdir");
        let app_support = dir.path().join("app-support");
        std::fs::create_dir_all(&app_support).expect("the app-support dir");
        let legacy = app_support.join("db.redb");
        {
            // A row in the legacy store, so the read below proves the DATA
            // moved and not just the file: a remove-file-and-open-fresh
            // would pass a file-existence check.
            let old = crate::store::Db::open(&legacy).expect("a store at the old path");
            crate::store::cron_names::put(
                &old,
                "p-adopt",
                &forge_primitives::cron::CronName {
                    cron_id: "c1".to_owned(),
                    description: Some("Morning summary".to_owned()),
                },
                std::time::SystemTime::now(),
            )
            .expect("seed a row in the legacy store");
        }
        let home_config = dirs::home_dir().expect("a home dir").join(".claude");
        // The boot creates the config dir before opening the store; a runner
        // without one gets an empty directory this test never writes into.
        std::fs::create_dir_all(&home_config).expect("the home config dir");

        let opened = open_db(&app_support, &home_config).expect("the adopted store opens");

        assert!(!legacy.exists(), "the machine-wide file moved");
        assert!(
            store_path(&app_support, &home_config).is_file(),
            "into this config dir's own store",
        );
        let rows = crate::store::cron_names::for_uuids(&opened, &["p-adopt"]).expect("read");
        assert_eq!(
            rows.get("p-adopt").and_then(|name| name.description.as_deref()),
            Some("Morning summary"),
            "the adopted store carries the legacy store's rows",
        );
        drop(opened);
    }

    /// **A held store defers the boot at the `open_db` boundary too**: no
    /// fresh target is created, so the next boot can still adopt the legacy
    /// file instead of finding a target and never looking again.
    #[test]
    fn open_db_leaves_no_target_when_the_legacy_store_is_held() {
        let dir = tempdir().expect("tempdir");
        let app_support = dir.path().join("app-support");
        std::fs::create_dir_all(&app_support).expect("the app-support dir");
        let legacy = app_support.join("db.redb");
        let held = crate::store::Db::open(&legacy).expect("a store at the old path");
        let home_config = dirs::home_dir().expect("a home dir").join(".claude");
        std::fs::create_dir_all(&home_config).expect("the home config dir");

        let opened = open_db(&app_support, &home_config);

        assert!(opened.is_none(), "the boot runs without durable state this run");
        assert!(
            !store_path(&app_support, &home_config).exists(),
            "and creates no target that would hide the legacy file for good",
        );
        assert!(legacy.is_file(), "the held file is still where its owner has it");
        drop(held);
    }

    /// **A peer's lock makes the machine shared.** A boot may prune shared
    /// app-support state only when this is false; a hardcoded true would let
    /// it delete a live peer's CEF bundle.
    #[test]
    fn sole_instance_sees_a_peer_lock() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_path_buf());
        assert!(ws.sole_instance(), "no peer is running in a fresh fixture");

        let peer = dir.path().join("peer-config");
        std::fs::create_dir_all(&peer).expect("peer config dir");
        let base = dir.path().join("app-support");
        let held = crate::single_instance::acquire(&peer, &base)
            .expect("the peer acquires")
            .expect("the peer holds its lock");

        assert!(!ws.sole_instance(), "a peer's held lock means the machine is shared");
        drop(held);
        assert!(ws.sole_instance(), "and it is the lock, not the file, that says so");
    }
}

#[cfg(test)]
mod prompt_dispatch_tests {
    //! A prompt's dispatch wiring, at the layer that answers for it: the
    //! command carries the id its row is drawn from and the source a reader's
    //! follow arms on, and no frame is forged here - the session task draws
    //! the row when the CLI starts the prompt.
    use super::*;

    fn a_prompt(key: &SessionSlot) -> Command {
        Command::Prompt { key: key.clone(), text: "hello".to_owned(), attachments: Vec::new() }
    }

    /// A fleet with one seat, and this seat's stream off the core's fan-out.
    ///
    /// The prompt is ACCEPTED through the dispatch intercept, which is this
    /// crate's own way of saying "the core took it" without standing up a real
    /// subprocess - the stub alone leaves the seat with no command sender, so
    /// every dispatch is refused for a reason the fixture invented.
    fn a_fleet() -> (Arc<Workspace>, mpsc::UnboundedReceiver<SeatUpdate>, SessionSlot) {
        let (ws, rx) = Workspace::testing_stub();
        ws.seed_test_project("proj", "/tmp/prompt-frame-origin");
        let seat = SessionSlot::lead("TestOrg", "proj");
        ws.enable_test_dispatch_intercept();
        (ws, rx, seat)
    }

    /// **The routed command carries the id its row is drawn from.** The
    /// session task announces this id and the CLI's lifecycle frames name it,
    /// so one id here is one id on the queue's row and the CLI's own copy of
    /// the message - a second id minted on the way would hold a row nothing
    /// can settle.
    #[test]
    fn a_routed_prompt_carries_the_id_its_lifecycle_frames_name() {
        let (ws, _rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(a_prompt(&seat));
        assert!(dispatched.is_ok(), "precondition: the core took the prompt: {dispatched:?}");

        let wired = ws.drain_test_dispatch_buffer();
        let [Command::PromptUnder { uuid, source, .. }] = wired.as_slice() else {
            panic!("a typed dispatch wires the prompt under a minted id: {wired:?}");
        };
        assert!(!uuid.is_empty(), "and a real one, not a blank");
        assert_eq!(*source, PromptSource::You, "and as a person's send");
    }

    /// `/new` from any composer is forge's own command, never the CLI's. The
    /// CLI answers that name as its own `/clear`, which rotates a
    /// conversation forge never records - no id minted, no `SessionReplaced` -
    /// so the seat is restarted here instead, and the words never reach it.
    #[test]
    fn a_new_prompt_restarts_the_seat_rather_than_reaching_the_cli() {
        let (ws, _rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/new".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "the core takes a /new prompt: {dispatched:?}");
        let commands = ws.drain_test_dispatch_buffer();
        assert!(
            commands.iter().any(|c| matches!(c, Command::NewSession { key, .. } if key == &seat)),
            "the seat is restarted: {commands:?}",
        );
        assert!(
            !commands
                .iter()
                .any(|c| matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. })),
            "and the words are never forwarded to the CLI: {commands:?}",
        );
    }

    /// `/resume <id>` is forge's too, and for a harder reason than `/new`:
    /// the CLI classifies its own `/resume` as local-jsx, so it cannot run
    /// away from a terminal at all. The seat is re-spawned onto the named
    /// session, from the same settings a `/new` would carry.
    #[test]
    fn a_resume_prompt_resumes_the_seat_rather_than_reaching_the_cli() {
        let (ws, _rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/resume 7f3a92e0".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "the core takes a /resume prompt: {dispatched:?}");
        let commands = ws.drain_test_dispatch_buffer();
        assert!(
            commands.iter().any(|c| matches!(
                c,
                Command::ResumeSession { key, session_id, .. }
                    if key == &seat && session_id == "7f3a92e0"
            )),
            "the named session is resumed: {commands:?}",
        );
        assert!(
            !commands
                .iter()
                .any(|c| matches!(c, Command::Prompt { .. } | Command::PromptUnder { .. })),
            "and the words are never forwarded to the CLI: {commands:?}",
        );
    }

    /// `/mode <id>` and `/model <id>` dispatch their own commands on either
    /// entry, so a view neither of them can run still changes both.
    #[test]
    fn mode_and_model_prompts_dispatch_their_own_commands() {
        let (ws, _rx, seat) = a_fleet();

        for (text, expected) in [
            (
                "/mode plan",
                Box::new(|command: &Command| {
                    matches!(
                        command,
                        Command::SetMode { mode, .. }
                            if *mode == forge_primitives::permission::PermissionMode::Plan
                    )
                }) as Box<dyn Fn(&Command) -> bool>,
            ),
            (
                "/model sonnet",
                Box::new(
                    |command: &Command| matches!(command, Command::SetModel { model, .. } if model == "sonnet"),
                ),
            ),
        ] {
            let dispatched = ws.dispatch_from_view(Command::Prompt {
                key: seat.clone(),
                text: text.to_owned(),
                attachments: Vec::new(),
            });
            assert!(dispatched.is_ok(), "{text}: {dispatched:?}");
            let commands = ws.drain_test_dispatch_buffer();
            assert!(
                matches!(commands.as_slice(), [command] if expected(command)),
                "{text} dispatches its own command: {commands:?}",
            );
        }
    }

    /// A mode the CLI has no name for is answered rather than sent: the
    /// command carries the enum, so an unparsed one cannot be dispatched.
    #[test]
    fn a_mode_the_cli_does_not_have_is_answered() {
        let (ws, mut rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/mode sideways".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "{dispatched:?}");
        // The echo of the reader's own words is one of these; the answer is
        // what this case is about (its ORDER is the case above, which does not
        // need the words' text).
        let notices: Vec<(NoticeSeverity, String)> = std::iter::from_fn(|| rx.try_recv().ok())
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                _ => None,
            })
            .collect();
        assert!(
            matches!(
                notices.as_slice(),
                [(NoticeSeverity::Error, text)] if text == "Unknown mode: sideways"
            ),
            "the reader is told the mode is not one the CLI has: {notices:?}",
        );
        assert!(ws.drain_test_dispatch_buffer().is_empty(), "and nothing is dispatched");
    }

    /// A forge command answers without drawing its prompt.
    ///
    /// The prompt never reaches a model, so no turn of the transcript holds
    /// it and no row is drawn for it (#2816). The answer is the whole of what
    /// the reader sees.
    #[test]
    fn a_forge_command_answers_without_drawing_its_prompt() {
        let (ws, mut rx, seat) = a_fleet();

        ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/mode sideways".to_owned(),
            attachments: vec![forge_primitives::ImageAttachment {
                data: "iVBORw0KGgo=".to_owned(),
                mime_type: "image/png".to_owned(),
            }],
        })
        .expect("the core takes it");

        let updates: Vec<_> = std::iter::from_fn(|| rx.try_recv().ok()).collect();
        assert!(
            !updates
                .iter()
                .any(|frame| matches!(&*frame.update, SessionUpdate::ChatAppended { .. })),
            "a prompt no model received draws no row: {updates:?}",
        );
        assert!(
            updates.iter().any(|frame| matches!(
                &*frame.update,
                SessionUpdate::Notice { severity: NoticeSeverity::Error, text, .. }
                    if text == "Unknown mode: sideways"
            )),
            "and the answer lands, where a client draws it: {updates:?}",
        );
    }

    /// `/effort <level>` writes the document the next launch reads, rather
    /// than dispatching: the CLI carries no control request for effort.
    #[test]
    fn effort_writes_the_launch_document_and_answers() {
        let (ws, mut rx, seat) = a_fleet();
        // The pool's stub handle is bound to a scratch config dir, so this
        // write is a real one against a path no user reads.
        ws.seed_test_bound_session(&seat, "acct-a");
        let config_dir = ws.config_dir_for(&seat).expect("the pooled stub names a config dir");
        let path = config_dir.join("settings.json");
        let before = std::fs::read_to_string(&path).ok();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/effort high".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "{dispatched:?}");
        let written: serde_json::Value = serde_json::from_str(
            &std::fs::read_to_string(&path).expect("the effort level lands in the document"),
        )
        .expect("the document parses");
        assert_eq!(written["effortLevel"], serde_json::json!("high"));
        let notices: Vec<(NoticeSeverity, String)> = std::iter::from_fn(|| rx.try_recv().ok())
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                _ => None,
            })
            .collect();
        assert!(
            matches!(
                notices.as_slice(),
                [(NoticeSeverity::Info, text)] if text.contains("Effort: High")
            ),
            "and the reader is told it took: {notices:?}",
        );
        assert!(ws.drain_test_dispatch_buffer().is_empty(), "nothing is dispatched");

        match before {
            Some(contents) => {
                std::fs::write(&path, contents).expect("restore the stub's document");
            }
            None => {
                let _ = std::fs::remove_file(&path);
            }
        }
    }

    /// A forge name invoked wrongly is answered with the command's own usage
    /// line, and dispatched nowhere: a mistyped command that reached the model
    /// would read as a question.
    #[test]
    fn a_wrong_forge_invocation_is_answered_rather_than_dispatched() {
        let (ws, mut rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/resume".to_owned(),
            // An attachment beside a wrongly invoked command never reaches a
            // model, so the echo draws the words alone.
            attachments: vec![forge_primitives::ImageAttachment {
                data: "iVBORw0KGgo=".to_owned(),
                mime_type: "image/png".to_owned(),
            }],
        });

        assert!(dispatched.is_ok(), "the core takes it: {dispatched:?}");
        let updates: Vec<_> = std::iter::from_fn(|| rx.try_recv().ok()).collect();
        assert!(
            !updates
                .iter()
                .any(|frame| matches!(&*frame.update, SessionUpdate::ChatAppended { .. })),
            "a prompt no model received draws no row: {updates:?}",
        );
        let notices: Vec<(SessionSlot, NoticeSeverity, String)> = updates
            .into_iter()
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { key, severity, text } => Some((key, severity, text)),
                _ => None,
            })
            .collect();
        assert!(
            matches!(
                notices.as_slice(),
                [(key, NoticeSeverity::Error, text)]
                    if key == &seat && text == "Usage: /resume <session_id>"
            ),
            "the reader is told what the command wanted: {notices:?}",
        );
        let commands = ws.drain_test_dispatch_buffer();
        assert!(commands.is_empty(), "and nothing is dispatched: {commands:?}");
    }

    /// One bare invocation, answered: what a view dispatches and the notices
    /// that answer it.
    fn bare(
        ws: &std::sync::Arc<Workspace>,
        rx: &mut mpsc::UnboundedReceiver<SeatUpdate>,
        seat: &SessionSlot,
        text: &str,
    ) -> Vec<(NoticeSeverity, String)> {
        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: text.to_owned(),
            attachments: Vec::new(),
        });
        assert!(dispatched.is_ok(), "the core takes {text}: {dispatched:?}");
        std::iter::from_fn(|| rx.try_recv().ok())
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                _ => None,
            })
            .collect()
    }

    /// **A bare `/mode` and `/effort` answer the value in force.** The core
    /// holds what the session reported, so the reader is told it rather than
    /// handed the usage line (#1626).
    #[test]
    fn a_bare_mode_and_effort_answer_the_value_in_force() {
        let (ws, mut rx, seat) = a_fleet();
        let domain = ws.register_domain_session(seat.clone(), None);
        {
            let mut domain = domain.lock();
            domain.observed_permission_mode =
                Some(forge_primitives::permission::PermissionMode::Plan);
            domain.observed_effort = Some(forge_primitives::EffortLevel::High);
        }

        assert_eq!(
            bare(&ws, &mut rx, &seat, "/mode"),
            vec![(NoticeSeverity::Info, "Mode: plan".to_owned())],
            "the hook's observation is what the session runs",
        );
        assert_eq!(
            bare(&ws, &mut rx, &seat, "/effort"),
            vec![(NoticeSeverity::Info, "Effort: high".to_owned())],
        );

        // **The launch's own setting answers where no hook has reported**,
        // which is the precedence the inspector draws - the two surfaces
        // cannot disagree about the same session.
        {
            let mut domain = domain.lock();
            domain.observed_permission_mode = None;
            domain.configured_permission_mode =
                Some(forge_primitives::permission::PermissionMode::Ask);
            domain.observed_effort = None;
            domain.configured_effort = forge_primitives::EffortLevel::Low;
        }
        assert_eq!(
            bare(&ws, &mut rx, &seat, "/mode"),
            vec![(NoticeSeverity::Info, "Mode: default".to_owned())],
            "with nothing observed the launch's mode answers",
        );
        assert_eq!(
            bare(&ws, &mut rx, &seat, "/effort"),
            vec![(NoticeSeverity::Info, "Effort: low".to_owned())],
        );
        let commands = ws.drain_test_dispatch_buffer();
        assert!(commands.is_empty(), "and neither read dispatches anything: {commands:?}");
    }

    /// **A seat with no session at all answers the usage line it answered
    /// before** (#1626): the read is the domain's, and a slot no task holds
    /// has nothing to report.
    #[test]
    fn a_bare_mode_and_effort_with_no_session_answer_their_usage() {
        let (ws, mut rx, seat) = a_fleet();

        assert_eq!(
            bare(&ws, &mut rx, &seat, "/mode"),
            vec![(NoticeSeverity::Error, "Usage: /mode <id>".to_owned())],
        );
        assert_eq!(
            bare(&ws, &mut rx, &seat, "/effort"),
            vec![(NoticeSeverity::Error, "Usage: /effort <level>".to_owned())],
        );
        let commands = ws.drain_test_dispatch_buffer();
        assert!(commands.is_empty(), "and neither read dispatches anything: {commands:?}");
    }

    /// Slash text this session cannot run is answered where it is typed,
    /// rather than handed to the model as a question. What the session can
    /// run is what the CLI advertised, so the guard reads that and nothing
    /// else.
    #[test]
    fn a_slash_name_the_session_does_not_have_is_refused() {
        let (ws, mut rx, seat) = a_fleet();
        ws.seed_test_advertised_catalogues(
            &seat,
            vec![forge_primitives::AvailableCommand::new("compact", "Compact")],
            Vec::new(),
        );

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/spinner now".to_owned(),
            attachments: vec![forge_primitives::ImageAttachment {
                data: "iVBORw0KGgo=".to_owned(),
                mime_type: "image/png".to_owned(),
            }],
        });

        assert!(dispatched.is_ok(), "the core takes it: {dispatched:?}");
        let updates: Vec<_> = std::iter::from_fn(|| rx.try_recv().ok()).collect();
        assert!(
            !updates
                .iter()
                .any(|frame| matches!(&*frame.update, SessionUpdate::ChatAppended { .. })),
            "a prompt no model received draws no row: {updates:?}",
        );
        let notices: Vec<(NoticeSeverity, String)> = updates
            .into_iter()
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                _ => None,
            })
            .collect();
        assert!(
            matches!(
                notices.as_slice(),
                [(NoticeSeverity::Error, text)] if text == "/spinner is not yet supported"
            ),
            "the reader is told the name is not one this session has: {notices:?}",
        );
        let commands = ws.drain_test_dispatch_buffer();
        assert!(commands.is_empty(), "and nothing reaches the model: {commands:?}");
    }

    /// The guard's clauses, one row each: prose with no slash is the model's,
    /// a name the CLI resolves is the CLI's, an advertised name is the CLI's,
    /// and only a name nothing has is refused.
    ///
    /// **A slash-led first word is refused whether or not words follow it.**
    /// The two readings cannot be told
    /// apart at the first token, and the permissive one reopens the hole the
    /// guard exists for: `/spinner now`, a typo with an argument, would reach
    /// the model as a question.
    #[test]
    fn the_guard_refuses_only_a_name_nothing_has() {
        let (ws, mut rx, seat) = a_fleet();
        ws.seed_test_advertised_catalogues(
            &seat,
            vec![forge_primitives::AvailableCommand::new("compact", "Compact")],
            Vec::new(),
        );

        for (text, refusal) in [
            ("hello", None),
            ("/tmp is full, why?", Some("/tmp is not yet supported")),
            ("/help", None),
            ("/compact 3", None),
            ("/compact3", Some("/compact3 is not yet supported")),
        ] {
            // The rows share one fleet, so each starts from an empty stream:
            // the frame the row above drew would otherwise answer for this one.
            while rx.try_recv().is_ok() {}
            let dispatched = ws.dispatch_from_view(Command::Prompt {
                key: seat.clone(),
                text: text.to_owned(),
                attachments: Vec::new(),
            });
            assert!(dispatched.is_ok(), "{text}: {dispatched:?}");
            if let Some(expected) = refusal {
                // The echo of the words is on the stream too, after the fix
                // that put the answer under them; the refusal is what this row
                // is about.
                let notices: Vec<(NoticeSeverity, String)> =
                    std::iter::from_fn(|| rx.try_recv().ok())
                        .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                            SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                            _ => None,
                        })
                        .collect();
                assert!(
                    matches!(
                        notices.as_slice(),
                        [(NoticeSeverity::Error, text)] if text == expected
                    ),
                    "{text} is refused with {expected:?}, got {notices:?}",
                );
                assert!(ws.drain_test_dispatch_buffer().is_empty(), "{text} reaches nothing");
            } else {
                let commands = ws.drain_test_dispatch_buffer();
                assert!(
                    matches!(
                        commands.as_slice(),
                        [Command::Prompt { .. } | Command::PromptUnder { .. }]
                    ),
                    "{text} is the CLI's: {commands:?}",
                );
            }
        }
    }

    /// Effort is user-level, so it lands even when the seat has no session
    /// behind it: what it writes is the document a launch reads, not anything
    /// about a run.
    #[test]
    fn effort_lands_for_a_seat_with_no_live_session() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (ws, mut rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("proj", "/tmp/prompt-frame-origin");
        ws.enable_test_dispatch_intercept();

        ws.dispatch_from_view(Command::Prompt {
            key: SessionSlot::lead("TestOrg", "proj"),
            text: "/effort low".to_owned(),
            attachments: Vec::new(),
        })
        .expect("the core takes it");

        let written = std::fs::read_to_string(dir.path().join("settings.json"))
            .expect("the document is written");
        let document: serde_json::Value = serde_json::from_str(&written).expect("it parses");
        assert_eq!(document["effortLevel"], serde_json::json!("low"));
        let notices: Vec<(NoticeSeverity, String)> = std::iter::from_fn(|| rx.try_recv().ok())
            .filter_map(|frame| match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Notice { severity, text, .. } => Some((severity, text)),
                _ => None,
            })
            .collect();
        assert!(
            matches!(notices.as_slice(), [(NoticeSeverity::Info, _)]),
            "and the reader is told it took: {notices:?}",
        );
    }

    /// A spawn a view could not complete is completed by the core: a client
    /// has no config to read, so what it sends carries none, and the settings
    /// the launch reads are built from the settings documents instead.
    #[test]
    fn a_spawn_without_settings_gets_them_from_the_documents() {
        // A config dir of its own, so the line the spawn carries is read from
        // a document this test wrote rather than from the machine's.
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(dir.path().join("settings.json"), br#"{ "effortLevel": "low" }"#)
            .expect("seed the document");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.enable_test_dispatch_intercept();

        ws.dispatch_from_view(Command::SpawnProject {
            project_name: "proj".to_owned(),
            launch_settings: SessionLaunchSettings::default(),
        })
        .expect("the core takes it");

        let commands = ws.drain_test_dispatch_buffer();
        let [Command::SpawnProject { launch_settings, .. }] = commands.as_slice() else {
            panic!("the spawn was not the command routed: {commands:?}");
        };
        let settings = launch_settings.settings.as_ref().expect("the documents filled it in");
        assert_eq!(
            settings["effortLevel"],
            serde_json::json!("low"),
            "the value the document holds, which a bare spawn would not have carried",
        );
    }

    /// The mirror: a spawn that built its own settings keeps them, so the
    /// caller's snapshot is not silently replaced by the core's read.
    #[test]
    fn a_spawn_that_supplied_settings_keeps_them() {
        let (ws, _rx, _seat) = a_fleet();
        let supplied = SessionLaunchSettings {
            settings: Some(serde_json::json!({ "model": "haiku" })),
            ..SessionLaunchSettings::default()
        };

        ws.dispatch_from_view(Command::SpawnProject {
            project_name: "proj".to_owned(),
            launch_settings: supplied,
        })
        .expect("the core takes it");

        let commands = ws.drain_test_dispatch_buffer();
        let [Command::SpawnProject { launch_settings, .. }] = commands.as_slice() else {
            panic!("the spawn was not the command routed: {commands:?}");
        };
        assert_eq!(
            launch_settings.settings,
            Some(serde_json::json!({ "model": "haiku" })),
            "the caller's own settings are left alone",
        );
    }

    /// A name the CLI advertised is the CLI's, and goes to it.
    #[test]
    fn a_slash_name_the_cli_advertised_is_forwarded() {
        let (ws, _rx, seat) = a_fleet();
        ws.seed_test_advertised_catalogues(
            &seat,
            vec![forge_primitives::AvailableCommand::new("compact", "Compact")],
            Vec::new(),
        );

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/compact".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "the core takes it: {dispatched:?}");
        let commands = ws.drain_test_dispatch_buffer();
        assert!(
            matches!(
                commands.as_slice(),
                [Command::Prompt { text, .. } | Command::PromptUnder { text, .. }]
                    if text == "/compact"
            ),
            "an advertised name is the CLI's: {commands:?}",
        );
    }

    /// A session that has advertised nothing refuses nothing: an empty
    /// catalogue is not knowing what the CLI offers, and refusing on
    /// ignorance would drop names it does have.
    #[test]
    fn a_session_that_advertised_nothing_refuses_nothing() {
        let (ws, _rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/compact".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "the core takes it: {dispatched:?}");
        let commands = ws.drain_test_dispatch_buffer();
        assert!(
            matches!(commands.as_slice(), [Command::Prompt { .. } | Command::PromptUnder { .. }]),
            "nothing is refused before the CLI has said what it has: {commands:?}",
        );
    }

    /// A name that only LOOKS like a forge command is the reader's prose, and
    /// reaches the model as they typed it.
    #[test]
    fn a_prompt_that_only_starts_like_a_forge_command_is_still_a_prompt() {
        let (ws, _rx, seat) = a_fleet();

        let dispatched = ws.dispatch_from_view(Command::Prompt {
            key: seat.clone(),
            text: "/newer please".to_owned(),
            attachments: Vec::new(),
        });

        assert!(dispatched.is_ok(), "the core takes it: {dispatched:?}");
        let commands = ws.drain_test_dispatch_buffer();
        assert!(
            matches!(
                commands.as_slice(),
                [Command::Prompt { text, .. } | Command::PromptUnder { text, .. }]
                    if text == "/newer please"
            ),
            "a near miss is prose: {commands:?}",
        );
    }

    /// **A routed prompt draws no row at dispatch.** The queue carries its
    /// words and the row lands when the CLI starts it (#2816); a frame forged
    /// here would sit above the answer the running turn was still writing.
    #[test]
    fn a_routed_prompt_draws_no_row_from_the_dispatcher() {
        let (ws, mut rx, seat) = a_fleet();

        ws.dispatch_from_view(a_prompt(&seat)).expect("the core took the prompt");

        let mut drawn = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::ChatAppended { msg, .. } = &*frame.update {
                drawn.push(msg.clone());
            }
        }
        assert!(
            drawn.is_empty(),
            "the queue carries the words and the CLI's start draws the row, so dispatch forges \
             none: {drawn:?}",
        );
        assert!(!ws.drain_test_dispatch_buffer().is_empty(), "the prompt itself is wired");
    }

    /// The delivery path, which already draws as an envelope turn of its own.
    #[test]
    fn a_delivery_emits_no_frame() {
        let (ws, mut rx, seat) = a_fleet();

        let _ = ws.dispatch_workspace_prompt(&seat, "run the morning summary".to_owned());

        assert!(
            rx.try_recv().is_err(),
            "a bare user turn beside a delivery's envelope turn draws the same words twice",
        );
    }

    /// A prompt the core refuses draws nothing anywhere.
    ///
    /// It never reached a model, so there is no turn to draw - and a frame for
    /// one would open a live turn in every view but the sender, while the
    /// refusal is written to the asking socket alone. Those views cannot learn
    /// why, so the turn bar spins for the life of the connection.
    #[test]
    fn a_refused_prompt_emits_no_frame() {
        // No intercept: the dispatch takes the real path and is refused, which
        // is the case this pins.
        let (ws, mut rx) = Workspace::testing_stub();
        let nowhere = SessionSlot::lead("TestOrg", "no-such-project");

        let refused = ws.dispatch(a_prompt(&nowhere));

        assert!(refused.is_err(), "precondition: the core holds no session here: {refused:?}");
        assert!(
            rx.try_recv().is_err(),
            "a refused prompt opened a turn in every view but the sender",
        );
    }

    /// **The config's profile names reach the fleet's resolver.** The boot
    /// copies this pair straight into `configure_profiles`; an org's fallback
    /// arrives keyed by its name, and a project's override by its
    /// `(org, project)`.
    #[test]
    fn the_configs_profile_names_reach_the_fleet_as_org_and_project_maps() {
        let dir = tempfile::tempdir().expect("tempdir");
        let forge = crate::config::ensure_forge_data_dir(dir.path()).expect("forge/ dir");
        std::fs::write(
            forge.join("forge.toml"),
            r#"
[[accounts]]
display_name = "main"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[orgs]]
name = "Busytools"
accounts = ["main"]
browser_profile = "work"

  [[orgs.projects]]
  name = "forge"
  path = "/tmp/forge"

  [[orgs.projects]]
  name = "apply"
  path = "/tmp/apply"
  browser_profile = "job"

[[orgs]]
name = "Personal"
accounts = ["main"]

  [[orgs.projects]]
  name = "notes"
  path = "/tmp/notes"
"#,
        )
        .expect("the config is written");
        let config = load_from_dir(dir.path()).expect("the config loads");
        let (ws, _rx) =
            Workspace::testing_stub_with_config(dir.path().to_owned(), config).expect("the stub");
        let (orgs, projects) = ws.browser_profile_config();
        assert_eq!(orgs.get("Busytools").map(String::as_str), Some("work"), "the org's key");
        assert_eq!(orgs.get("Personal").map(String::as_str), Some("default"), "no key is default");
        assert_eq!(
            projects.get(&("Busytools".to_owned(), "apply".to_owned())).map(String::as_str),
            Some("job"),
            "the project's override, keyed by its org and name",
        );
        assert_eq!(
            projects.get(&("Busytools".to_owned(), "forge".to_owned())).map(String::as_str),
            Some("work"),
            "a project with no key carries the org's",
        );
    }
}