forge_workspace/

spawn.rs

//! App-level spawn command handlers. Called from
//! [`crate::Workspace::dispatch`] when an App-level
//! `Command::SpawnProject` arrives.
//! Each handler resolves the id the session will run under, emits
//! `SessionUpdate::Spawning` under it, and kicks off the agent spawn.
//! The matching `Connected` arrives later under the same key.

use std::sync::Arc;
use std::time::{Duration, SystemTime};

use forge_agent::client::SessionLaunchSettings;

use crate::mcp::gotify::types::GotifyNotification;
use crate::mcp::peers::types::WrappedPrompt;
use crate::protocol::{
    Command, PromptSource, SessionUpdate, WorkerSpawnReply, WorkerStatusAction, WorktreeDisposition,
};
use crate::target::ProjectKey;
use crate::workspace::DespawnCleanupPending;
use crate::workspace::LiveWorkerRefusal;
use crate::workspace::Workspace;
use crate::{SessionSlot, SessionTarget};
use std::fmt::Write as _;

use forge_primitives::slack::SlackMessage;

/// A failed prompt dispatch to a running target unwinds the echo's
/// already-opened turn: without this its bar counts forever and the
/// bucket spinner never drops (mirrors the typed-submit
/// compensation). Per-site warns stay at the call sites.
pub(crate) fn send_dispatch_turn_error(
    workspace: &Workspace,
    key: SessionSlot,
    err: &crate::protocol::DispatchError,
) {
    let _ = workspace.update_sender().send(SessionUpdate::TurnError {
        key,
        message: err.to_string(),
        class: None,
        terminal_reason: None,
    });
}

/// The `claude` CLI's tools forge has replaced with its own surfaces: the
/// task quartet (`mcp__forge__tasks__*` over forge's own store), the cron
/// trio (forge's durable crons), `SendMessage` / `ListAgents` (the
/// `agents__*` group), `Workflow` (forge's workers) and `RemoteTrigger`
/// (cloud routines, which forge has no equivalent for and nothing here
/// reaches for).
const REPLACED_CLI_TOOLS: [&str; 11] = [
    "CronCreate",
    "CronDelete",
    "CronList",
    "TaskCreate",
    "TaskGet",
    "TaskList",
    "TaskUpdate",
    "SendMessage",
    "ListAgents",
    "Workflow",
    "RemoteTrigger",
];

/// The `--disallowedTools` value for a session, comma-separated - the form
/// the CLI's variadic `<tools...>` parser accepts.
///
/// Every session loses the tools forge has replaced, so nothing depends on
/// a distinction a caller cannot see. A worker additionally loses the two
/// worktree-hop tools, because it is pinned to its spawn location, and a
/// session that cannot put a question to the user loses
/// `AskUserQuestion` - that one is a property of the spawn, not of the
/// kind.
fn blocked_tools_for(kind: crate::mcp::SessionKind, interactive: bool) -> String {
    let mut blocked: Vec<&str> = REPLACED_CLI_TOOLS.to_vec();
    if matches!(kind, crate::mcp::SessionKind::Worker) {
        blocked.extend(["EnterWorktree", "ExitWorktree"]);
    }
    if !interactive {
        blocked.push("AskUserQuestion");
    }
    blocked.join(",")
}

/// Deny every session - lead, resumed or worker - the tools forge has
/// replaced, merging into a `--disallowedTools` value already there, so the
/// flag is emitted once with every name in it rather than twice. A worker's
/// spawn is the case that carries one: its own denials already hold that
/// entry. Called from the one spawn path every session goes through and
/// from the respawn stamp, so no launch can be assembled without it.
///
/// `interactive` decides the question denial, and each caller answers it
/// from the only place it can. A worker's spawn hands it the flag it was
/// given; a respawn reads the worker's stored row, which is where the flag
/// outlives the launch settings a view rebuilds. The one spawn path in
/// `get_agent_handle_at_key` passes `true` because it cannot know: a
/// worker's [`build_worker_extra_args`] has already written that name into
/// the same entry, and the merge leaves it there.
pub(crate) fn apply_blocked_tools(
    settings: &mut SessionLaunchSettings,
    kind: crate::mcp::SessionKind,
    interactive: bool,
) {
    let blocked = blocked_tools_for(kind, interactive);
    let Some((_, value)) =
        settings.extra_args.iter_mut().find(|(flag, _)| flag == "disallowedTools")
    else {
        settings.extra_args.push(("disallowedTools".to_owned(), Some(blocked)));
        return;
    };
    let existing = value.get_or_insert_with(String::new);
    for tool in blocked.split(',') {
        if existing.split(',').any(|name| name == tool) {
            continue;
        }
        if !existing.is_empty() {
            existing.push(',');
        }
        existing.push_str(tool);
    }
}

/// Build the list of `(flag, value)` extra CLI args specific to a
/// worker spawn. When the project is a git repo, append
/// `("worktree", Some(label))` so the spawned `claude` subprocess
/// creates a worktree at `<base>/.claude/worktrees/<label>/` - `base`
/// the repo's canonical root, the main checkout for a project that is
/// itself a linked worktree - and runs the session inside it. In all
/// cases, append the worker's
/// [`blocked_tools_for`] set as its `--disallowedTools` entry: workers are
/// pinned to their spawn-time location (whether a worktree or the
/// project cwd) and must not be able to call claude's built-in
/// worktree-hop tools to escape. Comma-separated value form is
/// empirically accepted by the CLI's variadic `<tools...>` parser.
///
/// Unless `interactive`, `AskUserQuestion` joins that list. A worker's
/// question renders in its own row, which nobody is usually looking
/// at, and an answer that does arrive is indistinguishable from a
/// decision the user made. Denying it at spawn means the capability is
/// never offered rather than refused after the model has already
/// decided to ask.
///
/// The `is_git_repo` boolean is passed in (already-computed by the
/// caller) so the git-repo probe runs at most once per spawn even
/// when the same answer is needed for both the `WorkerEntry.is_git_repo_at_spawn`
/// field and this argument list.
fn build_worker_extra_args(
    is_git_repo: bool,
    label: &str,
    interactive: bool,
) -> Vec<(String, Option<String>)> {
    let mut args = Vec::new();
    if is_git_repo {
        args.push(("worktree".to_owned(), Some(label.to_owned())));
    }
    let blocked = blocked_tools_for(crate::mcp::SessionKind::Worker, interactive);
    args.push(("disallowedTools".to_owned(), Some(blocked)));
    args
}

/// Charter every lead session is launched with.
const DEFAULT_LEAD_CHARTER: &str = include_str!("spawn/lead_charter.md");

/// Stamp [`DEFAULT_LEAD_CHARTER`] onto the launch settings so every lead
/// session carries one. No-op when a charter is already set - worker
/// spawns supply their own and we never overwrite it.
pub(crate) fn apply_lead_charter(settings: &mut SessionLaunchSettings) {
    if settings.charter.is_some() {
        return;
    }
    settings.charter = Some(DEFAULT_LEAD_CHARTER.to_owned());
}

/// Stamp the project's `permission_mode` into the launch settings'
/// `permissions.defaultMode`, where the existing
/// `applied_permission_mode` arm in `forge_sdk_worker` picks it up;
/// overrides a launcher-supplied default.
pub(crate) fn stamp_permission_mode(
    settings: &mut SessionLaunchSettings,
    mode: forge_primitives::permission::PermissionMode,
) {
    let object =
        settings.settings.get_or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()));
    let Some(map) = object.as_object_mut() else {
        return;
    };
    let perms = map
        .entry(SessionLaunchSettings::PERMISSIONS_KEY.to_owned())
        .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()));
    if let Some(perms) = perms.as_object_mut() {
        perms.insert(
            SessionLaunchSettings::PERMISSIONS_DEFAULT_MODE_KEY.to_owned(),
            serde_json::Value::String(mode.as_wire().to_owned()),
        );
    }
}

/// Emit a `SessionUpdate` and log at debug when no subscriber took it
/// (the view has not attached yet, or has gone). The send is logically
/// best-effort - no caller can act on the failure - but visibility
/// in the log distinguishes "no view took it" from "the emit never
/// happened" during diagnosis.
fn try_emit(workspace: &Workspace, label: &'static str, update: SessionUpdate) {
    // Held before it goes out: a fatal error is an App-level event with no
    // state behind it, so without this a view that was not subscribed when
    // it fired can never learn of it at all.
    if let SessionUpdate::FatalError { error, .. } = &update {
        workspace.record_fatal_error(error.clone());
    }
    if !workspace.update_tx().send(update) {
        tracing::debug!(
            target: "forge_workspace::spawn",
            label,
            "SessionUpdate not taken - no subscriber attached"
        );
    }
}

/// Resolve the id the project's lead will run under, emit
/// `SessionUpdate::Spawning` under it, then spawn the agent. The
/// `Connected` event from the resulting `SessionTask` lands under the
/// same key, so the announced bucket is the one the child connects
/// under. A spawn that fails names the reason, which the heal's own
/// supervisor counts as a failed attempt; a command dispatch drops it.
pub(crate) fn handle_spawn_project(
    workspace: &Arc<Workspace>,
    project_name: &str,
    launch_settings: SessionLaunchSettings,
) -> Result<(), String> {
    spawn_project_inner(workspace, project_name, launch_settings, true)
}

/// The heal's resume: the same spawn as [`handle_spawn_project`], but it
/// cannot open a seat the reader closed. A heal recovers a death; it is
/// never an opening door.
pub(crate) fn handle_heal_project_spawn(
    workspace: &Arc<Workspace>,
    project_name: &str,
    launch_settings: SessionLaunchSettings,
) -> Result<(), String> {
    spawn_project_inner(workspace, project_name, launch_settings, false)
}

fn spawn_project_inner(
    workspace: &Arc<Workspace>,
    project_name: &str,
    mut launch_settings: SessionLaunchSettings,
    reopen: bool,
) -> Result<(), String> {
    let Some(project) = workspace.find_project_view_by_name(project_name) else {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = project_name,
            "Command::SpawnProject for unknown project; ignoring"
        );
        try_emit(
            workspace,
            "spawn_project::unknown_project",
            SessionUpdate::ServiceStatus {
                severity: forge_primitives::cloud::service_status::ServiceSeverity::Warning,
                message: format!("Unknown project: {project_name}"),
            },
        );
        return Err(format!("Unknown project: {project_name}"));
    };

    apply_lead_charter(&mut launch_settings);

    // The id this lead will run under, resolved before the spawn so the
    // bucket announced here is the bucket the child connects under.
    let session_key = match workspace.resolve_slot(&SessionTarget::Named(project_name.to_owned())) {
        Ok(key) => key,
        Err(err) => {
            tracing::warn!(
                target: "forge_workspace::spawn",
                project = project_name,
                error = %err,
                "spawn_project: target resolution failed",
            );
            // No spawn will happen, so record what this project's lead
            // has parked rather than leaving it for a connect that never
            // comes.
            workspace.expire_parked_for_slot(
                &crate::SessionSlot::lead(&project.org, &project.name),
                crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
            );
            let message = format!("agent spawn failed: {err}");
            try_emit(
                workspace,
                "spawn_project::ConnectionFailed",
                SessionUpdate::ConnectionFailed {
                    key: SessionSlot::lead(&project.org, &project.name),
                    message: message.clone(),
                    fatal: false,
                },
            );
            return Err(message);
        }
    };
    try_emit(
        workspace,
        "spawn_project::Spawning",
        SessionUpdate::Spawning {
            key: session_key.clone(),
            project_name: project_name.to_owned(),
            cwd: project.path.to_string_lossy().to_string(),
            display_name: project.display_path.clone(),
        },
    );

    match workspace.get_agent_handle_at_key(
        SessionTarget::Named(project_name.to_owned()),
        launch_settings,
        Some(session_key.clone()),
        &crate::protocol::SpawnRole::Lead,
        reopen,
    ) {
        Ok(_handle) => {
            tracing::info!(
                target: "forge_workspace::spawn",
                project = project_name,
                slot = %session_key.display(),
                // The pool fast path returns a live handle without
                // building a task, so `forge_sdk_options_built` is the
                // per-subprocess signal.
                "spawn dispatched for project"
            );
            // The lead's profile comes up with the session rather than
            // paying the launch on its first browser call.
            warm_browser_seat(workspace, &session_key);
            Ok(())
        }
        Err(err) => {
            // **A close that landed mid-spawn is the reader's stop, not a
            // spawn failure.** Only the heal's non-opening spawn can be
            // refused this way, and it must leave no failure record or
            // Failed row for the project the reader just shut.
            if matches!(
                err.downcast_ref::<crate::error::WorkspaceError>(),
                Some(crate::error::WorkspaceError::SeatClosedDuringSpawn { .. })
            ) {
                tracing::debug!(
                    target: "forge_workspace::spawn",
                    project = project_name,
                    slot = %session_key.display(),
                    "the seat was closed while its recovery spawn was in flight; the stop stands"
                );
                return Ok(());
            }
            tracing::error!(
                target: "forge_workspace::spawn",
                project = project_name,
                error = %err,
                "spawn_project: get_agent_handle failed"
            );
            // No SessionTask exists to run its ConnectionFailed arm, so
            // record everything parked for this project's lead here -
            // otherwise the caller's LLM waits on a spawn that never
            // happened, and a committed delivery is lost unannounced.
            workspace.expire_parked_for_slot(
                &crate::SessionSlot::lead(&project.org, &project.name),
                crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
            );
            // The only record of the failure for the same reason: a view
            // reading the slot afterwards would otherwise see a project
            // that never started and no way to say why.
            let message = format!("agent spawn failed: {err}");
            workspace.record_spawn_failure(&session_key, &message);
            try_emit(
                workspace,
                "spawn_project::ConnectionFailed",
                SessionUpdate::ConnectionFailed {
                    key: session_key,
                    message: message.clone(),
                    fatal: false,
                },
            );
            Err(message)
        }
    }
}

/// Handle a `Command::DeliverPeerPrompt`. Resolves the target
/// project to a running SessionTask (deliver immediately) or a
/// sleeping one (buffer + auto-spawn), then dispatches the wrapped
/// prompt as a regular `Command::Prompt`.
///
/// The answer is this handler's own: `Ok(())` once the prompt was accepted
/// by the running session or parked for a spawn it kicked off, `Err(reason)`
/// when nothing could take it. The caller's ack is built from it, so a
/// delivery that never left forge cannot read as sent (#2342).
pub(crate) fn handle_deliver_peer_prompt(
    workspace: &Arc<Workspace>,
    caller: &SessionSlot,
    target_project: String,
    wrapped: WrappedPrompt,
) -> Result<(), String> {
    // Find the target project's running lead session (if any). The
    // `list_projects()` snapshot has `sessions: Vec<SessionView>` per
    // project; `is_open == true` on a session means an Agent is in
    // the workspace pool - that's "running." MUST skip worker
    // sessions: once a worker connects it lands in `view.sessions`
    // too, and a worker can sit at position 0 / be the first
    // is_open session. Returning a worker here dispatches the peer
    // envelope to the worker's chat instead of the lead's, which is
    // wrong (peers address project leads, not workers). Asking for the
    // lead slot by name cannot reach a worker: the label is part of the
    // slot, so the two are distinct keys rather than candidates to
    // subtract.
    let target_running_key =
        workspace.list_projects().into_iter().find(|v| v.name == target_project).and_then(|v| {
            let slot = SessionSlot::lead(&v.org, &v.name);
            workspace.session_is_pooled(&slot).then_some(slot)
        });

    if let Some(target_key) = target_running_key {
        // Fire the typed peer-envelope echo BEFORE the LLM-side
        // dispatch so the user-turn block renders in the right
        // order regardless of which event a view reducer drains
        // first. The CLI doesn't echo stdin-injected prompts back
        // on stream-json output (only tool_result-bearing user
        // envelopes come back), so a view gets no inbound user-turn
        // signal from the SDK side - `PeerEnvelopeAppended` is how
        // a view knows to render the peer block.
        let uuid = forge_sdk::request_id::next_prompt_id();
        push_peer_user_turn_into_chat(workspace, &target_key, &wrapped, &uuid);
        let text = wrapped.to_prose();
        // The peer path keeps the sender: a swap's hold answers that seat if
        // the handoff never reaches a successor.
        if let Err(err) = workspace.dispatch_peer_prompt_under(caller, &target_key, text, uuid) {
            tracing::warn!(
                target: "forge_workspace::spawn",
                target_project = %target_project,
                error = ?err,
                "DeliverPeerPrompt dispatch to running target failed"
            );
            send_dispatch_turn_error(workspace, target_key, &err);
            return Err(format!("the target's running session did not take the message ({err})"));
        }
        return Ok(());
    }

    // Target is sleeping (or unknown - defensive). If the project
    // exists in forge.toml, park the envelope for its lead and dispatch
    // SpawnProject.
    let Some(target) = workspace.find_project_view_by_name(&target_project) else {
        tracing::warn!(
            target: "forge_workspace::spawn",
            target_project = %target_project,
            "DeliverPeerPrompt target not in forge.toml; dropping"
        );
        return Err(format!(
            "project '{target_project}' is not in forge.toml any more, so the message went nowhere"
        ));
    };

    // The lead's own first `Connected` drains the bucket, so the park
    // must land BEFORE the spawn. The sender rides beside the payload so a
    // spawn that never connects can acknowledge the message back to it.
    let target_key = crate::SessionSlot::lead(&target.org, &target.name);
    let message_id = wrapped.id.clone();
    workspace.park_peer_prompt(&target_key, caller, wrapped);

    // Dispatch SpawnProject. Move target_project
    // into the command rather than cloning (it's the last use).
    let project_for_log = target_project.clone();
    if let Err(err) = workspace.dispatch(Command::SpawnProject {
        project_name: target_project,
        launch_settings: SessionLaunchSettings::default(),
    }) {
        tracing::warn!(
            target: "forge_workspace::spawn",
            target_project = %project_for_log,
            error = ?err,
            "DeliverPeerPrompt SpawnProject dispatch failed"
        );
        return Err(format!(
            "the target's project could not be woken ({err}); the parked message stays with it"
        ));
    }
    // **The dispatch's Ok is not the wake's.** `handle_spawn_project` runs
    // inline and can fail, and its own arm expires the bucket it just parked;
    // a message that is no longer parked was not accepted, whatever the
    // command returned.
    if !workspace.peer_prompt_is_parked(&target_key, &message_id) {
        return Err(format!(
            "project '{}' could not be woken, so the parked message was returned to you",
            target.org,
        ));
    }
    Ok(())
}

/// Outcome of a cron fire's delivery, so `fire_due_crons` can decide the
/// entry's fate rather than treating every hand-off as a success.
pub(crate) enum CronFireOutcome {
    /// Dispatched into a running session, or buffered + a spawn kicked off.
    /// The caller advances/removes the cron as normal.
    Delivered,
    /// The cron's project is no longer in forge.toml. The caller removes
    /// the entry instead of advancing a dead cron forever.
    TargetGone,
    /// The owner still has a row, but the boot wave would skip it, so
    /// nothing can drain a prompt buffered for it and the prompt cannot
    /// reach anyone. `directory` is where its session would have started,
    /// for the warning. Distinct from [`Self::TargetGone`] because the
    /// row is kept: a restored worktree brings the owner back.
    ///
    /// The caller's fate for the entry splits on the kind. A recurring
    /// cron drops this fire and advances - leaving it due would re-fire
    /// every tick, and parking it would grow a bucket nothing drains. A
    /// one-shot stays due instead, because advancing removes a one-shot:
    /// dropping it would throw the prompt away with no later slot.
    TargetCannotBeWoken { directory: std::path::PathBuf },
    /// Every account serving the project's model is cooling until the
    /// carried reset: the caller leaves the entry due, because a refusal
    /// right now would expire the parked prompt.
    DeferredCooling { cooling: crate::workspace::ProjectCooling },
    /// The Command channel is closed (workspace shutting down). The caller
    /// leaves the cron due so the next boot catch-up re-fires it.
    DispatchFailed,
    /// The owner is asleep and this cron may not wake it (`wake: false`).
    /// The caller leaves the entry due without advancing, so the next
    /// session start (or a tick while the owner is awake) delivers it.
    SkippedAsleep,
}

/// Text delivered for a cron fire: the raw prompt, prefixed with a plain
/// marker when the fire is overdue so the owner can tell a catch-up from
/// an on-time fire.
pub(crate) fn missed_cron_text(prompt: &str, missed: bool) -> String {
    if missed { format!("[missed cron] {prompt}") } else { prompt.to_owned() }
}

/// Deliver a due cron's prompt into its OWNER's session as a plain user
/// turn AND echo it as a cron block. `team_role` `None` routes to the
/// project lead, `Some(label)` to that worker. A live owner gets a
/// `Command::Prompt`; an asleep-but-existing owner is woken by dispatching
/// `Command::SpawnProject` (which resumes the lead and, through the lead's
/// respawn, the worker), the prompt buffered by `(project, team_role)`
/// and drained on the owner's connect. An owner that no longer exists (a
/// gone project, or a worker label with no persisted row) yields
/// `TargetGone`.
pub(crate) fn deliver_cron_prompt(
    workspace: &Arc<Workspace>,
    cron: &forge_primitives::CronEntry,
    missed: bool,
) -> CronFireOutcome {
    let project_name = cron.project_name.as_str();
    let team_role = cron.team_role.as_deref();
    let Some(view) = workspace.list_projects().into_iter().find(|v| v.name == project_name) else {
        return CronFireOutcome::TargetGone;
    };

    if let Some(target_key) = live_cron_slot(workspace, &view, team_role) {
        // Echo the cron block BEFORE the LLM-side dispatch so it renders in
        // order regardless of which event a view reducer drains first. The id
        // is minted here so the block's row and the dispatched prompt's
        // lifecycle frames are one thing by id.
        let text = missed_cron_text(&cron.prompt, missed);
        let uuid = forge_sdk::request_id::next_prompt_id();
        push_cron_prompt_into_chat(
            workspace,
            &target_key,
            &text,
            &uuid,
            cron.id.as_str(),
            cron.description.as_deref(),
        );
        return match workspace.dispatch_workspace_prompt_under(
            &target_key,
            text,
            PromptSource::Cron,
            uuid,
        ) {
            Ok(()) => CronFireOutcome::Delivered,
            Err(err) => {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    project = %project_name,
                    error = ?err,
                    "cron fire dispatch to live owner failed",
                );
                send_dispatch_turn_error(workspace, target_key, &err);
                CronFireOutcome::DispatchFailed
            }
        };
    }

    // Asleep: only wake an owner we can confirm still exists. A conclusive
    // absence removes the cron; an owner check that could not read leaves it
    // for the next tick rather than deleting a real owner's cron on a hiccup.
    match cron_slot_exists(workspace, &view, team_role) {
        CronOwnerCheck::Exists => {}
        CronOwnerCheck::CannotBeWoken { directory } => {
            if cron.wake {
                return CronFireOutcome::TargetCannotBeWoken { directory };
            }
        }
        CronOwnerCheck::Absent => return CronFireOutcome::TargetGone,
        CronOwnerCheck::Unknown => {
            if cron.wake {
                return CronFireOutcome::DispatchFailed;
            }
        }
    }
    // No live slot and no wake: skip the tick and leave the entry due, so
    // the next session start runs it. A `wake: false` cron asks for this.
    if !cron.wake {
        return CronFireOutcome::SkippedAsleep;
    }
    // A spawn needs the account map settled: the walk skips every account
    // still `Loading`, so a project whose only account for its model has
    // not settled is refused at the walk, and that refusal is transient
    // where a dead target is not. Deferring the fire is a delay rather
    // than a drop, because the next tick retries once the map settles;
    // parking now would have the spawn refusal expire the prompt instead.
    //
    // This is NOT a boot gate, and do not simplify it into one. The two
    // halves are different kinds of thing: `gateway_ready` is bind-time
    // only and monotonic, while `all_loaded` is defined over the account
    // map, so it goes false again whenever anything re-enters `Loading`.
    // A fire deferred by the second half is a delay for the same reason
    // as the first, not a drop.
    if !workspace.all_accounts_loaded() {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project_name,
            "cron fire deferred: the account map has not settled, so a spawn would be refused \
             and its parked prompt expired",
        );
        return CronFireOutcome::DispatchFailed;
    }
    // A cooldown empties the walk until its reset, which is transient the
    // same way an unsettled map is, and a refusal there expires the park
    // too. A walk empty because no account declares the model is the other
    // case, and that one is permanent - deferring it would retry a broken
    // cron forever, so it is left to fail as before.
    if let Some(cooling) = workspace.project_walk_cooling(&view.key) {
        return CronFireOutcome::DeferredCooling { cooling };
    }
    // Buffer by owner, then wake via resume: SpawnProject resumes the lead,
    // whose reconnect re-spawns the persisted workers; each drains its own
    // bucket on connect.
    let slot = crate::SessionSlot::for_label(&view.org, &view.name, team_role);
    workspace.park_cron(&slot, cron, missed);
    match workspace.dispatch(Command::SpawnProject {
        project_name: project_name.to_owned(),
        launch_settings: SessionLaunchSettings::default(),
    }) {
        Ok(()) => CronFireOutcome::Delivered,
        Err(err) => {
            tracing::warn!(
                target: "forge_workspace::spawn",
                project = %project_name,
                error = ?err,
                "cron fire SpawnProject dispatch failed",
            );
            CronFireOutcome::DispatchFailed
        }
    }
}

/// The live session that fills the cron's slot in `view`: for a lead
/// cron the running lead (the first open session that is not a live
/// worker); for a worker cron the live worker with that label. `None`
/// when no session holds the slot.
fn live_cron_slot(
    workspace: &Arc<Workspace>,
    view: &crate::views::ProjectView,
    team_role: Option<&str>,
) -> Option<SessionSlot> {
    let live = workspace.list_live_workers(&view.key);
    let candidate = if let Some(label) = team_role {
        // **`live_worker_with_label`, not a bare label match**: a `Failed`
        // entry is kept by design and is NOT live, so a bare match picks a
        // slot whose session failed and drops the prompt into it.
        // `cron_slot_exists` beside this applies the same rule (#1208's
        // class, one resolver over).
        crate::mcp::workers::types::live_worker_with_label(&live, label).map(|w| w.slot.clone())
    } else {
        let slot = SessionSlot::lead(&view.org, &view.name);
        workspace.session_is_pooled(&slot).then_some(slot)
    };
    // Only treat the owner as a live dispatch target once it has stamped
    // its session_id. A still-spawning owner (session_id None) would drop
    // a bare Command::Prompt, so fall through to the buffer-and-wake path
    // where its own Connected handler drains the owner-keyed buffer.
    let key = candidate?;
    workspace.domain_session_for(&key).filter(|d| d.lock().session_id.is_some()).map(|_| key)
}

/// Outcome of checking whether a cron's owner still exists to be woken.
enum CronOwnerCheck {
    /// The owner exists (the lead, or a worker with a persisted row).
    Exists,
    /// The owner has a row, but the boot wave would skip it - a resume
    /// would have no directory to start in - so there is nothing to wake
    /// and nothing that would drain a parked prompt. Carries that
    /// directory for the fire's warning.
    CannotBeWoken { directory: std::path::PathBuf },
    /// Conclusively gone: the read succeeded and the label has no row in
    /// the session store.
    Absent,
    /// The durable-worker lookup could not read, so absence is unconfirmed.
    Unknown,
}

/// Whether a cron's slot still has a session that can be woken. A lead's
/// does whenever its project does; a worker's does while its label has a
/// row AND that row can still start, since the boot wave is what
/// re-spawns it. A read failure yields [`CronOwnerCheck::Unknown`] so the
/// fire router leaves the cron rather than deleting a live slot's cron on
/// a transient hiccup.
fn cron_slot_exists(
    workspace: &Arc<Workspace>,
    view: &crate::views::ProjectView,
    team_role: Option<&str>,
) -> CronOwnerCheck {
    let Some(label) = team_role else {
        return CronOwnerCheck::Exists;
    };
    // A worker spawned this second is live before it is connected, and
    // `live_cron_slot` cannot address it until it stamps a session id on
    // connect. Its directory is being created along with it, so it is not
    // unwakeable: the fire parks and the worker's own Connected drains it.
    //
    // `live_worker_with_label`, not a bare label match: a `Failed` entry
    // is kept by design and is NOT live, so counting one would answer
    // "wakeable" for a worker the wave will never start - parking the fire
    // in the bucket this path exists to keep empty, with nothing left to
    // drain it.
    if crate::mcp::workers::types::live_worker_with_label(
        &workspace.list_live_workers(&view.key),
        label,
    )
    .is_some()
    {
        return CronOwnerCheck::Exists;
    }
    match workspace.stored_worker_row(&view.key, label) {
        Ok(None) => CronOwnerCheck::Absent,
        Ok(Some(row)) => {
            // The tree this fire would wake the worker in is the one the
            // ROW records: a worker pointed at another directory starts
            // there, so its worktree (and its absence) is read there.
            let root = row.cwd.as_deref().map_or(view.path.as_path(), std::path::Path::new);
            let directory = crate::mcp::workers::types::worker_tag_dir(
                root,
                &row.label,
                matches!(row.is_git_repo, Some(true)),
            );
            let can_start = crate::mcp::workers::types::worker_row_can_start(
                root,
                &row.label,
                row.is_git_repo,
                row.session_id.is_some(),
            );
            if can_start {
                CronOwnerCheck::Exists
            } else {
                CronOwnerCheck::CannotBeWoken { directory }
            }
        }
        Err(_) => CronOwnerCheck::Unknown,
    }
}

/// Deliver a matched Gotify `notification` into `project` as a plain user
/// turn AND echo it into the target's chat as a notification block. When
/// `team_role` names a running team worker, deliver straight to it;
/// otherwise deliver to the project lead - echo + dispatch a
/// `Command::Prompt` if it's running, else park it for the target's slot
/// and dispatch `Command::SpawnProject`
/// (`SessionTask` drains + echoes on Connected via
/// `deliver_parked_gotify`). A team-worker subscription with NO live entry
/// falls through to lead delivery (spawning the project brings the team
/// up); a live-but-not-yet-connected worker parks for its own label
/// instead. A project no longer in forge.toml is logged and skipped.
pub(crate) fn deliver_gotify_message(
    workspace: &Arc<Workspace>,
    project: &str,
    team_role: Option<&str>,
    notification: GotifyNotification,
) {
    // A team-worker subscription targets that worker. Once it's a live
    // entry the notification belongs to it, never the lead - so handle
    // both the connected case (dispatch now) and the still-spawning case
    // (buffer on the worker's own DomainSession for its Connected drain)
    // here, and never fall through to the lead below.
    if let Some(role) = team_role
        && let Some(worker_key) = team_worker_key(workspace, project, role)
    {
        let connected = workspace
            .domain_session_for(&worker_key)
            .is_some_and(|d| d.lock().session_id.is_some());
        if connected {
            // Echo the notification block BEFORE the LLM-side dispatch so
            // it renders in order regardless of which event a view reducer
            // drains first (mirrors handle_deliver_peer_prompt).
            let uuid = forge_sdk::request_id::next_prompt_id();
            push_gotify_notification_into_chat(workspace, &worker_key, &notification, &uuid);
            if let Err(err) = workspace.dispatch_workspace_prompt_under(
                &worker_key,
                notification.to_prose(),
                PromptSource::Gotify,
                uuid,
            ) {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    project = %project,
                    role = %role,
                    error = ?err,
                    "gotify deliver to running team worker failed",
                );
                send_dispatch_turn_error(workspace, worker_key, &err);
            }
        } else {
            // Still spawning: park it for the worker's slot, drained by
            // its own first `Connected`.
            workspace.park_gotify(&worker_key, notification);
        }
        return;
    }

    let running_lead =
        workspace.list_projects().into_iter().find(|v| v.name == project).and_then(|v| {
            let slot = SessionSlot::lead(&v.org, &v.name);
            workspace.session_is_pooled(&slot).then_some(slot)
        });

    if let Some(target_key) = running_lead {
        let uuid = forge_sdk::request_id::next_prompt_id();
        push_gotify_notification_into_chat(workspace, &target_key, &notification, &uuid);
        if let Err(err) = workspace.dispatch_workspace_prompt_under(
            &target_key,
            notification.to_prose(),
            PromptSource::Gotify,
            uuid,
        ) {
            tracing::warn!(
                target: "forge_workspace::spawn",
                project = %project,
                error = ?err,
                "gotify deliver to running project failed",
            );
            send_dispatch_turn_error(workspace, target_key, &err);
        }
        return;
    }

    // Asleep: park it for the project's lead and spawn the project (only
    // if it's a real forge.toml project).
    let Some(view) = workspace.find_project_view_by_name(project) else {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project,
            "gotify delivery target gone from forge.toml; skipping",
        );
        return;
    };

    workspace.park_gotify(&crate::SessionSlot::lead(&view.org, &view.name), notification);

    if let Err(err) = workspace.dispatch(Command::SpawnProject {
        project_name: project.to_owned(),
        launch_settings: SessionLaunchSettings::default(),
    }) {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project,
            error = ?err,
            "gotify fire SpawnProject dispatch failed",
        );
    }
}

/// The user-turn prose for one conversation's delivered Slack messages. It
/// carries the ids a reply needs - conversation, each member's own ts, and
/// its thread - because the only way an agent can answer in place is to feed
/// those back to `slack__post` or `slack__edit`.
/// `forge_server::envelope::detect_inbound` parses this shape into a Slack
/// envelope and a view renders that as a block,
/// so the bracketed header, its optional age clause, its member count and the
/// one-line-per-member body are a contract with the parser.
pub(crate) fn slack_bundle_to_prose(
    messages: &[SlackMessage],
    stale_after: Duration,
    now: SystemTime,
) -> String {
    let Some(head) = messages.first() else { return String::new() };
    let newest = messages.iter().map(|message| message.ts.as_str()).max().unwrap_or(&head.ts);
    let mut out = format!(
        "[Slack - workspace '{}', {}] id {} ts {newest}",
        head.workspace, head.conversation_label, head.conversation,
    );
    if let Some(age) = stale_age_clause(newest, stale_after, now) {
        out.push_str(&age);
    }
    if messages.len() > 1 {
        let _ = write!(out, " ({} messages)", messages.len());
    }
    for message in in_thread_order(messages) {
        out.push('\n');
        out.push_str(&member_line(message));
    }
    out
}

const SECONDS_PER_DAY: u64 = 24 * 60 * 60;

/// The `, 8d old` clause a header carries when its newest message is at or
/// past the workspace's stale age. Zero turns the mark off; a future or
/// unparseable ts carries none.
fn stale_age_clause(newest: &str, stale_after: Duration, now: SystemTime) -> Option<String> {
    if stale_after.is_zero() {
        return None;
    }
    let seconds: u64 =
        newest.split_once('.').map_or(newest, |(seconds, _)| seconds).parse().ok()?;
    let now = now.duration_since(SystemTime::UNIX_EPOCH).ok()?.as_secs();
    let age = now.checked_sub(seconds)?;
    if age < stale_after.as_secs() {
        return None;
    }
    Some(if age >= 2 * SECONDS_PER_DAY {
        format!(", {}d old", age / SECONDS_PER_DAY)
    } else {
        format!(", {}h old", age / 3_600)
    })
}

/// The bundle's members in reading order: oldest first, with a thread's
/// replies directly under the parent they answer.
fn in_thread_order(messages: &[SlackMessage]) -> Vec<&SlackMessage> {
    let mut grouped: Vec<(String, &SlackMessage)> = messages
        .iter()
        .map(|message| {
            // A reply whose parent is not in the bundle keeps its place in
            // time: the parent ages out of the sweep window while the
            // thread keeps moving.
            let key = match &message.thread_ts {
                Some(parent) if messages.iter().any(|other| &other.ts == parent) => parent.clone(),
                _ => message.ts.clone(),
            };
            (key, message)
        })
        .collect();
    grouped.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.ts.cmp(&b.1.ts)));
    grouped.into_iter().map(|(_, message)| message).collect()
}

/// One bundle member. The `<author>: ` clause is what
/// `forge_server::envelope::detect_inbound` keys on, so a member always
/// carries one. A resolved name is preferred; the raw id is only a fallback
/// the block drops, since an id is never a name to print.
fn member_line(message: &SlackMessage) -> String {
    let author = message.author.as_deref().or(message.user.as_deref()).unwrap_or("unknown");
    let mut out = format!("{author}: {} [ts {}", message.text, message.ts);
    // A parent carries its own ts as `thread_ts`, and the ts above already
    // answers into that thread, so only a real parent's reply says so.
    if let Some(thread) = message.thread_ts.as_deref()
        && thread != message.ts
    {
        let _ = write!(out, " in thread {thread}");
    }
    // An edited message keeps its ts, so a correction must be marked or it reads as a duplicate.
    if message.edited.is_some() {
        out.push_str(" edited");
    }
    out.push(']');
    for file in &message.files {
        let _ = write!(out, " [file {} {}]", file.id, file.name);
    }
    out
}

/// Deliver one conversation's matched Slack messages to its subscriber's
/// session: dispatch them now when that session is running, buffer them on
/// the session's own domain when it is still spawning. Mirrors
/// [`deliver_gotify_message`], including its rule that a worker-owned
/// subscription falls through to the lead only when the worker is gone
/// entirely: the despawn race (teardown removed its subscriptions first),
/// or a `Failed` entry, which is kept by design and is not live - a bucket
/// parked for one would never drain. The fall-through commits under the
/// worker's own dedupe key, so the batch counts as delivered and stays
/// with the lead: a durable worker that later respawns does not
/// re-receive it.
///
/// Returns whether the batch reached a destination it can be read from:
/// dispatched, or buffered for one that will. `false` tells the pump the
/// cursor must not advance past this batch, so a sweep re-runs it - which is
/// why the dedupe entries commit only after a successful hand-off.
pub(crate) fn deliver_slack_message(
    workspace: &Arc<Workspace>,
    project: &str,
    team_role: Option<&str>,
    messages: Vec<SlackMessage>,
) -> bool {
    // A sweep re-runs a batch after a 429, a failed watermark write or a
    // crash; the re-run must drop what was already handed over. "Already
    // delivered" is success for the caller: the cursor may advance.
    let Some(head) = messages.first() else { return true };
    let conversation = head.conversation.clone();
    let workspace_label = head.workspace.clone();
    let pending: Vec<SlackMessage> = messages
        .into_iter()
        .filter(|message| !workspace.slack_delivery_seen(project, team_role, message))
        .collect();
    if pending.is_empty() {
        tracing::debug!(
            target: "forge_workspace::spawn",
            project = %project,
            conversation = %conversation,
            "every message in this slack batch was already delivered; dropping the re-run",
        );
        return true;
    }
    let prose = slack_bundle_to_prose(
        &pending,
        workspace.slack_stale_after(&workspace_label),
        SystemTime::now(),
    );

    if let Some(role) = team_role
        && let Some(worker_key) = team_worker_key(workspace, project, role)
    {
        let connected = workspace
            .domain_session_for(&worker_key)
            .is_some_and(|d| d.lock().session_id.is_some());
        if connected {
            let uuid = forge_sdk::request_id::next_prompt_id();
            if let Err(err) = workspace.dispatch_workspace_prompt_under(
                &worker_key,
                prose.clone(),
                PromptSource::Slack,
                uuid.clone(),
            ) {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    project = %project,
                    role = %role,
                    error = ?err,
                    "slack deliver to running team worker failed",
                );
                send_dispatch_turn_error(workspace, worker_key, &err);
                return false;
            }
            // Echo only once the dispatch lands: a failed one returns false so
            // the sweep re-runs the batch, and an echo pushed before it would
            // paint the block twice for a turn the LLM sees once.
            push_slack_message_into_chat(workspace, &worker_key, &prose, &uuid);
            workspace.slack_delivery_commit(project, team_role, &pending);
        } else {
            // Still spawning: commit the dedupe (the sweep must not
            // re-run it) and park it for the worker's slot, drained by
            // its own first `Connected`. The slot carries the worker's
            // own org and project, so a project dropped from forge.toml
            // since its spawn still keys correctly.
            workspace.slack_delivery_commit(project, team_role, &pending);
            workspace.park_slack(&worker_key, pending);
        }
        return true;
    }

    let running_lead =
        workspace.list_projects().into_iter().find(|v| v.name == project).and_then(|v| {
            let slot = SessionSlot::lead(&v.org, &v.name);
            workspace.session_is_pooled(&slot).then_some(slot)
        });

    if let Some(target_key) = running_lead {
        let uuid = forge_sdk::request_id::next_prompt_id();
        if let Err(err) = workspace.dispatch_workspace_prompt_under(
            &target_key,
            prose.clone(),
            PromptSource::Slack,
            uuid.clone(),
        ) {
            tracing::warn!(
                target: "forge_workspace::spawn",
                project = %project,
                error = ?err,
                "slack deliver to running project failed",
            );
            send_dispatch_turn_error(workspace, target_key, &err);
            return false;
        }
        // Echo after the dispatch lands, so the sweep's re-run of a failed
        // delivery does not paint a second block for the same batch.
        push_slack_message_into_chat(workspace, &target_key, &prose, &uuid);
        workspace.slack_delivery_commit(project, team_role, &pending);
        return true;
    }

    // Asleep: park it for the project's lead and spawn the project (only
    // if it's a real forge.toml project). A target missing from
    // forge.toml returns false uncommitted: the sweep re-runs it, and
    // delivery resumes if the project returns or the subscription is
    // removed - the pump sees a decision, not a silent drop.
    let Some(view) = workspace.find_project_view_by_name(project) else {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project,
            "slack delivery target gone from forge.toml; leaving it for the next sweep",
        );
        return false;
    };

    workspace.slack_delivery_commit(project, team_role, &pending);
    workspace.park_slack(&crate::SessionSlot::lead(&view.org, &view.name), pending);

    if let Err(err) = workspace.dispatch(Command::SpawnProject {
        project_name: project.to_owned(),
        launch_settings: SessionLaunchSettings::default(),
    }) {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project,
            error = ?err,
            "slack fire SpawnProject dispatch failed",
        );
    }
    true
}

/// The team worker labelled `label` in `project`, if a LIVE entry
/// exists - regardless of whether it has finished connecting. The
/// caller checks connectedness to decide dispatch-vs-buffer.
///
/// A `Failed` entry is kept by design (its tombstone row stays
/// visible) but is not live: the worker has no session to drain a
/// bucket and no spawn coming to make one, so it is not a delivery
/// target - parking for its slot is the bucket nothing drains, whose
/// contents land as fresh turns whenever the worker is next opened.
fn team_worker_key(workspace: &Arc<Workspace>, project: &str, label: &str) -> Option<SessionSlot> {
    let view = workspace.list_projects().into_iter().find(|v| v.name == project)?;
    crate::mcp::workers::types::live_worker_with_label(
        &workspace.list_live_workers(&view.key),
        label,
    )
    .map(|w| w.slot.clone())
}

/// Emit a typed `PeerEnvelopeAppended` so the target session's
/// chat buffer shows the inbound peer user-turn. A view's reducer
/// builds the chat-side echo directly from the `WrappedPrompt`'s
/// typed fields - workspace no longer forges an SDK `Message::User`
/// frame (audit I11).
///
/// Note: this only affects the visible chat echo. The
/// recipient's `claude` subprocess still receives the prose via a
/// separate `Command::Prompt` dispatch - the CLI's input channel
/// is text-shaped and stays that way.
pub(crate) fn push_peer_user_turn_into_chat(
    workspace: &Workspace,
    target_key: &SessionSlot,
    wrapped: &WrappedPrompt,
    uuid: &str,
) {
    let _ = workspace.update_sender().send(SessionUpdate::PeerEnvelopeAppended {
        key: target_key.clone(),
        wrapped: wrapped.clone(),
        uuid: uuid.to_owned(),
    });
}

/// Emit a typed `GotifyNotificationAppended` so the target session's
/// chat buffer shows the inbound notification block. Mirrors
/// [`push_peer_user_turn_into_chat`] - the target's `claude` subprocess
/// still receives the prose via a separate `Command::Prompt` dispatch;
/// this only drives the visible chat echo.
pub(crate) fn push_gotify_notification_into_chat(
    workspace: &Workspace,
    target_key: &SessionSlot,
    notification: &GotifyNotification,
    uuid: &str,
) {
    let _ = workspace.update_sender().send(SessionUpdate::GotifyNotificationAppended {
        key: target_key.clone(),
        notification: notification.clone(),
        uuid: uuid.to_owned(),
    });
}

/// Emit a typed `CronPromptAppended` so the target session's chat
/// buffer shows a cron block for the fired prompt. Mirrors
/// [`push_gotify_notification_into_chat`] - the target's `claude`
/// subprocess still receives the raw prompt via a separate
/// `Command::Prompt`; this only drives the visible chat echo.
pub(crate) fn push_cron_prompt_into_chat(
    workspace: &Workspace,
    target_key: &SessionSlot,
    text: &str,
    uuid: &str,
    cron_id: &str,
    description: Option<&str>,
) {
    // The frame names the schedule once, and the row outlives it: keep the
    // pairing so the read path can title the same row after a reload.
    workspace.remember_cron_name(target_key, uuid, cron_id, description);
    let _ = workspace.update_sender().send(SessionUpdate::CronPromptAppended {
        key: target_key.clone(),
        text: text.to_owned(),
        uuid: uuid.to_owned(),
        cron_id: cron_id.to_owned(),
        description: description.map(str::to_owned),
    });
}

/// Emit a typed `SlackMessageAppended` so the target session's chat buffer
/// shows the inbound Slack block. Mirrors
/// [`push_gotify_notification_into_chat`] - the target's `claude` subprocess
/// still receives the prose via a separate `Command::Prompt` dispatch; this
/// only drives the visible chat echo.
pub(crate) fn push_slack_message_into_chat(
    workspace: &Workspace,
    target_key: &SessionSlot,
    prose: &str,
    uuid: &str,
) {
    let _ = workspace.update_sender().send(SessionUpdate::SlackMessageAppended {
        key: target_key.clone(),
        prose: prose.to_owned(),
        uuid: uuid.to_owned(),
    });
}

/// The caller-facing refusal for an at-cap worker spawn. One source so
/// the classifier pin in the facade tests tracks the real text.
pub(crate) fn worker_limit_reached_message(project: &str, live: usize, cap: usize) -> String {
    let workers = if live == 1 { "worker" } else { "workers" };
    format!(
        "worker limit reached: project '{project}' has {live} {workers} live and its cap is {cap} (the project's max_workers in forge.toml, default {}); despawn one first, or raise/remove max_workers",
        crate::config::DEFAULT_MAX_WORKERS_PER_PROJECT
    )
}

/// The refusal for a spawn whose tree resolves to a project `forge.toml`
/// declares (D3). One source: the facade refuses with it before it
/// ensures anything, and the handler refuses with it as the shared core
/// both dispatch sources pass through.
///
/// The sentence interpolates a project NAME, which is whatever a project
/// is called - "worktree" included - and the classifier scans this text
/// for exactly that word. What keeps it a dispatch failure is the
/// classifier's own guard on the phrase "which forge.toml declares",
/// which sits ahead of the name in both arms.
pub(crate) fn known_project_refusal(known: &str, own: &str) -> String {
    if known == own {
        format!(
            "this worker's tree is inside '{known}', which forge.toml declares - your own \
             project, which a worker of it already runs in by default; omit `cwd`"
        )
    } else {
        format!(
            "this worker's tree is inside the project '{known}', which forge.toml declares; a \
             declared project is driven by its own agent - message that project's agent \
             instead of pointing a worker at its tree"
        )
    }
}

/// The per-worker half of a spawn request, bundled so a caller cannot
/// transpose `kick` with `resume_kick` - both are `Option<String>` and
/// the mistake is silent.
pub(crate) struct WorkerSpawnArgs {
    pub label: String,
    pub charter: String,
    pub kick: Option<String>,
    pub resume_kick: Option<String>,
    pub interactive: bool,
    /// The validated MCP-family allowlist from `agents__spawn`; `None`
    /// or empty means every family.
    pub mcp_families: Option<Vec<String>>,
    /// The tree this spawn runs the worker in, resolved to its repo root
    /// by the facade (or, on a boot re-spawn, taken from the row): `None`
    /// means the project's own path.
    pub cwd: Option<String>,
}

/// The charter a spawned worker's prompt carries: the stored text plus
/// the withheld-family lines for the EFFECTIVE set - the same config
/// gate the tool build applies, so the prompt and the tools cannot
/// disagree about a family.
fn spawn_prompt_charter(
    charter: &str,
    families: Option<&[String]>,
    systemone_available: bool,
    voice_available: bool,
    vault_available: bool,
) -> String {
    charter_with_withheld_families(
        charter,
        &crate::mcp::effective_mcp_families(
            families,
            systemone_available,
            voice_available,
            vault_available,
        ),
    )
}

/// The worker's prompt charter: the stored text plus one line per
/// withheld MCP family. The row keeps the RAW charter - these lines are
/// composed per spawn from the current selection, so they can neither
/// duplicate across re-spawns nor outlive a revision.
fn charter_with_withheld_families(
    charter: &str,
    families: &std::collections::BTreeSet<crate::mcp::McpFamily>,
) -> String {
    let lines = crate::mcp::withheld_family_lines(families);
    if lines.is_empty() {
        return charter.to_owned();
    }
    let mut text = String::with_capacity(
        charter.len() + lines.iter().map(|line| line.len() + 1).sum::<usize>(),
    );
    text.push_str(charter);
    for line in lines {
        text.push('\n');
        text.push_str(line);
    }
    text
}

/// Handle a `Command::SpawnWorker`: insert a `Spawning` worker entry
/// in `live_workers[project_key]`, dispatch a spawn for the id the
/// worker will run under (or the id being resumed) with the charter
/// threaded onto `SessionLaunchSettings`, then reply on `return_to`
/// with that id and the tag value. The Connected handler in
/// `session_task::translate_event` writes the actual JSONL tag row
/// and transitions the entry from Spawning to Running (or rolls back
/// on tag-write failure).
///
/// The reply's session id is informational: the LLM's `agents__spawn`
/// caller addresses the worker by label, not by id, and logs the id to
/// have a stable handle on the row.
pub(crate) fn handle_spawn_worker(
    workspace: &Arc<Workspace>,
    project_key: ProjectKey,
    args: WorkerSpawnArgs,
    spawned_by: SessionSlot,
    resume_existing: Option<&str>,
    from_boot_respawn: bool,
    return_to: tokio::sync::oneshot::Sender<Result<WorkerSpawnReply, String>>,
) {
    let WorkerSpawnArgs { label, charter, kick, resume_kick, interactive, mcp_families, cwd } =
        args;
    let label = label.as_str();
    let resume_kick = resume_kick.as_deref();
    // **The label rules belong to this handler, not only to the tool.** The
    // command bus and the socket pass-through reach it without the MCP
    // facade's own validation, and a `lead` label there collides with the
    // lead's slot while a slash desynchronises forge's worktree path and
    // branch from claude's rewritten pair (#1682, #1603). Nothing is minted
    // or probed before this refusal.
    if let Err(refusal) = crate::mcp::workers::facade::validate_worker_label(label) {
        let _ = return_to.send(Err(refusal.message()));
        return;
    }
    // Verify the project exists before minting the worker's id. A worker
    // that already has a row takes its git-repo-ness from that row: it is
    // the flag the launchpad and the boot wave read to decide whether the
    // directory this spawn would enter is there, so probing again here
    // could compose a different cwd than the one they cleared. Only a
    // first spawn probes the project path - a blocking FS call,
    // deliberately BEFORE the live_workers critical section below so it
    // never widens the dedup window. Either way the result feeds both the
    // WorkerEntry flag and the `--worktree` extra-arg threading below.
    let projects = workspace.list_projects();
    let Some(view) = projects.iter().find(|v| v.key == project_key) else {
        let _ = return_to.send(Err(format!("project not found: {}", project_key.as_str())));
        return;
    };
    // The tree this spawn runs the worker in: the resolved root the facade
    // resolved (or the boot wave took off the row), else the project's own
    // path. Every probe below and every path composed from it reads the
    // same root, so the entry, the row and the CLI cannot disagree about
    // where the worker lives.
    let root = cwd.as_deref().map_or_else(|| view.path.clone(), std::path::PathBuf::from);
    // D3: a tree inside a project `forge.toml` declares is driven by that
    // project's own agent, so the spawn is refused here - before the label
    // is reserved, before the obstruction probe and before the row is
    // written, so nothing at all is minted for a spawn that cannot run.
    // The sentence names the project as the door; the classifier reads it
    // as a dispatch failure by its own phrase guard, which see.
    if cwd.is_some()
        && let Some(known) = workspace.project_name_for_resolved_path(&root.to_string_lossy())
    {
        let reason = known_project_refusal(&known, &view.name);
        tracing::warn!(
            target: "forge_workspace::spawn",
            event_name = "worker_spawn_refused_known_project",
            project = %project_key.as_str(),
            label = %label,
            tree = %root.display(),
            known_project = %known,
            "the worker's tree resolves to a declared project, so the spawn is refused",
        );
        let _ = return_to.send(Err(reason));
        return;
    }
    let is_git = if cwd.is_some() {
        // A stated tree answers for itself: the row's recorded gitness
        // belongs to the directory the row names, which is not this one.
        forge_agent::env::worktree::is_git_repo(&root)
    } else {
        workspace
            .recorded_worker_is_git_repo(&project_key, label)
            .unwrap_or_else(|error| {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    event_name = "worker_row_gitness_unreadable",
                    project = %project_key.as_str(),
                    label = %label,
                    %error,
                    "reading the worker's recorded gitness failed; probing the project path, \
                     which may compose a different directory than the row names",
                );
                None
            })
            .unwrap_or_else(|| forge_agent::env::worktree::is_git_repo(&root))
    };

    // The tree this worker runs in: the CLI's location under the base
    // checkout.
    let worktree_path =
        is_git.then(|| crate::mcp::workers::types::worker_tag_dir(&root, label, true));

    // Hold the composed path for the whole spawn, so the claim taken and
    // the registry insert cannot be separated by another project's spawn
    // or by a despawn removing the tree this one is entering. Re-entrant
    // with a resume facade's pre-ensure claim.
    let _claim = match worktree_path.as_ref() {
        Some(path) => match workspace.claim_worktree(
            path,
            &project_key,
            label,
            crate::workspace::WorktreeOp::Spawn,
        ) {
            Ok(claim) => Some(claim),
            Err(reason) => {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    event_name = "worker_spawn_refused_worktree_claimed",
                    project = %project_key.as_str(),
                    label = %label,
                    tree = %root.display(),
                    reason = %reason,
                    "the worker's worktree is in use, so the spawn is refused",
                );
                let _ = return_to.send(Err(format!(
                    "this worker's worktree cannot be shared: {reason}; spawn under a different \
                     label"
                )));
                return;
            }
        },
        None => None,
    };

    // The composed worktree is repository-global, so a label can name a
    // tree that already belongs to another project - its own checkout, or
    // another project's worker's worktree. Reusing it would put two
    // sessions in one tree and hand the later despawn the power to delete
    // it; refuse before anything is minted.
    if let Some(collision) = worktree_path.as_ref().and_then(|dir| {
        workspace.worktree_collision(dir, &project_key, label, crate::workspace::WorktreeOp::Spawn)
    }) {
        tracing::warn!(
            target: "forge_workspace::spawn",
            event_name = "worker_spawn_refused_shared_worktree",
            project = %project_key.as_str(),
            label = %label,
            tree = %root.display(),
            reason = %collision,
            "the worker's worktree is shared with another project, so the spawn is refused",
        );
        let _ = return_to.send(Err(format!(
            "this worker's worktree cannot be shared: {collision}; spawn under a different label"
        )));
        return;
    }

    // The pool key a fresh worker spawns under: an id minted here and
    // recorded under the worker's slot before the child starts, so the
    // pool, the registry entry, the gateway binding and the CLI's own
    // `--session-id` all name the same string and nothing has to move on
    // `Connected`. A resume keys on the id being resumed instead.
    // The worker's slot, and the id it runs under. A fresh spawn mints
    // and records the id here; a resume adopts the one being resumed, so
    // the row names the occupant the child will actually run as.
    let is_resume = resume_existing.is_some();
    let slot = SessionSlot::worker(&view.org, &view.name, label);
    let session_id = match resume_existing {
        Some(resuming) => forge_primitives::SessionId::new(resuming),
        None => forge_primitives::SessionId::new(uuid::Uuid::new_v4().to_string()),
    };
    let tag = forge_primitives::worker_tag(label);

    // Insert WorkerEntry as Spawning BEFORE the agent spawn so the
    // Connected handler can find the entry via worker_lookup_for_session
    // when it fires (worker_lookup_for_session reads live_workers).
    //
    // On the resume path `needs_tag` is false - the tag is already on
    // disk in the JSONL (the lead Connected hook only resumes sessions
    // whose tag matches `forge:worker:<label>` so this invariant is
    // guaranteed by the caller).
    //
    // The entry is keyed by the worker's slot, and carries the id it
    // runs under: a fresh one was minted above and recorded below, once
    // the guard admits the spawn, so the pool, the registry and the
    // child's `--session-id` agree from the first instant and `Connected`
    // has nothing to move.
    let entry = crate::mcp::workers::types::WorkerEntry {
        label: label.to_owned(),
        charter: charter.clone(),
        slot: slot.clone(),
        session_id: Some(session_id.clone()),
        status: forge_primitives::WorkerLiveness::Spawning,
        spawned_at: std::time::SystemTime::now(),
        spawned_by,
        needs_tag: !is_resume,
        is_git_repo_at_spawn: is_git,
        cwd: cwd.as_deref().map(std::path::PathBuf::from),
        diagnostic: None,
        kick,
    };
    // Label uniqueness AND the project's worker cap, enforced atomically
    // at this shared core so neither dispatch source - the boot
    // re-spawn or an MCP `agents__spawn` - can double-insert and fork
    // two subprocesses onto one worktree, or overshoot the cap on
    // genuinely-concurrent dispatches. The cap is per project: the
    // project's `max_workers` override, else the
    // default. Boot re-spawns pass no cap: they restore persisted
    // workers the user already had, and their spawn reply is dropped,
    // so a refusal there could never reach a caller.
    let cap = (!from_boot_respawn).then(|| {
        workspace
            .project_for_key(&project_key)
            .and_then(|project| project.max_workers)
            .unwrap_or(crate::config::DEFAULT_MAX_WORKERS_PER_PROJECT)
    });
    if let Err(refusal) =
        workspace.insert_live_worker_if_label_absent(&project_key, entry.clone(), cap)
    {
        match refusal {
            LiveWorkerRefusal::LabelLive(existing) => {
                let existing_session = existing.display();
                tracing::debug!(
                    target: "forge_workspace::spawn",
                    project = %project_key.as_str(),
                    label = %label,
                    %existing_session,
                    "spawn_worker: label already live; skipping duplicate spawn",
                );
                let _ = return_to.send(Err(format!(
                    "a worker labeled '{label}' is already live (session {existing_session}); message it with agents__send_message or close it first (one live worker per label)"
                )));
            }
            LiveWorkerRefusal::CleanupPending => {
                tracing::info!(
                    target: "forge_workspace::spawn",
                    project = %project_key.as_str(),
                    label = %label,
                    "spawn_worker: refused, the label's previous despawn is still cleaning up",
                );
                // No "worktree" in this sentence, and no interpolated
                // label either (a label may carry the word): the facade's
                // failure classifier routes that word to a
                // worktree-creation failure, which is not what happened.
                let _ = return_to.send(Err(
                    "this label's previous despawn is still cleaning up; retry once it finishes"
                        .to_owned(),
                ));
            }
            LiveWorkerRefusal::AtCap { live, cap } => {
                tracing::info!(
                    target: "forge_workspace::spawn",
                    project = %project_key.as_str(),
                    label = %label,
                    live,
                    cap,
                    "spawn_worker: refused, at the concurrent worker cap",
                );
                let _ = return_to.send(Err(worker_limit_reached_message(
                    project_key.as_str(),
                    live,
                    cap,
                )));
            }
        }
        return;
    }
    // The worker's directory is not optional, and claude's `--worktree
    // <label>` creation is not a check: when it does nothing (measured:
    // the derived branch is already checked out in another worktree),
    // the session starts anyway and the worker reads live with nowhere to
    // work. Ask git what creation would be refused for, and refuse the
    // spawn here instead - before the row is written and before any
    // subprocess exists - leaving claude to create the worktree as it
    // always has.
    if is_git
        && !is_resume
        && let Some(obstacle) = forge_agent::env::worktree::worktree_creation_obstacle(
            &root,
            label,
            &crate::mcp::workers::types::worker_tag_dir(&root, label, true),
        )
    {
        tracing::warn!(
            target: "forge_workspace::spawn",
            event_name = "worker_spawn_refused_no_worktree",
            project = %project_key.as_str(),
            label = %label,
            %obstacle,
            "a worktree cannot be created for this worker where it would have to run, so the \
             spawn is refused rather than started with nowhere to work",
        );
        // A boot re-spawn's reply is dropped, so rolling the entry back
        // would leave the row listed and nothing running with the reason
        // nowhere on screen. It keeps the entry as the visible failure the
        // async spawn failures leave instead; every caller that DOES hear
        // the reply gets the rollback, so nothing half-live is left behind.
        if from_boot_respawn {
            crate::workspace::transition_worker_to_failed(
                workspace,
                &project_key,
                &slot,
                Some(obstacle.clone()),
            );
        } else {
            let _ = workspace.remove_latest_worker(&project_key, label);
        }
        // The obstacle text reads as one sentence, so the MCP tool's
        // "worktree creation failed:" label lands on top of it as one
        // statement rather than two.
        let _ = return_to.send(Err(obstacle));
        return;
    }
    // The row is the whole registry entry a boot re-spawns from, so it
    // carries the spawn args alongside the id rather than leaving them in
    // memory. One path writes it for both spawns and re-spawns; what a
    // re-spawn must not restate is the `kick` handled just below.
    //
    // AFTER the guard above, which is the point of the order: both
    // refusals return without spawning, and a row written first would
    // outlive them. A refused duplicate would have overwritten the
    // RUNNING worker's row with a fresh id and the new args, so the next
    // boot would resume an id no session ever ran under; an at-cap
    // refusal would leave a row the boot re-spawn wave picks up with no
    // cap, bringing back a worker the caller was told does not exist.
    // The row's `kick` is the worker's first turn, which only a first
    // spawn states. A resume's live kick is the restart note (or the row's
    // `resume_kick`) when the seat's turn was cut off - decided upstream
    // from the pre-spawn row - and writing that here would make it the
    // worker's opening turn on every later `--new` re-spawn.
    let kick_field = if is_resume { None } else { entry.kick.as_deref() };
    // The stored-selection contract, mirrored exactly by `families`
    // below so the reply, the running surface and the row cannot
    // disagree: a re-spawn stating nothing adopts the stored value; a
    // stated list is a revision; a fresh spawn stating nothing means
    // every family, which writes as absence.
    let resume_like = is_resume || from_boot_respawn;
    let families_field: Option<&[String]> = if resume_like && mcp_families.is_none() {
        None
    } else {
        Some(mcp_families.as_deref().unwrap_or(&[]))
    };
    let durability_warning = match workspace.record_worker_row(
        &project_key,
        label,
        session_id.as_str(),
        &charter,
        kick_field,
        resume_kick,
        interactive,
        crate::mcp::workers::types::WorkerTree {
            is_git_repo: is_git,
            // What the spawn resolved, written verbatim: a stated tree is
            // the row's durable handle to where the JSONL lives, and a
            // spawn that stated none records none.
            cwd: cwd.clone(),
        },
        families_field,
    ) {
        Ok(()) => None,
        Err(error) => {
            tracing::warn!(
                target: "forge_workspace::spawn",
                project = %project_key.as_str(),
                label = %label,
                %error,
                "recording the worker's row failed; it will not survive a restart",
            );
            Some(format!(
                "recording this worker for durability failed ({error}); it will not survive a forge restart"
            ))
        }
    };
    try_emit(
        workspace,
        "spawn_worker::WorkerStatusChanged::Added",
        SessionUpdate::WorkerStatusChanged {
            project_key: project_key.clone(),
            action: WorkerStatusAction::Added,
            status: entry.to_status(),
            worktree: WorktreeDisposition::untouched(entry.is_git_repo_at_spawn),
        },
    );

    // Spawn the fresh session under the picked account. The charter
    // is threaded onto SessionLaunchSettings.charter; the spawn path
    // (forge_sdk_worker::build_options_with_callback) appends it to
    // the system prompt via --append-system-prompt. `extra_args`
    // carries `("worktree", Some(label))` for git-repo projects so
    // claude forks a worktree at `<base>/.claude/worktrees/<label>/`,
    // `base` being the repo's canonical root (#2460).
    //
    // Resume path: `SessionTarget::Session` reads the original cwd
    // from the catalog (Workspace::session_cwd_for) so claude lands
    // back in the worktree it was first spawned in. If the worktree
    // dir was removed out-of-band, claude's spawn fails and the
    // existing ConnectionFailed surface (workspace.rs:570) reports
    // it - we don't silently fall back to fresh-spawn (that would
    // lose state without warning).
    // The selection this spawn composes from: a stated argument wins (a
    // resume stating one is a revision); otherwise a resume or boot
    // re-spawn adopts the row; a fresh spawn with nothing stated means
    // every family.
    let families = if mcp_families.is_some() {
        mcp_families.clone()
    } else if resume_like {
        workspace.recorded_worker_mcp_families(&project_key, label).unwrap_or_else(|error| {
            tracing::warn!(
                target: "forge_workspace::spawn",
                event_name = "worker_row_families_unreadable",
                project = %project_key.as_str(),
                label = %label,
                %error,
                "reading the worker's recorded mcp families failed; \
                 composing the full surface",
            );
            None
        })
    } else {
        None
    };
    let settings = SessionLaunchSettings {
        charter: Some(spawn_prompt_charter(
            &charter,
            families.as_deref(),
            workspace.systemone.read().is_some(),
            workspace.voice_enabled(),
            workspace.vault.read().is_some(),
        )),
        extra_args: build_worker_extra_args(is_git, label, interactive),
        ..Default::default()
    };
    let target = if resume_existing.is_some() {
        SessionTarget::Session(slot.clone())
    } else {
        SessionTarget::FreshInProject {
            slot: slot.clone(),
            // The same resolved root the row and the entry carry, so the
            // child starts where they say it runs.
            cwd: cwd.as_deref().map(std::path::PathBuf::from),
        }
    };
    match workspace.get_agent_handle_at_key(
        target,
        settings,
        None,
        &crate::protocol::SpawnRole::Worker {
            label: label.to_owned(),
            // The same predicate the synchronous rollback below deletes
            // under: a resume and a boot re-spawn adopt a row that was
            // already there, so only a spawn that minted this one may
            // take it away.
            wrote_row: !is_resume && !from_boot_respawn,
            mcp_families: families.clone(),
        },
        // A worker spawn is an opening door like the lead's: it starts the
        // seat it names.
        true,
    ) {
        Ok(handle) => {
            tracing::info!(
                target: "forge_workspace::spawn",
                project = %project_key.as_str(),
                label = %label,
                slot = %slot.display(),
                "spawn dispatched for worker"
            );
            // Best-effort, like the lead's: the profile is up before the
            // worker's first browser call rather than because of it.
            warm_browser_seat(workspace, &slot);
            // The walk lands on a saturated or bailed account only when
            // nothing else in the pin declares the project's model, so
            // the lead hears about it at spawn rather than when the
            // worker stalls on a 429.
            let rate_limited_account =
                handle.display_name().and_then(|name| workspace.degraded_account_name(&name));
            // Reply to the LLM with the id the worker runs under. The
            // LLM addresses subsequent calls by label; the session_id
            // field is informational, and it is no longer a placeholder
            // the rekey machinery has to correct.
            let _ = return_to.send(Ok(WorkerSpawnReply {
                session_id: session_id.as_str().to_owned(),
                tag,
                // The stored selection, canonicalised; `None` means every
                // family. The lead sees exactly what this worker got.
                mcp_families: families,
                rate_limited_account,
                // Set when the row could not be written above; the boot
                // re-spawn paths drop the reply, so they read the warn
                // instead.
                durability_warning,
                // Where the worker runs, which this handler decided above:
                // a git project's worker gets the CLI's
                // `<base>/.claude/worktrees/<label>`, and everything else
                // runs in the project root and has no worktree to name.
                worktree: worktree_path.as_ref().map(|dir| dir.display().to_string()),
                // What the arguments say, which is all this handler
                // knows: a `resume_session` spawn whose lookup found
                // nothing arrives here as a fresh spawn like any other,
                // and the facade that resolved it restates this.
                session_choice: if is_resume {
                    crate::protocol::SessionChoice::Resumed
                } else {
                    crate::protocol::SessionChoice::Fresh
                },
            }));
        }
        Err(err) => {
            let message = format!("agent spawn failed: {err}");
            tracing::error!(
                target: "forge_workspace::spawn",
                project = %project_key.as_str(),
                label = %label,
                error = %err,
                "spawn_worker: get_agent_handle failed"
            );
            // **The reason a view reads.** The lead's arm records the same
            // failure for its slot, and without this one the rollback's
            // `Removed` event is all a view has: it names no cause, and the
            // chat draws it as a close.
            workspace.record_spawn_failure(&slot, &message);
            // A fresh spawn the caller asked for creates its row above, so
            // a failure here has to take the row with it: the caller is
            // told the spawn failed and the live entry is rolled back, and
            // a row left behind brings the worker back on the next boot.
            // A resume and a boot re-spawn are not that case - their row
            // pre-existed and is the only handle on the id being resumed,
            // so deleting it would lose the worker rather than let it
            // retry.
            if !is_resume && !from_boot_respawn {
                let _ = workspace.delete_worker_row(&project_key, label);
            }
            // Roll back the live_workers entry we just inserted.
            let removed = workspace.remove_latest_worker(&project_key, label);
            if let Some(mut rolled) = removed {
                // The last-known snapshot is carried for symmetry, so the
                // reason rides it too: a view that renders the event's
                // status has the cause even though the entry is gone.
                rolled.diagnostic = Some(message.clone());
                try_emit(
                    workspace,
                    "spawn_worker::WorkerStatusChanged::Removed",
                    SessionUpdate::WorkerStatusChanged {
                        project_key,
                        action: WorkerStatusAction::Removed,
                        status: rolled.to_status(),
                        // The rollback beat the subprocess, so
                        // `--worktree <label>` never reached one and
                        // there is no worktree to point the user at.
                        worktree: WorktreeDisposition::Absent,
                    },
                );
            }
            // The caller's error is the same sentence the slot records, so
            // the two cannot name different failures.
            let _ = return_to.send(Err(message));
        }
    }
}

/// Shared worker teardown used by both `handle_close_worker` (a view's
/// X-button) and `handle_despawn_worker` (the `agents__despawn` MCP
/// tool): remove the latest-spawned worker matching `label` from
/// `live_workers[project_key]` and release its session (terminates the
/// claude subprocess on drop). Returns
/// the removed `WorkerEntry`, or `None` when no live worker matched.
/// JSONL on disk is NOT deleted - teardown only removes the in-memory
/// live state.
///
/// The `Removed` event is the caller's to emit via
/// [`emit_worker_removed`]: the despawn path only learns what became
/// of the worktree after this returns.
fn teardown_worker(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    label: &str,
) -> Option<crate::mcp::workers::types::WorkerEntry> {
    let entry = workspace.remove_latest_worker(project_key, label)?;
    // Both entry points into this routine (the Projects-pane close and
    // the `agents__despawn` MCP tool) delete the persisted worker row so
    // it never re-spawns. Cancel and the lead-close cascade go through
    // other paths and deliberately leave the row intact.
    let _ = workspace.delete_worker_row(project_key, label);
    // The row is gone, so nothing re-spawns this label: its durable state
    // has no owner left to wake and goes with it.
    workspace.remove_gotify_subscriptions_for_worker(project_key, label);
    // Same for its Slack subscriptions: a despawned worker cannot strand
    // records that would reload at boot, and a delivery for it must not
    // fall through to the lead.
    workspace.remove_slack_subscriptions_for_worker(project_key, label);
    workspace.stop_slack_subsystem_if_idle();
    workspace.delete_crons_for_worker(project_key, label);
    // Closes exactly one worker, so the non-cascading primitive. The
    // cascading variant would reach the same result: it cascades only
    // from a lead slot, and this one carries the worker's own label.
    // Per-row close must only affect the worker being closed, so the
    // narrower call is the one to read here.
    workspace.release_session(&entry.slot);
    // A payload parked for this label while it was still spawning has no
    // session left to drain it.
    workspace.expire_parked_for_slot(
        &entry.slot,
        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
    );
    Some(entry)
}

/// Announce a torn-down worker to the views, carrying what became of its
/// worktree.
fn emit_worker_removed(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    entry: &crate::mcp::workers::types::WorkerEntry,
    worktree: WorktreeDisposition,
) {
    let _ = workspace.update_tx().send(SessionUpdate::WorkerStatusChanged {
        project_key: project_key.clone(),
        action: WorkerStatusAction::Removed,
        status: entry.to_status(),
        worktree,
    });
}

/// Handle a `Command::CloseWorker` (a view's per-row X-button): tear
/// the worker down via [`teardown_worker`]. Does NOT touch the git
/// worktree - that's the `agents__despawn` path's job; the X-button's
/// behavior is intentionally unchanged.
pub(crate) fn handle_close_worker(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    label: &str,
) {
    // Announced before the teardown, and only where a worker is really here:
    // other views' rows say where the seat is going for the seconds the close
    // takes, and a label with no live worker has no row to mark (#1930). The
    // peek is the despawn handler's own shape, for the same reason - the
    // single-threaded command loop means nothing moves between it and the
    // teardown below.
    let live = workspace
        .list_live_workers(project_key)
        .into_iter()
        .rev()
        .find(|worker| worker.label == label);
    // **A failed spawn is a seat to dismiss, not a session to tear down.**
    // Its entry is a tombstone (or was rolled back), so there is nothing
    // running to kill and the persisted row is what lets the label start
    // again - [`teardown_worker`] would delete it.
    if live
        .as_ref()
        .is_some_and(|entry| matches!(entry.status, forge_primitives::WorkerLiveness::Failed))
    {
        dismiss_failed_worker(workspace, project_key, label, live.as_ref());
        return;
    }
    if let Some(entry) = live.as_ref() {
        workspace.announce_release(&entry.slot);
    }
    let Some(entry) = teardown_worker(workspace, project_key, label) else {
        // No live entry: the seat may still be here as a persisted row with
        // a spawn failure that rolled its entry back. The close dismisses
        // that trace; with none, there is nothing to close.
        if dismiss_failed_worker(workspace, project_key, label, None) {
            return;
        }
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project_key.as_str(),
            label = %label,
            "handle_close_worker: no matching live worker"
        );
        return;
    };
    let worktree = WorktreeDisposition::untouched(entry.is_git_repo_at_spawn);
    emit_worker_removed(workspace, project_key, &entry, worktree);
    sweep_browser_seats(workspace);
}

/// Close a failed worker, or one whose failure is all that is left of it:
/// take the tombstone entry when one survives, clear the slot's failure
/// record, and announce the release so views re-read the row without it.
///
/// **Not [`teardown_worker`]**: the persisted row stays, because it is what
/// lets the label start again once whatever refused the spawn is fixed. The
/// worker's subscriptions and schedules stay with it for the same reason.
/// Answers whether anything was there to dismiss.
fn dismiss_failed_worker(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    label: &str,
    entry: Option<&crate::mcp::workers::types::WorkerEntry>,
) -> bool {
    let slot = if let Some(entry) = entry {
        entry.slot.clone()
    } else {
        // The slot is the identity the failure is recorded under; a project
        // no longer in the config has no seat left to address.
        let Some(view) =
            workspace.list_projects().into_iter().find(|view| view.key == *project_key)
        else {
            return false;
        };
        SessionSlot::worker(&view.org, &view.name, label)
    };
    if entry.is_none() && workspace.spawn_failure(&slot).is_none() {
        return false;
    }
    if let Some(entry) = entry {
        let _ = workspace.remove_worker_by_session_key(&entry.slot);
    }
    workspace.announce_release(&slot);
    workspace.expire_parked_for_slot(
        &slot,
        crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
    );
    if let Some(entry) = entry {
        let worktree = WorktreeDisposition::untouched(entry.is_git_repo_at_spawn);
        emit_worker_removed(workspace, project_key, entry, worktree);
    }
    sweep_browser_seats(workspace);
    true
}

/// Tell the browser fleet which seats remain: **the seat is down, so its
/// tabs go with it**, except any a parked hand-off holds. The sweep runs off
/// the teardown path, which is reaping a child and can take minutes; a fleet
/// that is not installed is a workspace with no browsers to sweep. The
/// snapshot carries its capture generation, so the fleet drops a sweep that
/// arrives after a newer capture.
fn sweep_browser_seats(workspace: &Arc<Workspace>) {
    let (Some(host), Some(snapshot)) = (workspace.browser_host(), workspace.live_seats()) else {
        return;
    };
    tokio::spawn(async move { host.sweep_sessions(&snapshot.seats, snapshot.generation).await });
}

/// Warm the seat's browser profile: create the entry and start its host, with
/// no tab. **Best-effort**, off the spawn's own path: a profile whose host
/// cannot start is logged by the fleet rather than failing the spawn.
fn warm_browser_seat(workspace: &Arc<Workspace>, seat: &forge_primitives::SessionSlot) {
    let Some(host) = workspace.browser_host() else { return };
    let seat = seat.clone();
    tokio::spawn(async move { host.warm(&seat).await });
}

/// Handle a `Command::DespawnWorker` (the `agents__despawn` MCP
/// tool): the lead's clean-close gesture. Unlike `handle_close_worker`
/// it also cleans up the worker's git worktree.
///
/// Order matters: the worktree dirty-check runs BEFORE any teardown,
/// so a dirty worker (uncommitted/untracked or unpushed) is blocked
/// without being killed (unless `force`). Teardown then releases the
/// session, which drops the worker's command sender; the disconnect
/// itself runs asynchronously on the worker's own task and can take
/// up to the 5s close-wait budget to reap the child. The worktree
/// removal runs on the blocking pool (see [`DespawnCleanup`]) only after
/// that task has finished dying - its exit path reaps the session's own
/// child (waits it out, then SIGKILLs), so that child is dead before the
/// removal takes the tree (#1767; descendants that outlive a SIGKILLed
/// child are #2337) - without holding the caller's runtime, and bounded
/// by [`TEARDOWN_WAIT`] so a teardown that never answers cannot wedge the
/// reply. A post-teardown worktree-removal failure is surfaced as a
/// warning in the
/// [`DespawnResult`](crate::protocol::DespawnResult) but never rolls back
/// the kill - teardown and worktree cleanup are independent.
pub(crate) fn handle_despawn_worker(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    label: &str,
    force: bool,
    respond: tokio::sync::oneshot::Sender<crate::protocol::DespawnResult>,
) {
    handle_despawn_worker_within(workspace, project_key, label, force, TEARDOWN_WAIT, respond);
}

/// How long the despawn holds its worktree removal for the session task's
/// teardown signal before giving up and removing anyway: the SDK's
/// close-wait budget (the child's reap) plus a margin for the task to
/// observe its closed channel, disconnect and drop. An expiry is logged -
/// it is the one shape where the removal goes ahead unprotected.
pub(crate) const TEARDOWN_WAIT: std::time::Duration =
    forge_sdk::CLOSE_WAIT_TIMEOUT.saturating_add(std::time::Duration::from_secs(5));

/// [`handle_despawn_worker`] with the teardown wait injected, so a case
/// can drive the expiry without sitting out the production budget.
pub(crate) fn handle_despawn_worker_within(
    workspace: &Arc<Workspace>,
    project_key: &ProjectKey,
    label: &str,
    force: bool,
    teardown_wait: std::time::Duration,
    respond: tokio::sync::oneshot::Sender<crate::protocol::DespawnResult>,
) {
    use crate::protocol::DespawnResult;

    // `lead` is not a worker label: it is the project lead's own row, the
    // stored id an ordinary boot resumes the lead from, and the spawn path
    // reserves the label so no worker can hold it. Clearing that row and
    // reporting a despawn would orphan the lead's conversation.
    if label == crate::store::sessions::LEAD_LABEL {
        let _ = respond.send(DespawnResult::NotFound);
        return;
    }

    // Peek the latest-spawned matching worker WITHOUT removing it, so a
    // blocked despawn leaves it live.
    let live =
        workspace.list_live_workers(project_key).into_iter().rev().find(|w| w.label == label);

    // The gitness this despawn acts on, and whether there is a worker here
    // at all. A live entry stamped its gitness at spawn; with no entry the
    // durable row answers both, and the two questions are separate: a row
    // whose `is_git_repo` is absent has a worker but no known worktree,
    // which is how `worker_tag_dir` and the boot wave read the same field.
    // Asking one question for both is what makes a row the migration wrote
    // - it records no gitness before the first spawn - look like no row,
    // and that row is exactly the one #1142 exists to reach.
    //
    // The tree is read in the same breath for the same reason: a worker
    // the spawn pointed at another directory keeps its worktree THERE, so
    // the probe, the removal and the branch reap all run against that
    // tree - composing them against the project path would probe (and
    // block on) a directory the worker never ran in.
    let (is_git_repo, recorded_cwd) = match live.as_ref() {
        Some(entry) => (Some(entry.is_git_repo_at_spawn), entry.cwd.clone()),
        None => match workspace.stored_worker_row(project_key, label) {
            Ok(Some(row)) => {
                (Some(matches!(row.is_git_repo, Some(true))), row.cwd.map(std::path::PathBuf::from))
            }
            Ok(None) => (None, None),
            // A row that cannot be read is not an absent one, and reading
            // it is how this call decides whether there is anything here.
            Err(error) => {
                let _ = respond.send(DespawnResult::Failed {
                    reason: format!(
                        "could not read the durable row for '{label}': {error}; whether one \
                         exists is unknown"
                    ),
                });
                return;
            }
        },
    };
    let Some(is_git_repo) = is_git_repo else {
        let _ = respond.send(DespawnResult::NotFound);
        return;
    };

    // Resolve the worktree path for git-repo workers (claude's
    // `<base>/.claude/worktrees/<label>/`, `base` being the CLI's
    // canonical root, so a project that is itself a linked worktree
    // resolves to the main checkout - which is where the CLI created the
    // worktree). Non-git workers have no worktree to clean.
    let project_view = workspace.list_projects().into_iter().find(|v| v.key == *project_key);
    let spawn_root = recorded_cwd.or_else(|| project_view.as_ref().map(|v| v.path.clone()));
    let worktree_path = if is_git_repo {
        spawn_root
            .as_ref()
            .map(|root| crate::mcp::workers::types::worker_tag_dir(root, label, true))
    } else {
        None
    };
    // Every worktree operation below runs against the checkout whose
    // `.claude/worktrees` holds the tree - the CLI's base, which is the
    // main checkout for a linked-worktree project.
    let worktree_root = if is_git_repo {
        spawn_root.map(|root| forge_agent::env::worktree::worktree_base(&root))
    } else {
        spawn_root
    };

    // The path is repository-global: it may be another project's checkout
    // or another project's worker's tree. Removing it would delete that,
    // so refuse before the probe; a force cannot override this.
    if let Some(path) = worktree_path.as_ref()
        && let Some(collision) = workspace.worktree_collision(
            path,
            project_key,
            label,
            crate::workspace::WorktreeOp::Despawn,
        )
    {
        tracing::warn!(
            target: "forge_workspace::spawn",
            event_name = "despawn_refused_shared_worktree",
            project = %project_key.as_str(),
            label = %label,
            worktree = %path.display(),
            reason = %collision,
            "the worker's worktree is shared with another project, so the despawn is refused",
        );
        let _ = respond.send(DespawnResult::Failed {
            reason: format!(
                "refusing to despawn '{label}': {collision}; if it is not that project's tree, \
                 remove it by hand"
            ),
        });
        return;
    }

    // Hold the path through the teardown and the removal: teardown drops
    // the durable row before the removal runs, so another project's spawn
    // would otherwise be admitted into a tree the cleanup is deleting.
    // Released when the cleanup ends.
    let claim = match worktree_path.as_ref() {
        Some(path) => match workspace.claim_worktree(
            path,
            project_key,
            label,
            crate::workspace::WorktreeOp::Despawn,
        ) {
            Ok(claim) => Some(claim),
            Err(reason) => {
                let _ = respond.send(DespawnResult::Failed {
                    reason: format!("refusing to despawn '{label}': {reason}"),
                });
                return;
            }
        },
        None => None,
    };

    // A worker's worktree carries its own build tree, so the removal
    // below deletes hundreds of thousands of files and can run for
    // minutes. Nothing else on this path is slow, so these phase records
    // are what tells a long close apart from a hung one (#1113).
    let worktree_display =
        worktree_path.as_ref().map_or_else(|| "none".to_owned(), |path| path.display().to_string());
    tracing::info!(
        target: "forge_workspace::spawn",
        project = %project_key.as_str(),
        label = %label,
        force,
        worktree = %worktree_display,
        "despawn: starting",
    );

    // A stranded row whose worktree is already gone is the shape the boot
    // wave skips: nothing is on disk to remove and nothing in it to lose,
    // so the checks that guard live work stand down for it. A live
    // worker's worktree vanishing is the opposite case, and keeps them.
    let worktree_already_gone =
        live.is_none() && worktree_path.as_ref().is_some_and(|path| !path.exists());

    // Dirty-check BEFORE teardown: block (nothing torn down) when the
    // worktree is dirty and `force` is not set. `force` skips the probe
    // rather than ignoring its verdict, and so does a worktree that is not
    // there to probe - `worktree_dirty_reason` cannot read a directory
    // that does not exist, and blocking on that would refuse a despawn
    // over work there is no worktree to hold.
    let dirty_reason = if force || worktree_already_gone {
        None
    } else {
        worktree_path.as_ref().and_then(|path| worktree_dirty_verdict(path))
    };
    tracing::info!(
        target: "forge_workspace::spawn",
        project = %project_key.as_str(),
        label = %label,
        dirty = dirty_reason.is_some(),
        reason = dirty_reason.as_deref().unwrap_or("none"),
        "despawn: dirty verdict",
    );
    if let Some(reason) = dirty_reason {
        let _ = respond.send(DespawnResult::Blocked { reason });
        return;
    }

    // The session's teardown signal, taken before the teardown releases
    // it, so the cleanup below can hold the worktree removal until the
    // worker's session has finished dying (#1767). Only a git worker has
    // a worktree to order against, so only it takes one.
    //
    // A git worker with a live entry but no signal yet is MID-SPAWN - the
    // entry goes in before the session task is minted - so the removal
    // would race a child that is only starting: #1767's own class of
    // overlap, for that window. Refuse rather than report Despawned over
    // a live spawn; the caller retries once the worker is up.
    let mut teardown_done = None;
    if is_git_repo && let Some(entry) = live.as_ref() {
        teardown_done = workspace.session_teardown(&entry.slot);
        if teardown_done.is_none()
            && matches!(entry.status, forge_primitives::WorkerLiveness::Spawning)
        {
            let _ = respond.send(DespawnResult::Blocked {
                reason: format!(
                    "'{label}' is still spawning, so its session's teardown cannot be waited \
                     for; retry once it is up"
                ),
            });
            return;
        }
    }

    // The label stays reserved for the whole cleanup: marked here, before
    // the teardown frees the entry, so no spawn can take the label in
    // between and be handed the worktree this despawn is about to delete.
    // The guard rides into the cleanup below and releases the label when
    // the cleanup ends (or unwinds). Every refusal path above this point
    // returns before the mark, so a blocked or absent despawn frees
    // nothing it did not take.
    let cleanup_pending = workspace.mark_despawn_cleanup_pending(project_key, label);

    // Teardown. A live worker goes through `teardown_worker`, which kills
    // the subprocess on drop, removes the entry, deletes the row and
    // clears the records and payloads addressed to it.
    //
    // A stranded row has no entry to tear down: the row is the whole of
    // it, so it goes here with the records and payloads its label still
    // owns. Without that, a despawn would report a worker gone while
    // leaving exactly what the live path exists to clear (#1142).
    if live.is_some() {
        // Announced here rather than at the removal below: this despawn's
        // own frame only goes out once the worktree cleanup finishes, and
        // that can run for minutes - so other views' rows read the seat as
        // working for the whole cleanup without this (#1930). Every refusal
        // path returned above, so a blocked or absent despawn marks nothing.
        if let Some(entry) = live.as_ref() {
            workspace.announce_release(&entry.slot);
        }
        // The single-threaded command loop means nothing mutated
        // `live_workers` between the peek above and here, but re-checking
        // the removal is defensive.
        if teardown_worker(workspace, project_key, label).is_none() {
            let _ = respond.send(DespawnResult::NotFound);
            return;
        }
    } else {
        match workspace.delete_worker_row(project_key, label) {
            Ok(true) => {}
            Ok(false) => {
                let _ = respond.send(DespawnResult::NotFound);
                return;
            }
            // A store that could not be written is not an absent row:
            // reporting NotFound would send the caller looking for a
            // worker that is right there. `delete_worker_row` has already
            // logged why, so the caller gets the reason and the log has
            // the site.
            Err(error) => {
                let _ = respond.send(DespawnResult::Failed {
                    reason: format!(
                        "could not clear the durable row for '{label}': {error}; whether one \
                         exists is unknown, so nothing was reported as removed"
                    ),
                });
                return;
            }
        }
        workspace.remove_gotify_subscriptions_for_worker(project_key, label);
        workspace.remove_slack_subscriptions_for_worker(project_key, label);
        workspace.stop_slack_subsystem_if_idle();
        workspace.delete_crons_for_worker(project_key, label);
        if let Some(view) = project_view.as_ref() {
            workspace.expire_parked_for_slot(
                &SessionSlot::worker(&view.org, &view.name, label),
                crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
            );
        }
        tracing::info!(
            target: "forge_workspace::spawn",
            event_name = "despawn_cleared_stranded_worker",
            project = %project_key.as_str(),
            label = %label,
            "despawn: no live worker matched; cleared its stranded durable row and records",
        );
    }

    // **The seat is down, so its browser profiles go with it** - here, after
    // teardown and before the worktree cleanup, which can run for minutes.
    sweep_browser_seats(workspace);

    // Everything from here runs `git` or walks the tree, and the removal
    // alone can take minutes: inline on a runtime worker it holds the
    // socket's own work for the whole time (#1633), so it goes to the
    // blocking pool, as the subagent worktree reap does. The reply, the
    // pane's event and any warning still go out when the cleanup finishes.
    let log_project = project_key.clone();
    let log_label = label.to_owned();
    let cleanup = DespawnCleanup {
        workspace: Arc::clone(workspace),
        project_key: project_key.clone(),
        label: label.to_owned(),
        force,
        worktree_path,
        worktree_display,
        worktree_already_gone,
        claim,
        worktree_root,
        project_view,
        live,
        is_git_repo,
        respond,
    };
    if let Ok(handle) = tokio::runtime::Handle::try_current() {
        // A wrapper task holds the removal until the worker's session
        // has finished dying, then awaits the blocking handle, so a
        // panic in the cleanup names its site in the log instead of
        // vanishing with the JoinHandle; the caller still sees the
        // dropped reply.
        //
        // The wait is the point: the session's exit path is what reaps
        // the claude child (waits it out, then SIGKILLs), and a
        // removal that overlapped those final seconds is how a
        // runaway wrote back into the path the removal had already
        // taken (#1767). `Err` means the task went away without
        // firing - nothing is left to wait for. The wait is BOUNDED:
        // the close-wait budget bounds the reap, not the whole path to
        // the task's drop, and an unbounded wait would leave the reply
        // never arriving and the label cleanup-pending forever.
        handle.spawn(async move {
            if let Some(mut done) = teardown_done
                && tokio::time::timeout(teardown_wait, async {
                    if *done.borrow_and_update() {
                        return;
                    }
                    let _ = done.changed().await;
                })
                .await
                .is_err()
            {
                warn_teardown_wait_expired(&log_project, &log_label, teardown_wait);
            }
            let task = tokio::task::spawn_blocking(move || cleanup.run(cleanup_pending));
            if let Err(join_err) = task.await {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    event_name = "despawn_cleanup_panicked",
                    project = %log_project.as_str(),
                    label = %log_label,
                    error = %join_err,
                    "despawn: the worktree cleanup panicked part-way through",
                );
            }
        });
    } else {
        // No runtime to hand it to - a caller outside one: the cleanup runs
        // where it is, the way this path always did. The wait still
        // happens, bounded: the value is polled on a deadline, since the
        // watch's change notification is async-only.
        if let Some(mut done) = teardown_done {
            let deadline = std::time::Instant::now() + teardown_wait;
            while !*done.borrow_and_update() && std::time::Instant::now() < deadline {
                std::thread::sleep(std::time::Duration::from_millis(25));
            }
            if !*done.borrow() {
                warn_teardown_wait_expired(project_key, label, teardown_wait);
            }
        }
        cleanup.run(cleanup_pending);
    }
}

/// The removal went ahead without the ordering: the session's teardown did
/// not answer within the wait. Warned rather than silent - it is the one
/// shape where the despawn's protection is absent.
fn warn_teardown_wait_expired(project_key: &ProjectKey, label: &str, wait: std::time::Duration) {
    tracing::warn!(
        target: "forge_workspace::spawn",
        event_name = "despawn_teardown_wait_expired",
        project = %project_key.as_str(),
        label = %label,
        ?wait,
        "despawn: the worker's session did not finish dying within the wait; removing the \
         worktree without it",
    );
}

/// The despawn's dirty verdict, taken off the runtime's worker: `git status`
/// walks the tracked tree, and the verdict gates the teardown, so the caller
/// cannot await a `spawn_blocking` handle. `block_in_place` hands the worker's
/// tasks to another thread for the call; a current-thread runtime has no other
/// thread, and stays inline. A `LocalSet` is not detected - tokio still reports
/// `MultiThread` there, where `block_in_place` panics - and the workspace runs
/// none.
fn worktree_dirty_verdict(path: &std::path::Path) -> Option<String> {
    let on_runtime_worker = tokio::runtime::Handle::try_current()
        .is_ok_and(|handle| handle.runtime_flavor() == tokio::runtime::RuntimeFlavor::MultiThread);
    if on_runtime_worker {
        return tokio::task::block_in_place(|| {
            forge_agent::env::worktree::worktree_dirty_reason(path)
        });
    }
    forge_agent::env::worktree::worktree_dirty_reason(path)
}

/// The despawn's filesystem half, handed to the blocking pool.
///
/// Split out of [`handle_despawn_worker`] so the peek, the dirty verdict's
/// ordering and the teardown stay on the calling task, while the probe and the
/// cleanup's own `git` calls - the `git worktree remove` above all - run off
/// the runtime.
struct DespawnCleanup {
    workspace: Arc<Workspace>,
    project_key: ProjectKey,
    label: String,
    force: bool,
    worktree_path: Option<std::path::PathBuf>,
    worktree_display: String,
    worktree_already_gone: bool,
    /// The path's claim, held until the cleanup ends so no spawn in
    /// another project can enter the tree while it is removed.
    claim: Option<crate::workspace::WorktreeClaimGuard>,
    /// The checkout whose `.claude/worktrees` holds the worker's tree -
    /// the repo every `git` call in the cleanup anchors on. The main
    /// checkout for a worker the CLI forked under it. `None` when the
    /// project is no longer loaded and the row recorded no tree of its
    /// own.
    worktree_root: Option<std::path::PathBuf>,
    project_view: Option<crate::views::ProjectView>,
    live: Option<crate::mcp::workers::types::WorkerEntry>,
    is_git_repo: bool,
    respond: tokio::sync::oneshot::Sender<crate::protocol::DespawnResult>,
}

impl DespawnCleanup {
    /// Run the cleanup, holding `pending` - the label's in-flight mark -
    /// until the end, so the label is reserved for every step that touches
    /// the worktree and released only once the removal is done and its
    /// outcome has been announced.
    fn run(self, pending: DespawnCleanupPending) {
        use crate::protocol::DespawnResult;

        let Self {
            workspace,
            project_key,
            label,
            force,
            worktree_path,
            worktree_display,
            worktree_already_gone,
            // Held for the cleanup's whole span; released on drop.
            claim: _claim,
            worktree_root,
            project_view,
            live,
            is_git_repo,
            respond,
        } = self;
        let label = label.as_str();
        // Resolve the torn-down worktree's `(project name, branch)` while
        // the path still exists, so its persisted review state can be judged
        // once the worktree is gone. Keyed by the forge.toml project NAME to
        // match what the diff overlay saved under.
        let review_key = worktree_path.as_ref().and_then(|path| {
            let Some(branch) = forge_agent::env::worktree::worktree_branch(path) else {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    project = %project_key.as_str(),
                    label = %label,
                    "despawn: could not resolve the worktree branch (detached HEAD or git error); its review threads are not cleaned up and may resurrect on a later worktree reusing the branch",
                );
                return None;
            };
            let Some(name) = project_view.as_ref().map(|v| v.name.clone()) else {
                tracing::warn!(
                    target: "forge_workspace::spawn",
                    project = %project_key.as_str(),
                    label = %label,
                    branch = %branch,
                    "despawn: could not resolve the project name; the branch's review threads are not cleaned up",
                );
                return None;
            };
            Some((name, branch))
        });

        // Worktree cleanup runs AFTER teardown on a verified-clean (or
        // forced) worktree. A failure here is reported but never rolls
        // back the already-completed teardown.
        let mut branch_cleanup_warning = None;
        let worktree_cleanup_warning = match worktree_path.as_ref() {
            // A stranded row whose worktree is already gone is the definition
            // of that state - it is why the boot wave skips the row - so there
            // is nothing to remove and git's failure over an untracked path
            // would be a warning about nothing. A live worker's worktree
            // vanishing is the opposite: anomalous, and the live shape below
            // keeps reporting what git said.
            //
            // The BRANCH is a different matter, and it is still there: `git
            // worktree remove` never deletes one. With the directory gone the
            // branch is certainly not checked out, so this is the one place
            // reaping it is unambiguously safe.
            Some(path) if worktree_already_gone => {
                tracing::debug!(
                    target: "forge_workspace::spawn",
                    event_name = "despawn_stranded_worktree_already_gone",
                    project = %project_key.as_str(),
                    label = %label,
                    worktree = %worktree_display,
                    "despawn: the stranded row's worktree is already gone; nothing to remove",
                );
                // The directory is gone, so any earlier admission for this
                // label is spent; retract it rather than let it authorize
                // deleting a directory that later takes its place.
                if let Some(root) = worktree_root.as_deref() {
                    forge_agent::env::worktree::record_worktree_gone(root, label, path);
                }
                branch_cleanup_warning = reap_branch_and_reviews(
                    &workspace,
                    worktree_root.as_deref(),
                    review_key.as_ref(),
                    label,
                );
                None
            }
            Some(path) => {
                // git refuses a worktree holding initialized submodules
                // however clean it is (git-worktree(1)), so its refusal is
                // not a verdict on the disk and cannot stand as one. Re-judge
                // it against the worktree as it is now: `--force` discards
                // uncommitted work, so it stands in only for a verdict taken
                // here rather than one taken before the worker was torn down.
                // The admitted removal is recorded before git runs, so a
                // removal that dies part-way leaves the record the
                // leftover clear deletes on. `worktree_root` is Some
                // whenever `worktree_path` is (the path is derived from
                // the root above), so the plain-removal arm is a fallback
                // the flow cannot reach today.
                let remove = |force: bool| match worktree_root.as_deref() {
                    Some(root) => {
                        forge_agent::env::worktree::remove_owned_worktree(root, label, path, force)
                    }
                    None => forge_agent::env::worktree::remove_worktree(path, force),
                };
                let removal = match remove(force) {
                    Err(err)
                        if !force
                            && forge_agent::env::worktree::worktree_dirty_reason(path)
                                .is_none() =>
                    {
                        tracing::debug!(
                            target: "forge_workspace::spawn",
                            event_name = "despawn_worktree_removal_forced",
                            project = %project_key.as_str(),
                            label = %label,
                            worktree = %path.display(),
                            error = %err,
                            "despawn: git refused the removal of a clean worktree; retrying with --force",
                        );
                        remove(true)
                    }
                    other => other,
                };
                // git deregisters a worktree before it walks the tree, so
                // a delete that failed part-way (a build still writing
                // into `target/`) leaves the directory with no
                // registration: the re-check above can no longer read the
                // tree and every later `git worktree remove` refuses it.
                // With the tree unreadable, the fallback re-checks the
                // path's shape, that git no longer lists it, and the
                // removal record written above; the cleanliness behind
                // the delete is the verdict taken before teardown (or the
                // caller's `force`), since a deregistered tree cannot be
                // asked again.
                let removal = match removal {
                    Ok(()) => Ok(()),
                    Err(git_error) => match worktree_root.as_deref() {
                        None => Err(git_error.to_string()),
                        Some(root) => {
                            match forge_agent::env::worktree::remove_orphaned_worktree_dir(
                                root, path,
                            ) {
                                Ok(()) => {
                                    tracing::info!(
                                        target: "forge_workspace::spawn",
                                        event_name = "despawn_worktree_leftover_removed",
                                        project = %project_key.as_str(),
                                        label = %label,
                                        worktree = %path.display(),
                                        "despawn: removed the leftover directory git could no \
                                         longer remove",
                                    );
                                    Ok(())
                                }
                                Err(
                                    forge_agent::env::worktree::WorktreeError::LeftoverUndeletable {
                                        error,
                                        ..
                                    },
                                ) => Err(format!(
                                    "{git_error}; and its leftover directory could not be \
                                     deleted: {error}"
                                )),
                                // A refusal means the directory was kept -
                                // a registered worktree, a foreign one, or
                                // one with no admitted removal. Carry its
                                // detail so the operator sees why, and the
                                // remedy, rather than git's bare error.
                                Err(refusal) => {
                                    tracing::debug!(
                                        target: "forge_workspace::spawn",
                                        event_name = "despawn_worktree_leftover_kept",
                                        project = %project_key.as_str(),
                                        label = %label,
                                        worktree = %path.display(),
                                        error = %refusal,
                                        "despawn: the leftover path was left in place",
                                    );
                                    Err(format!(
                                        "{git_error}; and the leftover directory was kept: \
                                         {refusal}"
                                    ))
                                }
                            }
                        }
                    },
                };
                match removal {
                    Ok(()) => {
                        tracing::info!(
                            target: "forge_workspace::spawn",
                            project = %project_key.as_str(),
                            label = %label,
                            worktree = %path.display(),
                            "despawn: worktree removed",
                        );
                        // Only after a successful removal: while the worktree
                        // stands it holds the branch checked out, and git refuses
                        // to delete a checked-out branch.
                        branch_cleanup_warning = reap_branch_and_reviews(
                            &workspace,
                            worktree_root.as_deref(),
                            review_key.as_ref(),
                            label,
                        );
                        None
                    }
                    Err(err) => {
                        tracing::warn!(
                            target: "forge_workspace::spawn",
                            project = %project_key.as_str(),
                            label = %label,
                            error = %err,
                            "despawn: worker torn down but worktree cleanup failed"
                        );
                        Some(err)
                    }
                }
            }
            None => None,
        };

        // Ground-truthed against the directory rather than git's exit code:
        // git errors for a path it no longer tracks whether or not the
        // directory survives, and the toast's only claim is what is on disk.
        let worktree = match (worktree_path.as_ref(), worktree_cleanup_warning.as_ref()) {
            (None, _) => WorktreeDisposition::untouched(is_git_repo),
            (Some(path), Some(_)) if path.exists() => WorktreeDisposition::RemovalFailed,
            (Some(_), _) => WorktreeDisposition::Removed,
        };
        // Only a torn-down live worker has a pane row to remove; a stranded
        // row's label reaches the launchpad by reading the store per frame, so
        // it needs no event.
        //
        // The event is keyed by label and lands here, after the removal, so
        // it evicts whichever occupant holds the seat when a viewer reads it.
        // The in-flight mark is load-bearing for that: it keeps a same-label
        // spawn from putting a new occupant under the seat this event is
        // about to clear, and it is held until the guard below drops.
        if let Some(entry) = live.as_ref() {
            emit_worker_removed(&workspace, &project_key, entry, worktree);
        }

        // The label is free from here, before the reply: the worktree this
        // held it for is gone (or the failure to remove it was reported),
        // and a caller that re-admits the label the moment its reply lands
        // must find it free by ordering, not by luck.
        drop(pending);
        let _ = respond
            .send(DespawnResult::Despawned { worktree_cleanup_warning, branch_cleanup_warning });
    }
}

/// Reap the worker's branch and, once that is gone, the review state keyed
/// to it. Returns the warning a kept branch produces, which the caller's
/// result carries.
///
/// The branch outlives the worktree - `git worktree remove` does not delete
/// one - so this runs after a removal, and also for a worktree that was
/// already gone: gone means the branch is no longer checked out, which is
/// exactly when the delete is safe.
fn reap_branch_and_reviews(
    workspace: &Arc<Workspace>,
    repo: Option<&std::path::Path>,
    review_key: Option<&(String, String)>,
    label: &str,
) -> Option<String> {
    let warning = repo.and_then(|repo| reap_worker_branch(repo, label));
    // Threads are only orphaned once their branch is gone, and the reap
    // above can be what removes it - a worker that made no branch of its
    // own sits on `worktree-<label>`. The review state stays keyed by the
    // project's name: that is where the diff overlay saved it, even when
    // the worker ran in another tree.
    if let Some((project, branch)) = review_key
        && let Some(repo) = repo
        && !forge_agent::env::worktree::branch_ref_exists(repo, branch)
    {
        workspace.delete_branch_review_state(project, branch);
    }
    warning
}

/// Reap the `worktree-<label>` branch claude creates for a worker's
/// worktree, which outlives the worktree itself. Returns a warning when
/// the branch was left in place, `None` when it was deleted or never
/// existed.
///
/// The branch is named by convention, never taken from whatever the
/// worktree had checked out: a worker that made its own feature branch
/// has real work on that one, and this must not aim at it.
fn reap_worker_branch(repo: &std::path::Path, label: &str) -> Option<String> {
    use forge_agent::env::worktree::BranchReapOutcome;

    let branch = format!("worktree-{label}");
    let warning = match forge_agent::env::worktree::reap_worktree_branch(repo, &branch) {
        BranchReapOutcome::Reaped => None,
        BranchReapOutcome::NotPresent => {
            tracing::debug!(
                target: "forge_workspace::spawn",
                label = %label,
                branch = %branch,
                "despawn: no worktree branch to reap"
            );
            None
        }
        BranchReapOutcome::Kept { count, tip } => {
            let plural = if count == 1 { "" } else { "s" };
            Some(format!(
                "branch '{branch}' kept: {count} commit{plural} reachable from no other ref \
                 (tip {tip}). Inspect with 'git log -{count} {tip}', then 'git branch -D \
                 {branch}' once it has landed."
            ))
        }
        BranchReapOutcome::KeptOnError { reason } => Some(format!(
            "branch '{branch}' kept: could not verify it holds no unique commits ({reason}). \
             Check 'git log {branch}' and delete it by hand."
        )),
        BranchReapOutcome::DeleteFailed { reason } => Some(format!(
            "branch '{branch}' holds no unique commits, but the delete failed ({reason}). \
             Retry with 'git branch -D {branch}'."
        )),
    };
    // The oneshot reply reaches an LLM's tool result and nothing else, so
    // without this the operator's log has no record of a kept branch.
    if let Some(warning) = &warning {
        tracing::warn!(
            target: "forge_workspace::spawn",
            label = %label,
            branch = %branch,
            warning = %warning,
            "despawn: worktree branch kept"
        );
    }
    warning
}

/// Handle a `Command::DeliverWorkerPrompt`: route a wrapped peer-style
/// envelope to the worker matching `target_label` in the caller's
/// project. Latest-spawned-wins on duplicate labels. The typed
/// PeerEnvelopeAppended echo follows the same pattern as
/// `handle_deliver_peer_prompt` - workers reuse the peer envelope
/// verbatim so a view's chat render is identical between the two
/// paths.
///
/// Unlike `handle_deliver_peer_prompt`, this handler never buffers +
/// auto-spawns: workers are only addressable while live. If the
/// target label vanished between the dispatch and the handler firing
/// (worker closed, lead cascade fired), the prompt is dropped with a
/// warn log.
/// Buffer `wrapped` on `target_key`'s `DomainSession` when the target
/// hasn't finished its Connected handshake (no `session_id` yet). Returns
/// `Some(wrapped)` when the target IS connected (caller delivers now), or
/// `None` when it parked (the target's Connected handler drains the
/// bucket, doing the render + dispatch). Mirrors the sleeping-peer
/// buffering in `handle_deliver_peer_prompt`, sender included so an
/// expired bucket can still acknowledge the message.
fn buffer_prompt_until_connected(
    workspace: &Arc<Workspace>,
    sender: &crate::SessionSlot,
    target_key: &SessionSlot,
    wrapped: WrappedPrompt,
) -> Option<WrappedPrompt> {
    let Some(domain) = workspace.domain_session_for(target_key) else {
        // No DomainSession to park against (target vanished); let the
        // caller proceed - its dispatch warns on the missing target.
        return Some(wrapped);
    };
    if domain.lock().session_id.is_some() {
        return Some(wrapped);
    }
    workspace.park_peer_prompt(target_key, sender, wrapped);
    None
}

pub(crate) fn handle_deliver_worker_prompt(
    workspace: &Arc<Workspace>,
    caller: &SessionSlot,
    project_key: &ProjectKey,
    target_label: &str,
    wrapped: WrappedPrompt,
    respond: Option<tokio::sync::oneshot::Sender<Result<(), String>>>,
) {
    // Latest-spawned matching label wins (mirrors the addressing rule
    // in agents__send_message). Failed entries are skipped, the same rule
    // the spawn gate applies: a crashed worker keeps its row for the label
    // to be respawnable, and a prompt addressed there would go nowhere.
    let Some(entry) = workspace
        .list_live_workers(project_key)
        .into_iter()
        .rev()
        .find(|w| w.label == target_label && w.is_live())
    else {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project_key.as_str(),
            label = %target_label,
            "deliver_worker_prompt: no matching live worker (target gone since dispatch)"
        );
        answer_delivery(
            respond,
            Err(format!(
                "no live worker with label '{target_label}' in '{}' any more",
                project_key.as_str()
            )),
        );
        return;
    };
    let target_key = entry.slot.clone();

    // A worker addressed before it finishes its Connected handshake has
    // no session_id yet, so a bare Command::Prompt would be dropped by
    // execute_command_via_handle. Park it for the worker's label instead -
    // its Connected handler drains the bucket (render + dispatch)
    // exactly like the sleeping-peer path. Skips the tag retry / dispatch
    // below.
    let Some(wrapped) = buffer_prompt_until_connected(workspace, caller, &target_key, wrapped)
    else {
        // Parked for the worker's connect, whose drain delivers it.
        answer_delivery(respond, Ok(()));
        return;
    };

    // A delivery that lands while the seat is mid-turn is folded into the
    // running turn as a queued_command attachment with no standing of its
    // own - the follow-up a working worker reads past (measured on
    // 2.1.280). Hold it and deliver it at turn end, so it starts a turn.
    let held = {
        let domain = workspace.domain_session_for(&target_key);
        workspace.hold_peer_prompt_unless_turn_ended(&target_key, caller, wrapped, || {
            domain.as_ref().is_some_and(|domain| delivery_hold_signal(&domain.lock()))
        })
    };
    let Some(wrapped) = held else {
        answer_delivery(respond, Ok(()));
        return;
    };

    // Opportunistic tag-write retry: if this worker was spawned idle
    // (no initial_prompt), the JSONL didn't exist at Connected and
    // the tag-write at that point exhausted into a deferred state.
    // claude is about to process this turn, which means it's about
    // to write the JSONL - kick off a fire-and-forget retry now.
    if entry.needs_tag
        && let Some(session_id) = entry.session_id.clone()
    {
        // The retry composes the tag directory from the worker's OWN
        // tree - the same rule every read-back follows - with the
        // project's path as the fallback for a worker that has none: a
        // worker the spawn pointed at another repository keeps its JSONL
        // under that repository's worktree, so a retry aimed at the
        // project's path never finds it and the worker stays untagged.
        let root = entry.cwd.clone().or_else(|| {
            workspace
                .list_projects()
                .into_iter()
                .find(|view| view.key == *project_key)
                .map(|view| view.path)
        });
        if let Some(root) = root {
            workspace.retry_worker_tag_opportunistic(
                project_key,
                &target_key,
                session_id.as_str(),
                target_label,
                &root.to_string_lossy(),
                entry.is_git_repo_at_spawn,
            );
        } else {
            tracing::debug!(
                target: "forge_workspace::spawn",
                project = %project_key.as_str(),
                label = %target_label,
                "deliver_worker_prompt: project view missing; skipping tag retry"
            );
        }
    }

    // Fire the typed peer-envelope echo BEFORE the LLM-side dispatch
    // so the user-turn block renders in the right order regardless
    // of which event a view reducer drains first. Compute the prose
    // body BEFORE the move into PeerEnvelopeAppended so we consume
    // `wrapped` exactly once (the push_peer_user_turn_into_chat helper
    // takes `&WrappedPrompt` and clones internally).
    let text = wrapped.to_prose();
    let uuid = forge_sdk::request_id::next_prompt_id();
    push_peer_user_turn_into_chat(workspace, &target_key, &wrapped, &uuid);
    drop(wrapped);
    if let Err(err) =
        workspace.dispatch_workspace_prompt_under(&target_key, text, PromptSource::Peer, uuid)
    {
        tracing::warn!(
            target: "forge_workspace::spawn",
            project = %project_key.as_str(),
            label = %target_label,
            error = ?err,
            "DeliverWorkerPrompt dispatch to worker failed"
        );
        send_dispatch_turn_error(workspace, target_key, &err);
        answer_delivery(respond, Err(format!("the worker's session did not take it ({err:?})")));
        return;
    }
    answer_delivery(respond, Ok(()));
}

/// The turn signal a delivery is held on: only what a `Result` clears.
///
/// Stricter than
/// [`turn_in_flight`](crate::domain_session::DomainSession::turn_in_flight),
/// which ORs in `runtime_state` for the in-flight guards - no `Result`
/// clears that one, so a gate reading it could hold every later delivery
/// with nothing left to release it. Both signals here are down once a
/// Result has landed, which is what lets the hold and the turn-end drain
/// pair up.
fn delivery_hold_signal(domain: &crate::domain_session::DomainSession) -> bool {
    domain.turn_pending || domain.turn_open
}

/// Answer a delivery's `respond` channel, if the caller asked for one:
/// `Ok(())` once the prompt was accepted - handed to the target's session
/// queue, held for its turn end, or parked for its connect - and
/// `Err(reason)` when nothing could take it. The sender's ack is built
/// from this answer alone, so it never claims a delivery that did not
/// happen.
fn answer_delivery(
    respond: Option<tokio::sync::oneshot::Sender<Result<(), String>>>,
    outcome: Result<(), String>,
) {
    if let Some(tx) = respond {
        let _ = tx.send(outcome);
    }
}

/// Deliver everything held for `slot` while a turn was in flight, in the
/// order it arrived. Called where the turn's Result lands, so each held
/// prompt starts a turn of its own instead of folding into the one that
/// was running. A prompt the seat cannot take now - the session died
/// between the hold and the turn end - is told to its sender rather than
/// dropped, which is the whole point of holding it.
///
/// **The boundary's own settle is the session task's**, since it knows which
/// turn ended; this drain clears no liveness. The take shares its lock with a
/// concurrent hold's check-and-enqueue, so a delivery decides on
/// [`delivery_hold_signal`] either before this drain (and is delivered by it)
/// or after (and is delivered directly).
pub(crate) fn drain_turn_held_for_slot(workspace: &Arc<Workspace>, slot: &SessionSlot) {
    for crate::parked::ParkedPeer { sender, wrapped } in workspace.take_turn_held_for_slot(slot) {
        let text = wrapped.to_prose();
        let uuid = forge_sdk::request_id::next_prompt_id();
        push_peer_user_turn_into_chat(workspace, slot, &wrapped, &uuid);
        if let Err(err) =
            workspace.dispatch_workspace_prompt_under(slot, text, PromptSource::Peer, uuid)
        {
            tracing::warn!(
                target: "forge_workspace::spawn",
                slot = %slot.display(),
                error = ?err,
                "a held prompt could not be delivered when the turn ended"
            );
            workspace.notice_undelivered_message(
                &sender,
                slot,
                crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
            );
        }
    }
}

/// Handle a `Command::DeliverWorkerPromptToLead`: route a wrapped
/// peer-style prompt from a worker back to its lead, addressed by
/// the lead's `SessionSlot` (resolved at Tool dispatch from the
/// worker's `spawned_by_session_id`). Same wire shape as
/// `DeliverWorkerPrompt` - PeerEnvelopeAppended echo + Command::Prompt
/// dispatch - so a view renders the lead's message identically to
/// a sibling-worker delivery.
///
/// Drops with a warn log when the target lead session is no longer
/// in the pool (lead closed since the worker captured its
/// `spawned_by_session_id`). The lead can't be auto-respawned from
/// this path: that's a project-level decision the worker isn't
/// authorized to make.
pub(crate) fn handle_deliver_worker_prompt_to_lead(
    workspace: &Arc<Workspace>,
    caller: &SessionSlot,
    target_lead_key: &SessionSlot,
    wrapped: WrappedPrompt,
    respond: Option<tokio::sync::oneshot::Sender<Result<(), String>>>,
) {
    // Defensive: confirm the lead session is still in the pool. If it
    // closed since the worker captured its `spawned_by_session_id`,
    // drop the prompt with a warn - same shape as `DeliverWorkerPrompt`
    // does for a worker that vanished between dispatch and handler.
    if !workspace.pool.lock().contains_key(target_lead_key) {
        tracing::warn!(
            target: "forge_workspace::spawn",
            slot = %target_lead_key.display(),
            "deliver_worker_prompt_to_lead: lead session not in pool (closed since dispatch)"
        );
        answer_delivery(respond, Err("the lead's session is no longer running".to_owned()));
        return;
    }

    // Same pre-Connect guard as the sibling-worker path: if the lead
    // hasn't stamped its session_id yet, buffer for its Connected drain
    // rather than dispatching a Command::Prompt that would be dropped.
    let Some(wrapped) = buffer_prompt_until_connected(workspace, caller, target_lead_key, wrapped)
    else {
        // Parked for the lead's connect, whose drain delivers it.
        answer_delivery(respond, Ok(()));
        return;
    };

    // Same hold as the sibling-worker path: a lead mid-turn folds the
    // message into its running turn, where it has no standing of its own.
    let held = {
        let domain = workspace.domain_session_for(target_lead_key);
        workspace.hold_peer_prompt_unless_turn_ended(target_lead_key, caller, wrapped, || {
            domain.as_ref().is_some_and(|domain| delivery_hold_signal(&domain.lock()))
        })
    };
    let Some(wrapped) = held else {
        answer_delivery(respond, Ok(()));
        return;
    };

    let text = wrapped.to_prose();
    let uuid = forge_sdk::request_id::next_prompt_id();
    push_peer_user_turn_into_chat(workspace, target_lead_key, &wrapped, &uuid);
    drop(wrapped);
    if let Err(err) =
        workspace.dispatch_workspace_prompt_under(target_lead_key, text, PromptSource::Peer, uuid)
    {
        tracing::warn!(
            target: "forge_workspace::spawn",
            slot = %target_lead_key.display(),
            error = ?err,
            "DeliverWorkerPromptToLead dispatch to lead failed"
        );
        send_dispatch_turn_error(workspace, target_lead_key.clone(), &err);
        answer_delivery(respond, Err(format!("the lead's session did not take it ({err:?})")));
        return;
    }
    answer_delivery(respond, Ok(()));
}

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

    /// Ensure `forge/` exists and return the production `forge/forge.toml`
    /// path, so tests write where forge reads (not the legacy fallback).
    fn forge_toml_path(config_dir: &std::path::Path) -> std::path::PathBuf {
        crate::config::ensure_forge_data_dir(config_dir).expect("forge/ dir").join("forge.toml")
    }

    /// A fatal error is an App-level event with no state behind it, so a
    /// view that was not subscribed when it fired could never learn of it -
    /// and a client attaching to a running forge would draw a healthy
    /// startup that had already failed. The emit holds it; the read answers
    /// from what was held.
    #[test]
    fn a_fatal_error_is_held_where_it_is_emitted() {
        let (ws, _rx) = Workspace::testing_stub();
        let failed = forge_primitives::error::AppError::ConnectionFailed;

        assert!(ws.last_fatal_error().is_none(), "nothing has failed fatally yet");

        try_emit(
            &ws,
            "test",
            SessionUpdate::FatalError {
                message: failed.user_message().to_owned(),
                error: failed.clone(),
            },
        );

        assert_eq!(
            ws.last_fatal_error(),
            Some(failed),
            "the error the emit carried is the error the read answers with",
        );
    }

    /// The project path the shared fixture points at. The maintainer's own
    /// checkout, which is a git repo, so the gitness probe answers true for
    /// it; a fixture that needs a different answer writes its own.
    const FIXTURE_PROJECT_PATH: &str = "~/Projects/forge";

    fn write_forge_toml(dir: &std::path::Path, project_path: &str) {
        fs::write(
            forge_toml_path(dir),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

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

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

    #[test]
    fn project_permission_mode_stamps_into_absent_settings() {
        let mut settings = SessionLaunchSettings::default();
        stamp_permission_mode(
            &mut settings,
            forge_primitives::permission::PermissionMode::BypassPermissions,
        );
        let mode = settings
            .settings
            .as_ref()
            .and_then(|s| s.get("permissions"))
            .and_then(|p| p.get("defaultMode"))
            .and_then(serde_json::Value::as_str);
        assert_eq!(
            mode,
            Some("bypassPermissions"),
            "the project mode reaches the settings JSON the worker's applied_permission_mode arm reads",
        );
    }

    #[test]
    fn project_permission_mode_overrides_the_launcher_default_and_keeps_siblings() {
        let mut settings = SessionLaunchSettings {
            settings: Some(serde_json::json!({
                "permissions": { "defaultMode": "default" },
                "model": "haiku",
            })),
            ..SessionLaunchSettings::default()
        };
        stamp_permission_mode(
            &mut settings,
            forge_primitives::permission::PermissionMode::BypassPermissions,
        );
        let record = settings.settings.as_ref().expect("settings kept");
        assert_eq!(
            record
                .get("permissions")
                .and_then(|p| p.get("defaultMode"))
                .and_then(serde_json::Value::as_str),
            Some("bypassPermissions"),
            "the project mode wins over the launcher's session default",
        );
        assert_eq!(
            record.get("model").and_then(serde_json::Value::as_str),
            Some("haiku"),
            "sibling settings keys survive the stamp",
        );
    }

    /// `handle_spawn_project` for an unknown project name must not
    /// panic, must not emit a `SessionUpdate::Spawning`, and must
    /// log a warning. Important for the user-input boundary - a
    /// click on a stale row shouldn't crash forge.
    #[tokio::test]
    async fn spawn_project_unknown_project_emits_no_update() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut rx = workspace.subscribe_answerer();

        assert!(
            handle_spawn_project(&workspace, "no-such-project", SessionLaunchSettings::default())
                .is_err(),
            "an unknown project is refused rather than ignored",
        );

        // The user sees a typed notice naming the unknown project.
        assert!(
            matches!(
                rx.try_recv(),
                Ok(frame)
                    if matches!(&*frame.update, SessionUpdate::ServiceStatus { message, .. } if message.contains("no-such-project"))
            ),
            "unknown project surfaces a ServiceStatus notice"
        );
        assert!(rx.try_recv().is_err(), "nothing beyond the notice");
    }

    /// `handle_spawn_project` for a known project must emit a
    /// `SessionUpdate::Spawning` under the id the lead will run under,
    /// so a view can show a Waking placeholder before the agent reaches
    /// Connected and the bucket it draws is the one that connects.
    #[tokio::test]
    async fn spawn_project_known_project_announces_the_id_it_will_run_under() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut rx = workspace.subscribe_answerer();

        let _ = handle_spawn_project(&workspace, "forge", SessionLaunchSettings::default());

        let update = rx.try_recv().expect("Spawning emit");
        match std::sync::Arc::unwrap_or_clone(update.update) {
            SessionUpdate::Spawning { key, project_name, .. } => {
                assert_eq!(
                    key,
                    SessionSlot::lead("Default", "forge"),
                    "the announced key is the project's lead slot",
                );
                assert_eq!(project_name, "forge");
            }
            other => panic!("expected Spawning update; got {other:?}"),
        }
    }

    /// A spawn that fails before a `SessionTask` exists records the failure
    /// where a view reads it. The `ConnectionFailed` arm that would
    /// normally record it runs inside that task, so this path has to do it
    /// itself; a view rebuilding later reads the slot, and the record is
    /// the only thing left to say why the row reads failed.
    #[tokio::test]
    async fn spawn_project_records_the_failure_it_announces() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // A shut boot gate is the cheapest way to a spawn that never
        // builds a task: the slot resolves and is announced, then the
        // handle construction refuses.
        workspace.seed_test_gateway_ready(false);
        let mut rx = workspace.subscribe_answerer();

        let _ = handle_spawn_project(&workspace, "forge", SessionLaunchSettings::default());

        assert!(
            matches!(
                rx.try_recv(),
                Ok(frame) if matches!(&*frame.update, SessionUpdate::Spawning { .. })
            ),
            "the spawn is announced before the handle is built",
        );
        let key = match std::sync::Arc::unwrap_or_clone(
            rx.try_recv().expect("ConnectionFailed emit").update,
        ) {
            SessionUpdate::ConnectionFailed { key, .. } => key,
            other => panic!("expected ConnectionFailed; got {other:?}"),
        };
        assert_eq!(key, SessionSlot::lead("Default", "forge"));
        let record = workspace
            .spawn_failure(&key)
            .expect("the announced failure is recorded against the key the envelope carried");
        assert!(
            record.contains("agent spawn failed"),
            "the record carries the reason the envelope announced: {record}",
        );
    }

    /// The worker counterpart of `spawn_project_records_the_failure_it_announces`:
    /// a synchronous worker spawn failure records the reason on the worker's
    /// slot and carries it on the rollback's `Removed` event, so a view says
    /// why instead of drawing the rollback as a close.
    #[tokio::test]
    async fn a_synchronous_worker_spawn_failure_names_its_cause() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // A shut boot gate is the cheapest way to a spawn that never
        // builds a task: the entry is written and then the handle
        // construction refuses.
        workspace.seed_test_gateway_ready(false);
        let project =
            workspace.list_projects().into_iter().next().expect("fixture project present").key;
        let mut rx = workspace.subscribe_answerer();
        let (tx, reply) = tokio::sync::oneshot::channel();

        handle_spawn_worker(
            &workspace,
            project,
            WorkerSpawnArgs {
                label: "builder".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );

        let reason = reply.await.expect("reply channel").expect_err("the shut gate refuses");
        assert!(
            reason.contains("agent spawn failed") && reason.contains("boot gate is shut"),
            "the caller is told the cause, not just that it failed: {reason}",
        );
        let slot = SessionSlot::worker("Default", "forge", "builder");
        let record = workspace.spawn_failure(&slot).expect("the failure is recorded on the slot");
        assert!(
            record.contains("boot gate is shut"),
            "the record carries the cause itself: {record}",
        );

        let mut removed_diagnostic = None;
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::WorkerStatusChanged {
                action: WorkerStatusAction::Removed,
                status,
                ..
            } = &*frame.update
            {
                removed_diagnostic = status.diagnostic.clone();
            }
        }
        assert!(
            removed_diagnostic
                .as_ref()
                .is_some_and(|diagnostic| diagnostic.contains("agent spawn failed")),
            "the rollback event carries the cause a view shows: {removed_diagnostic:?}",
        );
    }

    /// The label rules are the spawn handler's, not only the MCP tool's:
    /// the command bus and the socket pass-through reach this handler
    /// directly. A `lead` label there collides with the lead's slot (#1682),
    /// and a slash desynchronises forge's worktree path and branch from
    /// claude's rewritten pair (#1603). Neither may mint anything.
    #[tokio::test]
    async fn the_spawn_handler_refuses_a_reserved_or_path_shaped_label() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/forge");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|view| view.name == "forge")
            .expect("seeded project")
            .key;

        for (label, expected) in [("lead", "reserved"), ("a/b", "slash")] {
            let (tx, reply) = tokio::sync::oneshot::channel();
            handle_spawn_worker(
                &workspace,
                project.clone(),
                WorkerSpawnArgs {
                    label: label.to_owned(),
                    charter: "charter".to_owned(),
                    kick: None,
                    resume_kick: None,
                    interactive: false,
                    mcp_families: None,
                    cwd: None,
                },
                SessionSlot::from_str_for_test("lead"),
                None,
                false,
                tx,
            );
            let refusal = reply.await.expect("reply channel").expect_err("the label is refused");
            assert!(
                refusal.contains(expected),
                "the refusal names the rule '{expected}' for '{label}': {refusal}",
            );
        }
        assert!(
            workspace.list_live_workers(&project).is_empty(),
            "a refused label mints no worker entry",
        );
    }

    /// A pooled handle whose session task is gone is not a session: the
    /// spawn fast path handed it back as a success, so no child started,
    /// the client read "no session task registered", and every later spawn
    /// repeated it (#2683). The spawn must rebuild the task instead.
    #[tokio::test]
    async fn a_spawn_rebuilds_a_pooled_handle_whose_task_is_gone() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        let view = workspace.list_projects().into_iter().next().expect("fixture project");
        let key = SessionSlot::lead(&view.org, &view.name);
        // The poison is the shape a dropped task leaves: an ANSWERED
        // teardown signal (a presence check passes it) and a command sender
        // whose task has gone.
        let (stale, _stale_commands) = Workspace::testing_stub_handle();
        let stale = Arc::new(stale);
        let teardown = workspace.mint_session_teardown(&key).expect("a teardown for the dead task");
        teardown.send_replace(true);
        let (stale_tx, mut stale_rx) = tokio::sync::mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(key.clone(), stale_tx);
        workspace.pool.lock().insert(
            key.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::clone(&stale),
                account: forge_gateway::AccountKey("Stargate".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "stale-id".to_owned(),
            },
        );
        // The cold path's stand-in, so the rebuild launches no real child.
        let (fresh, _fresh_commands) = Workspace::testing_stub_handle();
        workspace.install_test_spawn_handle(fresh);

        let handle = workspace
            .get_agent_handle_at_key(
                crate::target::SessionTarget::Named(view.name.clone()),
                SessionLaunchSettings::default(),
                Some(key.clone()),
                &crate::protocol::SpawnRole::Lead,
                true,
            )
            .expect("the spawn rebuilds rather than handing back a dead handle");

        assert!(!Arc::ptr_eq(&handle, &stale), "the stale handle is not the answer");
        assert!(
            workspace.session_is_live(&key),
            "and a session task now consumes the slot the stale handle held",
        );
        assert!(
            matches!(
                stale_rx.try_recv(),
                Err(tokio::sync::mpsc::error::TryRecvError::Disconnected)
            ),
            "the stale sender was replaced, so the command channel its old task reads is closed",
        );
    }

    fn fixture_wrapped() -> WrappedPrompt {
        WrappedPrompt {
            id: crate::mcp::peers::types::MessageId::mint(),
            kind: crate::mcp::peers::types::WrappedKind::Message,
            sender_name: "forge".to_owned(),
            sender_org: "Default".to_owned(),
            body: "fyi".to_owned(),
        }
    }

    /// I3 - `handle_deliver_peer_prompt` for an unknown target must
    /// not panic and must not emit a fatal envelope, and its answer must be
    /// an error naming the target: the tool's ack is this handler's own, so
    /// a delivery that went nowhere cannot read as sent (#2342).
    #[tokio::test]
    async fn handle_deliver_peer_prompt_unknown_target_is_an_error() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        let mut rx = workspace.subscribe_answerer();

        let caller = SessionSlot::from_str_for_test("caller-1");
        let outcome = handle_deliver_peer_prompt(
            &workspace,
            &caller,
            "no-such-project".to_owned(),
            fixture_wrapped(),
        );

        let refusal = outcome.expect_err("an unknown target is not a delivery");
        assert!(
            refusal.contains("no-such-project"),
            "the refusal names the target that went nowhere: {refusal}",
        );
        while let Ok(frame) = rx.try_recv() {
            assert!(
                !matches!(&*frame.update, SessionUpdate::FatalError { .. }),
                "unknown target must not emit FatalError"
            );
        }
    }

    /// A wake whose spawn fails inline is not an accepted delivery: the
    /// project handler's own arm expires the parked message, and the ack
    /// says so rather than reading the dispatch's Ok as the wake working
    /// (#2342).
    #[tokio::test]
    async fn a_delivery_whose_wake_fails_is_an_error() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        // A shut boot gate is the cheapest wake that fails with no child.
        workspace.seed_test_gateway_ready(false);
        let caller = SessionSlot::from_str_for_test("caller-wake");
        let wrapped = fixture_wrapped();
        let message_id = wrapped.id.clone();
        let lead = SessionSlot::lead("Default", "forge");

        let outcome = handle_deliver_peer_prompt(&workspace, &caller, "forge".to_owned(), wrapped);

        let refusal = outcome.expect_err("a wake that never started is not a delivery");
        assert!(
            refusal.contains("parked message was returned to you"),
            "the refusal is the parked-bucket read, not the dispatch error arm: {refusal}",
        );
        assert!(
            !workspace.peer_prompt_is_parked(&lead, &message_id),
            "the failed wake's arm expired the parked message",
        );
    }

    /// The running branch's own acceptance: a live lead takes the prompt and
    /// the handler answers Ok, routing a `PromptUnder` to its session. A
    /// branch that answered Err unconditionally would read every peer
    /// message to a live lead as failed.
    #[tokio::test]
    async fn a_delivery_a_running_lead_takes_is_ok() {
        let (workspace, _updates) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/forge");
        let lead = SessionSlot::lead("TestOrg", "forge");
        // The two facts the running branch resolves on: a pooled handle and
        // a live command sender behind it.
        let (handle, _commands) = Workspace::testing_stub_handle();
        workspace.pool.lock().insert(
            lead.clone(),
            crate::workspace::PooledAgent {
                handle: Arc::new(handle),
                account: forge_gateway::AccountKey("acct-a".to_owned()),
                permission_mode: None,
                registration: None,
                session_id: "lead-session".to_owned(),
            },
        );
        let (commands, mut routed) = tokio::sync::mpsc::unbounded_channel();
        workspace.command_senders.lock().insert(lead.clone(), commands);

        let outcome = handle_deliver_peer_prompt(
            &workspace,
            &SessionSlot::from_str_for_test("caller-running"),
            "forge".to_owned(),
            fixture_wrapped(),
        );

        assert!(outcome.is_ok(), "a live session takes the prompt: {outcome:?}");
        match routed.try_recv().expect("the prompt is routed to the lead's session") {
            Command::PromptUnder { text, .. } => {
                assert!(text.contains("fyi"), "the routed prose is the wrapped body: {text}");
            }
            other => panic!("expected PromptUnder; got {other:?}"),
        }
    }

    /// I3 - `handle_deliver_peer_prompt` against a sleeping known
    /// project parks the prompt for that project's lead and triggers a
    /// SpawnProject. The bucket is addressed by `(org, project, label)`,
    /// so no synthetic key is anywhere in the path; the drain side is
    /// pinned in `session_task`, which delivers a parked prompt on the
    /// owner's first `Connected`.
    #[tokio::test]
    async fn handle_deliver_peer_prompt_sleeping_target_parks_for_the_projects_lead() {
        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"

[[orgs.projects]]
name = "gateway-backend"
path = "~/Projects/gateway-backend"

[[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"));
        // Intercept dispatch so the spawn this delivery triggers does not
        // run inline and expire the park it just made: with no `claude`
        // binary the spawn's failure arm releases the slot, which is the
        // production behaviour but hides the parking under test.
        workspace.enable_test_dispatch_intercept();
        let caller = SessionSlot::from_str_for_test("caller-sleep");
        let w = fixture_wrapped();

        handle_deliver_peer_prompt(&workspace, &caller, "gateway-backend".to_owned(), w.clone())
            .expect("a sleeping target's parked message is an accepted delivery");

        // The sleeping branch parks the envelope for the project's lead
        // under `(org, project, None)`. EXACTLY ONE bucket holds our
        // wrapped prompt - assert on the id as well, so a mis-keyed
        // parking cannot pass by parking twice.
        let parked = workspace.parked_by_slot.lock();
        let bucket = parked
            .get(&crate::SessionSlot::lead("Default", "gateway-backend"))
            .expect("the project's lead bucket");
        assert_eq!(bucket.peer.len(), 1, "the project's lead bucket holds the wrapped prompt");
        assert_eq!(
            bucket.peer[0].wrapped.id, w.id,
            "and it is the payload that was handed to the delivery",
        );
        assert_eq!(
            bucket.peer[0].sender, caller,
            "with the SENDER beside it, which is the seat the ack goes back to when the spawn \
             fails - the bucket's own key is the target, so a mutant that parked the target \
             there would pass every other assertion here",
        );
    }

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

    use forge_primitives::slack::{SlackFile, SlackFileShares};

    fn slack_msg(text: &str) -> SlackMessage {
        SlackMessage {
            workspace: "acme".to_owned(),
            conversation: "D1".to_owned(),
            conversation_label: "U9".to_owned(),
            ts: "100.000001".to_owned(),
            thread_ts: None,
            user: Some("U9".to_owned()),
            author: None,
            text: text.to_owned(),
            parent_user_id: None,
            latest_reply: None,
            edited: None,
            files: Vec::new(),
        }
    }

    fn slack_msg_at(ts: &str, user: &str, text: &str) -> SlackMessage {
        SlackMessage { ts: ts.to_owned(), user: Some(user.to_owned()), ..slack_msg(text) }
    }

    /// The prose at a fixed moment below the default stale threshold, for the
    /// shape tests that do not exercise the age clause.
    fn fresh_prose(messages: &[SlackMessage]) -> String {
        slack_bundle_to_prose(
            messages,
            Duration::from_secs(24 * 60 * 60),
            SystemTime::UNIX_EPOCH + Duration::from_secs(200),
        )
    }

    #[test]
    fn a_slack_message_for_a_worker_targets_the_worker_not_the_lead() {
        let (ws, _rx) = Workspace::testing_stub();
        ws.seed_test_project("forge", "/tmp/slack-forge");
        let key = ws.list_projects().into_iter().find(|v| v.name == "forge").expect("seeded").key;
        // Delivery routes by the live entry's slot, so the fixture carries
        // the one production derives for this worker.
        let worker_key = crate::SessionSlot::worker("TestOrg", "forge", "tester");
        let mut entry = fake_worker_entry("tester", "worker-uuid");
        entry.slot = worker_key.clone();
        ws.insert_live_worker(&key, entry);

        deliver_slack_message(&ws, "forge", Some("tester"), vec![slack_msg("hello")]);

        let parked =
            ws.parked_by_slot.lock().get(&worker_key).map_or(0, |parked| parked.slack.len());
        assert_eq!(parked, 1, "the message is parked for the worker that subscribed");
        assert_eq!(
            ws.parked_by_slot
                .lock()
                .get(&crate::SessionSlot::lead("TestOrg", "forge"))
                .map_or(0, |parked| parked.slack.len()),
            0,
            "a worker-owned subscription never falls through to the lead",
        );
    }

    /// A `Failed` entry is kept by design (its tombstone row stays visible),
    /// but it is NOT live: the worker has no session to drain a bucket and no
    /// spawn coming to make one. So it must not be a delivery target - the
    /// batch would park forever and land as fresh user turns whenever the
    /// worker is next opened, however long that takes (#1208). Routing as if
    /// the worker were gone sends the message to the lead, which wakes the
    /// project the way the lead path always has.
    #[test]
    fn a_slack_message_for_a_failed_worker_goes_to_the_lead_not_a_frozen_bucket() {
        let dir = tempdir().expect("tempdir");
        let (ws, _rx) = Workspace::testing_stub_with_config_dir(dir.path().to_owned());
        ws.seed_test_project("forge", "/tmp/slack-failed-worker");
        let project_key =
            ws.list_projects().into_iter().find(|v| v.name == "forge").expect("seeded").key;
        // Delivery resolves the target through the live entry's slot, so the
        // fixture carries the one production derives for this worker.
        let worker_key = crate::SessionSlot::worker("TestOrg", "forge", "tester");
        let mut failed = fake_worker_entry("tester", "worker-uuid");
        failed.slot = worker_key.clone();
        failed.status = forge_primitives::WorkerLiveness::Failed;
        failed.diagnostic = Some("connection closed".to_owned());
        ws.insert_live_worker(&project_key, failed);
        ws.enable_test_dispatch_intercept();

        deliver_slack_message(&ws, "forge", Some("tester"), vec![slack_msg("hello")]);

        assert_eq!(
            ws.parked_by_slot.lock().get(&worker_key).map_or(0, |parked| parked.slack.len()),
            0,
            "a failed worker's slot is not a destination: nothing parks for a bucket nothing \
             will drain",
        );
        let dispatched = ws.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|c| matches!(
                c,
                crate::protocol::Command::SpawnProject { project_name, .. }
                    if project_name == "forge"
            )),
            "the message wakes the project: {dispatched:?}",
        );
        assert_eq!(
            ws.parked_by_slot
                .lock()
                .get(&crate::SessionSlot::lead("TestOrg", "forge"))
                .map_or(0, |parked| parked.slack.len()),
            1,
            "and waits for the lead the spawn brings up",
        );
    }

    /// A live delivery to a connected team worker dispatches the prose AND
    /// echoes the block into that worker's chat. The CLI never echoes a
    /// stdin-injected prompt back, so without the echo the agent works the
    /// message and the user sees nothing; asserting only the echo would let a
    /// regression through where the block paints and the agent never receives it.
    #[test]
    fn deliver_slack_message_to_a_connected_worker_dispatches_and_echoes() {
        let (ws, mut update_rx) = Workspace::testing_stub();
        ws.seed_test_project("forge", "/tmp/slack-worker-echo");
        let key = ws.list_projects().into_iter().find(|v| v.name == "forge").expect("seeded").key;
        ws.insert_live_worker(&key, fake_worker_entry("tester", "worker-uuid"));
        let worker_key = SessionSlot::from_str_for_test("worker-uuid");
        ws.mark_session_connected_for_test(&worker_key, "worker-uuid");
        ws.enable_test_dispatch_intercept();

        deliver_slack_message(&ws, "forge", Some("tester"), vec![slack_msg("hello")]);

        let dispatched = ws.drain_test_dispatch_buffer();
        assert!(
            dispatched.iter().any(|c| matches!(
                c, crate::protocol::Command::Prompt { key, text, .. }
                    | crate::protocol::Command::PromptUnder { key, text, .. }
                    if *key == worker_key && text.contains("hello")
            )),
            "the worker receives the message as a prompt: {dispatched:?}",
        );

        let mut echoed = false;
        while let Ok(frame) = update_rx.try_recv() {
            if matches!(
                &*frame.update,
                crate::protocol::SessionUpdate::SlackMessageAppended { key, prose, .. }
                    if key == &worker_key
                        && prose.starts_with("[Slack")
                        && prose.contains("hello")
            ) {
                echoed = true;
            }
        }
        assert!(
            echoed,
            "a connected worker's delivery emits a SlackMessageAppended echo with the body",
        );
    }

    /// The delivery path reads the workspace's own threshold, in both
    /// directions: a million-hour threshold leaves the 1970 fixture unmarked
    /// where a wrong key would fall back to 24 hours and mark it, and a
    /// one-hour threshold marks a two-hour-old message where a zero (the
    /// feature off) would not.
    #[test]
    fn a_workspace_threshold_bounds_what_delivery_marks() {
        let dir = tempdir().expect("tempdir");
        let mut config = crate::config::LoadedConfig::empty_for_test();
        config.slack = vec![
            forge_primitives::slack::SlackConfig {
                workspace: "acme".to_owned(),
                token: "xoxp-test".to_owned(),
                poll_seconds: 30,
                dm_poll_seconds: 150,
                thread_idle_days: 14,
                stale_after_hours: 1_000_000_000,
            },
            forge_primitives::slack::SlackConfig {
                workspace: "live".to_owned(),
                token: "xoxp-test".to_owned(),
                poll_seconds: 30,
                dm_poll_seconds: 150,
                thread_idle_days: 14,
                stale_after_hours: 1,
            },
        ];
        let (ws, mut update_rx) =
            Workspace::testing_stub_with_config(dir.path().to_path_buf(), config)
                .expect("the stub config's [[slack]] entries are well-formed");
        ws.seed_test_project("forge", "/tmp/slack-stale-threshold");
        let key = ws.list_projects().into_iter().find(|v| v.name == "forge").expect("seeded").key;
        ws.insert_live_worker(&key, fake_worker_entry("tester", "worker-uuid"));
        let worker_key = SessionSlot::from_str_for_test("worker-uuid");
        ws.mark_session_connected_for_test(&worker_key, "worker-uuid");
        ws.enable_test_dispatch_intercept();

        let now = SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .expect("the clock is past the epoch")
            .as_secs();
        let mut recent = slack_msg_at(&format!("{}.000000", now - 2 * 3_600), "U9", "recent");
        recent.workspace = "live".to_owned();

        deliver_slack_message(&ws, "forge", Some("tester"), vec![slack_msg("hello")]);
        deliver_slack_message(&ws, "forge", Some("tester"), vec![recent]);

        let mut echoes = Vec::new();
        while let Ok(frame) = update_rx.try_recv() {
            if let crate::protocol::SessionUpdate::SlackMessageAppended { key, prose, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && key == worker_key
            {
                echoes.push(prose);
            }
        }
        let unmarked = echoes
            .iter()
            .find(|prose| prose.contains("hello"))
            .expect("the huge-threshold delivery echoes its block");
        assert!(
            !unmarked.contains(" old"),
            "a million-hour threshold leaves the header unmarked: {unmarked}",
        );
        let marked = echoes
            .iter()
            .find(|prose| prose.contains("recent"))
            .expect("the small-threshold delivery echoes its block");
        assert!(
            marked.contains(", 2h old"),
            "a one-hour threshold marks a two-hour-old message: {marked}",
        );
    }

    /// A worker spawn that fails rolls its live entry back, so no live row
    /// lingers with no session behind it. The failure is the same
    /// `FreshInProject` miss the project-spawn arm hits: the overlay satisfies
    /// `list_projects` but not the config lookup inside the spawn.
    /// A fresh worker is keyed by the id it will run under: minted and
    /// recorded before the child starts, so the registry entry, the pool
    /// and the child's `--session-id` all name one string and `Connected`
    /// has nothing to move. Verified on a worker rather than a lead,
    /// because the worker used to be the path that spawned under a
    /// placeholder and rekeyed later.
    #[tokio::test]
    async fn a_fresh_worker_is_keyed_by_the_id_it_runs_under() {
        let dir = tempdir().expect("tempdir");
        // A repo of this test's own, because it reads the worktree the reply
        // names: the fixture project's gitness must not depend on where the
        // suite runs, and a fixed home path is a git repo on one machine and
        // a plain directory on a runner.
        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        run_git(repo.path(), &["config", "user.email", "t@example.com"]);
        run_git(repo.path(), &["config", "user.name", "Test"]);
        run_git(repo.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(repo.path().join("README.md"), "seed").expect("write seed");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "-q", "-m", "init"]);
        write_forge_toml(dir.path(), &repo.path().to_string_lossy());
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;
        let (tx, rx) = tokio::sync::oneshot::channel();

        handle_spawn_worker(
            &ws,
            key,
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );

        let reply = rx.await.expect("spawn replies").expect("spawn succeeds");
        assert!(
            uuid::Uuid::parse_str(&reply.session_id).is_ok(),
            "the worker is told the id it runs under, not a placeholder: {}",
            reply.session_id,
        );
        // The fixture project is a git repo, so this worker runs in its own
        // worktree and the reply names it: the path a lead uses to find the
        // worker's work has to be the directory the worker actually runs in.
        // Canonical like the CLI's own root: a fixture under `/var` (a
        // symlink to `/private/var` on macOS) would otherwise compare a
        // spelling claude never uses.
        let expected_worktree = std::fs::canonicalize(
            ws.list_projects()
                .into_iter()
                .find(|v| v.name == "forge")
                .expect("fixture project")
                .path,
        )
        .expect("canonical fixture project")
        .join(".claude/worktrees/tester");
        assert_eq!(
            reply.worktree.as_deref(),
            Some(expected_worktree.to_string_lossy().into_owned().as_str()),
            "the reply names the worktree the worker was spawned into",
        );
        let entry = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .and_then(|view| ws.list_live_workers(&view.key).into_iter().next())
            .expect("the worker is registered");
        assert_eq!(
            entry.slot,
            SessionSlot::worker("Default", "forge", "tester"),
            "the registry entry is keyed by the worker's slot",
        );
        assert!(ws.pool.lock().contains_key(&entry.slot), "and so is the pool");
        let stored = {
            let db = ws.db.lock();
            let db = db.as_ref().expect("db");
            crate::store::sessions::get(db, "Default", "forge", "tester")
                .expect("read")
                .and_then(|row| row.session_id)
        };
        assert_eq!(stored.as_deref(), Some(reply.session_id.as_str()), "and the store row");
    }

    /// Drive a spawn that fails at dispatch and return the durable row it
    /// left behind. The project is in the test overlay but not in
    /// `forge.toml`, and the config lookup inside the spawn is what misses.
    ///
    /// A row is seeded first, under the same `(org, project, label)` the
    /// spawn will write, so a missing row afterwards means one was removed
    /// rather than that none was ever written - without it, `is_none()`
    /// passes just as well against a `record_worker_row` that never ran.
    async fn failed_spawn_leftover_row(
        resume_existing: Option<&str>,
        from_boot_respawn: bool,
        seeded_is_git: Option<bool>,
    ) -> Option<crate::store::sessions::SessionRecord> {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_project("overlayonly", "/tmp/slack-worker-rollback");
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "overlayonly")
            .expect("seeded project present")
            .key;
        {
            let db = ws.db.lock();
            crate::store::sessions::put(
                db.as_ref().expect("db"),
                &crate::store::sessions::SessionRecord {
                    org: "TestOrg".to_owned(),
                    project: "overlayonly".to_owned(),
                    label: "tester".to_owned(),
                    session_id: Some("tester-id".to_owned()),
                    charter: None,
                    kick: None,
                    resume_kick: None,
                    interactive: None,
                    seat_state: None,
                    is_git_repo: seeded_is_git,
                    mcp_families: None,
                    cwd: None,
                },
            )
            .expect("seed the row the spawn will write");
        }
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            resume_existing,
            from_boot_respawn,
            tx,
        );

        assert!(matches!(rx.await, Ok(Err(_))), "the spawn reports the failure to its caller");
        assert!(
            ws.list_live_workers(&key).is_empty(),
            "and the placeholder entry is rolled back, not left live",
        );
        let db = ws.db.lock();
        crate::store::sessions::get(db.as_ref().expect("db"), "TestOrg", "overlayonly", "tester")
            .expect("read")
    }

    #[tokio::test]
    async fn a_failed_worker_spawn_rolls_the_live_entry_back() {
        let row = failed_spawn_leftover_row(None, false, None).await;
        assert!(
            row.is_none(),
            "the durable row goes with the rollback: left behind, the next boot re-spawns a \
             worker the caller was told had failed",
        );
    }

    /// A RESUME whose dispatch fails keeps its row, because that row is the
    /// only durable handle on the id being resumed - deleting it loses the
    /// worker rather than letting it retry. Nothing else reaches this arm
    /// with the flag set, so without this the guard's negative half is
    /// pinned by nothing.
    #[tokio::test]
    async fn a_failed_resume_spawn_keeps_the_row_holding_the_id() {
        let row = failed_spawn_leftover_row(Some("tester-id"), false, None).await;
        assert_eq!(
            row.and_then(|row| row.session_id).as_deref(),
            Some("tester-id"),
            "the rollback leaves the row that names the id being resumed",
        );
    }

    /// The same for a boot re-spawn, which carries no `resume_existing` when
    /// it comes up fresh under `--new` - so the resume flag alone does not
    /// separate it from a spawn a caller asked for, and the boot flag is
    /// what keeps its row.
    ///
    /// That path mints a new id and writes it over the row, so what the
    /// guard protects here is the row's survival rather than this id: the
    /// boot wave owns the worker, and deleting the row on a failure would
    /// drop it from every later restart.
    #[tokio::test]
    async fn a_failed_boot_respawn_keeps_its_row() {
        let row = failed_spawn_leftover_row(None, true, None).await;
        assert!(row.is_some(), "the boot re-spawn keeps the row a later restart re-spawns from");
    }

    /// A resume may deliver the restart note (or the row's `resume_kick`)
    /// as this connection's kick - the re-spawn decider above hands one
    /// only to a seat whose turn was cut off, and this test states one
    /// directly to prove it - and that text must not land in the row's
    /// `kick`: that field is the worker's original first turn, and it is
    /// what a later `--new` re-spawn opens the worker with. Written, the
    /// resume text becomes the worker's opening turn for the rest of its
    /// life.
    #[tokio::test]
    async fn a_resume_spawn_leaves_the_stored_kick_alone() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;
        // The row a real first spawn writes, non-git so the resume runs in
        // the project root rather than a worktree that is not there.
        ws.record_worker_row(
            &key,
            "tester",
            "tester-id",
            "charter",
            Some("original kick"),
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
            None,
        )
        .expect("seed the row the resume re-writes");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                // What `dispatch_worker_respawns` hands a resuming worker.
                kick: Some("This session was restarted by forge; continue.".to_owned()),
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            Some("tester-id"),
            true,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert!(reply.is_ok(), "the resume spawn succeeds: {reply:?}");

        assert_eq!(
            ws.list_live_workers(&key).into_iter().next().and_then(|entry| entry.kick).as_deref(),
            Some("This session was restarted by forge; continue."),
            "the resuming connection is kicked with the resume text",
        );
        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "tester")
            .expect("the row survives the resume");
        assert_eq!(
            stored.kick.as_deref(),
            Some("original kick"),
            "the row keeps the worker's original first turn; overwriting it makes the restart \
             note the worker's opening turn on every later --new re-spawn",
        );
    }

    fn spawn_scaffold() -> (Arc<Workspace>, crate::ProjectKey, tempfile::TempDir) {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;
        (ws, key, dir)
    }

    /// A spawn whose tree is inside a project `forge.toml` declares is
    /// refused (D3): that project is driven by its own agent, so the
    /// door is a message to it. The refusal comes BEFORE the label is
    /// reserved, the obstruction probed or the row written, so a refused
    /// spawn leaves nothing at all behind.
    ///
    /// The tree is fed in canonical, the way the facade resolves one,
    /// while the declared path is the alias a tempdir hands out - the
    /// shape `/tmp` and a symlinked parent both take - so the refusal has
    /// to resolve both sides rather than compare strings.
    #[tokio::test]
    async fn a_cwd_inside_a_declared_project_is_refused() {
        let (workspace, (_config, projects_dir)) = stub_with_project_cap(5);
        let project = seeded_project(&workspace);
        let inside = std::fs::canonicalize(projects_dir.path().join("notes"))
            .expect("canonical notes path")
            .join("crates");
        std::fs::create_dir_all(&inside).expect("create the nested dir");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "trespasser".to_owned(),
                charter: "c".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: Some(inside.to_string_lossy().into_owned()),
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );

        let error = rx.await.expect("reply").expect_err("a declared project's tree is refused");
        assert!(
            error.contains("'notes'") && error.contains("which forge.toml declares"),
            "the refusal names the project and the reason, not merely a path the fixture \
             happens to spell: {error}",
        );
        assert!(
            error.contains("message that project's agent"),
            "and points at the door - a different project's agent: {error}",
        );
        assert!(
            !error.contains("worktree"),
            "the word routes the spawn failure classifier to a worktree-creation failure, \
             which this is not: {error}",
        );
        assert!(
            workspace.list_live_workers(&project).is_empty(),
            "a refused spawn leaves no live worker",
        );
        assert!(
            workspace.worker_rows_for_project(&project).is_empty(),
            "and no durable row, so nothing comes back on the next boot",
        );
    }

    /// The despawn acts on the tree the ROW records, not the project's:
    /// a worker the spawn pointed at another repository keeps its
    /// worktree there, so the dirty probe and the removal have to read
    /// that tree. Composing them against the project path probes a
    /// directory the worker never ran in - today's code would read the
    /// project's tree, find it clean, and block on the dirty one under
    /// the worker's own root instead.
    #[tokio::test]
    async fn a_despawn_reads_the_tree_the_row_records() {
        let (workspace, project_key, project_wt, repo, _config) = git_despawn_fixture("traveller");
        let dir = tempfile::tempdir().expect("store dir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );

        // The worker's own tree: a sibling repo the spawn pointed it at,
        // with the worktree claude's `--worktree` would have forked.
        let sibling = tempfile::tempdir().expect("sibling repo");
        run_git(sibling.path(), &["init", "-q"]);
        run_git(sibling.path(), &["config", "user.email", "t@example.com"]);
        run_git(sibling.path(), &["config", "user.name", "Test"]);
        run_git(sibling.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(sibling.path().join("README.md"), "seed").expect("write seed");
        run_git(sibling.path(), &["add", "."]);
        run_git(sibling.path(), &["commit", "-q", "-m", "init"]);
        let sibling_root = std::fs::canonicalize(sibling.path()).expect("canonical sibling");
        let worker_wt = sibling_root.join(".claude").join("worktrees").join("traveller");
        std::fs::create_dir_all(worker_wt.parent().expect("wt parent")).expect("mkdir worktrees");
        run_git(
            &sibling_root,
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                "worktree-traveller",
                worker_wt.to_str().expect("utf8 path"),
            ],
        );

        // What the spawn writes: the row names the sibling tree, and the
        // live entry carries the same root.
        workspace
            .record_worker_row(
                &project_key,
                "traveller",
                "traveller-id",
                "charter",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree {
                    is_git_repo: true,
                    cwd: Some(sibling_root.to_string_lossy().into_owned()),
                },
                None,
            )
            .expect("record the row the despawn reads");
        workspace.remove_latest_worker(&project_key, "traveller");
        let mut entry = fake_git_worker_entry("traveller", "worker-1");
        entry.cwd = Some(sibling_root.clone());
        workspace.insert_live_worker(&project_key, entry);

        // Dirty in the WORKER's tree, clean in the project's: the probe
        // must block on the worker's.
        std::fs::write(worker_wt.join("dirty.txt"), "uncommitted").expect("write dirty file");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "traveller", false, tx);
        let blocked = rx.await.expect("despawn result");
        let crate::protocol::DespawnResult::Blocked { reason } = blocked else {
            panic!("a dirty worktree in the worker's own tree must block the despawn: {blocked:?}");
        };
        assert!(
            reason.contains("uncommitted or untracked changes"),
            "the reason is the worker's tree's own verdict, not the project's: {reason}",
        );

        // Clean: the despawn removes the worktree under the worker's own
        // tree, not one under the project.
        std::fs::remove_file(worker_wt.join("dirty.txt")).expect("clean the worktree");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "traveller", false, tx);
        let result = rx.await.expect("despawn result");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "a clean despawn lands: {result:?}",
        );
        assert!(!worker_wt.exists(), "the worker's own worktree is the one removed");
        let reaped = std::process::Command::new("git")
            .args(["branch", "--list", "worktree-traveller"])
            .current_dir(&sibling_root)
            .output()
            .expect("git branch");
        assert!(
            String::from_utf8_lossy(&reaped.stdout).trim().is_empty(),
            "the worker's own tree is where the branch reap aimed: {:?}",
            String::from_utf8_lossy(&reaped.stdout),
        );
        let decoy = std::process::Command::new("git")
            .args(["branch", "--list", "worktree-traveller"])
            .current_dir(repo.path())
            .output()
            .expect("git branch");
        assert!(
            String::from_utf8_lossy(&decoy.stdout).contains("worktree-traveller"),
            "and the project's same-named branch is untouched: {:?}",
            String::from_utf8_lossy(&decoy.stdout),
        );
        assert!(
            project_wt.exists(),
            "as is the worktree the project forked for its own worker of that name: the \
             despawn acted on the worker's tree, not the project's",
        );
    }

    /// A project that is itself a linked worktree: `--worktree <label>`
    /// creates the worktree under the MAIN checkout's `.claude/worktrees`,
    /// because the CLI composes it from the repository's canonical root
    /// (measured on 2.1.280), not from the project path. Recording it
    /// under the project path leaves the despawn's dirty probe reading a
    /// directory nothing created, so the probe answers "could not
    /// determine" and blocks, and a forced despawn leaves the real
    /// worktree and branch behind (#2460).
    #[tokio::test]
    async fn a_linked_worktree_project_records_its_worker_where_the_cli_creates_it() {
        let _binary = MOCK_BINARY.lock().await;
        let main = tempdir().expect("main repo tempdir");
        run_git(main.path(), &["init", "-q"]);
        run_git(main.path(), &["config", "user.email", "t@example.com"]);
        run_git(main.path(), &["config", "user.name", "Test"]);
        run_git(main.path(), &["config", "commit.gpgsign", "false"]);
        fs::write(main.path().join("README.md"), "seed").expect("write seed");
        run_git(main.path(), &["add", "."]);
        run_git(main.path(), &["commit", "-q", "-m", "init"]);
        let main_root = std::fs::canonicalize(main.path()).expect("canonical main");

        // The project path is a linked worktree of that repo, the shape the
        // dev stack builds.
        let holder = tempdir().expect("linked holder");
        let linked = holder.path().join("linked");
        run_git(
            &main_root,
            &["worktree", "add", "-q", "-b", "linked-project", linked.to_str().expect("utf8")],
        );

        let dir = tempdir().expect("config tempdir");
        write_forge_toml(dir.path(), &linked.to_string_lossy());
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        // **The worker's spawn is a warm too**, not only the lead's: the
        // fleet hears the seat before the worker's first browser call.
        let (calls, mut heard) = tokio::sync::mpsc::unbounded_channel();
        ws.install_browser_host(Arc::new(crate::browser::testing::StubHost { calls }));
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;

        // Where the CLI creates it: the fixture forks it there itself, so
        // the assertion below compares forge's composition against the
        // CLI's own root rather than against the code under test.
        let created = main_root.join(".claude").join("worktrees").join("labourer");
        fs::create_dir_all(created.parent().expect("wt parent")).expect("mkdir worktrees");
        run_git(
            &main_root,
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                "worktree-labourer",
                created.to_str().expect("utf8 path"),
            ],
        );

        forge_agent::set_test_sdk_binary(Some(
            concat!(env!("CARGO_MANIFEST_DIR"), "/../forge-sdk/tests/fixtures/mock_claude.sh")
                .to_owned(),
        ));
        let mut updates = ws.subscribe_mirror();
        let reply = spawn_reply(&ws, &key, "labourer", false)
            .await
            .expect("reply channel")
            .expect("the spawn is admitted");
        assert_eq!(
            reply.worktree.as_deref(),
            Some(created.to_string_lossy().as_ref()),
            "the recorded worktree must be the directory the CLI creates",
        );
        let slot = SessionSlot::worker("Default", "forge", "labourer");
        let mut warmed = None;
        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;
            };
            if what == "warm" {
                warmed = Some(args);
                break;
            }
        }
        assert_eq!(
            warmed,
            Some(serde_json::json!(slot)),
            "the worker's spawn path warms its own seat",
        );
        assert_eq!(
            ws.cwd_for_session(&slot),
            Some(created.to_string_lossy().into_owned()),
            "and every read-back composes the same directory",
        );
        // The despawn waits for the worker's child to die, so the session
        // has to be up before it is asked.
        tokio::time::timeout(spawn_wait(), async {
            while let Some(seat) = updates.recv().await {
                if matches!(&*seat.update, SessionUpdate::Connected { key, .. } if *key == slot) {
                    return;
                }
            }
            panic!("the update stream closed before the worker's session connected");
        })
        .await
        .expect("the worker's session reaches Connected");

        // Dirty in the worktree the CLI created: the probe must find it and
        // block for the worktree's own reason, not "could not determine".
        fs::write(created.join("dirty.txt"), "uncommitted").expect("write dirty file");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key, "labourer", false, tx);
        let blocked = rx.await.expect("despawn result");
        let crate::protocol::DespawnResult::Blocked { reason } = blocked else {
            panic!("the dirty probe must find the worktree the CLI created: {blocked:?}");
        };
        assert!(
            reason.contains("uncommitted or untracked changes"),
            "the verdict is the created worktree's own: {reason}",
        );

        fs::remove_file(created.join("dirty.txt")).expect("clean the worktree");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key, "labourer", false, tx);
        let result = rx.await.expect("despawn result");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "a clean despawn lands: {result:?}",
        );
        assert!(!created.exists(), "the worktree the CLI created is the one removed");
        let branches = std::process::Command::new("git")
            .args(["branch", "--list", "worktree-labourer"])
            .current_dir(&main_root)
            .output()
            .expect("git branch");
        assert!(
            String::from_utf8_lossy(&branches.stdout).trim().is_empty(),
            "and the branch behind it is reaped: {:?}",
            String::from_utf8_lossy(&branches.stdout),
        );
        forge_agent::set_test_sdk_binary(None);
    }

    /// A main repo with one linked worktree per name, each declared as a
    /// project of that name. Every one of them composes its workers'
    /// worktrees under the main checkout (#2460), so they share one
    /// `<main>/.claude/worktrees/<label>` namespace. No project declares a
    /// model, so a spawn that gets past the worktree checks dies at the
    /// account walk instead of starting a child.
    fn linked_projects_fixture(
        names: &[&str],
    ) -> (Arc<Workspace>, std::path::PathBuf, Vec<tempfile::TempDir>) {
        let holder = tempdir().expect("holder");
        let main = holder.path().join("main");
        fs::create_dir_all(&main).expect("main dir");
        run_git(&main, &["init", "-q"]);
        run_git(&main, &["config", "user.email", "t@example.com"]);
        run_git(&main, &["config", "user.name", "Test"]);
        run_git(&main, &["config", "commit.gpgsign", "false"]);
        fs::write(main.join("README.md"), "seed").expect("write seed");
        run_git(&main, &["add", "."]);
        run_git(&main, &["commit", "-q", "-m", "init"]);
        let main = std::fs::canonicalize(&main).expect("canonical main");

        let mut projects = String::new();
        for name in names {
            let linked = holder.path().join(name);
            run_git(&main, &["worktree", "add", "-q", "-b", name, linked.to_str().expect("utf8")]);
            let _ = writeln!(
                projects,
                "[[orgs.projects]]\nname = \"{name}\"\npath = \"{}\"\n",
                linked.display()
            );
        }
        let config = tempdir().expect("config tempdir");
        fs::write(
            forge_toml_path(config.path()),
            format!(
                "[[orgs]]\nname = \"Default\"\naccounts = [\"Stargate\"]\n\n{projects}\
                 [[accounts]]\ndisplay_name = \"Stargate\"\ntoken = \"t\"\n\
                 models = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n"
            ),
        )
        .expect("write forge.toml");
        let workspace =
            Arc::new(Workspace::new_for_test(config.path().to_owned()).expect("workspace"));
        (workspace, main, vec![holder, config])
    }

    /// The base is repository-global, so two projects of one repo compose
    /// the same worktree path for one label. The one-live-worker guard is
    /// per project, so without this a second spawn would run in the first
    /// worker's tree - and its despawn would delete it. A label that names
    /// a project parked under `.claude/worktrees` is the same collision
    /// against that project's own checkout.
    #[tokio::test]
    async fn a_spawn_refuses_a_worktree_another_project_holds() {
        let (ws, main, _keep) = linked_projects_fixture(&["proj-a", "proj-b"]);
        let key_of = |name: &str| {
            ws.list_projects().into_iter().find(|v| v.name == name).expect("declared project").key
        };
        ws.insert_live_worker(&key_of("proj-a"), fake_git_worker_entry("shared", "worker-1"));

        let err = spawn_reply(&ws, &key_of("proj-b"), "shared", false)
            .await
            .expect("reply channel")
            .expect_err("the shared worktree is refused");
        assert!(err.contains("worker 'shared'"), "the refusal names the holder: {err}");
        assert!(err.contains("proj-a"), "and the project it belongs to: {err}");
        assert!(
            ws.list_live_workers(&key_of("proj-b")).is_empty(),
            "the refused spawn mints nothing",
        );

        // A crashed worker's row still claims its path until the row is
        // closed: refusing is the safe direction.
        let mut failed = fake_git_worker_entry("ghost", "worker-2");
        failed.status = forge_primitives::WorkerLiveness::Failed;
        ws.insert_live_worker(&key_of("proj-b"), failed);
        let err = spawn_reply(&ws, &key_of("proj-a"), "ghost", false)
            .await
            .expect("reply channel")
            .expect_err("the crashed worker's row still claims its tree");
        assert!(
            err.contains("worker 'ghost'") && err.contains("proj-b"),
            "the refusal names the crashed worker and its project: {err}",
        );

        // A seat still spawning holds its tree too: every state counts,
        // not only Running.
        let mut spawning = fake_git_worker_entry("launching", "worker-3");
        spawning.status = forge_primitives::WorkerLiveness::Spawning;
        ws.insert_live_worker(&key_of("proj-b"), spawning);
        let err = spawn_reply(&ws, &key_of("proj-a"), "launching", false)
            .await
            .expect("reply channel")
            .expect_err("a spawning worker's tree is claimed");
        assert!(
            err.contains("worker 'launching'") && err.contains("proj-b"),
            "the refusal names the spawning worker and its project: {err}",
        );

        // A durable row claims the tree even with no in-memory entry:
        // after a restart, before that project's lead connects.
        ws.record_worker_row(
            &key_of("proj-b"),
            "parked",
            "550e8400-e29b-41d4-a716-446655440083",
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
            None,
        )
        .expect("record proj-b's parked row");
        let err = spawn_reply(&ws, &key_of("proj-a"), "parked", false)
            .await
            .expect("reply channel")
            .expect_err("the durable row claims the composed path");
        assert!(
            err.contains("worker 'parked'") && err.contains("proj-b"),
            "the durable row names its project: {err}",
        );

        // An in-flight claim in another project refuses the spawn even
        // with no entry or row yet: the check and the insert are one step.
        let owner = ws.project_root_for_key(&key_of("proj-a")).expect("proj-a root");
        let claimed = crate::mcp::workers::types::worker_tag_dir(&owner, "held", true);
        let claim = ws
            .claim_worktree(
                &claimed,
                &key_of("proj-a"),
                "held",
                crate::workspace::WorktreeOp::Spawn,
            )
            .expect("claim");
        let err = spawn_reply(&ws, &key_of("proj-b"), "held", false)
            .await
            .expect("reply channel")
            .expect_err("another project's claim refuses the spawn");
        assert!(
            err.contains("in use by the worker 'held'") && err.contains("proj-a"),
            "the refusal names the claim holder: {err}",
        );
        drop(claim);

        // A row from before `is_git_repo` existed still claims its
        // base+label path: refusing on that name is the safe direction.
        let store = tempdir().expect("store dir");
        let db = crate::store::Db::open(&store.path().join("db.redb")).expect("open db");
        crate::store::sessions::put(
            &db,
            &crate::store::sessions::SessionRecord {
                org: "Default".to_owned(),
                project: "proj-b".to_owned(),
                label: "old".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("write a row with no recorded gitness");
        ws.install_db_for_test(db);
        let err = spawn_reply(&ws, &key_of("proj-a"), "old", false)
            .await
            .expect("reply channel")
            .expect_err("a gitness-less row still claims the composed path");
        assert!(
            err.contains("worker 'old'") && err.contains("proj-b"),
            "the old row names its project: {err}",
        );

        // A project declared at the path a worker label would compose is
        // its own checkout, not a worktree anyone may reuse or remove.
        let checkout = main.join(".claude").join("worktrees").join("dev");
        fs::create_dir_all(checkout.parent().expect("worktrees root")).expect("mkdir worktrees");
        run_git(
            &main,
            &["worktree", "add", "-q", "-b", "dev-project", checkout.to_str().expect("utf8")],
        );
        ws.seed_test_project("proj-dev", &checkout.to_string_lossy());
        let err = spawn_reply(&ws, &key_of("proj-b"), "dev", false)
            .await
            .expect("reply channel")
            .expect_err("a project's own checkout is refused");
        assert!(err.contains("checkout of project 'proj-dev'"), "the refusal names it: {err}");
    }

    /// The collision check compares real paths: the shared tree reached
    /// through a symlinked spelling is the same tree a live worker holds.
    #[test]
    fn the_collision_check_reads_a_symlinked_spelling_as_the_same_tree() {
        let (ws, main, _keep) = linked_projects_fixture(&["proj-a", "proj-b"]);
        let key_of = |name: &str| {
            ws.list_projects().into_iter().find(|v| v.name == name).expect("declared project").key
        };
        let shared = main.join(".claude").join("worktrees").join("shared");
        fs::create_dir_all(shared.parent().expect("worktrees root")).expect("mkdir worktrees");
        run_git(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-shared", shared.to_str().expect("utf8")],
        );
        ws.insert_live_worker(&key_of("proj-a"), fake_git_worker_entry("shared", "worker-1"));
        let holder = tempdir().expect("alias holder");
        let alias = holder.path().join("shared-alias");
        std::os::unix::fs::symlink(&shared, &alias).expect("symlink");

        let collision = ws.worktree_collision(
            &alias,
            &key_of("proj-b"),
            "shared",
            crate::workspace::WorktreeOp::Spawn,
        );

        assert!(
            collision.as_deref().is_some_and(|reason| reason.contains("worker 'shared'")),
            "the canonical comparison finds the holder through the alias: {collision:?}",
        );
    }

    /// The despawn end of the same collision: removing the shared tree
    /// would delete the other project's live worker's cwd, so it refuses
    /// even when forced and leaves the tree standing.
    #[tokio::test]
    async fn a_despawn_refuses_a_worktree_another_project_holds() {
        let (ws, main, _keep) = linked_projects_fixture(&["proj-a", "proj-b"]);
        let key_of = |name: &str| {
            ws.list_projects().into_iter().find(|v| v.name == name).expect("declared project").key
        };
        let shared = main.join(".claude").join("worktrees").join("shared");
        fs::create_dir_all(shared.parent().expect("worktrees root")).expect("mkdir worktrees");
        run_git(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-shared", shared.to_str().expect("utf8")],
        );
        ws.insert_live_worker(&key_of("proj-a"), fake_git_worker_entry("shared", "a-worker"));
        ws.insert_live_worker(&key_of("proj-b"), fake_git_worker_entry("shared", "b-worker"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key_of("proj-a"), "shared", true, tx);
        let result = rx.await.expect("despawn result");
        let crate::protocol::DespawnResult::Failed { reason } = result else {
            panic!("a shared worktree must refuse the despawn even when forced: {result:?}");
        };
        assert!(reason.contains("worker 'shared'"), "the reason names the holder: {reason}");
        assert!(reason.contains("proj-b"), "and its project: {reason}");
        assert!(shared.exists(), "the shared tree was not removed");
        assert_eq!(ws.list_live_workers(&key_of("proj-a")).len(), 1, "and the worker stays live");
    }

    /// A despawn consults the same repository-wide claims: while another
    /// project's spawn or cleanup holds the path, it refuses.
    #[tokio::test]
    async fn a_despawn_refuses_a_worktree_another_project_claims() {
        let (ws, main, _keep) = linked_projects_fixture(&["proj-a", "proj-b"]);
        let key_of = |name: &str| {
            ws.list_projects().into_iter().find(|v| v.name == name).expect("declared project").key
        };
        let shared = main.join(".claude").join("worktrees").join("shared");
        fs::create_dir_all(shared.parent().expect("worktrees root")).expect("mkdir worktrees");
        run_git(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-shared", shared.to_str().expect("utf8")],
        );
        ws.insert_live_worker(&key_of("proj-b"), fake_git_worker_entry("shared", "b-worker"));
        let claim = ws
            .claim_worktree(
                &shared,
                &key_of("proj-a"),
                "shared",
                crate::workspace::WorktreeOp::Spawn,
            )
            .expect("proj-a holds the path");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key_of("proj-b"), "shared", true, tx);
        let result = rx.await.expect("despawn result");
        let crate::protocol::DespawnResult::Failed { reason } = result else {
            panic!("a claimed worktree refuses the despawn: {result:?}");
        };
        assert!(
            reason.contains("in use by the worker 'shared'") && reason.contains("proj-a"),
            "the reason names the claim holder: {reason}",
        );
        assert!(shared.exists(), "the claimed tree was not removed");
        drop(claim);
    }

    /// A linked project's worktree sits under the MAIN checkout, and the
    /// despawn-side conversion is what lets the leftover fallback aim
    /// there: composing against the project path refuses a directory that
    /// is not under its `.claude/worktrees` and leaves it behind.
    #[tokio::test]
    async fn despawn_removes_a_deregistered_leftover_in_a_linked_project() {
        let (ws, main, _keep) = linked_projects_fixture(&["proj-a"]);
        let key = ws.list_projects().into_iter().next().expect("declared project").key;
        let leftover = main.join(".claude").join("worktrees").join("leftover");
        fs::create_dir_all(leftover.parent().expect("worktrees root")).expect("mkdir worktrees");
        run_git(
            &main,
            &["worktree", "add", "-q", "-b", "worktree-leftover", leftover.to_str().expect("utf8")],
        );
        // The state a failed delete leaves: deregistered, directory on
        // disk.
        fs::remove_dir_all(main.join(".git").join("worktrees").join("leftover"))
            .expect("deregister the worktree");
        let refused = std::process::Command::new("git")
            .args(["worktree", "remove", "--force", leftover.to_str().expect("utf8 path")])
            .current_dir(leftover.parent().expect("wt parent"))
            .output()
            .expect("spawn git");
        assert!(
            !refused.status.success(),
            "fixture precondition: git refuses the deregistered leftover outright"
        );
        ws.insert_live_worker(&key, fake_git_worker_entry("leftover", "worker-1"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key, "leftover", true, tx);
        let result = rx.await.expect("despawn result");
        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "the leftover is removed under the main checkout: {result:?}"
        );
        assert!(!leftover.exists(), "the leftover directory is gone");
    }

    /// The one handle on the process-wide mock-binary slot below: the case
    /// that drives it holds this for its span, so no sibling case can spawn
    /// against a mock it did not ask for (or against the clearing of one).
    static MOCK_BINARY: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

    /// How long a case waits for a spawn's first event: the SDK's own
    /// handshake budget plus a settle margin - a wait shorter than the
    /// budget under it fails a machine that is merely slow.
    fn spawn_wait() -> std::time::Duration {
        forge_sdk::INIT_HANDSHAKE_TIMEOUT + std::time::Duration::from_secs(5)
    }

    /// The real mock wrapped so the child's death throes write into the
    /// worktree: after its stdin closes (the despawn's first teardown act)
    /// it waits `throes`, recreates the path and writes, then exits. The
    /// path is baked in because nothing tells the child where its worktree
    /// is - the real CLI derives it from `--worktree`, which the mock
    /// ignores. The write also lands a marker OUTSIDE the worktree, which
    /// is what lets the case prove the throes really ran: inside, the
    /// removal erases the evidence along with the write.
    fn death_throes_mock(
        dir: &std::path::Path,
        worktree: &std::path::Path,
        throes: std::time::Duration,
    ) -> String {
        use std::os::unix::fs::PermissionsExt as _;
        let real =
            concat!(env!("CARGO_MANIFEST_DIR"), "/../forge-sdk/tests/fixtures/mock_claude.sh");
        let wrapper = dir.join("death-throes-mock");
        fs::write(
            &wrapper,
            format!(
                "#!/bin/bash\nif [[ ${{1:-}} == \"--version\" ]]; then exec {real} \"$@\"; fi\n\
                 {real} \"$@\"\n\
                 /bin/sleep {}\n\
                 mkdir -p {wt} && printf 'wrote while dying\\n' > {wt}/late-write.txt\n\
                 printf 'throes ran\\n' > {marker}\n",
                throes.as_secs_f64(),
                wt = worktree.display(),
                marker = death_throes_marker(dir).display(),
            ),
        )
        .expect("write the death-throes mock");
        std::fs::set_permissions(&wrapper, std::fs::Permissions::from_mode(0o755)).expect("+x");
        wrapper.to_string_lossy().into_owned()
    }

    /// Where the death-throes mock records that its dying write ran.
    fn death_throes_marker(dir: &std::path::Path) -> std::path::PathBuf {
        dir.join("death-throes-ran")
    }

    /// **The despawn must take the worker's session down before the
    /// worktree.** The incident (#1767): the worktree came out at 15:47:08
    /// while the session's child was still alive for five seconds more,
    /// and in that gap the dying vite wrote its cache back into the path
    /// the removal had already taken. The despawn used to overlap them -
    /// teardown released the session and returned, the disconnect reaped
    /// the child asynchronously, and `DespawnCleanup` removed the worktree
    /// immediately.
    ///
    /// This drives exactly that shape: a real worker session over a mock
    /// child that, once its stdin closes, waits and then writes into the
    /// worktree before it exits. The despawn must not come back - and so
    /// must not remove anything - before that child is dead.
    #[tokio::test]
    async fn a_despawn_holds_the_removal_until_the_worker_child_has_died() {
        let _binary = MOCK_BINARY.lock().await;
        let dir = tempdir().expect("config tempdir");
        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        run_git(repo.path(), &["config", "user.email", "t@example.com"]);
        run_git(repo.path(), &["config", "user.name", "Test"]);
        run_git(repo.path(), &["config", "commit.gpgsign", "false"]);
        fs::write(repo.path().join("README.md"), "seed").expect("write seed");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "-q", "-m", "init"]);
        let repo_root = std::fs::canonicalize(repo.path()).expect("canonical repo");
        write_forge_toml(dir.path(), &repo_root.to_string_lossy());
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;

        // The worktree `--worktree dying` would fork (the mock ignores the
        // flag, so the fixture forks it).
        let wt = repo_root.join(".claude").join("worktrees").join("dying");
        std::fs::create_dir_all(wt.parent().expect("wt parent")).expect("mkdir worktrees");
        run_git(
            &repo_root,
            &["worktree", "add", "-q", "-b", "worktree-dying", wt.to_str().expect("utf8")],
        );
        // The dying child's write is a build artifact git ignores - the
        // incident's vite cache - so the removal it races is the ordinary
        // one, not the dirty-worktree refusal.
        let excludes = dir.path().join("excludes");
        fs::write(&excludes, "late-write.txt\n").expect("write excludes");
        run_git(&repo_root, &["config", "core.excludesFile", excludes.to_str().expect("utf8")]);

        let throes = std::time::Duration::from_secs(2);
        forge_agent::set_test_sdk_binary(Some(death_throes_mock(dir.path(), &wt, throes)));

        let mut updates = ws.subscribe_mirror();
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "dying".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        rx.await.expect("spawn replies").expect("spawn succeeds");
        // The despawn has an ordering to enforce only once the child is up
        // and holding its stdin; Connected is that moment. A stream that
        // ends first is a failure too - the wait must not read as settled
        // on a closed channel.
        let slot = SessionSlot::worker("Default", "forge", "dying");
        tokio::time::timeout(spawn_wait(), async {
            while let Some(seat) = updates.recv().await {
                if matches!(&*seat.update, SessionUpdate::Connected { key, .. } if *key == slot) {
                    return;
                }
            }
            panic!("the update stream closed before the worker's session connected");
        })
        .await
        .expect("the worker's session reaches Connected");

        let started = std::time::Instant::now();
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key, "dying", false, tx);
        let result = rx.await.expect("despawn result");
        let elapsed = started.elapsed();

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "the despawn lands clean: {result:?}",
        );
        assert!(
            elapsed >= throes,
            "the despawn must not report the worker gone before its child is dead: it came back \
             after {elapsed:?}, while the child was still alive for {throes:?} of its death",
        );
        assert!(
            death_throes_marker(dir.path()).exists(),
            "the child's dying write really ran before the despawn came back",
        );
        assert!(
            !wt.exists(),
            "and the removal must come after the child's last write: a write landing in the \
             already-removed path is exactly the leftover this ordering exists to prevent",
        );
        forge_agent::set_test_sdk_binary(None);
    }

    // ---- auto-heal over the mock child -------------------------------------

    /// `forge.toml` with the `[sessions]` backoff the heal tests run on:
    /// real seconds would make a three-restart case wait out 5+30+120 s.
    fn write_heal_toml(dir: &std::path::Path, project_path: &str) {
        fs::write(
            forge_toml_path(dir),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

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

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

[sessions]
heal_backoff = ["150ms", "200ms", "300ms"]
heal_stable = "30s"
"#
            ),
        )
        .expect("write forge.toml");
    }

    /// The real mock wrapped so runs `die_from..=die_through` die of their
    /// own accord shortly after the handshake, which is what forge sees as
    /// a subprocess that closed mid-run. Every later run stays up. The run
    /// count is left on disk, which is how a case proves how many children
    /// ever started.
    fn heal_mock(dir: &std::path::Path, die_from: u32, die_through: u32) -> String {
        use std::os::unix::fs::PermissionsExt as _;
        let real =
            concat!(env!("CARGO_MANIFEST_DIR"), "/../forge-sdk/tests/fixtures/mock_claude.sh");
        let wrapper = dir.join("heal-mock");
        fs::write(
            &wrapper,
            format!(
                "#!/bin/bash\n\
                 if [[ ${{1:-}} == \"--version\" ]]; then exec {real} \"$@\"; fi\n\
                 runs={runs}\n\
                 n=$(( $(cat \"$runs\" 2>/dev/null || echo 0) + 1 ))\n\
                 echo \"$n\" > \"$runs\"\n\
                 {real} \"$@\" <&0 & child=$!\n\
                 if [[ \"$n\" -ge {die_from} && \"$n\" -le {die_through} ]]; then\n\
                   ( /bin/sleep 0.6; kill -9 \"$child\" 2>/dev/null ) &\n\
                 fi\n\
                 wait \"$child\"\n",
                real = real,
                runs = dir.join("heal-mock-runs").display(),
                die_from = die_from,
                die_through = die_through,
            ),
        )
        .expect("write the heal mock");
        std::fs::set_permissions(&wrapper, std::fs::Permissions::from_mode(0o755)).expect("+x");
        wrapper.to_string_lossy().into_owned()
    }

    /// How many mock children have started.
    fn mock_runs(dir: &std::path::Path) -> u32 {
        fs::read_to_string(dir.join("heal-mock-runs"))
            .ok()
            .and_then(|raw| raw.trim().parse().ok())
            .unwrap_or(0)
    }

    /// Every update up to and including the one that satisfies `done`, before
    /// `spawn_wait` runs out. The frames are kept rather than matched one by
    /// one, because a case that waits for two things cannot know which
    /// arrives first.
    async fn await_updates(
        updates: &mut tokio::sync::mpsc::UnboundedReceiver<crate::update_fanout::SeatUpdate>,
        what: &str,
        mut done: impl FnMut(&[std::sync::Arc<SessionUpdate>]) -> bool,
    ) -> Vec<std::sync::Arc<SessionUpdate>> {
        let mut seen = Vec::new();
        tokio::time::timeout(spawn_wait(), async {
            while let Some(seat) = updates.recv().await {
                seen.push(std::sync::Arc::clone(&seat.update));
                if done(&seen) {
                    return;
                }
            }
            panic!("the update stream closed before {what}");
        })
        .await
        .unwrap_or_else(|_| {
            let shapes: Vec<String> = seen.iter().map(|update| shape(update)).collect();
            panic!("timed out waiting for {what}; saw {shapes:?}")
        });
        seen
    }

    /// An update's variant and, where it has one, the seat it names: enough
    /// to read a timeout without the payloads.
    fn shape(update: &SessionUpdate) -> String {
        let debug = format!("{update:?}");
        let head = debug.split_whitespace().next().unwrap_or("?");
        let at = update.slot().map_or_else(String::new, |slot| format!("@{}", slot.display()));
        match update {
            SessionUpdate::ChatAppended { msg, .. } => {
                let text = user_text(msg);
                format!("{head}{at}({}..)", text.chars().take(40).collect::<String>())
            }
            _ => format!("{head}{at}"),
        }
    }

    /// The next update `wants` accepts, before `spawn_wait` runs out.
    async fn await_update(
        updates: &mut tokio::sync::mpsc::UnboundedReceiver<crate::update_fanout::SeatUpdate>,
        what: &str,
        mut wants: impl FnMut(&SessionUpdate) -> bool,
    ) -> std::sync::Arc<SessionUpdate> {
        await_updates(updates, what, |seen| seen.iter().any(|update| wants(update)))
            .await
            .pop()
            .expect("a matched update")
    }

    /// **The budget is the bound**: a child that keeps dying gets three
    /// restarts and then one escalation, and no fourth child is ever
    /// started. Catches a supervisor that spins past its cap.
    #[tokio::test]
    async fn a_crash_loop_stops_after_three_restarts_and_escalates() {
        let _binary = MOCK_BINARY.lock().await;
        let (dir, _project, ws) = heal_fixture();
        // Run 1 is the lead; runs 2..=5 are the worker's four deaths.
        forge_agent::set_test_sdk_binary(Some(heal_mock(dir.path(), 2, 5)));
        let mut updates = ws.subscribe_mirror();
        let lead = start_lead(&ws, &mut updates).await;
        let slot = SessionSlot::worker("Default", "forge", "probe-heal");
        spawn_mock_worker(&ws, &lead, "probe-heal").await;

        let seen = await_updates(&mut updates, "the escalation", |seen| {
            seen.iter().any(|update| {
                matches!(
                    update.as_ref(),
                    SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. }
                        if *key == lead && wrapped.body.contains("Left Failed after 3 restarts")
                )
            })
        })
        .await;
        assert_eq!(mock_runs(dir.path()), 5, "the lead, the first worker and its three resumes");
        assert_eq!(connects(&seen, &slot), 4, "the first connect and three restarts");

        // Nothing starts a fourth child once the budget is spent.
        tokio::time::sleep(std::time::Duration::from_millis(1200)).await;
        assert_eq!(mock_runs(dir.path()), 5, "no fourth restart after the escalation");
        assert!(ws.heal_progress(&slot).is_none(), "the seat is left failed, not restarting");

        // Every death was reported, the escalation last.
        let notices: Vec<String> = seen
            .iter()
            .filter_map(|update| match update.as_ref() {
                SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. } if *key == lead => {
                    Some(wrapped.body.clone())
                }
                _ => None,
            })
            .collect();
        assert_eq!(notices.len(), 4, "one notice per death: {notices:?}");
        assert!(
            notices.last().is_some_and(|body| body.contains("Left Failed after 3 restarts")),
            "and the last is the escalation: {notices:?}",
        );
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A despawn never heals.** The stop owns the seat, so the death its
    /// own teardown causes must not bring the worker back.
    #[tokio::test]
    async fn a_despawned_worker_does_not_heal() {
        let _binary = MOCK_BINARY.lock().await;
        let (dir, _project, ws) = heal_fixture();
        forge_agent::set_test_sdk_binary(Some(heal_mock(dir.path(), 2, 2)));
        let mut updates = ws.subscribe_mirror();
        let lead = start_lead(&ws, &mut updates).await;
        let key = forge_key(&ws);
        let slot = SessionSlot::worker("Default", "forge", "probe-heal");
        spawn_mock_worker(&ws, &lead, "probe-heal").await;
        await_update(
            &mut updates,
            "the worker's first connect",
            |update| matches!(update, SessionUpdate::Connected { key, .. } if *key == slot),
        )
        .await;

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&ws, &key, "probe-heal", false, tx);
        rx.await.expect("despawn result");

        // The child dies 0.6 s in; a heal that wrongly fired would start a
        // new one 150 ms after that.
        tokio::time::sleep(std::time::Duration::from_millis(1500)).await;
        assert_eq!(mock_runs(dir.path()), 2, "nothing was started for the stop's own death");
        assert!(ws.heal_progress(&slot).is_none(), "the seat is not restarting");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A seat with no durable row is not forge's to bring back**: a row
    /// deleted under a live seat leaves a death with nothing a resume could
    /// return, and it stays dead until a person starts it.
    #[tokio::test]
    async fn an_ad_hoc_seats_death_does_not_heal() {
        let _binary = MOCK_BINARY.lock().await;
        let (dir, _project, ws) = heal_fixture();
        forge_agent::set_test_sdk_binary(Some(heal_mock(dir.path(), 2, 2)));
        let mut updates = ws.subscribe_mirror();
        let lead = start_lead(&ws, &mut updates).await;
        let key = forge_key(&ws);
        let slot = SessionSlot::worker("Default", "forge", "probe-heal");
        spawn_mock_worker(&ws, &lead, "probe-heal").await;
        await_update(
            &mut updates,
            "the worker's first connect",
            |update| matches!(update, SessionUpdate::Connected { key, .. } if *key == slot),
        )
        .await;

        assert!(
            ws.delete_worker_row(&key, "probe-heal").expect("the row is deleted"),
            "precondition: the row existed",
        );

        tokio::time::sleep(std::time::Duration::from_millis(1500)).await;
        assert_eq!(mock_runs(dir.path()), 2, "no child was started for the ad-hoc death");
        assert!(ws.heal_progress(&slot).is_none(), "the seat is not restarting");
        forge_agent::set_test_sdk_binary(None);
    }

    /// Wait until `done` holds, polling every 20 ms, up to `spawn_wait`.
    async fn wait_until(what: &str, mut done: impl FnMut() -> bool) {
        tokio::time::timeout(spawn_wait(), async {
            while !done() {
                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
            }
        })
        .await
        .unwrap_or_else(|_| panic!("timed out waiting for {what}"));
    }

    /// **A lead whose project tree is gone fails every attempt with the
    /// tree's own reason and escalates at the cap**, rather than reporting a
    /// generic failure or resting as if it had come back.
    #[tokio::test]
    async fn a_lead_whose_project_tree_is_gone_escalates_at_the_cap() {
        let _binary = MOCK_BINARY.lock().await;
        let (dir, project, ws) = heal_fixture();
        // Run 1 is the lead, which then dies; its resumes never start.
        forge_agent::set_test_sdk_binary(Some(heal_mock(dir.path(), 1, 1)));
        let mut updates = ws.subscribe_mirror();
        let lead = start_lead(&ws, &mut updates).await;
        let root = std::fs::canonicalize(project.path()).expect("canonical tree");
        fs::remove_dir_all(&root).expect("remove the tree");

        // The lead's child dies of its own accord, the first attempt is
        // scheduled, and then every attempt is refused by the gone tree
        // until the budget runs out.
        wait_until("the first attempt", || ws.heal_progress(&lead).is_some()).await;
        wait_until("the budget to run out", || ws.heal_progress(&lead).is_none()).await;

        let reason = ws.spawn_failure(&lead).expect("the last attempt's reason stays on the row");
        assert!(reason.contains("spawn failed"), "the refusal's own words: {reason}");
        assert!(
            reason.contains(root.to_string_lossy().as_ref()),
            "the tree the attempt could not enter: {reason}",
        );
        // The first spawn's Spawning frame went with the connect; every
        // frame left on the stream is one heal attempt taking the tree on.
        let mut attempts = 0;
        while let Ok(seat) = updates.try_recv() {
            if matches!(&*seat.update, SessionUpdate::Spawning { key, .. } if *key == lead) {
                attempts += 1;
            }
        }
        assert_eq!(attempts, 3, "the cap's three attempts were each made, then it escalated");
        assert_eq!(mock_runs(dir.path()), 1, "no resume ever started a child");
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A worker whose worktree is gone comes back anyway**: the heal
    /// resumes through the boot re-spawn path, which re-creates the tree the
    /// worker needs rather than refusing to start. This is the
    /// inference-shop death's shape.
    #[tokio::test]
    async fn a_dead_workers_missing_worktree_is_recreated_by_the_heal() {
        let _binary = MOCK_BINARY.lock().await;
        let dir = tempdir().expect("config tempdir");
        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        run_git(repo.path(), &["config", "user.email", "t@example.com"]);
        run_git(repo.path(), &["config", "user.name", "Test"]);
        run_git(repo.path(), &["config", "commit.gpgsign", "false"]);
        fs::write(repo.path().join("README.md"), "seed").expect("write seed");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "-q", "-m", "init"]);
        let repo_root = std::fs::canonicalize(repo.path()).expect("canonical repo");
        // The worktree `--worktree probe-heal` names: the mock ignores the
        // flag, so the fixture forks it the way the CLI would.
        let worktree = repo_root.join(".claude/worktrees/probe-heal");
        std::fs::create_dir_all(worktree.parent().expect("worktrees dir")).expect("mkdir");
        run_git(
            &repo_root,
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                "worktree-probe-heal",
                worktree.to_str().expect("utf8"),
            ],
        );
        write_heal_toml(dir.path(), &repo_root.to_string_lossy());
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        ws.start_kick_dispatcher();
        forge_agent::set_test_sdk_binary(Some(heal_mock(dir.path(), 2, 2)));

        let mut updates = ws.subscribe_mirror();
        let lead = start_lead(&ws, &mut updates).await;
        let slot = SessionSlot::worker("Default", "forge", "probe-heal");
        spawn_mock_worker(&ws, &lead, "probe-heal").await;
        await_update(
            &mut updates,
            "the worker's first connect",
            |update| matches!(update, SessionUpdate::Connected { key, .. } if *key == slot),
        )
        .await;
        // Mid-work when the tree goes, so the heal's resume carries the
        // restart note this test waits on.
        ws.record_seat_state(&slot, crate::store::sessions::SeatState::InTurn);

        // The tree the worker needs disappears while it is up; the resume
        // is what must put it back. The registration goes with it, so the
        // re-create is a fresh `git worktree add` rather than a repair.
        fs::remove_dir_all(&worktree).expect("remove the worktree");
        run_git(&repo_root, &["worktree", "prune"]);
        assert!(!worktree.is_dir(), "precondition: the worktree is gone");

        // The scan starts after the first connect, so the restart is one
        // more connect on the same seat.
        let seen = await_updates(&mut updates, "the restart and its note", |seen| {
            connects(seen, &slot) >= 1 && heard(seen, &slot, "This session was restarted by forge")
        })
        .await;
        assert_eq!(connects(&seen, &slot), 1, "the seat came back despite the missing tree");
        assert!(worktree.is_dir(), "the resume re-created the worktree the worker needs");
        forge_agent::set_test_sdk_binary(None);
    }

    fn user_text(msg: &forge_primitives::Message) -> String {
        let forge_primitives::Message::User { message, .. } = msg else {
            return String::new();
        };
        message
            .content
            .iter()
            .filter_map(|block| match block {
                forge_primitives::ContentBlock::Text { text, .. } => Some(text.as_str()),
                _ => None,
            })
            .collect::<Vec<_>>()
            .join("\n")
    }

    /// Whether `seen` holds a chat row on `slot` whose user text contains
    /// `needle`.
    fn heard(seen: &[std::sync::Arc<SessionUpdate>], slot: &SessionSlot, needle: &str) -> bool {
        seen.iter().any(|update| match update.as_ref() {
            SessionUpdate::ChatAppended { key, msg, .. } => {
                key == slot && user_text(msg).contains(needle)
            }
            _ => false,
        })
    }

    /// How many connects on `slot` `seen` holds.
    fn connects(seen: &[std::sync::Arc<SessionUpdate>], slot: &SessionSlot) -> usize {
        seen.iter()
            .filter(|update| matches!(update.as_ref(), SessionUpdate::Connected { key, .. } if key == slot))
            .count()
    }

    /// A project the mock can be spawned into, with the heal `[sessions]`
    /// table. The project is not a git repo, so its workers run in the
    /// project root and forge's first-connect worktree check stays out of
    /// the way - a git worker needs the worktree the mock never creates,
    /// which the worktree case builds for itself.
    fn heal_fixture() -> (tempfile::TempDir, tempfile::TempDir, Arc<Workspace>) {
        let dir = tempdir().expect("config tempdir");
        let project = tempdir().expect("project tempdir");
        let root = std::fs::canonicalize(project.path()).expect("canonical project");
        write_heal_toml(dir.path(), &root.to_string_lossy());
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        // The server starts this at boot; a kick a worker is meant to
        // continue on would otherwise sit in the queue forever.
        ws.start_kick_dispatcher();
        (dir, project, ws)
    }

    /// Start the project's lead over the mock and wait for it, so a worker's
    /// notice lands in a running chat rather than spawning the lead in the
    /// middle of the case.
    async fn start_lead(
        ws: &Arc<Workspace>,
        updates: &mut tokio::sync::mpsc::UnboundedReceiver<crate::update_fanout::SeatUpdate>,
    ) -> SessionSlot {
        let lead = SessionSlot::lead("Default", "forge");
        crate::spawn::handle_spawn_project(
            ws,
            "forge",
            forge_agent::client::SessionLaunchSettings::default(),
        )
        .expect("the lead spawns");
        await_update(
            updates,
            "the lead's connect",
            |update| matches!(update, SessionUpdate::Connected { key, .. } if *key == lead),
        )
        .await;
        lead
    }

    /// The fixture's project key.
    fn forge_key(ws: &Workspace) -> crate::ProjectKey {
        ws.list_projects()
            .into_iter()
            .find(|view| view.name == "forge")
            .expect("fixture project")
            .key
    }

    /// Spawn one worker over the mock and answer its spawn reply.
    async fn spawn_mock_worker(ws: &Arc<Workspace>, lead: &SessionSlot, label: &str) {
        let key = forge_key(ws);
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            ws,
            key,
            WorkerSpawnArgs {
                label: label.to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            lead.clone(),
            None,
            false,
            tx,
        );
        rx.await.expect("spawn replies").expect("spawn succeeds");
    }

    /// **A worker whose child closes while it is up comes back by itself**,
    /// on its own seat, with the restart note, and its project's lead hears
    /// the death and the outcome. Catches a death path that records the seat
    /// dead and leaves it there.
    #[tokio::test]
    async fn a_dead_worker_comes_back_and_its_lead_hears() {
        let _binary = MOCK_BINARY.lock().await;
        let (dir, _project, ws) = heal_fixture();
        // Run 1 is the lead, run 2 the worker that dies, run 3 its restart.
        forge_agent::set_test_sdk_binary(Some(heal_mock(dir.path(), 2, 2)));

        let mut updates = ws.subscribe_mirror();
        let lead = start_lead(&ws, &mut updates).await;
        let slot = SessionSlot::worker("Default", "forge", "probe-heal");
        spawn_mock_worker(&ws, &lead, "probe-heal").await;
        // The worker is mid-work when its child dies, which is the state
        // that earns the heal's restart note; a worker found parked comes
        // back silent.
        ws.record_seat_state(&slot, crate::store::sessions::SeatState::InTurn);

        // The first connect, then the child dies of its own accord 0.6 s in;
        // the supervisor's 150 ms wait brings the same seat back with the
        // restart note, and the lead hears the death and the outcome.
        let seen =
            await_updates(&mut updates, "the restart, its note and the lead's notice", |seen| {
                connects(seen, &slot) >= 2
                    && heard(seen, &slot, "This session was restarted by forge")
                    && seen.iter().any(|update| {
                        matches!(
                            update.as_ref(),
                            SessionUpdate::PeerEnvelopeAppended { key, .. } if *key == lead
                        )
                    })
            })
            .await;
        assert_eq!(mock_runs(dir.path()), 3, "the lead, the dead worker, and its resume");
        assert_eq!(connects(&seen, &slot), 2, "the same seat came back once");

        let told = seen
            .iter()
            .find_map(|update| match update.as_ref() {
                SessionUpdate::PeerEnvelopeAppended { key, wrapped, .. } if *key == lead => {
                    Some(wrapped.body.clone())
                }
                _ => None,
            })
            .expect("the lead's notice");
        assert!(told.contains("died at"), "the time: {told}");
        assert!(told.contains(" IST ("), "IST first, UTC after: {told}");
        assert!(told.contains("probe-heal"), "the seat the lead must act on: {told}");
        assert!(told.contains("attempt 1 of 3"), "the attempt and the cap: {told}");
        assert!(told.contains("Restarted"), "the outcome, even on success: {told}");
        forge_agent::set_test_sdk_binary(None);
    }

    /// A despawn racing the spawn itself: the live entry is registered
    /// before the session task (and its teardown signal) is minted, so a
    /// despawn in that window would remove the worktree under a child that
    /// is only starting - #1767's own overlap, for that window. It refuses
    /// instead, and leaves the entry alone so the caller's retry finds a
    /// live worker.
    #[tokio::test]
    async fn a_despawn_refuses_a_worker_that_is_still_spawning() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let mut entry = fake_git_worker_entry("mid-spawn", "worker-1");
        entry.status = forge_primitives::WorkerLiveness::Spawning;
        workspace.insert_live_worker(&project, entry);
        // No teardown signal registered: the spawn has not minted it yet.

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "mid-spawn", false, tx);
        let result = rx.await.expect("despawn result");

        let crate::protocol::DespawnResult::Blocked { reason } = result else {
            panic!("a mid-spawn worker must be refused, not despawned: {result:?}");
        };
        assert!(reason.contains("still spawning"), "the reason says what to wait for: {reason}");
        assert_eq!(
            workspace.list_live_workers(&project).len(),
            1,
            "the worker is left alone for the caller's retry",
        );
    }

    /// The same refusal after a re-spawn: the map still holds the previous
    /// occupant's answered entry while the new child starts, and handing
    /// that stale answer back would let the removal run over a child that
    /// is only starting.
    #[tokio::test]
    async fn a_respawns_mid_spawn_window_is_refused_despite_the_previous_answer() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let mut entry = fake_git_worker_entry("mid-spawn", "worker-1");
        let slot = entry.slot.clone();
        // The previous occupant finished: its entry is still there, answered.
        let previous = workspace.mint_session_teardown(&slot).expect("a mint before shutdown");
        let _ = previous.send_replace(true);
        entry.status = forge_primitives::WorkerLiveness::Spawning;
        workspace.insert_live_worker(&project, entry);

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "mid-spawn", false, tx);
        let result = rx.await.expect("despawn result");

        let crate::protocol::DespawnResult::Blocked { reason } = result else {
            panic!("a stale answer must not wave the removal through: {result:?}");
        };
        assert!(reason.contains("still spawning"), "the reason says what to wait for: {reason}");
    }

    /// A session teardown that never answers must not wedge the despawn:
    /// after the wait expires (injected small here) the removal goes ahead
    /// and the reply lands, rather than the label staying cleanup-pending
    /// forever.
    #[tokio::test]
    async fn a_despawn_whose_teardown_never_answers_removes_anyway() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("mute");
        // A registered session whose task never drops: the test holds the
        // sender and never fires it.
        let _mute = workspace.mint_session_teardown(&SessionSlot::from_str_for_test("worker-1"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker_within(
            &workspace,
            &project_key,
            "mute",
            false,
            std::time::Duration::from_millis(100),
            tx,
        );
        let result = rx.await.expect("despawn result");

        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "the despawn answers once its wait expires: {result:?}",
        );
        assert!(!wt.exists(), "and the removal went ahead after the wait expired");
    }

    /// A non-git worker's despawn removes no worktree, so it waits on no
    /// teardown signal: with a signal registered that never fires and a
    /// wait budget far larger than the work, the reply must land
    /// immediately rather than sit out the wait.
    #[tokio::test]
    async fn a_non_git_worker_despawn_waits_on_no_teardown_signal() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        workspace.insert_live_worker(&project, fake_worker_entry("plain", "worker-1"));
        // A session that never dies: if the despawn waited for it, the
        // reply would arrive only when the budget below expired.
        let _mute = workspace.mint_session_teardown(&SessionSlot::from_str_for_test("worker-1"));

        let started = std::time::Instant::now();
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker_within(
            &workspace,
            &project,
            "plain",
            false,
            std::time::Duration::from_secs(15),
            tx,
        );
        let result = rx.await.expect("despawn result");
        let elapsed = started.elapsed();

        let despawned = matches!(result, crate::protocol::DespawnResult::Despawned { .. });
        assert!(despawned, "{result:?}");
        assert!(
            elapsed < std::time::Duration::from_secs(5),
            "a worker with no worktree has no removal to order, so its despawn must not sit on \
             the teardown wait: it took {elapsed:?} against a 15s budget",
        );
    }

    /// The boot wave carries a persisted row's tree into the spawn it
    /// dispatches, so a worker pointed at another directory comes back in
    /// it after a restart.
    #[tokio::test]
    async fn the_boot_wave_carries_the_rows_tree() {
        let dir = tempdir().expect("tempdir");
        let sibling = tempdir().expect("sibling repo");
        std::fs::create_dir_all(&sibling).expect("sibling dir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;
        let store = tempdir().expect("store dir");
        ws.install_db_for_test(
            crate::store::Db::open(&store.path().join("db.redb")).expect("open db"),
        );
        let root = std::fs::canonicalize(sibling.path()).expect("canonical sibling");
        ws.seed_test_worker_row_at(&key, "traveller", &root.to_string_lossy(), false);
        ws.enable_test_dispatch_intercept();

        ws.dispatch_worker_respawns(
            &SessionSlot::lead("Default", "forge"),
            &key,
            &ws.worker_rows_for_project(&key),
            false,
        );

        let dispatched = ws.drain_test_dispatch_buffer();
        let spawn = dispatched
            .iter()
            .find_map(|cmd| match cmd {
                crate::protocol::Command::SpawnWorker { cwd, .. } => Some(cwd.clone()),
                _ => None,
            })
            .expect("the wave dispatches the persisted row");
        assert_eq!(
            spawn.as_deref(),
            Some(root.to_string_lossy().as_ref()),
            "the re-spawn carries the row's tree, so the worker comes back in it",
        );
    }

    /// A fresh spawn that omits `mcp_families` states "every family", so
    /// a stale stored selection must not survive it: reply, running
    /// surface and row have to agree.
    #[tokio::test]
    async fn a_fresh_spawn_without_families_clears_a_stale_selection() {
        let (ws, key, _dir) = spawn_scaffold();
        ws.record_worker_row(
            &key,
            "tester",
            "tester-id",
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
            Some(&["cron".to_owned()]),
        )
        .expect("seed a stale selection");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert!(reply.is_ok(), "the fresh spawn succeeds: {reply:?}");
        assert_eq!(reply.expect("ok").mcp_families, None, "the reply says every family");

        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "tester")
            .expect("the row the spawn wrote");
        assert_eq!(
            stored.mcp_families, None,
            "the row cannot keep a selection the running surface does not have; a restart \
             would silently narrow the worker",
        );
    }

    /// A spawn that states a tree writes it to the row AND the live
    /// entry. The row is the durable handle every read-back composes
    /// from - resume, the boot wave, the launchpad, the cron wake and
    /// the despawn - and the entry is what a seat read answers from, so
    /// a regression writing `None` (or carrying a stale tree forward,
    /// the way the row's kick and family fields deliberately do) leaves
    /// the feature half-working with the suite green.
    #[tokio::test]
    async fn a_stated_cwd_is_recorded_on_the_row_and_the_entry() {
        let (ws, key, _dir) = spawn_scaffold();
        let tree = tempdir().expect("worker tree");
        let root = std::fs::canonicalize(tree.path()).expect("canonical tree");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "traveller".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: Some(root.to_string_lossy().into_owned()),
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert!(reply.is_ok(), "the spawn succeeds: {reply:?}");

        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "traveller")
            .expect("the row the spawn wrote");
        assert_eq!(
            stored.cwd.as_deref(),
            Some(root.to_string_lossy().as_ref()),
            "the row records the tree the spawn resolved",
        );
        let entry = ws
            .list_live_workers(&key)
            .into_iter()
            .find(|entry| entry.label == "traveller")
            .expect("the live entry the spawn inserted");
        assert_eq!(
            entry.cwd.as_deref(),
            Some(root.as_path()),
            "and the live entry carries it, which is what a seat read answers from",
        );
    }

    /// A fresh spawn that states no tree clears one an older row
    /// recorded: a fresh spawn runs in the project's own path, and the
    /// row's other re-spawn fields carry forward only where the contract
    /// says so.
    #[tokio::test]
    async fn a_fresh_spawn_without_a_cwd_clears_a_stale_tree() {
        let (ws, key, _dir) = spawn_scaffold();
        let tree = tempdir().expect("worker tree");
        let root = std::fs::canonicalize(tree.path()).expect("canonical tree");
        ws.seed_test_worker_row_at(&key, "tester", &root.to_string_lossy(), true);

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert!(reply.is_ok(), "the fresh spawn succeeds: {reply:?}");

        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "tester")
            .expect("the row the spawn wrote");
        assert_eq!(
            stored.cwd, None,
            "a spawn that states no tree records none; carrying the old one forward would \
             run the worker somewhere the caller never asked for",
        );
    }

    /// A re-spawn that states no selection adopts the row's; one that
    /// states a selection is a revision and both the reply and the row
    /// carry it.
    #[tokio::test]
    async fn a_respawn_adopts_the_rows_selection_or_honours_a_stated_one() {
        let (ws, key, _dir) = spawn_scaffold();
        ws.record_worker_row(
            &key,
            "tester",
            "tester-id",
            "charter",
            None,
            None,
            false,
            crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
            Some(&["cron".to_owned()]),
        )
        .expect("seed the stored selection");

        // Adopt: no argument, boot re-spawn reads the row.
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            true,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert_eq!(
            reply.expect("ok").mcp_families,
            Some(vec!["cron".to_owned()]),
            "a re-spawn with nothing stated adopts the row's selection",
        );

        // State one: it wins, and the row is revised. Clear the live
        // entry the first re-spawn left, or the one-live-worker guard
        // refuses this second spawn for a reason unrelated to families.
        ws.remove_latest_worker(&key, "tester");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: Some(vec!["tasks".to_owned()]),
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            true,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert_eq!(
            reply.expect("ok").mcp_families,
            Some(vec!["tasks".to_owned()]),
            "a stated selection wins on a re-spawn",
        );
        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "tester")
            .expect("the row");
        assert_eq!(stored.mcp_families, Some(vec!["tasks".to_owned()]), "and is written");
    }

    /// The prompt charter carries one line per withheld family; the ROW
    /// keeps the raw charter, so the lines are recomposed per spawn and
    /// can neither duplicate nor outlive a revision.
    #[tokio::test]
    async fn a_narrowed_spawn_keeps_its_rows_charter_raw() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: Some(vec!["slack".to_owned()]),
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert!(reply.is_ok(), "the narrowed spawn succeeds: {reply:?}");

        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "tester")
            .expect("the row the spawn wrote");
        assert_eq!(
            stored.charter.as_deref(),
            Some("charter"),
            "the row keeps the raw charter; a later revision compares against this text, \
             so composed lines here would compound on every re-spawn",
        );
        assert_eq!(stored.mcp_families, Some(vec!["slack".to_owned()]));
    }

    /// The wiring the round-2 axis probed: an argument-less spawn on a
    /// systemone-less workspace composes the systemone withheld line,
    /// and the same spawn with the section on does not.
    #[test]
    fn the_spawn_prompt_charter_follows_the_config_gate() {
        let line = "This session has no `systemone__*` decision tools. When a decision is material and not obvious, route it to your lead instead of guessing.";
        let without = spawn_prompt_charter("charter", None, false, true, true);
        assert!(without.contains(line), "[systemone] off composes the line: {without}");
        let with = spawn_prompt_charter("charter", None, true, true, true);
        assert!(!with.contains(line), "the section on composes none: {with}");
    }

    /// The composer's contract: nothing withheld means the charter is
    /// untouched; a withheld family appends its line exactly once; the
    /// present family appends nothing.
    #[test]
    fn the_prompt_charter_carries_only_the_withheld_lines() {
        let all = crate::mcp::McpFamily::all();
        assert_eq!(charter_with_withheld_families("charter", &all), "charter");

        let slack_only: std::collections::BTreeSet<crate::mcp::McpFamily> =
            [crate::mcp::McpFamily::Slack].into_iter().collect();
        let text = charter_with_withheld_families("charter", &slack_only);
        assert!(text.starts_with("charter\n"), "{text}");
        assert!(text.contains("no `systemone__*` decision tools"), "{text}");
        assert!(!text.contains("no `slack__*` tools"), "the present family gets no line: {text}");
    }

    /// A first spawn writes the kick it opened the worker with: the row's
    /// `kick` is the worker's first turn, and a later `--new` re-spawn
    /// delivers it. A row that never got it opens the worker with nothing.
    #[tokio::test]
    async fn a_first_spawn_writes_the_kick_it_was_given() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key.clone(),
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: Some("opening turn".to_owned()),
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("spawn replies");
        assert!(reply.is_ok(), "the first spawn succeeds: {reply:?}");

        let stored = ws
            .worker_rows_for_project(&key)
            .into_iter()
            .find(|row| row.label == "tester")
            .expect("the row the spawn wrote");
        assert_eq!(
            stored.kick.as_deref(),
            Some("opening turn"),
            "the row keeps the kick the spawn opened the worker with; dropped, a later --new \
             re-spawn opens the worker with no first turn at all",
        );
    }

    /// The spawn composes the working directory from the gitness the ROW
    /// records, in preference to probing the project - that is what keeps
    /// it on the directory the launchpad already cleared. A fixture whose
    /// row agrees with the disk cannot tell the two apart, so this one
    /// disagrees: the row says worktree, the project path is not a repo.
    #[tokio::test]
    async fn a_spawn_keeps_the_rows_recorded_gitness_over_a_probe() {
        let row = failed_spawn_leftover_row(Some("tester-id"), false, Some(true)).await;
        assert_eq!(
            row.and_then(|row| row.is_git_repo),
            Some(true),
            "the spawn writes back the gitness the row recorded, not what a probe of the \
             project path would answer",
        );
    }

    /// The other direction of the row-over-probe preference: with no row to
    /// read, the probe is still the answer. A first spawn into a git
    /// project that recorded `false` here would pass no `--worktree`, and
    /// every later resume, the launchpad and the cron router would read
    /// that false record as the directory the worker runs in.
    ///
    /// The spawn has to succeed for the row to survive: a refused fresh
    /// spawn rolls its row back, so there would be nothing left to read.
    #[tokio::test]
    async fn a_first_spawn_probes_for_gitness_when_there_is_no_row() {
        let dir = tempdir().expect("tempdir");
        let repo = 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(), "fixture precondition: git init");
        write_forge_toml(dir.path(), &repo.path().to_string_lossy());
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;
        // Deliberately no row: this is the label's first spawn.

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &ws,
            key,
            WorkerSpawnArgs {
                label: "tester".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let admitted = rx.await.expect("reply").is_ok();
        assert!(admitted, "fixture precondition: the spawn is admitted, so its row survives");

        let db = ws.db.lock();
        let row =
            crate::store::sessions::get(db.as_ref().expect("db"), "Default", "forge", "tester")
                .expect("read")
                .expect("the spawn recorded its row");
        drop(db);
        assert_eq!(
            row.is_git_repo,
            Some(true),
            "with no row to read the probe is the answer; recording false here would send \
             every later resume, the launchpad and the cron router to the project root",
        );
    }

    /// A spawn refused before it reaches the project leaves the caller's
    /// parked payload where it is, so the caller's own expiry still reaches
    /// it rather than the workspace having consumed it on the way past.
    #[tokio::test]
    async fn a_refused_spawn_leaves_the_parked_payload_to_the_caller() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.park_slack(
            &crate::SessionSlot::lead("Default", "missing"),
            vec![slack_msg("parked while asleep")],
        );

        let result = ws.get_agent_handle_at_key(
            crate::target::SessionTarget::FreshInProject {
                slot: SessionSlot::worker("TestOrg", "not-in-config", "minted-worker-id"),
                cwd: None,
            },
            forge_agent::client::SessionLaunchSettings::default(),
            None,
            &crate::protocol::SpawnRole::Worker {
                label: "reviewer".to_owned(),
                wrote_row: false,
                mcp_families: None,
            },
            true,
        );

        assert!(result.is_err(), "a target mapping to no project is refused");
        let owner = crate::SessionSlot::lead("Default", "missing");
        assert_eq!(
            ws.parked_by_slot.lock().get(&owner).map_or(0, |parked| parked.slack.len()),
            1,
            "the refusal left the bucket alone, so the caller's expiry can still reach it",
        );

        ws.expire_parked_for_slot(
            &owner,
            crate::mcp::peers::types::PeerFailureReason::TargetConnectionFailed,
        );
        assert_eq!(
            ws.parked_by_slot.lock().get(&owner).map_or(0, |parked| parked.slack.len()),
            0,
            "and the caller's expiry is what records the loss",
        );
    }

    /// The synchronous spawn-failure arm is reachable: a project present only
    /// in the test overlay resolves by name but not by target, so the spawn
    /// fails before any `SessionTask` exists. Everything a delivery parked for
    /// that project's lead has to be recorded there, because nothing else will
    /// drain a bucket the session never reached.
    #[test]
    fn a_failed_project_spawn_expires_the_parked_payloads() {
        let (ws, _rx) = Workspace::testing_stub();
        ws.seed_test_project("overlayonly", "/tmp/slack-overlay-only");
        ws.park_slack(
            &crate::SessionSlot::lead("TestOrg", "overlayonly"),
            vec![slack_msg("parked while asleep")],
        );

        let _ = crate::spawn::handle_spawn_project(
            &ws,
            "overlayonly",
            forge_agent::client::SessionLaunchSettings::default(),
        );

        assert_eq!(
            ws.parked_by_slot
                .lock()
                .get(&crate::SessionSlot::lead("TestOrg", "overlayonly"))
                .map_or(0, |parked| parked.slack.len()),
            0,
            "the failed spawn records the messages parked for that project's lead",
        );
    }

    /// A delivery whose dispatch fails must not echo: `false` tells the sweep
    /// to re-run the message, and an echo pushed first would paint the block a
    /// second time on that re-run, for a turn the LLM never received.
    #[test]
    fn a_failed_worker_dispatch_leaves_no_echo_for_the_sweep_to_duplicate() {
        let (ws, mut update_rx) = Workspace::testing_stub();
        ws.seed_test_project("forge", "/tmp/slack-worker-doomed");
        let key = ws.list_projects().into_iter().find(|v| v.name == "forge").expect("seeded").key;
        ws.insert_live_worker(&key, fake_worker_entry("tester", "worker-uuid"));
        let worker_key = SessionSlot::from_str_for_test("worker-uuid");
        // Connected, but with no pooled handle and no conn: the dispatch fails.
        ws.mark_session_connected_for_test(&worker_key, "worker-uuid");

        let delivered =
            deliver_slack_message(&ws, "forge", Some("tester"), vec![slack_msg("hello")]);

        assert!(!delivered, "a failed dispatch tells the sweep to re-run the message");
        let echoed = std::iter::from_fn(|| update_rx.try_recv().ok()).any(|frame| {
            matches!(&*frame.update, crate::protocol::SessionUpdate::SlackMessageAppended { .. })
        });
        assert!(!echoed, "a failed worker dispatch must not echo a SlackMessageAppended");
    }

    /// The ids in the prose are the arguments a reply takes: without them
    /// the agent cannot answer in the place the message came from.
    #[test]
    fn slack_prose_carries_the_ids_a_reply_needs() {
        let mut message = slack_msg("please look");
        message.thread_ts = Some("100.0".to_owned());
        message.files = vec![SlackFile {
            id: "F1".to_owned(),
            name: "notes.txt".to_owned(),
            url_private: "https://files.slack.com/x".to_owned(),
            shares: SlackFileShares::default(),
        }];

        let prose = fresh_prose(&[message]);
        assert!(prose.contains("D1"), "the conversation id is present: {prose}");
        assert!(prose.contains("100.000001"), "the ts is present: {prose}");
        assert!(prose.contains("in thread 100.0"), "the thread is present: {prose}");
        assert!(prose.contains("F1"), "the file id is present: {prose}");
    }

    /// The header and the `<author>: ` member line are a contract with
    /// `forge_server::envelope::detect_inbound`, so the whole shape is
    /// pinned: a reformat here silently reverts the block to painting nothing.
    #[test]
    fn slack_prose_names_the_workspace_and_the_author() {
        let prose = fresh_prose(&[slack_msg("hello there")]);
        assert_eq!(
            prose,
            "[Slack - workspace 'acme', U9] id D1 ts 100.000001\nU9: hello there [ts 100.000001]",
            "the exact prose forge_server::envelope::detect_inbound keys on",
        );
    }

    /// A block that waited, in the parked bucket or across a sweep gap, says
    /// how old its newest message is, before the member count. The oldest
    /// member is older still, so the label has to be read off the newest.
    #[test]
    fn a_stale_bundle_carries_its_age_in_the_header() {
        let day = 24 * 60 * 60;
        // Ten-digit seconds, as Slack sends them: the header takes the newest
        // by string order, which is only time order at that width.
        let oldest = 1_001_827_200;
        let prose = slack_bundle_to_prose(
            &[
                slack_msg_at("1001827200.0", "alice", "hi"),
                slack_msg_at("1002000000.0", "bob", "there"),
            ],
            Duration::from_secs(day),
            SystemTime::UNIX_EPOCH + Duration::from_secs(oldest + 10 * day),
        );
        assert!(
            prose.starts_with(
                "[Slack - workspace 'acme', U9] id D1 ts 1002000000.0, 8d old (2 messages)\n"
            ),
            "the header carries the newest message's age: {prose}",
        );
    }

    /// A single message is marked the same way a bundle is: the clause is
    /// written by the header, not by the count branch.
    #[test]
    fn a_stale_single_message_carries_its_age() {
        let prose = slack_bundle_to_prose(
            &[slack_msg("hi")],
            Duration::from_secs(3_600),
            SystemTime::UNIX_EPOCH + Duration::from_secs(100 + 3 * 3_600),
        );
        assert!(
            prose.starts_with("[Slack - workspace 'acme', U9] id D1 ts 100.000001, 3h old\n"),
            "a one-message block carries its age too: {prose}",
        );
    }

    /// The threshold is a floor: below it the header is untouched, at it the
    /// block is marked, and the label reads in hours up to two days and days
    /// from there. A future or unparseable ts carries nothing.
    #[test]
    fn a_stale_age_reads_hours_below_two_days_and_days_from_there() {
        let day = 24 * 60 * 60;
        let at = |age: u64| {
            stale_age_clause(
                "100.0",
                Duration::from_secs(day),
                SystemTime::UNIX_EPOCH + Duration::from_secs(100 + age),
            )
        };
        assert_eq!(at(day - 1), None, "below the threshold carries nothing");
        assert_eq!(at(day).as_deref(), Some(", 24h old"), "the threshold itself is marked");
        assert_eq!(at(2 * day - 1).as_deref(), Some(", 47h old"), "hours up to the day switch");
        assert_eq!(at(2 * day).as_deref(), Some(", 2d old"), "two days reads in days");
        assert_eq!(
            stale_age_clause(
                "100.0",
                Duration::ZERO,
                SystemTime::UNIX_EPOCH + Duration::from_secs(100),
            ),
            None,
            "zero turns the mark off, even for a fresh message",
        );
        assert_eq!(
            stale_age_clause(
                "100.0",
                Duration::from_secs(day),
                SystemTime::UNIX_EPOCH + Duration::from_secs(50),
            ),
            None,
            "a ts in the future carries nothing",
        );
        assert_eq!(
            stale_age_clause(
                "not-a-ts",
                Duration::from_secs(day),
                SystemTime::UNIX_EPOCH + Duration::from_secs(9 * day),
            ),
            None,
            "an unparseable ts carries nothing",
        );
    }

    /// A redelivered correction keeps the message's ts and would read as
    /// a duplicate of one already delivered; the marker is what says the
    /// text changed.
    #[test]
    fn a_bundle_marks_an_edited_member() {
        let mut message = slack_msg("deploy is RED");
        message.edited = Some("150.0".to_owned());

        let prose = fresh_prose(&[message]);
        assert!(
            prose.contains("[ts 100.000001 edited]"),
            "the correction is marked in the member's own bracket: {prose}",
        );
    }

    /// Every member keeps its own `ts`, because that is the handle an agent
    /// answers one message with without touching the others.
    #[test]
    fn a_bundle_names_every_member_with_its_own_ts() {
        let prose =
            fresh_prose(&[slack_msg_at("1.1", "alice", "hi"), slack_msg_at("1.2", "bob", "there")]);

        assert!(prose.contains("[ts 1.1]"), "the first member's ts: {prose}");
        assert!(prose.contains("[ts 1.2]"), "and the second's: {prose}");
        assert!(prose.contains("alice: hi"), "each member names its author: {prose}");
        assert!(prose.contains("bob: there"), "and so does the second: {prose}");
    }

    /// A reply belongs under the parent it answers, whatever order the wire
    /// handed the two over in - history pages arrive newest first.
    #[test]
    fn a_bundle_shows_thread_replies_under_their_parent() {
        let mut reply = slack_msg_at("1.3", "carol", "agreed");
        reply.thread_ts = Some("1.1".to_owned());

        let prose = fresh_prose(&[reply, slack_msg_at("1.1", "alice", "hi")]);

        let parent_at = prose.find("[ts 1.1").expect("the parent is present");
        let reply_at = prose.find("[ts 1.3").expect("the reply is present");
        assert!(reply_at > parent_at, "a reply is grouped under its parent: {prose}");
    }

    /// A parent ages out of the sweep window while its thread keeps moving,
    /// so a bundle can hold a reply whose parent it never saw. Without the
    /// parent's ts the agent cannot answer in that thread at all.
    #[test]
    fn a_reply_whose_parent_is_absent_still_carries_the_parent_ts() {
        let mut reply = slack_msg_at("1.3", "carol", "agreed");
        reply.thread_ts = Some("1.1".to_owned());

        let prose = fresh_prose(&[reply]);
        assert!(prose.contains("in thread 1.1"), "the parent ts must survive: {prose}");
    }

    /// The name the connector resolved is what the block shows. The raw id
    /// stays on the message and the block drops it, so the resolved name is
    /// the only one that reaches a reader.
    #[test]
    fn a_bundle_prefers_the_resolved_author_over_the_id() {
        let mut message = slack_msg_at("1.1", "U0ATEK2EAGP", "hi");
        message.author = Some("architect2".to_owned());

        let prose = fresh_prose(&[message]);
        assert!(prose.contains("architect2: hi"), "the resolved handle is shown: {prose}");
        assert!(!prose.contains("U0ATEK2EAGP"), "an id is never a name to print: {prose}");
    }

    /// A parent carries its own `ts` as `thread_ts`, so saying so again on
    /// the member line is noise - the ts is already the handle a reply into
    /// that thread passes.
    #[test]
    fn a_parent_does_not_restate_its_own_ts_as_a_thread() {
        let mut parent = slack_msg_at("1.1", "alice", "hi");
        parent.thread_ts = Some("1.1".to_owned());

        let prose = fresh_prose(&[parent]);
        assert!(!prose.contains("in thread"), "no self-referential thread clause: {prose}");
    }

    /// #1: the at-most-one-live-per-label guard lives in the shared
    /// `handle_spawn_worker` core, so a second dispatch for an
    /// already-live label - a boot re-spawn racing an MCP spawn for the
    /// same label - inserts no duplicate entry and never reaches the
    /// subprocess spawn.
    #[tokio::test]
    async fn handle_spawn_worker_dedups_already_live_label() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/forge");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project present")
            .key;
        // Simulate the first (e.g. static) reviewer already live.
        workspace.insert_live_worker(&project, fake_worker_entry("reviewer", "reviewer-1"));

        // A second dispatch for the same label (e.g. the dynamic reviewer)
        // hits the guard before any insert or spawn.
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "reviewer".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );

        assert_eq!(
            workspace.list_live_workers(&project).len(),
            1,
            "the duplicate spawn must not add a second live worker",
        );
        let reply = rx.await.expect("reply channel");
        let err = reply.expect_err("a duplicate spawn replies an error");
        assert!(err.contains("already live"), "error names the collision: {err}");
    }

    /// A refused duplicate must leave the RUNNING worker's row exactly as
    /// it was. The row is written after the guard for this reason: written
    /// first, the refusal would have overwritten the live worker's id,
    /// charter and kick with the refused attempt's, and the next boot
    /// would resume an id no session ever ran under, orphaning the
    /// transcript it belongs to.
    ///
    /// The sibling test above cannot see this: it runs on a `testing_stub`
    /// with no DB, so the row write fails there and the ordering does not
    /// matter.
    #[tokio::test]
    async fn a_refused_duplicate_leaves_the_running_workers_row_alone() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let ws = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("workspace"));
        ws.seed_test_ready_account("Stargate");
        ws.seed_test_gateway_ready(true);
        let key = ws
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("fixture project")
            .key;
        let spawn = |charter: &str| {
            let (tx, rx) = tokio::sync::oneshot::channel();
            handle_spawn_worker(
                &ws,
                key.clone(),
                WorkerSpawnArgs {
                    label: "steward".to_owned(),
                    charter: charter.to_owned(),
                    kick: None,
                    resume_kick: None,
                    interactive: false,
                    mcp_families: None,
                    cwd: None,
                },
                SessionSlot::from_str_for_test("lead"),
                None,
                false,
                tx,
            );
            rx
        };

        let first = spawn("mind the queues")
            .await
            .expect("reply channel")
            .expect("the first spawn is admitted")
            .session_id;

        let refused = spawn("a second, refused charter").await.expect("reply channel");
        let refusal = refused.expect_err("the second spawn for a live label is refused");
        assert!(
            refusal.contains("already live"),
            "and it is the duplicate arm that refused, not some other failure: {refusal}",
        );

        let rows = ws.worker_rows_for_project(&key);
        let row = rows.iter().find(|r| r.label == "steward").expect("the running worker's row");
        assert_eq!(
            row.session_id.as_deref(),
            Some(first.as_str()),
            "the row still names the id the running worker was admitted under",
        );
        assert_eq!(
            row.charter.as_deref(),
            Some("mind the queues"),
            "and keeps the args it was admitted with, not the refused attempt's",
        );
    }

    /// A one-commit git repo as the project, the workspace over it, and
    /// the label's derived worktree path. The project declares no model,
    /// so a spawn that gets past the worktree step dies at the account
    /// walk with no subprocess behind it - which is what makes the real
    /// spawn path callable from a test at all.
    fn git_spawn_fixture(
        label: &str,
    ) -> (Arc<Workspace>, ProjectKey, std::path::PathBuf, tempfile::TempDir, tempfile::TempDir)
    {
        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        run_git(repo.path(), &["config", "user.email", "t@example.com"]);
        run_git(repo.path(), &["config", "user.name", "Test"]);
        run_git(repo.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(repo.path().join("README.md"), "seed").expect("write seed");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "-q", "-m", "init"]);

        let config = tempdir().expect("config tempdir");
        let repo_path_str = repo.path().to_string_lossy().replace('\\', "/");
        std::fs::write(
            forge_toml_path(config.path()),
            format!(
                "[[orgs]]\nname = \"Default\"\naccounts = [\"Stargate\"]\n\n[[orgs.projects]]\nname = \"forge\"\npath = \"{repo_path_str}\"\n\n[[accounts]]\ndisplay_name = \"Stargate\"\ntoken = \"t\"\nmodels = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n"
            ),
        )
        .expect("write forge.toml");

        let workspace =
            Arc::new(Workspace::new_for_test(config.path().to_owned()).expect("workspace new"));
        let view = workspace.list_projects().into_iter().next().expect("one project");
        let project_key = view.key.clone();
        let derived = view.path.join(".claude").join("worktrees").join(label);
        (workspace, project_key, derived, repo, config)
    }

    /// Spawn `label` in the fixture workspace and hand back the reply.
    fn spawn_reply(
        workspace: &Arc<Workspace>,
        key: &ProjectKey,
        label: &str,
        from_boot_respawn: bool,
    ) -> tokio::sync::oneshot::Receiver<Result<WorkerSpawnReply, String>> {
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            workspace,
            key.clone(),
            WorkerSpawnArgs {
                label: label.to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            from_boot_respawn,
            tx,
        );
        rx
    }

    /// A fresh spawn that cannot get its worktree must be refused rather
    /// than started. The measured case: the derived branch
    /// `worktree-<label>` is already checked out in another worktree, so
    /// nothing can be created at the path the worker is to run in - and
    /// unchecked, the session starts anyway and the worker reads live while
    /// having nowhere to work.
    #[tokio::test]
    async fn a_fresh_spawn_whose_branch_is_held_elsewhere_is_refused() {
        let (workspace, key, _derived, repo, _config) = git_spawn_fixture("reviewer");
        let elsewhere = tempdir().expect("elsewhere tempdir");
        run_git(
            repo.path(),
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                "worktree-reviewer",
                elsewhere.path().to_str().expect("utf8 path"),
            ],
        );

        let err = spawn_reply(&workspace, &key, "reviewer", false)
            .await
            .expect("reply channel")
            .expect_err("a spawn whose worktree cannot be created is refused");

        assert!(err.contains("already checked out"), "the refusal names the obstacle: {err}");
        assert!(err.contains("worktree-reviewer"), "and the branch it is about: {err}");
        assert!(
            workspace.list_live_workers(&key).is_empty(),
            "and no worker reads live off the refused spawn"
        );
        assert!(
            workspace.worker_rows_for_project(&key).is_empty(),
            "and nothing durable survives to re-spawn it on the next boot"
        );
    }

    /// A boot re-spawn's reply is dropped, so rolling the entry back would
    /// leave the row listed, nothing running, and the reason only in the
    /// log. The entry stays as the visible failure the async spawn
    /// failures already leave, carrying the reason.
    #[tokio::test]
    async fn a_refused_boot_respawn_leaves_a_failed_row_carrying_the_reason() {
        let (workspace, key, _derived, repo, _config) = git_spawn_fixture("reviewer");
        let elsewhere = tempdir().expect("elsewhere tempdir");
        run_git(
            repo.path(),
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                "worktree-reviewer",
                elsewhere.path().to_str().expect("utf8 path"),
            ],
        );

        let err = spawn_reply(&workspace, &key, "reviewer", true)
            .await
            .expect("reply channel")
            .expect_err("the boot re-spawn is refused");

        let entry = workspace
            .list_live_workers(&key)
            .into_iter()
            .next()
            .expect("the entry stays, so the row reads as failed rather than vanishing");
        assert_eq!(
            entry.status,
            forge_primitives::WorkerLiveness::Failed,
            "the refused boot re-spawn is not live"
        );
        assert!(
            entry
                .diagnostic
                .as_deref()
                .is_some_and(|reason| reason.contains("already checked out")),
            "and the reason is on the row for a reader, not just some worktree word: {:?}",
            entry.diagnostic
        );
        assert!(err.contains("already checked out"), "the dropped reply still carries it: {err}");
    }

    /// A `--new` re-spawn lands on the worktree the worker already has:
    /// registered at the derived path, holding its own branch, there to be
    /// reused. Refusing that would take out every fresh re-spawn, so the
    /// path comparison has to read a symlinked repo root as one directory.
    #[tokio::test]
    async fn a_fresh_spawn_onto_the_workers_own_worktree_gets_past_the_step() {
        let (workspace, key, derived, repo, _config) = git_spawn_fixture("reviewer");
        std::fs::create_dir_all(derived.parent().expect("worktrees dir")).expect("mkdir worktrees");
        run_git(
            repo.path(),
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                "worktree-reviewer",
                derived.to_str().expect("utf8 path"),
            ],
        );

        let err = spawn_reply(&workspace, &key, "reviewer", false)
            .await
            .expect("reply channel")
            .expect_err("the spawn still fails, at the account walk");

        assert!(
            err.contains("declares no model"),
            "the spawn is admitted onto the worktree it already has: {err}"
        );
    }

    /// Stub whose `forge.toml` caps the `forge` project at the given
    /// override via the entry's `max_workers`, loaded through the
    /// real config path because the full spawn below reads
    /// `config.projects`. The `notes` project stays at the default.
    /// Projects point at throwaway dirs: a real repo path would make
    /// `is_git` true and hang `--worktree <label>` spawns off the
    /// actual checkout.
    fn stub_with_project_cap(
        limit: usize,
    ) -> (Arc<Workspace>, (tempfile::TempDir, tempfile::TempDir)) {
        let dir = tempdir().expect("config tempdir");
        let projects_dir = tempdir().expect("projects tempdir");
        let forge_path = projects_dir.path().join("forge").display().to_string();
        let notes_path = projects_dir.path().join("notes").display().to_string();
        fs::create_dir_all(&forge_path).expect("create forge project dir");
        fs::create_dir_all(&notes_path).expect("create notes project dir");
        fs::write(
            forge_toml_path(dir.path()),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

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

[[orgs.projects]]
name = "notes"
path = "{notes_path}"
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("workspace new"));
        workspace.seed_test_ready_account("Stargate");
        (workspace, (dir, projects_dir))
    }

    fn seeded_project(workspace: &Arc<Workspace>) -> ProjectKey {
        workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project present")
            .key
    }

    /// #976: a lead-driven spawn at the project's worker cap
    /// replies a clean error naming the limit and inserts no entry.
    #[tokio::test]
    async fn spawn_worker_over_limit_refuses_and_creates_nothing() {
        let (workspace, _config_dir) = stub_with_project_cap(2);
        let project = seeded_project(&workspace);
        workspace.insert_live_worker(&project, fake_worker_entry("w1", "w1"));
        workspace.insert_live_worker(&project, fake_worker_entry("w2", "w2"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w3".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );

        let err = rx.await.expect("reply").expect_err("at-limit spawn must refuse");
        assert!(err.contains("worker limit reached"), "names the refusal: {err}");
        assert!(err.contains("cap is 2"), "names the cap: {err}");
        assert_eq!(
            workspace.list_live_workers(&project).len(),
            2,
            "the refused spawn creates no worker"
        );

        // Label precedence: at the cap, a DUPLICATE label reports the
        // collision, not the cap - the lead is pointed at the remedy
        // that matches the actual problem.
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w1".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let err = rx.await.expect("reply").expect_err("a live label must refuse");
        assert!(
            err.contains("already live") && !err.contains("worker limit reached"),
            "the collision wins over the cap: {err}"
        );
    }

    /// The cap is PER PROJECT: the gate counts only the spawning
    /// project's live workers, against that project's own
    /// `max_workers` override, else the default of
    /// 2. Workers live in other projects neither consume the budget
    /// nor raise it.
    #[tokio::test]
    async fn the_cap_is_per_project() {
        let (workspace, _config_dir) = stub_with_project_cap(1);
        let forge_project = seeded_project(&workspace);
        let notes_project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "notes")
            .expect("seeded notes project present")
            .key;
        // forge sits at its own cap (override 1); notes still has its
        // full default budget of 2.
        workspace.insert_live_worker(&forge_project, fake_worker_entry("w1", "w1"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            notes_project.clone(),
            WorkerSpawnArgs {
                label: "w2".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("reply");
        assert!(
            reply.is_ok(),
            "a worker in another project must not consume notes' budget: {:?}",
            reply.err()
        );
        if let Ok(reply) = reply {
            workspace.release_session(&SessionSlot::from_str_for_test(reply.session_id));
        }

        // notes fills to its own default cap of 2 and refuses past it.
        workspace.insert_live_worker(&notes_project, fake_worker_entry("w3", "w3"));
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            notes_project.clone(),
            WorkerSpawnArgs {
                label: "w4".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let err = rx.await.expect("reply").expect_err("notes at its cap must refuse");
        assert!(err.contains("worker limit reached"), "names the refusal: {err}");
        assert!(err.contains("cap is 2"), "names notes' own cap: {err}");
        assert!(
            err.contains(&format!("project '{}' has 2 workers live", notes_project.as_str())),
            "notes' refusal counts only notes' workers: {err}"
        );

        // forge's override still governs forge.
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            forge_project.clone(),
            WorkerSpawnArgs {
                label: "w5".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let err = rx.await.expect("reply").expect_err("forge at its cap must refuse");
        assert!(err.contains("cap is 1"), "names forge's override: {err}");
        assert!(
            err.contains(&format!("project '{}' has 1 worker live", forge_project.as_str())),
            "forge's refusal counts only forge's workers, singular: {err}"
        );
    }

    /// The override raises as well as lowers: a cap above the default
    /// admits past 2. Every other cap test also passes if the
    /// resolution clamps the override to the default, and the raise
    /// direction is the one the forge project's own config depends on.
    #[tokio::test]
    async fn a_cap_above_the_default_admits_past_two() {
        let (workspace, _config_dir) = stub_with_project_cap(3);
        let project = seeded_project(&workspace);
        workspace.insert_live_worker(&project, fake_worker_entry("w1", "w1"));
        workspace.insert_live_worker(&project, fake_worker_entry("w2", "w2"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w3".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("reply");
        assert!(
            reply.is_ok(),
            "the override must raise the cap past the default: {:?}",
            reply.err()
        );
        assert_eq!(
            workspace.list_live_workers(&project).len(),
            3,
            "the admitted spawn creates its worker"
        );
        if let Ok(reply) = reply {
            workspace.release_session(&SessionSlot::from_str_for_test(reply.session_id));
        }
    }

    /// The notice the lead reads: a worker spawned onto an account the
    /// walk had to take while it was bailed comes back named in the
    /// reply, so the lead hears it at spawn rather than when the worker
    /// stalls. The join from the spawned handle's account to the reply
    /// is the whole mechanism, and a regression there would drop the
    /// notice silently.
    #[tokio::test]
    async fn a_worker_spawned_onto_a_degraded_account_reports_it() {
        let (workspace, _config_dir) = stub_with_project_cap(2);
        let project = seeded_project(&workspace);
        workspace.account_pool().set_loading(
            &forge_gateway::AccountKey("Stargate".to_owned()),
            forge_gateway::LoadingState::Bailed,
        );

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w1".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("reply").expect("the spawn is admitted");
        assert_eq!(
            reply.rate_limited_account.as_deref(),
            Some("Stargate"),
            "the bailed account is named in the reply, which is what raises the notice",
        );
        // This fixture's projects are throwaway dirs, not git repos, so this
        // worker runs in the project root: the reply must not name a worktree
        // that was never created.
        assert_eq!(reply.worktree, None, "a non-git project's worker has no worktree");
        workspace.release_session(&SessionSlot::from_str_for_test(reply.session_id));
    }

    /// The atomicity pin, at the layer it lives: concurrent
    /// `insert_live_worker_if_label_absent` calls at cap 1 admit
    /// exactly one and refuse the rest, whatever order the lock grants.
    /// Direct inserts, so no spawn machinery can retire an entry
    /// mid-race. A barrier releases all callers at once; the count only
    /// stays at 1 if the cap check and the push share the lock.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn concurrent_cap_gate_admits_exactly_one() {
        let (workspace, _config_dir) = stub_with_project_cap(1);
        let project = seeded_project(&workspace);
        let barrier = Arc::new(tokio::sync::Barrier::new(32));

        let mut handles = Vec::new();
        for n in 0..32 {
            let workspace = Arc::clone(&workspace);
            let project = project.clone();
            let barrier = Arc::clone(&barrier);
            handles.push(tokio::spawn(async move {
                barrier.wait().await;
                let entry = fake_worker_entry(&format!("w{n}"), &format!("w{n}-session"));
                workspace.insert_live_worker_if_label_absent(&project, entry, Some(1))
            }));
        }

        let mut admitted = 0;
        let mut refused = 0;
        for handle in handles {
            match handle.await.expect("insert task joins") {
                Ok(()) => admitted += 1,
                Err(LiveWorkerRefusal::AtCap { live, cap }) => {
                    refused += 1;
                    assert_eq!((live, cap), (1, 1), "the refusal names the count and the cap");
                }
                Err(other) => panic!("no label collisions at distinct labels: {other:?}"),
            }
        }
        assert_eq!(admitted, 1, "exactly one insert wins the cap");
        assert_eq!(refused, 31, "every other insert is refused by the cap");
        assert_eq!(
            workspace.list_live_workers(&project).len(),
            1,
            "the pool holds exactly the one admitted entry"
        );
    }

    /// The same gate through the full handler: eight concurrent
    /// lead-driven spawns at cap 1, and the live (non-`Failed`) count
    /// never exceeds 1.
    ///
    /// Exactly one of the eight is admitted, which the stand-in is what
    /// makes assertable: with a real child the reply count is tolerant,
    /// because a winner whose subprocess dies asynchronously is
    /// transitioned to `Failed` by the spawn-failure handler, freeing
    /// its slot for a queued spawn.
    ///
    /// That stand-in is not only for determinism - a real child booted
    /// against this fixture's config directory outlives the test: the
    /// guard that removes the tree drops as soon as the assertions hold,
    /// and the child then writes the CLI's `.claude.json` layout back
    /// into the deleted path.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn concurrent_spawns_keep_the_live_count_under_the_cap() {
        let (workspace, _config_dir) = stub_with_project_cap(1);
        // Held for the test's lifetime: the receiver IS the stand-in's
        // dispatcher, and dropping it fails the admitted spawn, which
        // rolls the entry back and hands the freed slot on.
        let (stand_in, _agent_rx) = Workspace::testing_stub_handle();
        workspace.install_test_spawn_handle(stand_in);

        let mut handles = Vec::new();
        for n in 0..8 {
            let workspace = Arc::clone(&workspace);
            handles.push(tokio::spawn(async move {
                let project = seeded_project(&workspace);
                let (tx, rx) = tokio::sync::oneshot::channel();
                handle_spawn_worker(
                    &workspace,
                    project,
                    WorkerSpawnArgs {
                        label: format!("w{n}"),
                        charter: "charter".to_owned(),
                        kick: None,
                        resume_kick: None,
                        interactive: false,
                        mcp_families: None,
                        cwd: None,
                    },
                    SessionSlot::from_str_for_test("lead"),
                    None,
                    false,
                    tx,
                );
                rx.await.expect("reply")
            }));
        }

        let mut winners = 0;
        let mut winner_sessions = Vec::new();
        for handle in handles {
            match handle.await.expect("spawn task joins") {
                Ok(reply) => {
                    winners += 1;
                    winner_sessions.push(SessionSlot::from_str_for_test(reply.session_id));
                }
                Err(message) => {
                    assert!(
                        message.contains("worker limit reached"),
                        "the only refusal is the cap, never a collision or other error: {message}"
                    );
                }
            }
        }
        assert_eq!(winners, 1, "the cap admits the first arrival and refuses the other seven");
        let project = seeded_project(&workspace);
        let live = workspace.list_live_workers(&project).iter().filter(|w| w.is_live()).count();
        assert!(live <= 1, "no overshoot past the cap; got {live} live workers");
        // Release closes each winner's Command channel, so the
        // SessionTask's disconnect() reaps the client; kill_on_drop is
        // the backstop.
        for session in winner_sessions {
            workspace.release_session(&session);
        }
    }

    /// #976's open question, decided: the boot-time respawn wave is
    /// EXEMPT from the cap. Persisted workers are state the user
    /// already had, and the boot path drops the spawn reply, so an
    /// over-limit refusal there would strand rows silently with no
    /// retry. The exempt spawn proceeds past the cap.
    #[tokio::test]
    async fn boot_respawn_spawn_is_exempt_from_the_limit() {
        let (workspace, _config_dir) = stub_with_project_cap(2);
        let project = seeded_project(&workspace);
        workspace.insert_live_worker(&project, fake_worker_entry("w1", "w1"));
        workspace.insert_live_worker(&project, fake_worker_entry("w2", "w2"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w3".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            true,
            tx,
        );

        let reply = rx.await.expect("reply");
        assert!(reply.is_ok(), "boot respawn must not be refused by the cap: {:?}", reply.err());
        assert_eq!(
            workspace.list_live_workers(&project).len(),
            3,
            "the exempt spawn creates its worker"
        );
        if let Ok(reply) = reply {
            workspace.release_session(&SessionSlot::from_str_for_test(reply.session_id));
        }
    }

    /// #976: a despawn frees its slot; the next lead-driven spawn
    /// succeeds.
    #[tokio::test]
    async fn despawn_frees_a_spawn_slot() {
        let (workspace, _config_dir) = stub_with_project_cap(1);
        let project = seeded_project(&workspace);
        workspace.insert_live_worker(&project, fake_worker_entry("w1", "w1"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w2".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let err = rx.await.expect("reply").expect_err("at-limit spawn must refuse");
        assert!(err.contains("worker limit reached"), "names the refusal: {err}");

        let (despawn_tx, despawn_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "w1", false, despawn_tx);
        let outcome = despawn_rx.await.expect("despawn reply");
        assert!(
            matches!(outcome, crate::protocol::DespawnResult::Despawned { .. }),
            "the worker despawns: {outcome:?}"
        );

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "w2".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("reply");
        assert!(reply.is_ok(), "the freed slot lets the next spawn through: {:?}", reply.err());
        if let Ok(reply) = reply {
            workspace.release_session(&SessionSlot::from_str_for_test(reply.session_id));
        }
    }

    /// A `Failed` worker holds no cap slot, matching the label-dedup
    /// which already treats `Failed` as not-live. One connection
    /// failure must not wedge every later spawn until a manual despawn.
    #[tokio::test]
    async fn a_failed_worker_does_not_consume_a_cap_slot() {
        let (workspace, _config_dir) = stub_with_project_cap(1);
        let project = seeded_project(&workspace);
        let mut failed = fake_worker_entry("dead", "dead-1");
        failed.status = forge_primitives::WorkerLiveness::Failed;
        workspace.insert_live_worker(&project, failed);

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project,
            WorkerSpawnArgs {
                label: "fresh".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead"),
            None,
            false,
            tx,
        );
        let reply = rx.await.expect("reply");
        assert!(reply.is_ok(), "the Failed worker must not consume the slot: {:?}", reply.err());
        if let Ok(reply) = reply {
            workspace.release_session(&SessionSlot::from_str_for_test(reply.session_id));
        }
    }

    /// `handle_close_worker` removes the worker entry, releases the
    /// session, and emits `WorkerStatusChanged { Removed }`. The
    /// label-targeting picks the latest-spawned duplicate.
    #[tokio::test]
    async fn close_worker_removes_entry_and_emits_removed() {
        let (workspace, mut rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        workspace.insert_live_worker(&project, fake_worker_entry("r1", "worker-1"));

        handle_close_worker(&workspace, &project, "r1");

        assert!(workspace.list_live_workers(&project).is_empty());
        let mut frames: Vec<(&str, SessionSlot)> = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Releasing { key } => frames.push(("releasing", key)),
                SessionUpdate::WorkerStatusChanged {
                    action: WorkerStatusAction::Removed,
                    status,
                    ..
                } => {
                    frames.push(("removed", status.slot));
                }
                _ => {}
            }
        }
        // The release first, so other views' rows say where the seat is going
        // from the gesture; the removal follows it (#1930).
        assert_eq!(
            frames.iter().map(|(kind, _)| *kind).collect::<Vec<_>>(),
            vec!["releasing", "removed"],
            "the close announces the release ahead of the removal: {frames:?}",
        );
        assert_eq!(frames[0].1, frames[1].1, "and both name the seat that closed");
    }

    /// **A live worker's despawn announces the release at the gesture**, not
    /// at its removal: the worktree cleanup can run for minutes and the
    /// removal frame only follows it, so without this every other view's row
    /// reads that worker as working for the whole cleanup (#1930).
    #[tokio::test]
    async fn a_live_despawn_announces_the_release_before_its_removal() {
        let (workspace, mut rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        workspace.insert_live_worker(&project, fake_worker_entry("r1", "worker-1"));

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "r1", false, tx);
        let _ = resp_rx.await.expect("despawn result");

        let mut frames: Vec<(&str, SessionSlot)> = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            match std::sync::Arc::unwrap_or_clone(frame.update) {
                SessionUpdate::Releasing { key } => frames.push(("releasing", key)),
                SessionUpdate::WorkerStatusChanged {
                    action: WorkerStatusAction::Removed,
                    status,
                    ..
                } => {
                    frames.push(("removed", status.slot));
                }
                _ => {}
            }
        }
        assert_eq!(
            frames.iter().map(|(kind, _)| *kind).collect::<Vec<_>>(),
            vec!["releasing", "removed"],
            "the despawn announces the release ahead of the removal: {frames:?}",
        );
        assert_eq!(frames[0].1, frames[1].1, "and both name the seat that went");
    }

    /// **A spawned seat warms the browser it resolves to.** The call is off
    /// the spawn's own path, so the seat's first page call meets a host
    /// already up rather than paying the launch itself.
    #[tokio::test]
    async fn a_spawned_seat_warms_its_browser() {
        let (workspace, _rx) = Workspace::testing_stub();
        let (calls, mut heard) = tokio::sync::mpsc::unbounded_channel();
        workspace.install_browser_host(Arc::new(crate::browser::testing::StubHost { calls }));
        let seat = forge_primitives::SessionSlot::from_str_for_test("warm-seat");

        warm_browser_seat(&workspace, &seat);

        let (what, args) = tokio::time::timeout(std::time::Duration::from_secs(5), heard.recv())
            .await
            .expect("the fleet hears the warm")
            .expect("the stub's channel");
        assert_eq!(what, "warm", "the spawn asks the fleet to bring the profile up");
        assert_eq!(args, serde_json::json!(seat));
    }

    /// **The warm rides the lead's spawn path, not a call of its own.** A
    /// lead spawned through `handle_spawn_project` asks the fleet to bring
    /// its profile up as it starts, so the first browser call does not pay
    /// the host launch.
    #[tokio::test]
    async fn a_spawned_lead_warms_its_browser_through_the_spawn_path() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let workspace = Arc::new(Workspace::new_for_test(dir.path().to_owned()).expect("new"));
        workspace.seed_test_ready_account("Stargate");
        workspace.seed_test_gateway_ready(true);
        let (calls, mut heard) = tokio::sync::mpsc::unbounded_channel();
        workspace.install_browser_host(Arc::new(crate::browser::testing::StubHost { calls }));
        forge_agent::set_test_sdk_binary(Some(
            concat!(env!("CARGO_MANIFEST_DIR"), "/../forge-sdk/tests/fixtures/mock_claude.sh")
                .to_owned(),
        ));

        let _ = handle_spawn_project(&workspace, "forge", SessionLaunchSettings::default());

        let (what, args) = tokio::time::timeout(std::time::Duration::from_secs(5), heard.recv())
            .await
            .expect("the spawn path hears the warm")
            .expect("the stub's channel");
        assert_eq!(what, "warm", "the spawn path is what asks the fleet");
        assert_eq!(
            args,
            serde_json::json!(SessionSlot::lead("Default", "forge")),
            "the lead's own seat is warmed",
        );
        forge_agent::set_test_sdk_binary(None);
    }

    /// **A despawn sweeps the browsers to the seats that remain.** The seat
    /// that went is not in the set and the project's lead is, which is the
    /// whole of what the fleet needs to close exactly the down seat's tabs.
    #[tokio::test]
    async fn a_despawn_sweeps_the_browsers_to_the_remaining_seats() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let dir = tempfile::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-seat-sweep-test");
        workspace.insert_live_worker(&project, fake_worker_entry("gone", "session-gone"));

        let (calls, mut heard) = tokio::sync::mpsc::unbounded_channel();
        workspace.install_browser_host(Arc::new(crate::browser::testing::StubHost { calls }));

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "gone", false, tx);
        let _ = resp_rx.await.expect("despawn result");

        // **The close's own signals come first**: the seat is ended and its
        // tabs replaced before the sweep names the seats that remain.
        let mut ended = Vec::new();
        let (what, sweep) = loop {
            let (what, args) =
                tokio::time::timeout(std::time::Duration::from_secs(5), heard.recv())
                    .await
                    .expect("the sweep is asked")
                    .expect("the channel is fed");
            if what == "sweep_sessions" {
                break (what, args);
            }
            if what == "session_ended" {
                ended.push(args);
            }
        };
        assert_eq!(what, "sweep_sessions", "the fleet is told the seats that remain");
        assert_eq!(ended.len(), 1, "the despawned seat was told ended before the sweep: {ended:?}");
        let labels: Vec<&str> = sweep["seats"]
            .as_array()
            .expect("a seat set")
            .iter()
            .filter_map(|seat| seat.get("label").and_then(serde_json::Value::as_str))
            .collect();
        assert_eq!(labels, vec!["lead"], "the seat that went is not in the set");
        assert!(
            sweep["generation"].as_u64().is_some_and(|generation| generation >= 1),
            "a capture generation travels with the set, and zero is the fleet's floor: {sweep}",
        );
    }

    /// Regression: closing ONE worker must NOT cascade to the others.
    /// Before the fix, `handle_close_worker` called the cascading
    /// `release_session` AFTER `remove_latest_worker`. The cascade-
    /// detection (`in_catalog && !is_worker`) saw the orphaned
    /// session_key as a lead (because it was already gone from
    /// `live_workers` by step 1) and drained every OTHER worker.
    /// The fix calls `release_session_inner` directly.
    #[tokio::test]
    async fn close_one_worker_leaves_other_workers_intact() {
        let (workspace, mut rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        workspace.insert_live_worker(&project, fake_worker_entry("worker-a", "session-a"));
        workspace.insert_live_worker(&project, fake_worker_entry("worker-b", "session-b"));
        workspace.insert_live_worker(&project, fake_worker_entry("worker-c", "session-c"));
        assert_eq!(workspace.list_live_workers(&project).len(), 3);

        handle_close_worker(&workspace, &project, "worker-b");

        let remaining = workspace.list_live_workers(&project);
        assert_eq!(
            remaining.len(),
            2,
            "only the targeted worker should be removed; got {remaining:?}"
        );
        let labels: Vec<&str> = remaining.iter().map(|w| w.label.as_str()).collect();
        assert!(labels.contains(&"worker-a"), "worker-a must survive");
        assert!(labels.contains(&"worker-c"), "worker-c must survive");

        // Exactly one Removed event for worker-b.
        let mut removed_labels: Vec<String> = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::WorkerStatusChanged { action, status, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && action == WorkerStatusAction::Removed
            {
                removed_labels.push(status.label);
            }
        }
        assert_eq!(
            removed_labels,
            vec!["worker-b".to_owned()],
            "exactly one Removed event for the closed worker; got {removed_labels:?}"
        );
    }

    /// `handle_close_worker` for an unknown label logs but does not
    /// panic and emits no events. Defensive branch when a view's
    /// click races a lead-cascade or a concurrent close.
    #[tokio::test]
    async fn close_worker_unknown_label_is_noop() {
        let (workspace, mut rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");

        handle_close_worker(&workspace, &project, "missing");

        assert!(rx.try_recv().is_err(), "no events emitted for unknown label");
    }

    fn run_git(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:?}");
    }

    /// `git rev-parse <rev>` in `dir`, trimmed.
    fn git_rev(dir: &std::path::Path, rev: &str) -> String {
        let out = std::process::Command::new("git")
            .args(["rev-parse", rev])
            .current_dir(dir)
            .output()
            .expect("spawn git");
        assert!(out.status.success(), "git rev-parse {rev} failed in {dir:?}");
        String::from_utf8_lossy(&out.stdout).trim().to_owned()
    }

    fn branch_exists(repo: &std::path::Path, branch: &str) -> bool {
        let out = std::process::Command::new("git")
            .args(["rev-parse", "--verify", "--quiet", &format!("refs/heads/{branch}")])
            .current_dir(repo)
            .output()
            .expect("spawn git");
        match out.status.code() {
            Some(0) => true,
            Some(1) => false,
            other => panic!("git rev-parse in {repo:?} exited {other:?}, so absence is unproven"),
        }
    }

    fn fake_git_worker_entry(label: &str, key: &str) -> crate::mcp::workers::types::WorkerEntry {
        let mut entry = fake_worker_entry(label, key);
        entry.is_git_repo_at_spawn = true;
        entry
    }

    /// The wave asks about the ROW's tree, not the project's: a worker
    /// pointed at another repository whose own worktree is gone is
    /// skipped, even though the project's own worktree stands - a wave
    /// composing the project path sees a directory and dispatches a
    /// re-spawn that has nowhere to start.
    #[test]
    fn the_boot_wave_reads_a_cwd_rows_own_tree() {
        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 repo = tempfile::tempdir().expect("git project dir");
        run_git(repo.path(), &["init", "-q"]);
        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.
        std::fs::create_dir_all(repo.path().join(".claude").join("worktrees").join("moved"))
            .expect("project worktree");
        // The row's own tree has none.
        let sibling = tempfile::tempdir().expect("sibling repo");
        run_git(sibling.path(), &["init", "-q"]);
        let root = std::fs::canonicalize(sibling.path()).expect("canonical sibling");
        workspace.seed_test_worker_row_at(&proj_x, "moved", &root.to_string_lossy(), true);
        // A control: a project-root worker in the same wave, so a wave
        // that skipped everything would fail this test too.
        workspace.seed_test_worker_row(&proj_x, "at-home");

        let rows = workspace.worker_rows_for_project(&proj_x);
        workspace.dispatch_worker_respawns(
            &SessionSlot::lead("TestOrg", "proj-x"),
            &proj_x,
            &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(&"moved".to_owned()),
            "a cwd worker whose own tree has no worktree must not be re-spawned; \
             spawned {spawned:?}",
        );
        assert!(
            spawned.contains(&"at-home".to_owned()),
            "and the project's own worker still re-spawns; spawned {spawned:?}",
        );
    }

    /// A non-git worker despawns cleanly with no worktree step (the
    /// teardown runs, nothing touches a worktree).
    #[tokio::test]
    async fn despawn_non_git_worker_tears_down_without_worktree_step() {
        let (workspace, mut rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        workspace.insert_live_worker(&project, fake_worker_entry("r1", "worker-1"));

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "r1", false, tx);
        let result = resp_rx.await.expect("despawn result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "non-git worker despawns cleanly: {result:?}"
        );
        assert!(workspace.list_live_workers(&project).is_empty(), "worker removed");
        assert_eq!(
            drain_removed_dispositions(&mut rx),
            vec![WorktreeDisposition::Absent],
            "a worker that never had a worktree must not claim one",
        );
    }

    /// A stub over a configured `proj-x` with a real store, plus the key
    /// that project resolves under and the update receiver the stub minted.
    /// The despawn fall-through needs the store: it reads and writes the
    /// worker's durable row, so a stub with no DB never reaches the arm.
    struct StoreBackedStub {
        workspace: Arc<Workspace>,
        project: ProjectKey,
        rx: tokio::sync::mpsc::UnboundedReceiver<SeatUpdate>,
        /// Held so the store outlives the test.
        _dir: tempfile::TempDir,
    }

    fn store_backed_stub() -> StoreBackedStub {
        let (workspace, rx) = Workspace::testing_stub();
        workspace.seed_test_project("proj-x", "/tmp/proj-x");
        let dir = tempdir().expect("tempdir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        let project = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some("/tmp/proj-x")),
        );
        StoreBackedStub { workspace, project, rx, _dir: dir }
    }

    /// A durable row can outlive its live worker - the tag-write rollback
    /// removes the entry without the row - and the row is then the only
    /// handle on a worker the next boot re-spawns. Despawn is the tool a
    /// lead reaches for to remove a durable worker, so it must clear the
    /// row rather than report NotFound over it (#1142).
    #[tokio::test]
    async fn despawn_clears_a_stranded_row_with_no_live_worker() {
        let StoreBackedStub { workspace, project, mut rx, .. } = store_backed_stub();
        workspace
            .record_worker_row(
                &project,
                "stranded",
                "stranded-id",
                "charter",
                Some("kick"),
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the row whose live worker is gone");

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "stranded", false, tx);
        let result = resp_rx.await.expect("despawn result");

        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "clearing the row is a despawn, not a NotFound over the row it just removed: \
             {result:?}",
        );
        assert!(
            workspace.worker_rows_for_project(&project).is_empty(),
            "the stranded row must not survive the despawn that reported the worker gone",
        );
        assert!(
            rx.try_recv().is_err(),
            "nothing live was torn down, so there is no Removed event to emit",
        );
    }

    /// A despawn takes the worker's durable records with it, and a
    /// stranded row's label can still own subscriptions and crons from
    /// before it was orphaned. Clearing the row alone would report a
    /// completed despawn while leaving exactly the records the live path
    /// exists to clear.
    #[tokio::test]
    async fn despawn_clears_a_stranded_workers_subscriptions_and_crons() {
        let StoreBackedStub { workspace, project, .. } = store_backed_stub();
        workspace
            .record_worker_row(
                &project,
                "stranded",
                "stranded-id",
                "c",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the stranded row");
        let sub = forge_primitives::GotifySubscription {
            id: uuid::Uuid::new_v4(),
            project: "proj-x".to_owned(),
            team_role: Some("stranded".to_owned()),
            applications: Vec::new(),
            min_priority: None,
            created_at: std::time::SystemTime::UNIX_EPOCH,
        };
        workspace.add_gotify_subscription(sub.clone(), true);
        workspace.push_cron(forge_primitives::CronEntry {
            id: forge_primitives::CronId::from("stranded-cron"),
            project_name: "proj-x".to_owned(),
            kind: forge_primitives::CronKind::Recurring("0 9 * * *".to_owned()),
            prompt: "stand-up".to_owned(),
            created_at: std::time::SystemTime::UNIX_EPOCH,
            description: None,
            last_fire: None,
            next_fire: std::time::SystemTime::UNIX_EPOCH,
            team_role: Some("stranded".to_owned()),
            wake: true,
        });

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "stranded", false, tx);
        assert!(
            matches!(
                resp_rx.await.expect("result"),
                crate::protocol::DespawnResult::Despawned { .. }
            ),
            "the row was cleared, so the despawn reports the worker gone",
        );

        assert!(
            workspace.gotify_subscriptions_for_project("proj-x").iter().all(|s| s.id != sub.id),
            "the label's subscription goes with the worker it was registered for",
        );
        assert!(
            workspace.crons_for_project("proj-x").is_empty(),
            "and so do its crons, which would otherwise keep firing for a label with no worker",
        );
    }

    /// `lead` is the project lead's own row, not a worker: it is the
    /// stored id an ordinary boot resumes the lead from. A despawn for it
    /// finds no live worker, and the fall-through must not treat that as a
    /// stranded worker row and clear it.
    #[tokio::test]
    async fn despawn_refuses_to_clear_the_lead_row() {
        let StoreBackedStub { workspace, project, mut rx, .. } = store_backed_stub();
        workspace
            .record_worker_row(
                &project,
                crate::store::sessions::LEAD_LABEL,
                "lead-uuid",
                "the lead's charter",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed the lead's row");

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, crate::store::sessions::LEAD_LABEL, false, tx);

        assert!(
            matches!(resp_rx.await.expect("result"), crate::protocol::DespawnResult::NotFound),
            "there is no worker by that label, so the answer is NotFound",
        );
        // Read the row directly: `worker_rows_for_project` excludes the
        // lead's row by design, so it cannot witness this either way.
        let stored = {
            let db = workspace.db.lock();
            crate::store::sessions::get(
                db.as_ref().expect("db"),
                "TestOrg",
                "proj-x",
                crate::store::sessions::LEAD_LABEL,
            )
            .expect("read")
        };
        assert!(
            stored.is_some(),
            "the lead's row must survive a despawn for its label; cleared, the next boot mints a \
             fresh id and orphans the lead's conversation",
        );
        assert!(rx.try_recv().is_err(), "nothing live was torn down, so no Removed event");
    }

    /// Despawning an unknown label reports NotFound and emits nothing. The
    /// store is real, so the answer comes from the fall-through's own
    /// "no row there" arm rather than from a stub that cannot reach it.
    #[tokio::test]
    async fn despawn_unknown_label_reports_not_found() {
        let StoreBackedStub { workspace, project, mut rx, .. } = store_backed_stub();
        // A sibling row, so "nothing was cleared" cannot pass because the
        // store was empty.
        workspace
            .record_worker_row(
                &project,
                "other",
                "other-id",
                "c",
                None,
                None,
                false,
                crate::mcp::workers::types::WorkerTree { is_git_repo: false, cwd: None },
                None,
            )
            .expect("seed a row the despawn must leave alone");

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "missing", false, tx);

        assert!(matches!(resp_rx.await.expect("result"), crate::protocol::DespawnResult::NotFound));
        assert_eq!(
            workspace.worker_rows_for_project(&project).len(),
            1,
            "and the sibling row is untouched",
        );
        assert!(rx.try_recv().is_err(), "no events for unknown label");
    }

    /// A despawn whose store cannot be read or written is not a despawn of
    /// an absent worker: reporting NotFound there sends the caller looking
    /// for a worker that may be right there, with the row still on disk.
    #[tokio::test]
    async fn despawn_reports_a_store_failure_apart_from_an_absent_label() {
        let (workspace, _rx) = Workspace::testing_stub();
        // A configured project with no store: the shape of a forge that
        // came up without its database.
        workspace.seed_test_project("proj-x", "/tmp/proj-x");
        let project = ProjectKey::new(
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some("/tmp/proj-x")),
        );

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "stranded", false, tx);

        let result = resp_rx.await.expect("result");
        let crate::protocol::DespawnResult::Failed { reason } = result else {
            panic!("an unreadable store must not be reported as an absent row; got {result:?}");
        };
        assert!(
            reason.contains("stranded"),
            "the failure names the label it could not clear: {reason}",
        );
    }

    /// The same failure at the surface a caller actually reads: the facade
    /// must hand it back as a failed despawn, since `agents__despawn`
    /// renders `UnknownLabel` as "no live worker with label ...", which
    /// sends the lead looking for a worker that is right there.
    #[tokio::test]
    async fn a_despawn_store_failure_is_not_an_unknown_label() {
        let dir = tempdir().expect("tempdir");
        write_forge_toml(dir.path(), FIXTURE_PROJECT_PATH);
        let config = crate::config::load_from_dir(dir.path()).expect("load config");
        // No db installed: the shape of a forge that came up without its
        // store, where whether a row exists cannot be answered at all.
        let (workspace, _rx) = Workspace::testing_stub_with_config(dir.path().to_owned(), config)
            .expect("stub over the fixture config");
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&workspace);

        let error = facade
            .despawn_worker(&SessionSlot::lead("Default", "forge"), "stranded", false)
            .await
            .expect_err("a store that cannot be read is not a despawn of an absent worker");

        assert!(
            matches!(error, crate::mcp::workers::facade::WorkerDespawnError::DispatchFailed { .. }),
            "the caller must hear a failed despawn rather than an unknown label: {error:?}",
        );
    }

    /// Build a workspace whose single project points at a temp git
    /// repo, add a worktree at `<project>/.claude/worktrees/<label>`,
    /// and register a live git-worker under it. The worktree is built
    /// from the project path `list_projects` reports so the handler's
    /// `worker_tag_dir` resolves to the exact on-disk worktree (avoids
    /// the macOS /tmp symlink mismatch). Returns the pieces the test
    /// asserts on plus the tempdir guards (which must outlive the test).
    fn git_despawn_fixture(
        label: &str,
    ) -> (Arc<Workspace>, ProjectKey, std::path::PathBuf, tempfile::TempDir, tempfile::TempDir)
    {
        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        run_git(repo.path(), &["config", "user.email", "t@example.com"]);
        run_git(repo.path(), &["config", "user.name", "Test"]);
        run_git(repo.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(repo.path().join("README.md"), "seed").expect("write seed");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "-q", "-m", "init"]);

        let config = tempdir().expect("config tempdir");
        let repo_path_str = repo.path().to_string_lossy().replace('\\', "/");
        std::fs::write(
            forge_toml_path(config.path()),
            format!(
                "[[orgs]]\nname = \"Default\"\naccounts = [\"Stargate\"]\n\n[[orgs.projects]]\nname = \"forge\"\npath = \"{repo_path_str}\"\n\n[[accounts]]\ndisplay_name = \"Stargate\"\ntoken = \"t\"\nmodels = [\"claude-sonnet-5\"]\nprovider = \"anthropic\"\n"
            ),
        )
        .expect("write forge.toml");

        let workspace =
            Arc::new(Workspace::new_for_test(config.path().to_owned()).expect("workspace new"));
        let view = workspace.list_projects().into_iter().next().expect("one project");
        let project_key = view.key.clone();
        let project_path = view.path.clone();

        let wt = project_path.join(".claude").join("worktrees").join(label);
        std::fs::create_dir_all(wt.parent().expect("wt parent")).expect("mkdir worktrees");
        // `-b worktree-<label>` is what claude's `--worktree <label>` does;
        // without it git auto-names the branch after the directory and the
        // reap has nothing matching to find.
        run_git(
            &project_path,
            &[
                "worktree",
                "add",
                "-q",
                "-b",
                &format!("worktree-{label}"),
                wt.to_str().expect("utf8 path"),
            ],
        );

        workspace.insert_live_worker(&project_key, fake_git_worker_entry(label, "worker-1"));
        (workspace, project_key, wt, repo, config)
    }

    /// The despawn fixture whose worker worktree holds an initialized
    /// submodule. The repo gains the submodule and the worktree's branch
    /// follows it, then `git submodule update --init` runs in the
    /// worktree - what a worker does - which is what leaves
    /// `<repo>/.git/worktrees/<label>/modules` behind.
    fn git_despawn_fixture_with_submodule(
        label: &str,
    ) -> (Arc<Workspace>, ProjectKey, std::path::PathBuf, tempfile::TempDir, tempfile::TempDir)
    {
        let (workspace, project_key, wt, repo, config) = git_despawn_fixture(label);
        let source = tempdir().expect("submodule source tempdir");
        run_git(source.path(), &["init", "-q"]);
        run_git(source.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(source.path().join("sub.txt"), "submodule seed").expect("write seed");
        run_git(source.path(), &["add", "."]);
        run_git(
            source.path(),
            &[
                "-c",
                "user.email=t@example.com",
                "-c",
                "user.name=Test",
                "commit",
                "-q",
                "-m",
                "sub",
            ],
        );
        run_git(
            repo.path(),
            &[
                "-c",
                "protocol.file.allow=always",
                "submodule",
                "add",
                source.path().to_str().expect("utf8 path"),
                "contracts/sub",
            ],
        );
        run_git(repo.path(), &["commit", "-q", "-m", "add submodule"]);
        // The worktree is cut from the pre-submodule commit, so its branch
        // has to take the repo's HEAD before the submodule exists to init.
        run_git(&wt, &["reset", "--hard", &git_rev(repo.path(), "HEAD")]);
        run_git(&wt, &["-c", "protocol.file.allow=always", "submodule", "update", "--init"]);
        (workspace, project_key, wt, repo, config)
    }

    /// The shape `git worktree remove` refuses however clean the worktree
    /// is: a worker that ran `git submodule update --init` in its own
    /// worktree, whose directory the despawn must still remove. Left
    /// unfixed, git's refusal reads as a disk-state failure and the
    /// maintainer gets a toast about a worktree that is in fact clean.
    #[tokio::test]
    async fn despawn_removes_a_clean_worktree_holding_initialized_submodules() {
        let (workspace, project_key, wt, repo, _config) =
            git_despawn_fixture_with_submodule("reviewer");
        // Fixture precondition, and the reason the test exists: git will
        // not remove this worktree unforced. Asserted rather than assumed
        // so a git that stops refusing fails here instead of quietly
        // passing without exercising the fix.
        assert!(
            repo.path().join(".git").join("worktrees").join("reviewer").join("modules").is_dir(),
            "fixture precondition: the worktree's gitdir holds the submodule's modules dir",
        );
        let refused = std::process::Command::new("git")
            .args(["worktree", "remove", wt.to_str().expect("utf8 path")])
            .current_dir(wt.parent().expect("wt parent"))
            .output()
            .expect("spawn git");
        assert!(
            !refused.status.success(),
            "fixture precondition: git refuses this worktree unforced"
        );
        assert!(wt.exists(), "and the refusal leaves it on disk");
        let mut rx = workspace.subscribe_answerer();

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "a clean worktree git refuses by shape despawns without the caller forcing: {result:?}"
        );
        assert!(!wt.exists(), "the worktree is removed, not orphaned");
        assert_eq!(
            drain_removed_dispositions(&mut rx),
            vec![WorktreeDisposition::Removed],
            "and the toast is told the disk agrees, not that the removal failed",
        );
        assert!(
            !branch_exists(repo.path(), "worktree-reviewer"),
            "the branch behind it is reaped as usual"
        );
    }

    /// The despawn leftover: `git worktree remove` failed on the delete
    /// stage - a build still writing into `target/` while the removal
    /// walked the tree, which git reports as "Directory not empty" - and
    /// because it deregisters the path before that walk, the directory
    /// survives with no registration. Every later `git worktree remove`
    /// refuses it as "not a working tree", and the despawn's clean
    /// re-check cannot run at all, so before the fallback this left the
    /// directory behind for good.
    ///
    /// The race itself is not reproducible on demand, so the test drives
    /// the state it leaves: the deregistered directory, with the build
    /// tree still in it. The despawn is forced because a deregistered
    /// tree cannot be read by git, which blocks an unforced despawn by
    /// design - in the field the check passed a moment earlier, while the
    /// removal was still racing the build.
    #[tokio::test]
    async fn despawn_removes_a_deregistered_leftover_directory_that_git_refuses() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("leftover");
        let target = wt.join("target").join("debug");
        std::fs::create_dir_all(&target).expect("target dir");
        std::fs::write(target.join("obj.o"), "x").expect("object file");
        // Deregister without deleting the directory: exactly what the
        // failed delete above leaves.
        std::fs::remove_dir_all(repo.path().join(".git").join("worktrees").join("leftover"))
            .expect("deregister the worktree");
        // Fixture precondition, asserted rather than assumed so a git that
        // stops refusing fails here instead of passing without exercising
        // the fallback.
        let refused = std::process::Command::new("git")
            .args(["worktree", "remove", "--force", wt.to_str().expect("utf8 path")])
            .current_dir(wt.parent().expect("wt parent"))
            .output()
            .expect("spawn git");
        assert!(
            !refused.status.success(),
            "fixture precondition: git refuses the deregistered leftover outright"
        );
        assert!(wt.exists(), "and the refusal leaves it on disk");
        let mut rx = workspace.subscribe_answerer();

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "leftover", true, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "the leftover directory is removed, so the despawn carries no warning: {result:?}"
        );
        assert!(!wt.exists(), "the leftover directory is gone, not orphaned");
        assert_eq!(
            drain_removed_dispositions(&mut rx),
            vec![WorktreeDisposition::Removed],
            "and the toast is told the disk agrees, not that the removal failed",
        );
        assert!(
            !branch_exists(repo.path(), "worktree-leftover"),
            "the branch behind it is reaped as usual"
        );
    }

    /// The leftover fallback anchors on the WORKER's own tree: a
    /// deregistered worktree under a sibling repository is removed from
    /// there, where a fallback composing the project's path would refuse
    /// the directory (it is not under the project's worktrees root) and
    /// leave it behind with a warning - the outcome the fallback exists
    /// to prevent.
    #[tokio::test]
    async fn despawn_removes_a_cwd_workers_deregistered_leftover() {
        let (workspace, project_key, _project_wt, _repo, _config) =
            git_despawn_fixture("traveller");
        let dir = tempfile::tempdir().expect("store dir");
        workspace.install_db_for_test(
            crate::store::Db::open(&dir.path().join("db.redb")).expect("open db"),
        );
        // The worker's own tree, with the worktree claude would fork.
        let sibling = tempfile::tempdir().expect("sibling repo");
        run_git(sibling.path(), &["init", "-q"]);
        run_git(sibling.path(), &["config", "commit.gpgsign", "false"]);
        std::fs::write(sibling.path().join("README.md"), "seed").expect("write seed");
        run_git(sibling.path(), &["add", "."]);
        run_git(
            sibling.path(),
            &[
                "-c",
                "user.email=t@example.com",
                "-c",
                "user.name=Test",
                "commit",
                "-q",
                "-m",
                "init",
            ],
        );
        let root = std::fs::canonicalize(sibling.path()).expect("canonical sibling");
        let wt = root.join(".claude").join("worktrees").join("traveller");
        std::fs::create_dir_all(wt.parent().expect("wt parent")).expect("mkdir worktrees");
        run_git(
            &root,
            &["worktree", "add", "-q", "-b", "worktree-traveller", wt.to_str().expect("utf8")],
        );
        // The state a failed delete leaves: deregistered, directory on
        // disk. Asserted rather than assumed, so a git that stops
        // refusing fails here instead of passing without the fallback.
        std::fs::remove_dir_all(root.join(".git").join("worktrees").join("traveller"))
            .expect("deregister the worktree");
        let refused = std::process::Command::new("git")
            .args(["worktree", "remove", "--force", wt.to_str().expect("utf8 path")])
            .current_dir(wt.parent().expect("wt parent"))
            .output()
            .expect("spawn git");
        assert!(
            !refused.status.success(),
            "fixture precondition: git refuses the deregistered leftover outright"
        );
        assert!(wt.exists(), "and the refusal leaves it on disk");

        // The row and the live entry both name the sibling tree.
        workspace.seed_test_worker_row_at(&project_key, "traveller", &root.to_string_lossy(), true);
        workspace.remove_latest_worker(&project_key, "traveller");
        let mut entry = fake_git_worker_entry("traveller", "worker-1");
        entry.cwd = Some(root.clone());
        workspace.insert_live_worker(&project_key, entry);

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "traveller", true, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned { worktree_cleanup_warning: None, .. }
            ),
            "the leftover is removed from the worker's own tree: {result:?}"
        );
        assert!(!wt.exists(), "the leftover directory is gone, not orphaned");
    }

    /// A despawn hands back with the worktree still on disk: its cleanup
    /// runs off the caller, and the removal happens behind it.
    ///
    /// The #1633 shape. The cleanup used to run inline in the caller's
    /// task, so a whole `git worktree remove` - minutes for a worker's
    /// build tree - sat on a runtime worker, and every timer in the
    /// process, the socket's frame delivery above all, stopped for the
    /// removal's entire duration.
    ///
    /// **The assertion is an ordering, not a clock, but it is not free of
    /// scheduling.** The gap it measures is the removal below - ~130ms for
    /// the 3,000 files here - against the caller's return, which is
    /// microseconds of its own work; the window it cannot close is a
    /// machine that deschedules THIS thread for longer than the whole
    /// removal, and the file count below is what keeps that window small.
    #[tokio::test]
    async fn a_despawn_hands_back_before_the_worktree_is_gone() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("slow");
        let target = wt.join("target").join("debug");
        std::fs::create_dir_all(&target).expect("target dir");
        for i in 0..3_000 {
            std::fs::write(target.join(format!("obj{i}.o")), b"x").expect("filler");
        }
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "slow", true, tx);
        assert!(
            wt.exists(),
            "the despawn ran its cleanup on the caller: the worktree is already gone by the \
             time it hands back",
        );
        let result = rx.await.expect("the cleanup answers");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "the cleanup still runs to completion behind the caller: {result:?}"
        );
        assert!(!wt.exists(), "and it still removes the worktree");
    }

    /// The despawn's dirty probe runs off the runtime's worker. `git status`
    /// walks the tracked tree, so on a big repository it can hold a worker -
    /// and the frames it serves - for a beat.
    ///
    /// The probe is slowed deterministically through git's own fsmonitor hook,
    /// which waits for a RUNTIME task to release it and records whether that
    /// happened. The despawn and that task share the single worker below, so
    /// an inline probe starves the task and the hook records the timeout; a
    /// probe handed off to another thread lets it run.
    #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
    async fn a_despawn_probes_the_worktree_off_the_runtime() {
        use std::os::unix::fs::PermissionsExt as _;

        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("probe");
        let dir = tempdir().expect("hook tempdir");
        let started = dir.path().join("probe-started");
        let release = dir.path().join("probe-release");
        let released = dir.path().join("probe-released");
        let hook = dir.path().join("fsmonitor.sh");
        // Bounded so the inline shape fails by verdict rather than by hanging
        // the machine's test run; the release arrives in milliseconds. The
        // trailing NUL-separated `/` is the hook's "all files changed" answer,
        // which leaves the probe's full scan - and so its verdict - untouched.
        fs::write(
            &hook,
            format!(
                "#!/bin/sh\n: > {started}\ni=0\n\
                 while [ ! -e {release} ] && [ $i -lt 100 ]; do sleep 0.01; i=$((i+1)); done\n\
                 [ -e {release} ] && : > {released}\n\
                 printf 'forge-probe\\0/\\0'\n",
                started = started.display(),
                release = release.display(),
                released = released.display(),
            ),
        )
        .expect("write the fsmonitor hook");
        std::fs::set_permissions(&hook, std::fs::Permissions::from_mode(0o755)).expect("+x");
        run_git(&wt, &["config", "core.fsmonitor", hook.to_str().expect("utf8 hook")]);

        // The task the hook waits on. It shares the single worker with the
        // despawn, so only a probe that does not hold the worker lets it run.
        let (task_started, task_release) = (started.clone(), release.clone());
        tokio::spawn(async move {
            while !task_started.exists() {
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
            fs::write(&task_release, b"go").expect("release the probe");
        });

        let (tx, rx) = tokio::sync::oneshot::channel();
        let despawn = tokio::spawn(async move {
            handle_despawn_worker(&workspace, &project_key, "probe", false, tx);
        });
        despawn.await.expect("the despawn task ran");
        assert!(started.exists(), "fixture precondition: git ran the fsmonitor hook");
        assert!(
            released.exists(),
            "the probe held the runtime: the task that releases its hook never ran",
        );

        let result = rx.await.expect("despawn result");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "the verdict is still clean and the despawn still lands: {result:?}",
        );
        assert!(!wt.exists(), "and the worktree is still removed");
    }

    /// A despawn's cleanup reserves its label: a spawn offered the same
    /// label while the worktree is mid-removal is refused by name, and the
    /// label frees again once the cleanup finishes.
    ///
    /// The window this closes is minutes long for a worker's build tree.
    /// Teardown frees the label the instant it removes the entry, while the
    /// removal it hands off is still deleting the directory a spawn
    /// admitted in that window would be handed (and the spawn path's own
    /// guards treat the surviving worktree as reusable).
    #[tokio::test]
    async fn a_despawn_reserves_its_label_until_the_cleanup_finishes() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("reserved");
        let target = wt.join("target").join("debug");
        std::fs::create_dir_all(&target).expect("target dir");
        for i in 0..3_000 {
            std::fs::write(target.join(format!("obj{i}.o")), b"x").expect("filler");
        }
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reserved", true, tx);
        assert!(
            workspace.despawn_cleanup_pending(&project_key, "reserved"),
            "the label is reserved from the handoff, before the cleanup ends",
        );

        let (spawn_tx, spawn_rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project_key.clone(),
            WorkerSpawnArgs {
                label: "reserved".to_owned(),
                charter: "c".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::lead("Default", "forge"),
            None,
            false,
            spawn_tx,
        );
        let refusal = spawn_rx.await.expect("the spawn answers").expect_err("refused");
        assert!(
            refusal.contains("still cleaning up"),
            "the refusal names the cleanup rather than racing it: {refusal}",
        );
        assert!(
            wt.exists(),
            "and the refusal came before anything touched the worktree being removed",
        );

        let result = rx.await.expect("the cleanup answers");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "the cleanup still runs to completion: {result:?}",
        );
        assert!(
            !workspace.despawn_cleanup_pending(&project_key, "reserved"),
            "and the label frees when the cleanup ends",
        );
    }

    /// A resume for a label whose despawn cleanup is still running is
    /// refused before anything mints a worktree.
    ///
    /// Most of the cleanup is spent in exactly the state
    /// `ensure_worker_worktree` will act on: the directory gone while git
    /// still holds the registration. Minting there re-attaches the branch
    /// the cleanup is about to reap, and the reap then reports a branch it
    /// could not delete for a reason this spawn made. The facade refuses on
    /// the mark, so the ensure never runs; without that refusal this call
    /// comes back as a worktree-creation failure instead of naming the
    /// cleanup.
    #[tokio::test]
    async fn a_resume_is_refused_before_it_mints_a_worktree_for_a_pending_cleanup() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("resumed");
        std::fs::remove_dir_all(&wt).expect("clear the worktree directory");
        let held = workspace.mark_despawn_cleanup_pending(&project_key, "resumed");
        let facade = crate::mcp::workers::facade::ProdWorkerFacade::from_arc(&workspace);
        let refusal = facade
            .spawn_worker(
                &SessionSlot::lead("Default", "forge"),
                "resumed".to_owned(),
                "c".to_owned(),
                None,
                None,
                false,
                true,
                None,
                None,
            )
            .await
            .expect_err("a spawn for a label mid-cleanup is refused");
        let crate::mcp::workers::facade::WorkerSpawnError::DispatchFailed { message } = refusal
        else {
            panic!("the refusal names the cleanup, not a worktree failure: {refusal:?}");
        };
        assert!(message.contains("still cleaning up"), "{message}");
        drop(held);
    }

    /// A git worker with a clean worktree despawns AND removes the
    /// worktree AND reaps the `worktree-<label>` branch behind it.
    #[tokio::test]
    async fn despawn_git_worker_removes_clean_worktree() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        assert!(wt.exists(), "worktree exists before despawn");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = rx.await.expect("result");
        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "clean git worktree despawns + removes: {result:?}"
        );
        assert!(workspace.list_live_workers(&project_key).is_empty(), "worker removed");
        assert!(!wt.exists(), "clean worktree removed");
        assert!(
            !branch_exists(repo.path(), "worktree-reviewer"),
            "the worktree branch is reaped, not left behind"
        );
        let record = std::fs::read_to_string(repo.path().join(".git").join("forge-worktrees"))
            .expect("the despawn recorded the removal");
        assert!(
            record.lines().any(|line| {
                line.starts_with("cleared\treviewer\t")
                    && line.contains(".claude/worktrees/reviewer")
            }),
            "the removal is admitted before git runs and cleared after it: {record}",
        );
    }

    /// The git fixture with its live entry gone and a durable row left
    /// behind: the shape the tag-write rollback leaves, and the one a
    /// despawn has to reach without a live worker to ask.
    fn stranded_git_despawn_fixture(
        label: &str,
    ) -> (Arc<Workspace>, ProjectKey, std::path::PathBuf, tempfile::TempDir, tempfile::TempDir)
    {
        let (workspace, project_key, wt, repo, config) = git_despawn_fixture(label);
        workspace.remove_latest_worker(&project_key, label);
        workspace
            .record_worker_row(
                &project_key,
                label,
                "stranded-id",
                "c",
                Some("kick"),
                None,
                false,
                // The row is what says this worker runs in a worktree, so
                // it is what the despawn has to read the gitness from.
                crate::mcp::workers::types::WorkerTree { is_git_repo: true, cwd: None },
                None,
            )
            .expect("seed the row that outlived its worker");
        (workspace, project_key, wt, repo, config)
    }

    /// A stranded git worker is still a worker the tool must clean up
    /// after: the row carries the gitness, so the despawn removes the
    /// worktree and reaps the branch with no live entry to ask. Skipped,
    /// the worktree is orphaned once the row is gone - nothing is left
    /// for a later despawn to resolve it from.
    #[tokio::test]
    async fn despawn_clears_a_stranded_git_workers_worktree() {
        let (workspace, project_key, wt, repo, _config) = stranded_git_despawn_fixture("reviewer");
        assert!(wt.exists(), "the worktree exists before the despawn");

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "a stranded worker's clean worktree is removed like any other: {result:?}"
        );
        assert!(!wt.exists(), "the stranded worktree is removed, not orphaned");
        assert!(
            !branch_exists(repo.path(), "worktree-reviewer"),
            "and the branch behind it is reaped"
        );
        assert!(
            workspace.worker_rows_for_project(&project_key).is_empty(),
            "with the row it was resolved from",
        );
    }

    /// A row the migration wrote carries no gitness until its worker's
    /// first spawn fills it in, and that is a worker with no known
    /// worktree rather than no worker. Reading "no gitness" as "no row"
    /// leaves exactly the class of stranded row #1142 exists to clear.
    #[tokio::test]
    async fn despawn_reaches_a_row_that_records_no_gitness() {
        let StoreBackedStub { workspace, project, mut rx, .. } = store_backed_stub();
        {
            let db = workspace.db.lock();
            crate::store::sessions::put(
                db.as_ref().expect("db"),
                &crate::store::sessions::SessionRecord {
                    org: "TestOrg".to_owned(),
                    project: "proj-x".to_owned(),
                    label: "migrated".to_owned(),
                    session_id: None,
                    charter: Some("c".to_owned()),
                    kick: None,
                    resume_kick: None,
                    interactive: None,
                    seat_state: None,
                    // The shape `migrate_from_dynamic_workers` writes.
                    is_git_repo: None,
                    mcp_families: None,
                    cwd: None,
                },
            )
            .expect("seed the row the migration writes");
        }

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project, "migrated", false, tx);

        assert!(
            matches!(
                resp_rx.await.expect("result"),
                crate::protocol::DespawnResult::Despawned { .. }
            ),
            "a row with no recorded gitness is a worker the despawn must reach",
        );
        assert!(
            workspace.worker_rows_for_project(&project).is_empty(),
            "and it is cleared like any other",
        );
        assert!(rx.try_recv().is_err(), "nothing live was torn down");
    }

    /// A stranded row whose worktree is already gone is the shape the boot
    /// wave skips, so the despawn has nothing to remove and must not report
    /// a removal failure over it. It also has nothing to protect, so it
    /// runs without `force`: the dirty probe cannot read a directory that
    /// is not there, and blocking on that would refuse a despawn over work
    /// no worktree can hold. The live shape reports git's failure for the
    /// same state, which `despawn_reports_removed_when_the_worktree_is_
    /// already_off_disk` pins.
    #[tokio::test]
    async fn a_stranded_row_whose_worktree_is_gone_despawns_without_force() {
        let (workspace, project_key, wt, repo, _config) = stranded_git_despawn_fixture("reviewer");
        run_git(repo.path(), &["worktree", "remove", wt.to_str().expect("utf8 path")]);
        assert!(!wt.exists(), "nothing on disk before the despawn");

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "a worktree that was never there is not a cleanup failure: {result:?}"
        );
        assert!(
            workspace.worker_rows_for_project(&project_key).is_empty(),
            "and the row still goes, which is the whole point of the call",
        );
        assert!(
            !branch_exists(repo.path(), "worktree-reviewer"),
            "the branch outlives the worktree - `git worktree remove` never deletes one - so a \
             worktree that is already gone is still a branch to reap, and with the directory gone \
             it is not checked out",
        );
        let record = std::fs::read_to_string(repo.path().join(".git").join("forge-worktrees"))
            .expect("the despawn recorded the gone worktree");
        assert!(
            record.lines().any(|line| {
                line.starts_with("cleared\treviewer\t")
                    && line.contains(".claude/worktrees/reviewer")
            }),
            "the already-gone arm retracts any admission rather than leaving one to outlive it: \
             {record}",
        );
    }

    /// A dirty stranded worktree blocks before anything is cleared, the
    /// same way a live one does: the row survives, so a later despawn (or
    /// `force`) still has the worker to act on.
    #[tokio::test]
    async fn a_dirty_stranded_worktree_blocks_before_the_row_goes() {
        let (workspace, project_key, wt, _repo, _config) = stranded_git_despawn_fixture("reviewer");
        std::fs::write(wt.join("uncommitted.txt"), "work in progress").expect("dirty the worktree");

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);

        assert!(
            matches!(
                resp_rx.await.expect("result"),
                crate::protocol::DespawnResult::Blocked { .. }
            ),
            "a dirty worktree blocks the despawn",
        );
        assert!(wt.exists(), "and the worktree is left alone");
        assert_eq!(
            workspace.worker_rows_for_project(&project_key).len(),
            1,
            "a blocked despawn clears nothing, so the row it would have taken is still there",
        );
    }

    /// Every `Removed` event's worktree disposition, in order, so a
    /// caller can pin the count as well as the value.
    fn drain_removed_dispositions(
        rx: &mut tokio::sync::mpsc::UnboundedReceiver<SeatUpdate>,
    ) -> Vec<WorktreeDisposition> {
        let mut seen = Vec::new();
        while let Ok(frame) = rx.try_recv() {
            if let SessionUpdate::WorkerStatusChanged { action, worktree, .. } =
                std::sync::Arc::unwrap_or_clone(frame.update)
                && action == WorkerStatusAction::Removed
            {
                seen.push(worktree);
            }
        }
        seen
    }

    /// The `x` button leaves the worktree on disk, so its event still
    /// reports it intact.
    #[tokio::test]
    async fn close_worker_reports_the_worktree_intact() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("reviewer");
        let mut rx = workspace.subscribe_answerer();

        handle_close_worker(&workspace, &project_key, "reviewer");

        assert_eq!(drain_removed_dispositions(&mut rx), vec![WorktreeDisposition::Intact]);
        assert!(wt.exists(), "the x button does not touch the worktree");
    }

    /// A despawn that removed the worktree says so on the event the
    /// close toast is built from.
    #[tokio::test]
    async fn despawn_reports_the_worktree_removed() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("reviewer");
        let mut rx = workspace.subscribe_answerer();

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let _ = resp_rx.await.expect("result");

        assert_eq!(drain_removed_dispositions(&mut rx), vec![WorktreeDisposition::Removed]);
        assert!(!wt.exists(), "the worktree really is gone");
    }

    /// A despawn whose removal FAILED leaves something on disk, and the
    /// event separates that from a successful removal. The leftovers the
    /// fallback may delete are removed (see the deregistered-leftover test
    /// above), so the shape that still fails is one the fallback must
    /// refuse: a symlink at the worktree path. Deleting through it would
    /// hit whatever directory it points at, so the fallback refuses, git's
    /// own refusal stands, and the toast says the removal failed.
    #[tokio::test]
    async fn despawn_reports_a_failed_removal_apart_from_a_successful_one() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        let elsewhere = wt.parent().expect("wt parent").join("precious");
        std::fs::create_dir_all(&elsewhere).expect("precious dir");
        std::fs::write(elsewhere.join("keep.txt"), "keep").expect("keep file");
        // Deregister and replace the directory with a symlink to it. The
        // deregistration is why the despawn needs `force`: an unreadable
        // tree blocks the unforced path by design.
        std::fs::remove_dir_all(repo.path().join(".git").join("worktrees").join("reviewer"))
            .expect("deregister the worktree");
        std::fs::remove_dir_all(&wt).expect("clear the worktree dir");
        std::os::unix::fs::symlink(&elsewhere, &wt).expect("symlink at the worktree path");
        let mut rx = workspace.subscribe_answerer();

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", true, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned { worktree_cleanup_warning: Some(_), .. }
            ),
            "the removal failed: {result:?}"
        );
        assert!(
            elsewhere.join("keep.txt").exists(),
            "the fallback refused the symlink instead of deleting through it"
        );
        assert_eq!(drain_removed_dispositions(&mut rx), vec![WorktreeDisposition::RemovalFailed]);
    }

    /// A worktree already gone from disk is Removed, whatever git's exit
    /// code says - the toast's only claim is about the directory.
    #[tokio::test]
    async fn despawn_reports_removed_when_the_worktree_is_already_off_disk() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        run_git(repo.path(), &["worktree", "remove", wt.to_str().expect("utf8 path")]);
        assert!(!wt.exists(), "nothing on disk before the despawn");
        let mut rx = workspace.subscribe_answerer();

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", true, tx);
        let result = resp_rx.await.expect("result");

        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned { worktree_cleanup_warning: Some(_), .. }
            ),
            "git still reports its own failure to the caller: {result:?}"
        );
        assert_eq!(drain_removed_dispositions(&mut rx), vec![WorktreeDisposition::Removed]);
    }

    /// The sync spawn rollback runs before claude was ever launched, so
    /// `--worktree <label>` never reached a process and there is no
    /// worktree for the toast to point at. The `ghost` project is
    /// advertised by the `list_projects` overlay but absent from
    /// `config.projects`, which is what fails the agent-handle lookup
    /// without spawning a subprocess.
    #[tokio::test]
    async fn spawn_rollback_reports_no_worktree_to_preserve() {
        let config = tempdir().expect("config tempdir");
        write_forge_toml(config.path(), FIXTURE_PROJECT_PATH);
        let workspace =
            Arc::new(Workspace::new_for_test(config.path().to_owned()).expect("workspace new"));

        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        workspace.seed_test_project("ghost", &repo.path().to_string_lossy());
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "ghost")
            .expect("seeded project present")
            .key;
        let mut rx = workspace.subscribe_answerer();

        let (tx, resp_rx) = tokio::sync::oneshot::channel();
        handle_spawn_worker(
            &workspace,
            project.clone(),
            WorkerSpawnArgs {
                label: "reviewer".to_owned(),
                charter: "charter".to_owned(),
                kick: None,
                resume_kick: None,
                interactive: false,
                mcp_families: None,
                cwd: None,
            },
            SessionSlot::from_str_for_test("lead-uuid"),
            None,
            false,
            tx,
        );
        let err = resp_rx.await.expect("reply channel").expect_err("the agent spawn fails");
        // Failing earlier - at the project guard, before any insert -
        // would satisfy the emptiness check below without the rollback
        // ever running.
        assert!(
            err.contains("agent spawn failed"),
            "the rollback path must be the one taken: {err}"
        );

        assert!(workspace.list_live_workers(&project).is_empty(), "the entry rolled back");
        assert_eq!(
            drain_removed_dispositions(&mut rx),
            vec![WorktreeDisposition::Absent],
            "nothing was created, so the toast must not name a worktree",
        );
    }

    /// The despawn keeps a `worktree-<label>` branch the worker committed
    /// to, and names it in a warning rather than discarding the commits.
    #[tokio::test]
    async fn despawn_keeps_a_worktree_branch_holding_unique_commits() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        std::fs::write(wt.join("work.txt"), "a worker committed here").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = rx.await.expect("result");
        let crate::protocol::DespawnResult::Despawned {
            worktree_cleanup_warning: None,
            branch_cleanup_warning: Some(warning),
        } = result
        else {
            panic!("despawn succeeds with a branch warning, got {result:?}");
        };
        assert!(warning.contains("worktree-reviewer"), "warning names the branch: {warning}");
        assert!(
            warning.contains("1 commit reachable"),
            "warning names the commit count, not just a digit from the sha: {warning}"
        );
        assert!(warning.contains("git log"), "warning is executable: {warning}");
        assert!(!wt.exists(), "the worktree is still removed - the request succeeded");
        assert!(
            branch_exists(repo.path(), "worktree-reviewer"),
            "the branch with unique commits survives"
        );
    }

    /// The two quiet arms: nothing to reap says nothing, an unreadable repo
    /// warns rather than passing for a clean despawn.
    #[test]
    fn reap_worker_branch_warns_only_when_it_cannot_verify() {
        let not_a_repo = tempdir().expect("tempdir");
        let warning =
            reap_worker_branch(not_a_repo.path(), "reviewer").expect("an unreadable repo warns");
        assert!(warning.contains("could not verify"), "names the real cause: {warning}");

        let repo = tempdir().expect("repo tempdir");
        run_git(repo.path(), &["init", "-q"]);
        assert!(
            reap_worker_branch(repo.path(), "reviewer").is_none(),
            "no such branch is silent, not a spurious warning on every despawn",
        );
    }

    /// The reap targets `worktree-<label>` by convention, never whatever the
    /// worktree has checked out - a worker that made its own branch has real
    /// work on that one.
    #[tokio::test]
    async fn despawn_reaps_the_conventional_branch_not_the_checked_out_one() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        run_git(&wt, &["checkout", "-q", "-b", "feature-x"]);
        std::fs::write(wt.join("work.txt"), "the worker's real work").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = rx.await.expect("result");
        assert!(
            matches!(
                result,
                crate::protocol::DespawnResult::Despawned {
                    worktree_cleanup_warning: None,
                    branch_cleanup_warning: None,
                }
            ),
            "the conventional branch is pristine, so nothing is kept: {result:?}"
        );
        assert!(
            !branch_exists(repo.path(), "worktree-reviewer"),
            "the conventional branch is reaped"
        );
        assert!(branch_exists(repo.path(), "feature-x"), "the worker's own branch survives");
    }

    fn review_thread(id: &str) -> forge_primitives::review::ReviewThread {
        use forge_primitives::review::{
            ReviewAnchor, ReviewAuthor, ReviewComment, ReviewSide, ReviewStatus, ReviewThread,
        };
        ReviewThread {
            id: id.to_owned(),
            anchor: ReviewAnchor {
                path: "src/x.rs".to_owned(),
                side: ReviewSide::New,
                line: 1,
                content_hash: 1,
                context: Vec::new(),
                base_ref: "main".to_owned(),
            },
            comments: vec![ReviewComment {
                author: ReviewAuthor::User,
                text: "note".to_owned(),
                at: String::new(),
                review_id: None,
            }],
            status: ReviewStatus::Open,
            created_at: "t".to_owned(),
            updated_at: "t".to_owned(),
            commit: None,
        }
    }

    /// A worker's own feature branch outlives its worktree and is usually
    /// the open PR, so the review state keyed on it must survive the
    /// despawn.
    #[tokio::test]
    async fn despawn_keeps_review_state_for_a_branch_that_still_exists() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        run_git(&wt, &["checkout", "-q", "-b", "feature-x"]);
        std::fs::write(wt.join("work.txt"), "the worker's real work").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        workspace.upsert_review_thread("forge", "feature-x", review_thread("a"));
        workspace
            .submit_review(
                "forge",
                "feature-x",
                None,
                &[],
                SessionSlot::from_str_for_test("reviewer"),
            )
            .expect("seal a review on the feature branch");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let _ = rx.await.expect("result");

        assert!(branch_exists(repo.path(), "feature-x"), "the branch the threads key on is live");
        assert_eq!(
            workspace.load_review_threads("forge", "feature-x").expect("load").len(),
            1,
            "a live branch keeps its review threads",
        );
        assert_eq!(
            workspace.load_reviews("forge", "feature-x").expect("load").len(),
            1,
            "a live branch keeps its submitted reviews",
        );
    }

    /// A pushed branch is reaped locally because the remote holds its
    /// commits, so the review state has to key off the remote-tracking ref
    /// rather than the local head that the reap just removed.
    #[tokio::test]
    async fn despawn_keeps_review_state_for_a_branch_pushed_to_a_remote() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        let remote = tempdir().expect("remote tempdir");
        run_git(remote.path(), &["init", "-q", "--bare"]);
        run_git(&wt, &["remote", "add", "origin", remote.path().to_str().expect("utf8 path")]);
        std::fs::write(wt.join("work.txt"), "pushed work").expect("write work");
        run_git(&wt, &["add", "."]);
        run_git(&wt, &["commit", "-q", "-m", "real work"]);
        run_git(&wt, &["push", "-q", "-u", "origin", "worktree-reviewer"]);
        workspace.upsert_review_thread("forge", "worktree-reviewer", review_thread("a"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let _ = rx.await.expect("result");

        assert!(
            !branch_exists(repo.path(), "worktree-reviewer"),
            "the local head is reaped - without that this passes for the wrong reason",
        );
        assert_eq!(
            workspace.load_review_threads("forge", "worktree-reviewer").expect("load").len(),
            1,
            "a branch still on the remote keeps its review threads",
        );
    }

    /// Despawning a git worker deletes both the review threads AND the
    /// submitted reviews for the torn-down worktree's branch once that
    /// branch is gone, leaving other branches' rows intact (else a reused
    /// branch inherits phantoms).
    #[tokio::test]
    async fn despawn_deletes_that_branch_reviews_and_threads() {
        let (workspace, project_key, wt, repo, _config) = git_despawn_fixture("reviewer");
        let branch = forge_agent::env::worktree::worktree_branch(&wt).expect("worktree branch");
        let thread = review_thread;
        workspace.upsert_review_thread("forge", &branch, thread("a"));
        workspace.upsert_review_thread("forge", "survivor", thread("b"));
        // Seal a review on each branch (empty thread set just mints the row).
        let origin = SessionSlot::from_str_for_test("reviewer");
        workspace
            .submit_review("forge", &branch, None, &[], origin.clone())
            .expect("seal torn-down review");
        workspace
            .submit_review("forge", "survivor", None, &[], origin)
            .expect("seal survivor review");

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let _ = rx.await.expect("result");

        assert!(!branch_exists(repo.path(), &branch), "the branch the threads key on is gone");
        assert!(
            workspace.load_review_threads("forge", &branch).expect("load").is_empty(),
            "the torn-down branch's threads are cleaned",
        );
        assert!(
            workspace.load_reviews("forge", &branch).expect("load").is_empty(),
            "the torn-down branch's reviews are cleaned",
        );
        assert_eq!(
            workspace.load_review_threads("forge", "survivor").expect("load").len(),
            1,
            "another branch's threads survive",
        );
        assert_eq!(
            workspace.load_reviews("forge", "survivor").expect("load").len(),
            1,
            "another branch's reviews survive",
        );
    }

    /// A detached-HEAD worktree has no resolvable branch, so despawn skips
    /// review-thread cleanup gracefully (warns, no panic) and leaves
    /// unrelated branches' threads intact.
    #[tokio::test]
    async fn despawn_with_detached_head_skips_cleanup_gracefully() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("reviewer");
        run_git(&wt, &["checkout", "--detach"]);
        workspace.upsert_review_thread("forge", "survivor", review_thread("a"));

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let _ = rx.await.expect("result");

        assert_eq!(
            workspace.load_review_threads("forge", "survivor").expect("load").len(),
            1,
            "cleanup skipped gracefully, unrelated threads intact",
        );
    }

    /// A dirty worktree without `force` BLOCKS the despawn: nothing is
    /// torn down, the worker stays live, the worktree is intact.
    #[tokio::test]
    async fn despawn_dirty_worktree_without_force_blocks() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("reviewer");
        std::fs::write(wt.join("scratch.txt"), "uncommitted").expect("write scratch");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", false, tx);
        let result = rx.await.expect("result");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Blocked { .. }),
            "dirty worktree blocks without force: {result:?}"
        );
        assert_eq!(
            workspace.list_live_workers(&project_key).len(),
            1,
            "worker stays live when blocked"
        );
        assert!(wt.exists(), "worktree intact when blocked");
        assert!(
            !workspace.despawn_cleanup_pending(&project_key, "reviewer"),
            "a blocked despawn reserves nothing: no cleanup was handed off",
        );
    }

    /// A dirty worktree WITH `force` tears down + discards the worktree.
    #[tokio::test]
    async fn despawn_dirty_worktree_force_discards() {
        let (workspace, project_key, wt, _repo, _config) = git_despawn_fixture("reviewer");
        std::fs::write(wt.join("scratch.txt"), "uncommitted").expect("write scratch");
        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_despawn_worker(&workspace, &project_key, "reviewer", true, tx);
        let result = rx.await.expect("result");
        assert!(
            matches!(result, crate::protocol::DespawnResult::Despawned { .. }),
            "force despawns a dirty worktree: {result:?}"
        );
        assert!(workspace.list_live_workers(&project_key).is_empty(), "worker removed under force");
        assert!(!wt.exists(), "worktree discarded under force");
    }

    /// A delivery that lands while the seat is mid-turn is held for the
    /// turn's end rather than written into the running turn, where the CLI
    /// would fold it in as a queued_command attachment with no standing of
    /// its own.
    #[tokio::test]
    async fn a_mid_turn_delivery_is_held_for_the_turn_end() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/forge");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project")
            .key;
        let worker_key = SessionSlot::worker("TestOrg", "forge", "builder");
        workspace
            .insert_live_worker(&project, connected_worker_entry(&worker_key, "builder-session"));
        workspace.mark_session_connected_for_test(&worker_key, "builder-session");
        // The seat is mid-turn: a prompt is in flight at the CLI.
        workspace
            .domain_session_for(&worker_key)
            .expect("connected worker has a domain")
            .lock()
            .turn_pending = true;
        workspace.enable_test_dispatch_intercept();

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_deliver_worker_prompt(
            &workspace,
            &SessionSlot::lead("TestOrg", "forge"),
            &project,
            "builder",
            fixture_wrapped(),
            Some(tx),
        );

        rx.await
            .expect("the handler answers")
            .expect("a held prompt is accepted: the turn it waits on will deliver it");
        assert!(
            workspace.drain_test_dispatch_buffer().is_empty(),
            "nothing is written into the running turn",
        );
        assert_eq!(
            workspace.take_turn_held_for_slot(&worker_key).len(),
            1,
            "the prompt is held for the turn end instead",
        );
    }

    /// The gate reads only what a `Result` clears: a session whose
    /// `runtime_state` alone says Running (that mirror is cleared only on
    /// Connected/ConnectionFailed) must not hold a delivery, or every later
    /// message would wait on a turn-end signal that never comes.
    #[tokio::test]
    async fn a_sticky_runtime_state_does_not_hold_a_delivery() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/forge");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project")
            .key;
        let worker_key = SessionSlot::worker("TestOrg", "forge", "builder");
        workspace
            .insert_live_worker(&project, connected_worker_entry(&worker_key, "builder-session"));
        workspace.mark_session_connected_for_test(&worker_key, "builder-session");
        // No turn pending and no turn open - the Result-clearable signals
        // are both down - but the sticky mirror reads Running.
        workspace
            .domain_session_for(&worker_key)
            .expect("connected worker has a domain")
            .lock()
            .runtime_state = Some(forge_primitives::RuntimeSessionState::Running);
        workspace.enable_test_dispatch_intercept();

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_deliver_worker_prompt(
            &workspace,
            &SessionSlot::lead("TestOrg", "forge"),
            &project,
            "builder",
            fixture_wrapped(),
            Some(tx),
        );

        rx.await
            .expect("the handler answers")
            .expect("a delivery with no turn running is accepted");
        assert_eq!(
            workspace.drain_test_dispatch_buffer().len(),
            1,
            "the delivery is written now, not held behind a stale runtime_state",
        );
        assert!(
            workspace.take_turn_held_for_slot(&worker_key).is_empty(),
            "and nothing was held for a turn end that will not come",
        );
    }

    /// `handle_deliver_worker_prompt` refuses a target label with no
    /// live worker, and says so down the reply channel. Mirrors the
    /// close_worker_unknown branch - the upstream Tool gate
    /// (agents__send_message facade) rejects synchronously; the spawn
    /// handler is defence in depth. Silence here is the defect this pins:
    /// the sender's ack is built from this answer, so a drop nobody
    /// hears is a delivery claimed that never happened.
    #[tokio::test]
    async fn deliver_worker_prompt_unknown_label_is_refused_down_the_reply_channel() {
        let (workspace, _rx) = Workspace::testing_stub();
        let project = ProjectKey::new("forge");
        let caller = SessionSlot::from_str_for_test("caller-1");
        let (tx, rx) = tokio::sync::oneshot::channel();

        handle_deliver_worker_prompt(
            &workspace,
            &caller,
            &project,
            "missing",
            fixture_wrapped(),
            Some(tx),
        );
        let answer = rx.await.expect("the handler answers");
        let Err(reason) = answer else {
            panic!("a label with no live worker must be refused, got {answer:?}");
        };
        assert!(
            reason.contains("missing"),
            "the refusal names the label the caller addressed: {reason}"
        );
    }

    /// A worker addressed before it Connects (session_id still None)
    /// must have the prompt parked for its label, not dropped - its
    /// Connected handler drains the bucket.
    #[tokio::test]
    async fn deliver_to_unconnected_worker_buffers_the_prompt() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/deliver-unconnected");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project")
            .key;
        // The slot production derives for the seeded project's worker.
        let worker_key = SessionSlot::worker("TestOrg", "forge", "builder");
        workspace.insert_live_worker(
            &project,
            crate::mcp::workers::types::WorkerEntry {
                label: "builder".into(),
                charter: "c".into(),
                slot: worker_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: false,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );
        // Pre-Connect DomainSession: session_id is None.
        let domain = std::sync::Arc::new(parking_lot::Mutex::new(
            crate::domain_session::DomainSession::new(worker_key.clone(), None),
        ));
        workspace.domain_handles.lock().insert(worker_key.clone(), domain.clone());

        let (tx, rx) = tokio::sync::oneshot::channel();
        handle_deliver_worker_prompt(
            &workspace,
            &SessionSlot::lead("TestOrg", "forge"),
            &project,
            "builder",
            fixture_wrapped(),
            Some(tx),
        );
        rx.await.expect("the handler answers").expect("a parked prompt is accepted, not refused");

        assert_eq!(
            workspace
                .parked_by_slot
                .lock()
                .get(&crate::SessionSlot::worker("TestOrg", "forge", "builder"))
                .map_or(0, |parked| parked.peer.len()),
            1,
            "prompt parked for the worker's Connected drain, not dropped"
        );
    }

    /// The (source, text) of the one prompt a handler dispatched, read off
    /// the workspace's dispatch intercept: the pre-routing capture of the
    /// Command `record_queued` labels the queued row from.
    fn drain_the_prompt(workspace: &Workspace) -> (PromptSource, String) {
        workspace
            .drain_test_dispatch_buffer()
            .into_iter()
            .find_map(|cmd| match cmd {
                crate::protocol::Command::PromptUnder { source, text, .. } => Some((source, text)),
                _ => None,
            })
            .expect("the peer envelope is dispatched as a prompt")
    }

    /// A worker entry for `label`, connected, so the delivery dispatches
    /// now rather than parking on the pre-Connect bucket.
    fn connected_worker_entry(
        slot: &SessionSlot,
        session_id: &str,
    ) -> crate::mcp::workers::types::WorkerEntry {
        crate::mcp::workers::types::WorkerEntry {
            label: slot.label().to_owned(),
            charter: "c".into(),
            slot: slot.clone(),
            session_id: Some(forge_primitives::SessionId::new(session_id)),
            status: forge_primitives::WorkerLiveness::Running,
            spawned_at: std::time::SystemTime::UNIX_EPOCH,
            spawned_by: SessionSlot::lead("TestOrg", "forge"),
            needs_tag: false,
            is_git_repo_at_spawn: false,
            cwd: None,
            diagnostic: None,
            kick: None,
        }
    }

    /// A peer envelope delivered to a sibling worker is recorded with the
    /// peer source, not forge's: the prose IS a peer envelope, and every
    /// other peer path labels its queued row `peer`.
    #[tokio::test]
    async fn deliver_to_a_worker_records_the_peer_source() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/deliver-worker-peer-source");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project")
            .key;
        let worker_key = SessionSlot::worker("TestOrg", "forge", "builder");
        workspace
            .insert_live_worker(&project, connected_worker_entry(&worker_key, "builder-session"));
        workspace.mark_session_connected_for_test(&worker_key, "builder-session");
        workspace.enable_test_dispatch_intercept();

        handle_deliver_worker_prompt(
            &workspace,
            &SessionSlot::lead("TestOrg", "forge"),
            &project,
            "builder",
            fixture_wrapped(),
            None,
        );

        let (source, text) = drain_the_prompt(&workspace);
        assert_eq!(
            source,
            PromptSource::Peer,
            "a worker-to-worker peer envelope is recorded with the peer source",
        );
        assert!(text.contains("[Message id="), "the dispatched text is the peer envelope: {text}");
    }

    /// The same for the worker-to-lead path: the lead's queued row must
    /// read the peer source too, since the envelope is a peer message.
    #[tokio::test]
    async fn deliver_to_the_lead_records_the_peer_source() {
        let (workspace, _rx) = Workspace::testing_stub();
        let lead = SessionSlot::lead("TestOrg", "forge");
        // The handler drops a lead that is not pooled, and a connected
        // domain keeps the delivery a dispatch rather than a park.
        workspace.seed_test_running_session_id(&lead, "lead-session");
        workspace.mark_session_connected_for_test(&lead, "lead-session");
        workspace.enable_test_dispatch_intercept();

        handle_deliver_worker_prompt_to_lead(
            &workspace,
            &SessionSlot::worker("TestOrg", "forge", "builder"),
            &lead,
            fixture_wrapped(),
            None,
        );

        let (source, text) = drain_the_prompt(&workspace);
        assert_eq!(
            source,
            PromptSource::Peer,
            "a worker-to-lead peer envelope is recorded with the peer source",
        );
        assert!(text.contains("[Message id="), "the dispatched text is the peer envelope: {text}");
    }

    /// `handle_deliver_worker_prompt` for a worker carrying
    /// `needs_tag = true` must kick off an opportunistic tag-write
    /// retry. The worker was spawned idle (no initial_prompt), claude
    /// only writes the JSONL once the first turn arrives, and this
    /// handler runs as that first turn is being routed.
    ///
    /// Verifies the integration end-to-end: pre-seed a Running worker
    /// with `needs_tag = true`, install the testing-stub agent (its
    /// `config_dir` resolves to `/tmp/forge-testing-stub`), seed the
    /// JSONL at the path `tag_session` expects, and assert that after
    /// `handle_deliver_worker_prompt` fires the entry's `needs_tag`
    /// flips to `false` (the retry succeeded). Uses a unique session_id
    /// to avoid collision with other parallel tests that hit the
    /// shared stub config_dir.
    #[tokio::test]
    async fn deliver_prompt_kicks_opportunistic_tag_retry() {
        // Set up a real Workspace::new with a project pointing at a
        // tempdir so list_projects returns the project view we need.
        let toml_dir = tempdir().expect("toml dir");
        let project_root = tempdir().expect("project root");
        let project_path = project_root.path().to_string_lossy().into_owned();
        fs::write(
            forge_toml_path(toml_dir.path()),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "{project_path}"

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

        // Resolve the project's key + path from list_projects (matches
        // what the spawn handler will look up).
        let project_view = workspace
            .list_projects()
            .into_iter()
            .find(|view| view.name == "forge")
            .expect("forge project");
        let project_key = project_view.key.clone();

        // Unique session_id so concurrent test runs don't collide on
        // the shared /tmp/forge-testing-stub. Must be a valid UUID
        // since `tag_session` rejects non-UUID with `MessageParse`.
        let session_id = uuid::Uuid::new_v4().hyphenated().to_string();
        // The slot production derives for the worker under this project.
        let session_key = SessionSlot::worker(&project_view.org, &project_view.name, "idle");

        // Install the testing stub so config_dir_for resolves (to
        // /tmp/forge-testing-stub via the bridge's default config_dir).
        let _agent_rx = workspace.install_testing_stub(&session_key);
        // A Running worker has completed its Connected handshake, so
        // stamp session_id - otherwise the pre-Connect buffer guard in
        // handle_deliver_worker_prompt would park the prompt and the
        // tag retry (asserted below) would never fire.
        if let Some(domain) = workspace.domain_session_for(&session_key) {
            domain.lock().session_id = Some(forge_primitives::SessionId::new(&session_id));
        }

        // Pre-seed the worker entry: Running but needs_tag = true,
        // matching the post-deferred-NotFound state from the
        // `apply_worker_tag_or_rollback` deferred branch.
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "idle".into(),
                charter: "c".into(),
                slot: session_key.clone(),
                // The entry carries the id the worker runs under: the
                // opportunistic tag retry reads it from here.
                session_id: Some(forge_primitives::SessionId::new(&session_id)),
                status: forge_primitives::WorkerLiveness::Running,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::lead(&project_view.org, &project_view.name),
                needs_tag: true,
                is_git_repo_at_spawn: false,
                cwd: None,
                diagnostic: None,
                kick: None,
            },
        );

        // Pre-create the JSONL at the path the retry will look for.
        // /tmp/forge-testing-stub/projects/<sanitized>/<session_id>.jsonl
        let stub_config_dir = std::path::PathBuf::from("/tmp/forge-testing-stub");
        let sanitized =
            forge_agent::userdata::catalog::scan::project_key_for_directory(Some(&project_path));
        let projects_dir = forge_sdk::projects_dir_for(&stub_config_dir).join(&sanitized);
        fs::create_dir_all(&projects_dir).expect("project dir");
        let jsonl_path = projects_dir.join(format!("{session_id}.jsonl"));
        fs::write(&jsonl_path, "").expect("seed jsonl");

        // Fire the deliver. The handler observes needs_tag = true,
        // looks up the project view's path, and kicks the retry task.
        // It also dispatches Command::Prompt which the stub agent
        // accepts (the side-effect we don't assert on here).
        let caller = SessionSlot::from_str_for_test("caller-1");
        handle_deliver_worker_prompt(
            &workspace,
            &caller,
            &project_key,
            "idle",
            fixture_wrapped(),
            None,
        );

        // Wait briefly for the spawned task to finish the retry +
        // status update. The retry should succeed on first attempt
        // because the JSONL exists.
        let needs_tag = tokio::time::timeout(std::time::Duration::from_secs(2), async {
            loop {
                let entries = workspace.list_live_workers(&project_key);
                let entry = entries.iter().find(|e| e.slot == session_key);
                if let Some(entry) = entry
                    && !entry.needs_tag
                {
                    return false;
                }
                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
            }
        })
        .await
        .expect("needs_tag must clear within budget");
        assert!(!needs_tag, "needs_tag cleared after opportunistic retry succeeded");

        // Confirm the tag actually landed on disk.
        let body = fs::read_to_string(&jsonl_path).expect("read jsonl");
        assert!(
            body.contains("\"tag\":\"forge:worker:idle\""),
            "tag row appended on opportunistic retry: {body:?}"
        );

        // Clean up the shared stub config_dir entries we created so
        // subsequent parallel runs aren't polluted.
        let _ = fs::remove_file(&jsonl_path);
    }

    /// The opportunistic tag retry composes the tree from the worker's
    /// OWN tree, not the project's: a worker the spawn pointed at another
    /// repository keeps its JSONL under that repository's worktree, so a
    /// retry aimed at the project path never finds it and the worker
    /// stays untagged - which is what the resume-by-tag path reads.
    #[tokio::test]
    async fn deliver_prompt_kicks_the_tag_retry_at_the_workers_own_tree() {
        let toml_dir = tempdir().expect("toml dir");
        let project_root = tempdir().expect("project root");
        let project_path = project_root.path().to_string_lossy().into_owned();
        fs::write(
            forge_toml_path(toml_dir.path()),
            format!(
                r#"
[[orgs]]
name = "Default"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "{project_path}"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
            ),
        )
        .expect("write forge.toml");
        let workspace = Arc::new(Workspace::new_for_test(toml_dir.path().to_owned()).expect("new"));
        let project_view = workspace
            .list_projects()
            .into_iter()
            .find(|view| view.name == "forge")
            .expect("forge project");
        let project_key = project_view.key.clone();

        // The worker's own tree: a sibling repository the spawn pointed
        // it at, with the worktree claude's `--worktree` would have
        // forked there.
        let sibling = tempdir().expect("sibling repo");
        let sibling_root = std::fs::canonicalize(sibling.path()).expect("canonical sibling");
        let worker_wt = sibling_root.join(".claude").join("worktrees").join("idle");

        let session_id = uuid::Uuid::new_v4().hyphenated().to_string();
        let session_key = SessionSlot::worker(&project_view.org, &project_view.name, "idle");
        let _agent_rx = workspace.install_testing_stub(&session_key);
        if let Some(domain) = workspace.domain_session_for(&session_key) {
            domain.lock().session_id = Some(forge_primitives::SessionId::new(&session_id));
        }
        workspace.insert_live_worker(
            &project_key,
            crate::mcp::workers::types::WorkerEntry {
                label: "idle".into(),
                charter: "c".into(),
                slot: session_key.clone(),
                session_id: Some(forge_primitives::SessionId::new(&session_id)),
                status: forge_primitives::WorkerLiveness::Running,
                spawned_at: std::time::SystemTime::UNIX_EPOCH,
                spawned_by: SessionSlot::lead(&project_view.org, &project_view.name),
                needs_tag: true,
                is_git_repo_at_spawn: true,
                cwd: Some(sibling_root.clone()),
                diagnostic: None,
                kick: None,
            },
        );

        // The JSONL sits where the worker's own tree puts it.
        let stub_config_dir = std::path::PathBuf::from("/tmp/forge-testing-stub");
        std::fs::create_dir_all(&worker_wt).expect("worker worktree dir");
        let sanitized = forge_agent::userdata::catalog::scan::project_key_for_directory(Some(
            &worker_wt.to_string_lossy(),
        ));
        let projects_dir = forge_sdk::projects_dir_for(&stub_config_dir).join(&sanitized);
        fs::create_dir_all(&projects_dir).expect("project dir");
        let jsonl_path = projects_dir.join(format!("{session_id}.jsonl"));
        fs::write(&jsonl_path, "").expect("seed jsonl");

        let caller = SessionSlot::from_str_for_test("caller-1");
        handle_deliver_worker_prompt(
            &workspace,
            &caller,
            &project_key,
            "idle",
            fixture_wrapped(),
            None,
        );

        let cleared = tokio::time::timeout(std::time::Duration::from_secs(2), async {
            loop {
                let entries = workspace.list_live_workers(&project_key);
                let tagged = entries
                    .iter()
                    .find(|e| e.slot == session_key)
                    .is_some_and(|entry| !entry.needs_tag);
                if tagged {
                    return true;
                }
                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
            }
        })
        .await
        .expect("needs_tag must clear within budget");
        assert!(cleared);

        let body = fs::read_to_string(&jsonl_path).expect("read jsonl");
        assert!(
            body.contains("\"tag\":\"forge:worker:idle\""),
            "the tag lands in the worker's own tree: {body:?}",
        );

        let _ = fs::remove_file(&jsonl_path);
    }

    /// `build_worker_extra_args` returns `[("worktree", Some(label))]`
    /// when the project path is a git repo so the worker spawn picks
    /// up `--worktree=<label>` and lands inside an auto-created
    /// `<repo>/.claude/worktrees/<label>/`. The helper takes a
    /// pre-computed `is_git_repo` boolean (caller probes the path
    /// once and reuses the result for both the WorkerEntry flag and
    /// this arg list); the test seeds the bool via the same
    /// `forge_agent::env::worktree::is_git_repo` probe the spawn
    /// path uses so the two layers stay in sync.
    #[test]
    fn worker_in_git_repo_gets_worktree_flag() {
        let dir = tempdir().expect("tempdir");
        std::process::Command::new("git")
            .args(["init", "-q"])
            .current_dir(dir.path())
            .status()
            .expect("git init");
        let is_git = forge_agent::env::worktree::is_git_repo(dir.path());
        assert!(is_git, "freshly-initialised tempdir must register as git repo");
        let args = build_worker_extra_args(is_git, "reviewer", false);
        assert!(
            args.iter()
                .any(|(flag, value)| flag == "worktree" && value.as_deref() == Some("reviewer")),
            "expected (\"worktree\", Some(\"reviewer\")) in {args:?}"
        );
    }

    /// `build_worker_extra_args` returns no `worktree` entry when the
    /// project path isn't a git repo - the worker just spawns into
    /// the project's plain cwd and skips the worktree path entirely.
    #[test]
    fn worker_in_non_git_repo_gets_no_worktree_flag() {
        let dir = tempdir().expect("tempdir"); // empty, not a repo
        let is_git = forge_agent::env::worktree::is_git_repo(dir.path());
        assert!(!is_git, "empty tempdir must not register as git repo");
        let args = build_worker_extra_args(is_git, "reviewer", false);
        assert!(
            !args.iter().any(|(flag, _)| flag == "worktree"),
            "expected no worktree entry in {args:?}"
        );
    }

    /// The `--disallowedTools` value in `args`, failing loudly when the
    /// flag is absent.
    fn disallowed_tools_value(args: &[(String, Option<String>)]) -> String {
        args.iter()
            .find(|(flag, _)| flag == "disallowedTools")
            .and_then(|(_, value)| value.clone())
            .expect("expected a --disallowedTools entry")
    }

    /// A blocked set as whole names. Comparing substrings reports a kept
    /// tool as blocked - `Task` is inside `TaskCreate`, and `TaskStop`
    /// inside nothing here but read the same way.
    fn blocked_names(kind: crate::mcp::SessionKind, interactive: bool) -> Vec<String> {
        blocked_tools_for(kind, interactive).split(',').map(str::to_owned).collect()
    }

    /// The replaced tools written out rather than read off the constant
    /// that produces them, so dropping one from the constant fails here.
    const REPLACED: [&str; 11] = [
        "CronCreate",
        "CronDelete",
        "CronList",
        "TaskCreate",
        "TaskGet",
        "TaskList",
        "TaskUpdate",
        "SendMessage",
        "ListAgents",
        "Workflow",
        "RemoteTrigger",
    ];

    /// The change's whole point: a lead loses the tools forge has
    /// replaced. Before this, `--disallowedTools` was the worker path's
    /// flag alone and a lead ran with the CLI's full set.
    #[test]
    fn a_lead_is_blocked_from_the_tools_forge_replaced() {
        let blocked = blocked_names(crate::mcp::SessionKind::Lead, true);
        for tool in [
            "CronCreate",
            "CronDelete",
            "CronList",
            "TaskCreate",
            "TaskGet",
            "TaskList",
            "TaskUpdate",
            "SendMessage",
            "ListAgents",
            "Workflow",
            "RemoteTrigger",
        ] {
            assert!(blocked.iter().any(|name| name == tool), "{tool} is blocked for a lead");
        }
    }

    /// The question is a property of the spawn, not of the kind: one
    /// worker may ask (its row is open) and another may not.
    #[test]
    fn ask_user_question_follows_interactive_not_kind() {
        for (kind, interactive, expected) in [
            (crate::mcp::SessionKind::Worker, true, false),
            (crate::mcp::SessionKind::Worker, false, true),
            (crate::mcp::SessionKind::Lead, true, false),
        ] {
            let blocked = blocked_names(kind, interactive);
            let denied = blocked.iter().any(|name| name == "AskUserQuestion");
            assert_eq!(
                denied, expected,
                "AskUserQuestion denial is the spawn's, not the kind's; got {blocked:?}",
            );
        }
    }

    #[test]
    fn the_kept_tools_are_never_blocked() {
        for blocked in [
            blocked_names(crate::mcp::SessionKind::Lead, true),
            blocked_names(crate::mcp::SessionKind::Worker, false),
        ] {
            for tool in ["ScheduleWakeup", "Task", "TaskStop", "ReportFindings"] {
                assert!(!blocked.iter().any(|name| name == tool), "{tool} stays enabled");
            }
        }
    }

    /// The extent of the set, not just its members: every other assertion
    /// here says a name is present or a kept name is absent, and a twelfth
    /// name appended to the constant would satisfy all of them. This is the
    /// assertion that fails when the decided list grows by accident.
    #[test]
    fn the_blocked_set_holds_exactly_the_decided_names() {
        assert_eq!(
            blocked_names(crate::mcp::SessionKind::Lead, true).len(),
            11,
            "a lead loses the eleven replaced tools and nothing else",
        );
        assert_eq!(
            blocked_names(crate::mcp::SessionKind::Worker, false).len(),
            14,
            "a worker adds the two worktree pins and the question it may not ask",
        );
        assert_eq!(
            blocked_names(crate::mcp::SessionKind::Worker, true).len(),
            13,
            "an interactive worker keeps the question",
        );
    }

    /// The worker's own entry carries its own denials - the worktree pins
    /// and, for a session that cannot ask its row's user, the question -
    /// alongside the replaced tools, because one builder writes every
    /// name. Nothing outside the decided set is swept in with them.
    #[test]
    fn a_worker_carries_its_denials_and_the_replaced_tools_in_one_entry() {
        let list = blocked_names(crate::mcp::SessionKind::Worker, false);
        for tool in [
            "EnterWorktree",
            "ExitWorktree",
            "AskUserQuestion",
            "TaskCreate",
            "CronCreate",
            "SendMessage",
            "RemoteTrigger",
        ] {
            assert!(
                list.iter().any(|name| name == tool),
                "{tool} must be denied to a worker; got {list:?}"
            );
        }
        for tool in [
            "ScheduleWakeup",
            "Task",
            "TaskStop",
            "ReportFindings",
            "TaskOutput",
            "ToolSearch",
            "Monitor",
        ] {
            assert!(!list.iter().any(|name| name == tool), "{tool} stays available; got {list:?}");
        }
    }

    /// The cold spawn - the one a project's first lead and every worker go
    /// through - hands its child the denial. Nothing else observes this
    /// path: a pooled slot never reaches a launch, and a cold one otherwise
    /// ends in a real subprocess, so the test stands a stub handle in for
    /// the one the spawn would create and reads the setting it forwards.
    ///
    /// This is a lead's launch, which is the half that used to carry no
    /// denial at all.
    #[tokio::test]
    async fn a_cold_spawn_hands_its_child_the_replaced_tool_denial() {
        let dir = tempfile::tempdir().expect("tempdir");
        let forge_dir = crate::config::ensure_forge_data_dir(dir.path()).expect("forge dir");
        std::fs::write(
            forge_dir.join("forge.toml"),
            r#"
[[orgs]]
name = "TestOrg"
accounts = ["acct-a"]

[[orgs.projects]]
name = "proj"
path = "/tmp/spawn-denial"
model = "claude-sonnet-5"

[[accounts]]
display_name = "acct-a"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        )
        .expect("write forge.toml");
        let ws = std::sync::Arc::new(
            Workspace::new_for_test(dir.path().to_owned()).expect("boot from the fixture"),
        );
        ws.seed_test_ready_account("acct-a");
        let (handle, mut agent_rx) = Workspace::testing_stub_handle();
        ws.install_test_spawn_handle(handle);

        let _ = handle_spawn_project(&ws, "proj", SessionLaunchSettings::default());

        let Some(forge_primitives::AgentCommand::NewSession { launch_settings, .. }) =
            agent_rx.try_recv().ok()
        else {
            panic!("the cold spawn has to reach a launch for anything here to be observable");
        };
        let denied = launch_settings
            .get("extra_args")
            .and_then(serde_json::Value::as_array)
            .and_then(|pairs| {
                pairs.iter().find(|pair| {
                    pair.get(0).and_then(serde_json::Value::as_str) == Some("disallowedTools")
                })
            })
            .and_then(|pair| pair.get(1).and_then(serde_json::Value::as_str))
            .unwrap_or_default()
            .to_owned();
        for tool in REPLACED {
            assert!(
                denied.split(',').any(|name| name == tool),
                "{tool} must reach a spawned session's launch; got {denied:?}",
            );
        }
    }

    /// A lead's settings carry no denial of their own, so the call adds
    /// the flag. `--disallowedTools` used to be a worker-only flag, and a
    /// lead kept the CLI's tools.
    #[test]
    fn the_denial_adds_the_flag_when_there_is_none() {
        let mut settings = SessionLaunchSettings::default();
        apply_blocked_tools(&mut settings, crate::mcp::SessionKind::Lead, true);
        let list = disallowed_tools_value(&settings.extra_args);
        for tool in REPLACED {
            assert!(
                list.split(',').any(|name| name == tool),
                "{tool} must be denied to a lead; got {list:?}",
            );
        }
        assert!(
            !list.contains("EnterWorktree") && !list.contains("ExitWorktree"),
            "a lead still hops worktrees; got {list:?}",
        );
        assert!(
            !list.contains("AskUserQuestion"),
            "a lead is exactly the session that must be able to ask; got {list:?}",
        );
    }

    /// A session whose settings already carry denials - a worker's, which
    /// hold the worktree tools in the same value - gains the names it does
    /// not already have inside that value rather than a second
    /// `--disallowedTools` flag for the CLI to reconcile. A name both
    /// writers know lands once.
    #[test]
    fn the_denial_merges_into_a_list_that_is_already_there() {
        let mut settings = SessionLaunchSettings {
            extra_args: build_worker_extra_args(false, "reviewer", false),
            ..SessionLaunchSettings::default()
        };
        apply_blocked_tools(&mut settings, crate::mcp::SessionKind::Worker, false);
        let flags =
            settings.extra_args.iter().filter(|(flag, _)| flag == "disallowedTools").count();
        assert_eq!(flags, 1, "one flag, not two; got {:?}", settings.extra_args);
        let list = disallowed_tools_value(&settings.extra_args);
        for tool in REPLACED {
            assert_eq!(
                list.split(',').filter(|name| *name == tool).count(),
                1,
                "{tool} appears once; got {list:?}",
            );
        }
        assert!(list.contains("EnterWorktree"), "the worker's own denial survives; got {list:?}");
    }

    /// A `--disallowedTools` entry with no value is still an entry: the
    /// names go into it rather than a second flag being pushed beside it.
    #[test]
    fn the_denial_fills_a_valueless_entry_rather_than_adding_a_second_flag() {
        let mut settings = SessionLaunchSettings {
            extra_args: vec![("disallowedTools".to_owned(), None)],
            ..SessionLaunchSettings::default()
        };
        apply_blocked_tools(&mut settings, crate::mcp::SessionKind::Lead, true);
        assert_eq!(
            settings.extra_args.len(),
            1,
            "the entry that is there is filled, not duplicated: {:?}",
            settings.extra_args,
        );
        let list = disallowed_tools_value(&settings.extra_args);
        for tool in REPLACED {
            assert!(
                list.split(',').any(|name| name == tool),
                "{tool} must be denied; got {list:?}",
            );
        }
        assert!(
            !list.starts_with(','),
            "a filled entry carries no leading separator; got {list:?}"
        );
    }

    /// Workers are pinned to their worktree (when they have one) and
    /// must not be able to call claude's built-in `EnterWorktree` /
    /// `ExitWorktree` tools to hop elsewhere. `build_worker_extra_args`
    /// emits a `--disallowedTools` flag carrying both tool names as a
    /// single comma-separated value (empirically confirmed to be
    /// accepted by the claude CLI's variadic `<tools...>` parser).
    /// This test covers the git-repo case: the `worktree` flag is
    /// still present, and the `disallowedTools` flag is added on top.
    #[test]
    fn worker_in_git_repo_blocks_enter_and_exit_worktree() {
        let is_git = true;
        let args = build_worker_extra_args(is_git, "reviewer", false);
        let blocked = args.iter().find(|(flag, _)| flag == "disallowedTools");
        let (_, value) = blocked.expect("expected --disallowedTools entry");
        let value = value.as_deref().expect("expected value for --disallowedTools");
        assert!(value.contains("EnterWorktree"), "EnterWorktree must be blocked, got {value:?}");
        assert!(value.contains("ExitWorktree"), "ExitWorktree must be blocked, got {value:?}");
    }

    /// The non-git-repo case still blocks the worktree-hop tools even
    /// though the worker isn't running inside a worktree - the tool
    /// surface is uniform across project shapes so workers can't be
    /// nudged into surprising behaviour by the project layout.
    #[test]
    fn worker_in_non_git_repo_also_blocks_worktree_tools() {
        let is_git = false;
        let args = build_worker_extra_args(is_git, "reviewer", false);
        let blocked = args.iter().find(|(flag, _)| flag == "disallowedTools");
        let (_, value) = blocked.expect("expected --disallowedTools entry even outside git-repo");
        let value = value.as_deref().expect("expected value for --disallowedTools");
        assert!(value.contains("EnterWorktree"));
        assert!(value.contains("ExitWorktree"));
    }

    /// An answer to a worker's `AskUserQuestion` is indistinguishable
    /// from a decision the user made, and reaches it only if someone
    /// happens to be looking at that worker's row. The default is that
    /// the tool is never offered.
    #[test]
    fn worker_spawned_without_interactive_is_denied_ask_user_question() {
        let args = build_worker_extra_args(true, "reviewer", false);
        let blocked = args.iter().find(|(flag, _)| flag == "disallowedTools");
        let (_, value) = blocked.expect("expected --disallowedTools entry");
        let value = value.as_deref().expect("expected value for --disallowedTools");
        assert!(
            value.contains("AskUserQuestion"),
            "a worker spawned without interactive must not be offered AskUserQuestion, got {value:?}",
        );
    }

    /// The opt-in keeps the tool, and changes nothing else: a worker
    /// spawned to be talked to directly is one whose row the user has
    /// open, but it is still pinned to its spawn location.
    #[test]
    fn worker_spawned_interactive_keeps_ask_user_question() {
        let args = build_worker_extra_args(true, "reviewer", true);
        let blocked = args.iter().find(|(flag, _)| flag == "disallowedTools");
        let (_, value) = blocked.expect("expected --disallowedTools entry");
        let value = value.as_deref().expect("expected value for --disallowedTools");
        assert!(
            !value.contains("AskUserQuestion"),
            "an interactive worker must keep AskUserQuestion, got {value:?}",
        );
        assert!(
            value.contains("EnterWorktree") && value.contains("ExitWorktree"),
            "opting into interactive must not lift the worktree-hop denial, got {value:?}",
        );
    }

    /// A worker closed while it was still spawning drops whatever was buffered
    /// for it. The delivery already committed, so nothing re-delivers it, and
    /// the release is the last point that can record the loss.
    #[test]
    fn close_worker_records_the_delivery_parked_for_its_label() {
        let (workspace, _rx) = Workspace::testing_stub();
        workspace.seed_test_project("forge", "/tmp/close-parked");
        let project = workspace
            .list_projects()
            .into_iter()
            .find(|v| v.name == "forge")
            .expect("seeded project")
            .key;
        // Teardown expires the parked bucket by the entry's slot, so the
        // fixture carries the one production derives for this worker.
        let worker_key = SessionSlot::worker("TestOrg", "forge", "reviewer");
        let mut entry = fake_worker_entry("reviewer", "worker-1");
        entry.slot = worker_key.clone();
        workspace.insert_live_worker(&project, entry);
        workspace.register_domain_session(worker_key.clone(), None);
        workspace.park_slack(&worker_key, vec![slack_msg("buffered while spawning")]);

        handle_close_worker(&workspace, &project, "reviewer");

        assert_eq!(
            workspace.parked_by_slot.lock().get(&worker_key).map_or(0, |parked| parked.slack.len()),
            0,
            "the closed worker's parked delivery is recorded, not left for a later session",
        );
    }
}

#[cfg(test)]
mod lead_charter_tests {
    use super::*;

    /// A lead with no charter set gets the bundled one.
    #[test]
    fn lead_without_a_charter_gets_the_bundled_one() {
        let mut settings = SessionLaunchSettings::default();
        apply_lead_charter(&mut settings);
        assert_eq!(settings.charter.as_deref(), Some(DEFAULT_LEAD_CHARTER));
    }

    /// An already-set charter (a worker spawn's inline persona) is
    /// never overwritten - the guard short-circuits first.
    #[test]
    fn existing_charter_is_preserved_not_overwritten() {
        let mut settings = SessionLaunchSettings {
            charter: Some("pre-existing".into()),
            ..SessionLaunchSettings::default()
        };
        apply_lead_charter(&mut settings);
        assert_eq!(settings.charter.as_deref(), Some("pre-existing"));
    }

    /// A plan, spec or design the lead writes for the USER's own review
    /// reaches them as a document, not as a path in chat. Pinned on the
    /// plan step, which is the moment the file is written - a lead reads
    /// "write the spec/plan as a file" there and nothing else in the
    /// charter tells it how the USER is meant to receive it.
    #[test]
    fn lead_charter_hands_the_users_review_a_document() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "when the plan, spec or design is for the USER's own review, deliver it through \
                 `documents__hand_off` with `reviewable: true`"
            ),
            "the plan step hands the USER's review a document: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("a path in chat is not a hand-off"),
            "the correction is pinned: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// The bundled charter ships to every install, so it must not name
    /// tooling or projects that only exist in one author's environment:
    /// a fresh install has no user-scope skills, no plugins and no
    /// justfile, and `team` is not a `forge.toml` key. Most entries got
    /// here by being copied from an on-disk
    /// charter; the two path entries are pre-emptive, since prose about
    /// where a charter lives is the obvious place to write one.
    ///
    /// Every assertion below is a `!contains`, so all of them hold
    /// against an empty string - the first check is what makes the rest
    /// mean anything if the `include_str!` ever resolves somewhere else.
    #[test]
    fn bundled_lead_charter_assumes_no_local_environment() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("agents__spawn"),
            "the compiled-in charter is the real one, not an empty or wrong file",
        );
        for (token, why) in [
            ("pr-review-loop", "user-scope skill, absent on a fresh install"),
            ("superpowers", "plugin, absent on a fresh install"),
            ("commit-commands", "plugin, absent on a fresh install"),
            ("`just ", "project justfile, not every project has one"),
            ("hub-modules", "one user's project name"),
            ("team = ", "not a forge.toml key"),
            ("static_workers", "no longer a forge.toml key either"),
            ("~/.claude", "the charter must not pin a path in the user's home"),
            ("forge-team", "the charter must not name the deleted role filesystem"),
        ] {
            assert!(
                !DEFAULT_LEAD_CHARTER.contains(token),
                "bundled lead charter names '{token}' ({why})"
            );
        }
    }

    /// A worker handed off a reviewable document and had no `review__*`
    /// tools to read the comments with. The spawn step is where a lead
    /// picks the family selection, so the requirement ships there - pinned
    /// so a paraphrase cannot drop it.
    #[test]
    fn the_charter_names_the_review_family_for_a_document_worker() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "If you narrow a worker's `mcp_families`, include `review` for a worker whose \
                 deliverable can be handed off as a reviewable document - a fresh spawn that \
                 omits the field gives every family; a resume adopts the stored selection."
            ),
            "the spawn step scopes the requirement to a narrowed selection and states what a \
             fresh spawn and a resume each do",
        );
    }

    /// **The project handoff is the lead's**, and a worker's note is never
    /// the project's: the project's memory directory holds the lead's rolling
    /// handoff, so a worker writing `handoff.md` there overwrites it. Both
    /// addresses are pinned so a reword fails here rather than in whichever
    /// seat writes the lead's file.
    #[test]
    fn the_charter_says_the_project_handoff_is_the_leads() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "`handoff.md` in the project's memory directory is the project's rolling \
                 state, and you write it and keep it current"
            ),
            "the file, its owner and the keeping-current duty are pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "a worker's handoff note is its own file, `workers/<label>.md` in that same \
                 project memory directory, never the project's"
            ),
            "the worker's own address is anchored so the two cannot read alike",
        );
    }

    /// The charter's systemone cues ship to every lead on every install, and
    /// the names in them are tools that can be renamed - pinned so a rename
    /// fails here instead of handing a lead a call it cannot make.
    #[test]
    fn the_charter_carries_its_systemone_cues() {
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("if your tools include `systemone__ask_noul`, make one claim-check"),
            "the merge-gate claim cue and its guard are pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "if your tools include `systemone__ask_choice`, weigh them with one choice over the live set"
            ),
            "the routing cue and its guard are pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "if your tools include `systemone__ask_choice`, `ask_score` or `ask_noul`, put \
                 a decision this session could make to the model rather than the user - the \
                 user's attention is the exception, not the default"
            ),
            "the escalation cue, its guard and the attention rule are pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("Never park a dispatch decision on your own judgment.")
                && DEFAULT_LEAD_CHARTER.contains("decide whether the options genuinely differ")
                && DEFAULT_LEAD_CHARTER.contains(
                    "put the enumerated options and the context that bears on them to \
                     `systemone__ask_choice` when your tools include it"
                )
                && DEFAULT_LEAD_CHARTER.contains("without the tool, decide it yourself")
                && DEFAULT_LEAD_CHARTER
                    .contains("Either way, report the decision where the work is reported"),
            "the dispatch cue, its genuine-difference scope, its guard, its fallback and its \
             report duty are pinned",
        );
    }

    /// A merge conflict is a cost, not a barrier (#2509). The charter used
    /// to forbid parallel branches that edit the same files, and a lead
    /// held a fix behind another cut for it. Only genuine shared-state
    /// ordering still serializes, and the old same-files ban is pinned
    /// absent so a reversion fails here rather than in a silent queue.
    #[test]
    fn the_charter_parallelises_independent_work() {
        for (clause, why) in [
            (
                "Default is NOT strictly one-at-a-time: run ad-hoc workers CONCURRENTLY on \
                 independent work",
                "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:", "the narrow serialization test"),
            (
                "at most ONE in-flight migration branch at a time",
                "the migration sequence stays serialized",
            ),
            ("One main, one version line", "the merge queue and release line stay serialized"),
            (
                "Review is not serialization but it is a real cap",
                "review throughput is a cap, not a serialization claim",
            ),
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not carry the parallel rule ({why}): {clause}",
            );
        }
        assert!(
            !DEFAULT_LEAD_CHARTER.to_lowercase().contains("same files"),
            "the same-files hold is what #2509 removed; it must not come back in any casing",
        );
    }

    /// The one-shot rule ships to every lead, and its handle is the same
    /// sentence the conduct block and the lead-facing tool text carry -
    /// pinned so a paraphrase drifting between surfaces fails here. The
    /// planning half rides with it: the ban starts at the plan, and a cut
    /// that cannot land whole goes to the user before it is cut down.
    #[test]
    fn the_charter_carries_the_one_shot_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER.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",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.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!(
            DEFAULT_LEAD_CHARTER.contains("never sequence a cut as \"land A, then B, then C\""),
            "the planning ban is pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "if it genuinely cannot land whole, decide that with the user BEFORE anything is \
                 cut down"
            ),
            "the user-decision half is pinned",
        );
    }

    /// Mid-turn delivery had no written duty of its own in this charter, so the
    /// bullet that adds one is pinned sentence by sentence.
    #[test]
    fn the_charter_answers_a_mid_turn_message() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "- **A message from the user that arrives mid-turn is still owed an answer.**"
            ),
            "the bullet's own lead-in, so folding it into another bullet fails here",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("Answer it in that same turn, before you start the next piece of work"),
            "the duty falls due in the same turn, before the next piece of work",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("a question left unanswered is a dropped message, not a deferred one"),
            "the failure is named, so the line cannot be read as permission to defer",
        );
    }

    /// The charter's board lines carry the landing rule (#2377): a landed
    /// row with no epic above it is deleted in the same pass, a landed
    /// child of an open epic is left terminal so the epic can read `to
    /// close`, and the delete is never that child's - the lead is the
    /// pile's author, so a charter line still saying "complete the row
    /// when it is merged" would reproduce the 36-completed-rows board the
    /// tool text was fixed to prevent.
    #[test]
    fn the_charter_carries_the_landing_rule() {
        for (clause, why) in [
            (
                "a landed row with no children and no epic above it is deleted in the same \
                 pass (`tasks__delete`), never left completed, while a landed row under an \
                 epic - open or already terminal - is completed and left terminal, because \
                 the epic reads `to close` only once every child is terminal (a verify=user \
                 child parks in waiting on the user and counts only once the user approves)",
                "the row-true bullet carries the delete and its epic carve-out together",
            ),
            (
                "`tasks__delete` clears a row created in error, and a landed row with no \
                 children and no epic above it - never a child of an open epic, whose terminal \
                 state its epic's close depends on",
                "the close-epics bullet states what the delete is for",
            ),
            (
                "completing the ROOT row closes it and archives the tree",
                "the archive that closes an epic is pinned, so the carve-out's close signal \
                 has an action behind it",
            ),
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not carry the landing rule ({why}): {clause}",
            );
        }
    }

    /// Every client text box takes dictation, and a lead planning client
    /// work names the mechanism with the box - pinned so a charter rewrite
    /// keeps the rule beside the mockup step it applies from.
    #[test]
    fn the_charter_carries_the_dictation_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "the plan names dictation for every text box it adds - `DictateControl` beside \
                 the box"
            ),
            "the dictation rule and its control are pinned",
        );
    }

    /// A defect the review or the look of a cut surfaces belongs to that
    /// cut, not to the board: the lead fixes it in line with the worker
    /// frozen, and only work outside the cut gets a row. Pinned because
    /// the charter's filing rule reads as "file everything" without the
    /// carve-out, which is how a finding of the cut under review was
    /// filed as a separate issue.
    #[test]
    fn the_charter_fixes_a_cuts_findings_in_line() {
        for clause in [
            "File what is outside the cut; fix what is inside it",
            "A defect that surfaces in the review or the look of a cut under review is not \
             filed and not handed to a worker",
            "fix it in line on that cut's branch, with the worker frozen",
            "let the same branch carry it",
            "except a finding of a cut under review, which you fix in line with the worker \
             frozen",
            "dispatch, except a finding of a cut under review, which is yours to fix in line",
            "You orchestrate; you don't write code - except a finding of a cut under review, \
             which you fix in line",
            "found anywhere else becomes a row the moment it surfaces",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not fix a cut's findings in line: {clause}",
            );
        }
        assert!(
            !DEFAULT_LEAD_CHARTER.contains("File everything you find"),
            "the unconditional filing headline must not come back",
        );
    }

    /// A user-decision wait or a `verify: user` gate is the lead's to
    /// mint. A worker-parked decision outlives its answer and the lead
    /// cannot close it afterward, so the ask travels to the lead instead
    /// of parking on the user from a worker's row.
    #[test]
    fn the_charter_keeps_the_user_decision_mint_with_the_lead() {
        for clause in [
            "Only you mint a `verify: user` gate or a `kind: decision` wait",
            "a worker hands the ask to you instead",
            "A decision wait a worker parks outlives its answer and you cannot close it afterward",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not keep the user-decision mint with the lead: {clause}",
            );
        }
    }

    /// A review round builds in the same checkout the worker handed
    /// over, so reviewers read the pushed branch and a mutation pass
    /// runs in a detached throwaway worktree, never the live checkout.
    #[test]
    fn the_charter_scopes_reviewers_away_from_the_live_worktree() {
        for clause in [
            "Reviewers read the pushed branch",
            "a mutation pass runs in a detached throwaway worktree, never the live checkout",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not scope reviewers away from the live worktree: {clause}",
            );
        }
    }

    /// A finding is a claim about the pushed branch: one written
    /// without reading costs the worker a round and teaches it to
    /// discount the rest of the list. The grep and its point-at-the-line
    /// bar are pinned, with the withdrawal for one that goes out wrong.
    #[test]
    fn the_charter_verifies_a_finding_against_the_branch() {
        for clause in [
            "Before a finding goes to a worker, grep the pushed branch for the exact symbol, \
             string or file it names and point at the line",
            "one you cannot point at is not sent",
            "withdrawn immediately and named as withdrawn",
            "a plausible list written without reading costs the worker a round and teaches it \
             to discount the rest",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not verify a finding before sending it: {clause}",
            );
        }
    }

    /// A queued message can die with the worker's session, so the
    /// review step re-sends its list after a restart and the health
    /// check proves the new session actually holds it - never by the
    /// earlier `sent`, which reported only the queue's receipt.
    #[test]
    fn the_charter_resends_after_a_worker_restart() {
        for clause in [
            "If the worker restarted since you last wrote to it, re-send the findings and \
             confirm they landed (its answer, never the earlier `sent`) before waiting on a \
             round",
            "A message still queued to a worker when its session restarted can be gone",
            "re-send it and confirm it landed by a distinctive phrase in the worker's transcript \
             or by its answer",
            "never by the earlier `sent`",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not resend after a worker restart: {clause}",
            );
        }
    }

    /// A commit subject, a PR body and an agent's report are claims;
    /// the pushed commit is the object. Pinned at the merge gate so a
    /// report true only of a working tree cannot read as done.
    #[test]
    fn the_charter_checks_the_object_not_the_report() {
        for clause in [
            "A commit subject, a PR body and an agent's report are claims",
            "before reporting a change as done off one, `git show <sha>:<path>` the thing and \
             quote it back",
            "the pushed commit is the object",
            "a report can be true of the working tree and false of the commit",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not check the object before reporting done: {clause}",
            );
        }
    }

    /// The merge queue is pulled from GitHub, not held only on the push
    /// ping: an approved-and-green PR otherwise sits silently when a
    /// ping is lost.
    #[test]
    fn the_charter_pulls_the_merge_queue_from_github() {
        for clause in [
            "a worker's \"PR #N ready\" ping is a prompt, not the source of truth",
            "on every health check and resume",
            "pull `gh pr list --state open` and `gh pr checks <N>` and reconcile them against \
             the loops you ran",
            "an approved-and-green PR otherwise sits silently when a ping is lost",
            "(on each wake)",
            "plus `gh pr list --state open` and `gh pr checks <N>` for the merge queue - pull \
             both rather than waiting on a ping",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not pull the merge queue from GitHub: {clause}",
            );
        }
    }

    /// A turn that ends on stated intent schedules nothing, so making a
    /// worker the trigger for a timed or external condition leaves both
    /// sides idle. The report-only one-shot and the ban on one that
    /// performs the action itself are pinned with it, because either
    /// alone reads as a licence to schedule the work twice.
    #[test]
    fn the_charter_forbids_making_a_worker_a_trigger() {
        for clause in [
            "Never make a worker the trigger for a timed or external condition",
            "A turn that ends on stated intent schedules nothing",
            "forge can wake a worker through a cron or a subscription it set, but not on intent",
            "leaves both sides idle",
            "schedule a report-only `cron__create` one-shot (`run_once_at`)",
            "Never schedule a one-shot that performs the action itself",
            "it races the real trigger and can double a review round or a spend",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not forbid a worker as trigger: {clause}",
            );
        }
        assert!(
            !DEFAULT_LEAD_CHARTER.contains("A worker has no autonomous wake"),
            "the false absolute must not come back beside the correct wording",
        );
    }

    /// The charter is shipped text every lead reads, so a blocked CLI tool
    /// named here would send it to a surface its own launch denies. The
    /// preamble is the other lead-facing text and carries the same test in
    /// its own file.
    #[test]
    fn the_lead_charter_names_no_blocked_cli_tool() {
        for tool in [
            "CronCreate",
            "CronDelete",
            "CronList",
            "TaskCreate",
            "TaskGet",
            "TaskList",
            "TaskUpdate",
            "SendMessage",
            "ListAgents",
            "Workflow",
            "RemoteTrigger",
        ] {
            assert!(
                !DEFAULT_LEAD_CHARTER.contains(tool),
                "the lead charter must not name the blocked CLI tool {tool}",
            );
        }
    }

    /// The token test above checks absence only; these pin the decided
    /// despawn wording against silent softening in either direction.
    #[test]
    fn lead_charter_carries_the_despawn_trigger() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("despawn at the chain node"),
            "the chain-node despawn rule stays: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("NOT when the last downstream PR closes"),
            "the despawn point is the chain node, not the last PR: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("only when the next stage needs the context back"),
            "chain despawn closes at absorption; re-spawn waits for the next stage: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// The wind-down used to tell leads to have the worker reset its
    /// worktree to main and drop its branch; measured 2026-10-17, a
    /// worker seat's permission engine refuses that reset, and the
    /// despawn reaped the branch and closed clean without it. Pinned so
    /// the refusable step does not come back, and the honest half - the
    /// tree clean, the reap the despawn's - does not drift away either.
    #[test]
    fn lead_charter_wind_down_leaves_the_reap_to_the_despawn() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("leave its worktree clean"),
            "the honest cleanup instruction is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("commit and push what is in flight"),
            "the dirty bar is commit AND push, not either: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("the despawn reaps the worktree branch"),
            "the reap is the despawn's, not the worker's: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("once its commits are reachable elsewhere"),
            "the reap's reachability bar is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("names any it must keep"),
            "a kept branch is named, not silently left: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            !DEFAULT_LEAD_CHARTER.contains("reset to main"),
            "the refusable reset stays out of the wind-down: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// A worktree is a live cut's tree, not a cache: removing one by hand to
    /// reclaim disk loses its branch and forces a full rebuild. Pinned with
    /// the reclaim's owner and the in-tree clean that survives a live worker.
    #[test]
    fn lead_charter_never_prunes_a_worktree_by_hand() {
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("Never prune a worker's worktree by hand to reclaim disk"),
            "the rule's handle is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("a tree removed mid-cut loses its branch and forces a full rebuild"),
            "the reason a hand prune costs work is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "under disk pressure, have live workers push their branches and clean their \
                 build targets inside their own trees"
            ),
            "the reclaim that survives a live worker is pinned with what it cleans: \
             {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// The attention rule is the lead's posture toward the user, and both
    /// halves read as the opposite of themselves when softened: the shapes
    /// become "ask when unsure", and the spec half becomes a check-in.
    /// Pinned so a later edit cannot unship either silently.
    #[test]
    fn lead_charter_carries_the_attention_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "Nothing waits on the user except a hold the user \
                 explicitly asked for"
            ),
            "the rule's opening is pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("a look they should give when they return (the board's decision wait)"),
            "the at-convenience look is pinned beside the hold",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "the decision model, peer opinions and your own review already spent - something \
                 still genuinely ambiguous"
            ),
            "shape (c)'s channels and its bar are pinned together",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("A spec that exists is followed without check-ins"),
            "the spec half is pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("never parked on the user"),
            "the new-work half is pinned",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "A long-lived worker is a standing commitment of the user's attention rather \
                 than a step of work, so raise it with the user rather than deciding it yourself"
            ),
            "the long-lived-worker clause is pinned whole, its call included",
        );
    }

    /// The charter is the only shipped text telling a lead how to maintain
    /// the task list, and the only task surface forge ships is `tasks__*`
    /// over forge's own store. Guidance written against the CLI's tools
    /// names fields no tool offers, and sends every lead to a tool its
    /// session is denied.
    #[test]
    fn lead_charter_maintains_the_task_list_through_forge_s_own_tools() {
        // The whole family the board is worked through: the lead cuts and
        // dispatches, workers claim and wait, and the list is read.
        for tool in [
            "tasks__create",
            "tasks__update",
            "tasks__delete",
            "tasks__claim",
            "tasks__wait",
            "tasks__list",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(tool),
                "the charter maintains the list through {tool}: {DEFAULT_LEAD_CHARTER}",
            );
        }
        // Case-insensitively: the CLI spells its removal status lowercase
        // `deleted`, and a lead reading it as a state here would go looking
        // for it in `tasks__update`. The landed-row rule legitimately uses
        // the verb - "is deleted in the same pass", `tasks__delete` named
        // in the same clause - so the ban is the status spelling: the
        // backticked form, the word named as a status, or stated as a value
        // ("status: deleted", "set to deleted").
        for spelling in
            ["`deleted`", "deleted status", "status deleted", "status: deleted", "to deleted"]
        {
            assert!(
                !DEFAULT_LEAD_CHARTER.to_lowercase().contains(spelling),
                "the charter names `deleted` as a status ({spelling}): {DEFAULT_LEAD_CHARTER}",
            );
        }
    }

    /// #2831: the charter is where dispatch is decided, and pending is the
    /// board's Backlog. A ready row is a candidate, not a queued start, and
    /// the row is kept out of the sweep by ownership - the door the old text
    /// left out, and what made "backlog these rows" read as dispatched.
    #[test]
    fn lead_charter_carries_the_backlog_rule() {
        for clause in [
            "a ready row is a dispatch candidate, not work already queued to start",
            "Dispatch is your act: keep the row owned (the sweep dispatches only unowned rows) \
             to set it aside",
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the charter owes the backlog rule ({clause}): {DEFAULT_LEAD_CHARTER}",
            );
        }
    }

    /// The board bullets above say how a row is worked; the sweep has its
    /// own paragraph below them. That paragraph is pinned byte for byte, so
    /// nothing can be added, removed or qualified inside it. The rest of the
    /// board section is then scanned as a net for a cron call, a cron
    /// parameter or a cron expression: candidate windows are parsed with
    /// forge's own validator, so the net accepts exactly what a session
    /// could schedule - names, ranges and aliases included. It is a net,
    /// not a closure: prose naming no tool, parameter or expression cannot
    /// be told apart from advice. The charter's one-shot `cron__create`
    /// advice sits above that section, so the scan leaves it alone.
    #[test]
    fn the_charter_carries_the_board_sweep() {
        const SWEEP: &str = "**Sweep the board at the start of every session, when forge injects \
             a sweep (it does when you have been idle, at most once every two hours, or six \
             hours after the last sweep), and on demand.** First `cron__list` and delete any \
             sweep cron an older version of this charter had you create (`cron__delete`) - it \
             keeps firing its sweep prompt into this session until it is removed. Never create a \
             standing sweep cron. End every sweep with the next three lead-owned backlog rows, \
             each with one line on why it comes next; they are proposals, not dispatches, and \
             only you start a worker on one.";
        const CLEANUP: &str = "First `cron__list` and delete any sweep cron an older version of \
             this charter had you create (`cron__delete`)";
        const REASON: &str =
            "it keeps firing its sweep prompt into this session until it is removed";

        let section = board_section();
        assert!(
            section.contains("**Sweep the board"),
            "the sweep paragraph belongs in the board section, not elsewhere",
        );
        assert_eq!(
            DEFAULT_LEAD_CHARTER.matches("**Sweep the board").count(),
            1,
            "the charter carries exactly one sweep paragraph",
        );
        let sweep_at = section
            .find("**Sweep the board")
            .expect("the sweep paragraph belongs in the board section");
        let tail = &section[sweep_at..];
        let sweep_paragraph = &tail[..tail.find("\n\n").unwrap_or(tail.len())];
        assert_eq!(
            sweep_paragraph, SWEEP,
            "the sweep paragraph is pinned byte for byte: nothing added, removed or qualified",
        );

        for (clause, why) in [
            (CLEANUP, "the old standing entry is removed, not only forbidden"),
            (REASON, "the reason the cleanup is owed"),
            (
                "when forge injects a sweep (it does when you have been idle, at most once every \
                 two hours, or six hours after the last sweep)",
                "the injected trigger, its throttle and its six-hour fallback",
            ),
            ("at most once every two hours", "the idle throttle"),
            ("six hours after the last sweep", "the fallback is measured from the last sweep"),
            ("End every sweep with the next three lead-owned backlog rows", "the next-pick rule"),
            ("each with one line on why it comes next", "each pick says why it comes next"),
            ("they are proposals, not dispatches", "a pick is not a dispatch"),
            (
                "settle every row waiting on the user through one door",
                "the sweep's scope: a dependency or resource wait has no door here",
            ),
            ("attest a look the user already gave", "the look door"),
            (
                "withdraw a moot ask (`tasks__update` canceled, its `detail` a reason the row \
                 does not already carry)",
                "the withdraw door, and the new-reason requirement",
            ),
            ("park a wait the user deferred (`parked: true`)", "the park door"),
            ("leave a genuine decision for the user and name it in your line", "the decision door"),
            (
                "close every epic reading `to_close`, a `verify: user` root parking on the look \
                 first and then being attested",
                "the epic close, including the gate's park-then-attest order",
            ),
            ("dispatch the next ready and unowned row", "the dispatch pick"),
            (
                "report one line: attested, withdrawn, parked, closed, dispatched, and the \
                 decisions still waiting on the user",
                "the sweep answers in one line",
            ),
        ] {
            assert!(
                DEFAULT_LEAD_CHARTER.contains(clause),
                "the lead charter does not carry the board sweep ({why}): {clause}",
            );
        }

        // The two pinned sentences carry the cron tool names by necessity,
        // so they are cut out before the net runs over what is left.
        let cleanup_sentence = format!("{CLEANUP} - {REASON}.");
        let without_cleanup = section.replacen(&cleanup_sentence, "", 1);
        assert_ne!(
            without_cleanup, section,
            "the pinned cleanup sentence is one sentence: {cleanup_sentence}",
        );
        let prohibition = "Never create a standing sweep cron.";
        let rest = without_cleanup.replacen(prohibition, "", 1);
        assert_ne!(rest, without_cleanup, "the pinned prohibition is one sentence: {prohibition}");
        if let Some((marker, at)) = cron_marker(&rest) {
            let near = context_around(&rest, at);
            panic!("the board section carries {marker:?} near: {near}");
        }

        let creations: Vec<usize> =
            DEFAULT_LEAD_CHARTER.match_indices("cron__create").map(|(at, _)| at).collect();
        let sites = if creations.is_empty() {
            "none".to_owned()
        } else {
            creations
                .iter()
                .map(|&at| context_around(DEFAULT_LEAD_CHARTER, at))
                .collect::<Vec<_>>()
                .join(" | ")
        };
        assert_eq!(
            creations.len(),
            1,
            "the charter's only cron creation is the report-only one-shot sentence; found {} at: \
             {sites}",
            creations.len(),
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("schedule a report-only `cron__create` one-shot (`run_once_at`)"),
            "the single cron creation is the one-shot advice",
        );
    }

    /// The net's own machinery, proved away from the charter: the charter
    /// carries none of these markers today, so a detector that stopped
    /// matching, or a scan that stopped lowercasing, would leave every
    /// assertion above green. The expressions are the forms forge's own
    /// validator accepts - wildcards, names, ranges and aliases.
    #[test]
    fn the_board_section_net_catches_cron_markers() {
        for (text, why) in [
            ("`*/30 * * * *`.", "a backtick-wrapped expression ending in a period"),
            ("0 6 * * 1", "five plain fields"),
            ("(0 9 * * 1)", "a parenthesised expression"),
            ("0 9 * * MON", "a day name"),
            ("0 9 * * MON-FRI", "a day range"),
            ("@daily", "an alias"),
        ] {
            assert!(cron_expression(text).is_some(), "{text} is a cron expression ({why})");
        }
        assert!(
            cron_marker("Create a CRON job each morning").is_some(),
            "the scan lowercases, so a capitalised CRON is caught",
        );
        assert_eq!(trim_cron_token("`0`."), "0", "backticks and a period are trimmed");
        assert_eq!(trim_cron_token("`1`,"), "1", "backticks and a comma are trimmed");
        assert_eq!(trim_cron_token("(2);"), "2", "parentheses and a semicolon are trimmed");
        assert_eq!(cron_expression("word"), None, "prose is not a cron expression");
    }

    /// The board section, from its heading to the next top-level heading.
    fn board_section() -> &'static str {
        let start = DEFAULT_LEAD_CHARTER
            .find("## Keep the task board")
            .expect("the board section heading `## Keep the task board` is present");
        let tail = &DEFAULT_LEAD_CHARTER[start..];
        let end = tail.find("\n## ").unwrap_or(tail.len());
        &tail[..end]
    }

    /// The first cron marker the board-section net recognises in `text`: a
    /// cron word, a `wake:` parameter or a cron expression. The haystack is
    /// lowercased with the ASCII-only form on purpose - it preserves byte
    /// offsets, so the failure context can be sliced out of the original
    /// text.
    fn cron_marker(text: &str) -> Option<(String, usize)> {
        let haystack = text.to_ascii_lowercase();
        for token in ["cron", "wake:"] {
            if let Some(at) = haystack.find(token) {
                return Some((token.to_owned(), at));
            }
        }
        cron_expression(&haystack).map(|at| ("cron expression".to_owned(), at))
    }

    /// A whitespace-separated token with the punctuation prose wraps a
    /// schedule in: code-span ticks, a trailing period or comma, parentheses,
    /// semicolons and quotes.
    fn trim_cron_token(word: &str) -> &str {
        word.trim_matches(['`', '.', ',', '(', ')', ';', '"', '\''])
    }

    /// The byte offset of the first cron expression the board-section net
    /// recognises in `text`: every window of five whitespace-separated
    /// tokens, and every `@`-prefixed token, is stripped of its wrapping
    /// punctuation and handed to forge's own validator, so the net accepts
    /// exactly what `cron__create` would - names, ranges, aliases and all -
    /// and nothing else by construction. A numeric run such as `2 3 4 5 6`
    /// parses too; that is the trade for using the real validator, it fails
    /// loudly, and the board section carries no such run.
    fn cron_expression(text: &str) -> Option<usize> {
        let mut tokens: Vec<(usize, &str)> = Vec::new();
        let mut cursor = 0;
        for word in text.split_whitespace() {
            let at = cursor + text[cursor..].find(word)?;
            cursor = at + word.len();
            let trimmed = trim_cron_token(word);
            if !trimmed.is_empty() {
                tokens.push((at, trimmed));
            }
        }
        for (at, token) in &tokens {
            if token.starts_with('@')
                && crate::mcp::cron::schedule::validate_cron_expr(token).is_ok()
            {
                return Some(*at);
            }
        }
        for window in tokens.windows(5) {
            let expr = window.iter().map(|(_, word)| *word).collect::<Vec<_>>().join(" ");
            if crate::mcp::cron::schedule::validate_cron_expr(&expr).is_ok() {
                return Some(window[0].0);
            }
        }
        None
    }

    /// A window of `text` around `at`, so a failure names the lineage
    /// without dumping the whole charter.
    fn context_around(text: &str, at: usize) -> &str {
        let start = text[..at].char_indices().rev().nth(60).map_or(0, |(i, _)| i);
        let end = text[at..].char_indices().nth(120).map_or(text.len(), |(i, _)| at + i);
        &text[start..end]
    }

    /// #1494: the parallelism rule reads the project's own `max_workers`
    /// rather than a figure in the prose, and a slot held below the cap
    /// is held by a guardrail the lead names.
    #[test]
    fn lead_charter_derives_parallelism_from_the_project_cap() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("`max_workers`"),
            "the fill-the-cap rule names the project's own key: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("agents__capacity"),
            "the rule points at the tool that reports the cap: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("Hold a slot back only when a guardrail above blocks the next piece, and say plainly which one"),
            "a slot held below the cap is held by a named guardrail: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            !DEFAULT_LEAD_CHARTER.contains("2-3"),
            "no fixed worker figure in the prose - the cap is the config's: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// The guardrails say what a lead serializes; this rule says what a
    /// lead must NOT - a read-only stage queued behind a write idles for
    /// the whole write and reads as waiting rather than blocked. The
    /// one-question test is pinned with its verdict, since the verdict is
    /// what stops a cautious lead from holding a whole chain.
    #[test]
    fn lead_charter_carries_the_serialize_the_write_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("**Serialize the write, not the read.**"),
            "the rule's handle is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("ask which of its next stages touches shared state"),
            "the test before a HOLD is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "if I start this now, what does it touch? If nothing shared, it starts now, \
                 whatever the merge order"
            ),
            "the test question and its verdict are pinned together: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// The gate is independent review lenses, not the lead's own read of
    /// the diff - pinned with the fresh-install guard, so the sentence can
    /// never read as a mandate for tooling that is not there.
    #[test]
    fn lead_charter_carries_the_merge_gate_lens_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("The merge gate is not met by a solo diff-read"),
            "the rule's handle is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("independent review lenses where they exist are what satisfies it"),
            "the lenses and their condition are pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("Nothing here mandates tooling a fresh install does not have"),
            "the fresh-install guard is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("A round is not clean until every"),
            "a partial round is never clean: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "not a clean round, because the one still running is the one that has not spoken"
            ),
            "a clean return does not stand for the round: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("never merge on the first one back"),
            "the merge waits for the last review, not the first: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// A false claim of coverage survives author review because the diff
    /// cannot contradict a sentence, so one lens reads the prose. Pinned
    /// with what it reads, what it fails, and the phrases that hide a claim
    /// with nothing behind it.
    #[test]
    fn lead_charter_carries_the_prose_audit_lens() {
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("Every review round gets one lens that audits the prose, not the code"),
            "the lens, its every-round duty and its subject are pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "reads the PR body, the commit messages and the spec against what the work \
                 actually does"
            ),
            "what the lens reads is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "fails any claim of coverage, a passing gate, a failure mode or a known gap \
                 with no evidence behind it"
            ),
            "the claim classes it fails are pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "\"covered by tests\", \"cannot happen\", \"unchanged behaviour\" and \"known \
                 limitation\" are the highest-risk phrases"
            ),
            "the highest-risk phrases are pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("one of them reading the prose, not the code"),
            "the roster names the prose lens at the fan-out: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// Two workflows fire per push and their ids sit adjacent in no stable
    /// order, so a verdict is only checkable when it names its workflow.
    /// Pinned at the merge gate and the health check, where a lead reports.
    #[test]
    fn lead_charter_quotes_the_workflow_beside_a_verdict() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("Quote the workflow name beside every verdict"),
            "the rule's handle is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "read the job list off the run whose workflow is the one you are claiming"
            ),
            "the job list is read off the claimed workflow: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("one workflow's green is not another's"),
            "the adjacent-workflow confusion is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("quote each run's workflow name with its verdict"),
            "the health check repeats the rule where a lead reconciles: {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// A permission decision belongs to the conversation that raised it, so
    /// a lead relaying the user's go-ahead cannot clear a worker's gated
    /// action. Pinned at the merge step, where the lead is most likely to
    /// pass one on.
    #[test]
    fn lead_charter_carries_the_relayed_approval_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER.contains("a relayed approval is not an approval"),
            "the rule's handle is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains(
                "a worker's gated action needs the user's word in that worker's own \
                 conversation, not your relay of it"
            ),
            "the seat that needs the word is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("have the user paste it into that worker's chat"),
            "the route reconciling the rule with 'the user talks ONLY to you' is pinned: \
             {DEFAULT_LEAD_CHARTER}",
        );
    }

    /// Two PRs each green on its own base merged in sequence composed red
    /// on main (measured 2026-08, again 2026-10-17, from a branch that
    /// predated the other's merge), so the merge-gate bullet carries the
    /// moved-main rule: origin/main merged in before the final gate, and
    /// main's CI read after the merge. Pinned with both halves, because
    /// either alone reads as a caveat with no action.
    #[test]
    fn lead_charter_carries_the_composed_main_rule() {
        assert!(
            DEFAULT_LEAD_CHARTER
                .contains("A branch green on its own base can compose red on a moved main"),
            "the composed-red fact is pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("have the worker merge origin/main into its branch"),
            "the remedy's actor and its merge are pinned: {DEFAULT_LEAD_CHARTER}",
        );
        assert!(
            DEFAULT_LEAD_CHARTER.contains("after the PR merges main's CI is the only truth"),
            "the post-merge read is pinned: {DEFAULT_LEAD_CHARTER}",
        );
    }
}