forge_workspace/

mcp.rs

//! In-process MCP server forge exposes to every spawned `claude`
//! subprocess.
//!
//! The single MCP server is named `forge` and grouped by submodule:
//!
//! - `agents` - every session reaches every other by its slot: `list`,
//!   `tell`, `ask`, `whoami` and `handoff` for any caller, plus `spawn`,
//!   `despawn`, `update` and `capacity` for a lead. Tools render as
//!   `mcp__forge__agents__<name>`.
//! - `documents` - the document hand-off: a session hands the person at a
//!   client a document that opens in the client's own viewer. Renders as
//!   `mcp__forge__documents__hand_off`.
//! - `review` - the review-conversation loop (list / get / reply /
//!   resolve). Tools render as `mcp__forge__review__<name>`.
//! - `cron` - the caller's own durable crons.
//! - `tasks` - the caller's own project's live task list.
//! - `gotify` - the caller's own Gotify subscriptions.
//! - `slack` - the caller's own Slack subscriptions, reads and held
//!   outbound actions.
//! - `settings` - forge's own configuration (`index`, `get`, `set`,
//!   `unset`), with every write held for the reader's approval.
//! - `systemone` - the decision tools (`ask_noul`, `ask_choice`,
//!   `ask_score`), injected only when `[systemone]` is configured and
//!   enabled.
//! - `voice` - `say`: one utterance spoken aloud to the person listening to
//!   the seat. Renders as `mcp__forge__voice__say`.
//! - `vault` - the Vaultwarden family: search, read with a reveal, create,
//!   update, soft-delete and restore items, compute TOTP codes, move
//!   attachments, and manage folders. Every call is held for the reader's
//!   approval. Renders as `mcp__forge__vault__<name>`.
//!
//! Tool surface depends on the calling session's kind:
//!
//! - **Lead** sessions (project leads, including project sessions
//!   another agent spawned) see all eight `agents__*` verbs. A lead is
//!   the only role that can spawn, despawn, update or read capacity,
//!   because each of those acts on the caller's own project.
//! - **Worker** sessions see the four shared verbs and none of the
//!   lead-only ones. The reach is the same: a worker may address any
//!   other session by its slot, its own lead and siblings included. A
//!   handoff is shared because a seat is its own to hand over.
//!
//! Future submodules slot in alongside these (e.g. `worktree`,
//! `memory`) without changing the server name or the auto-approve
//! fast-path in `forge-sdk::control_dispatch` (which matches the
//! `mcp__forge__` prefix at the tool-name level).

use std::collections::BTreeSet;
use std::sync::Arc;

use forge_sdk::mcp::server::{McpServer, McpServerBuilder};

use crate::SessionSlot;
use crate::mcp::agents::facade::AgentDispatcher;
use crate::mcp::browser::facade::BrowserFacade;
use crate::mcp::cron::facade::CronFacade;
use crate::mcp::documents::facade::DocumentFacade;
use crate::mcp::gotify::facade::GotifyFacade;
use crate::mcp::peers::facade::WorkspaceFacade;
use crate::mcp::review::facade::ReviewFacade;
use crate::mcp::settings::facade::SettingsFacade;
use crate::mcp::slack::facade::SlackFacade;
use crate::mcp::systemone::facade::SystemOneFacade;
use crate::mcp::tasks::facade::TasksFacade;
use crate::mcp::vault::facade::VaultFacade;
use crate::mcp::workers::facade::WorkerFacade;

pub mod agents;
pub mod browser;
pub(crate) mod caller_context;
pub mod cron;
pub(crate) mod deleted;
pub mod documents;
pub mod gotify;
pub mod peers;
pub mod review;
pub mod settings;
pub mod slack;
pub mod systemone;
pub mod tasks;
pub mod terminal;
#[cfg(test)]
pub(crate) mod test_support;
pub mod vault;
pub mod voice;
pub mod workers;

/// Identifies which kind of session the MCP server is being built
/// for. Drives the tool-surface filter in [`build_forge_server`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionKind {
    /// Project lead - the session representing a project. Sees all
    /// eight `agents__*` verbs.
    Lead,
    /// Worker - a child agent a lead spawned. Sees the four shared
    /// `agents__*` verbs and none of the lead-only ones.
    Worker,
}

/// The toggleable MCP families. `agents` is always on and is not here:
/// a worker without `tell`/`ask` cannot report to its lead.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum McpFamily {
    Review,
    Cron,
    Tasks,
    Gotify,
    Slack,
    Systemone,
    Voice,
    Vault,
}

impl McpFamily {
    /// Every toggleable family, in wire order.
    pub const ALL: [McpFamily; 8] = [
        McpFamily::Review,
        McpFamily::Cron,
        McpFamily::Tasks,
        McpFamily::Gotify,
        McpFamily::Slack,
        McpFamily::Systemone,
        McpFamily::Voice,
        McpFamily::Vault,
    ];

    /// The default set: a worker whose row names none gets everything.
    pub fn all() -> BTreeSet<McpFamily> {
        Self::ALL.into_iter().collect()
    }

    /// The wire spelling, also the family segment its tool names carry.
    pub fn as_str(self) -> &'static str {
        match self {
            McpFamily::Review => "review",
            McpFamily::Cron => "cron",
            McpFamily::Tasks => "tasks",
            McpFamily::Gotify => "gotify",
            McpFamily::Slack => "slack",
            McpFamily::Systemone => "systemone",
            McpFamily::Voice => "voice",
            McpFamily::Vault => "vault",
        }
    }

    /// Parse a spawn argument's spelling; `None` for anything else.
    pub fn parse(name: &str) -> Option<Self> {
        Self::ALL.into_iter().find(|family| family.as_str() == name)
    }
}

/// A stored selection's resolved set: absent or empty means every
/// family; names are canonicalised into wire order and de-duplicated.
/// Unknown names cannot be written by either tool (both validate), but a
/// hand-edited row could carry one - it is dropped loudly rather than
/// widening or narrowing the surface silently.
pub(crate) fn resolve_mcp_families(stored: Option<&[String]>) -> BTreeSet<McpFamily> {
    let Some(stored) = stored else {
        return McpFamily::all();
    };
    if stored.is_empty() {
        return McpFamily::all();
    }
    let requested: BTreeSet<McpFamily> = stored
        .iter()
        .filter_map(|name| {
            let parsed = McpFamily::parse(name);
            if parsed.is_none() {
                tracing::warn!(
                    target: "forge_workspace::mcp",
                    event_name = "unknown_mcp_family_in_row",
                    name = %name,
                    "a stored mcp family name is not selectable; ignoring it",
                );
            }
            parsed
        })
        .collect();
    if requested.is_empty() {
        // A row nothing valid survives from is corrupt, not a selection
        // of nothing: fail open to every family the way an unreadable
        // row does, never to agents-only beside a withheld line per family.
        tracing::warn!(
            target: "forge_workspace::mcp",
            event_name = "mcp_family_row_all_unknown",
            "every stored mcp family name was unselectable; reading the row as every family",
        );
        return McpFamily::all();
    }
    requested
}

/// The effective set: the stored selection resolved, then narrowed by
/// what this forge's config can actually inject - the same gates the
/// build applies, so the prompt's withheld lines cannot drift from the
/// tools the session really gets. `[systemone]` and `[tts]` off are the
/// config gates that remove a family outright.
pub(crate) fn effective_mcp_families(
    stored: Option<&[String]>,
    systemone_available: bool,
    voice_available: bool,
    vault_available: bool,
) -> BTreeSet<McpFamily> {
    let mut families = resolve_mcp_families(stored);
    if !systemone_available {
        families.remove(&McpFamily::Systemone);
    }
    if !voice_available {
        families.remove(&McpFamily::Voice);
    }
    if !vault_available {
        families.remove(&McpFamily::Vault);
    }
    families
}

/// The canonical stored form of a selection: names in wire order,
/// de-duplicated; an empty list means every family, so it is stored as
/// `None`.
pub(crate) fn canonical_mcp_families(names: &[String]) -> Result<Option<Vec<String>>, String> {
    if names.is_empty() {
        return Ok(None);
    }
    let mut selected: BTreeSet<McpFamily> = BTreeSet::new();
    for name in names {
        if name == "agents" {
            return Err("`agents` is always on for every worker and cannot be listed".to_owned());
        }
        // The browser is the other always-on group, for a different reason:
        // it is one machine-global client rather than a project's scope, so
        // there is nothing a project could withhold.
        if name == "browser" {
            return Err("`browser` is always on for every session and cannot be listed".to_owned());
        }
        let Some(family) = McpFamily::parse(name) else {
            let selectable: Vec<&str> =
                McpFamily::ALL.iter().map(|family| family.as_str()).collect();
            return Err(format!(
                "unknown MCP family `{name}`; the selectable families are: {}",
                selectable.join(", ")
            ));
        };
        selected.insert(family);
    }
    Ok(Some(selected.into_iter().map(McpFamily::as_str).map(str::to_owned).collect()))
}

/// The lines a worker's prompt carries for the families it was NOT
/// given: one per withheld family, in wire order. All families selected
/// means no lines. This wording ships as the worker's own instruction
/// (rule 17), so it says what is absent and what to do instead.
pub(crate) fn withheld_family_lines(families: &BTreeSet<McpFamily>) -> Vec<&'static str> {
    McpFamily::ALL
        .into_iter()
        .filter(|family| !families.contains(family))
        .map(|family| match family {
            McpFamily::Review => {
                "This session has no `review__*` tools. Review threads for your work are \
                 handled through your lead - ask it to relay findings or to post your replies."
            }
            McpFamily::Cron => {
                "This session has no `cron__*` tools. You cannot schedule durable work; ask \
                 your lead to set up any recurring task."
            }
            McpFamily::Tasks => {
                "This session has no `tasks__*` tools. The project task list is not yours to \
                 edit; report status to your lead instead."
            }
            McpFamily::Gotify => {
                "This session has no `gotify__*` tools. Notifications from Gotify do not \
                 reach you; your lead carries anything urgent."
            }
            McpFamily::Slack => {
                "This session has no `slack__*` tools. Channel reads and posts go through \
                 your lead."
            }
            McpFamily::Systemone => {
                "This session has no `systemone__*` decision tools. When a decision is \
                 material and not obvious, route it to your lead instead of guessing."
            }
            McpFamily::Voice => {
                "This session has no `voice__*` tools. The person listening cannot hear this \
                 session; put anything they should know in your message to your lead."
            }
            McpFamily::Vault => {
                "This session has no `vault__*` tools. Credentials in the vault are not \
                 reachable from this session; ask your lead to read or change them."
            }
        })
        .collect()
}

/// The facades one session's server is composed from: the agents pair
/// plus one per toggleable family.
pub struct ForgeServerFacades {
    pub workspace: Arc<dyn WorkspaceFacade>,
    pub worker: Arc<dyn WorkerFacade>,
    pub browser: Arc<dyn BrowserFacade>,
    pub terminal: Arc<dyn crate::mcp::terminal::facade::TerminalFacade>,
    pub documents: Arc<dyn DocumentFacade>,
    pub review: Arc<dyn ReviewFacade>,
    pub cron: Arc<dyn CronFacade>,
    pub gotify: Arc<dyn GotifyFacade>,
    pub slack: Arc<dyn SlackFacade>,
    pub settings: Arc<dyn SettingsFacade>,
    pub tasks: Arc<dyn TasksFacade>,
    pub systemone: Option<Arc<dyn SystemOneFacade>>,
    pub voice: Arc<crate::voice::VoiceService>,
    /// The vault family's facade, `None` when `[vault]` is absent. The tools
    /// are doubly gated like systemone's: the family must be selected and a
    /// session must exist.
    pub vault: Option<Arc<dyn VaultFacade>>,
}

/// Build the per-session `forge` MCP server. ONE McpServer named
/// `forge` carrying the coordination tool groups appropriate for the
/// calling session's [`SessionKind`]:
///
/// - [`SessionKind::Lead`] → agents (all seven) + the selected families.
/// - [`SessionKind::Worker`] → agents (the shared three) + the selected
///   families.
///
/// `families` narrows the toggleable groups: only the selected ones
/// register. The `agents` core is unconditional, and `systemone` is
/// doubly gated - the family and a configured client.
///
/// `review`, `cron`, `tasks`, `gotify` and `slack` are any-caller, so they
/// register for both kinds - unlike the four lead-only `agents__*` verbs. What
/// each acts on is scoped rather than gated on session kind: a review
/// conversation belongs to a project and branch, crons and subscriptions to
/// the caller that made them, and tasks to the caller's project. A review
/// nudge lands on a worker seat, so the family must be offered to workers
/// and the nudge must stay usable when it is withheld.
///
/// All submodules share the server name so the LLM sees a single
/// namespace (`mcp__forge__<group>__*`) and the auto-approve fast-path
/// in `forge-sdk::control_dispatch` matches every tool group with one
/// `mcp__forge__` prefix check.
///
/// Building two separate `McpServer::builder("forge")` instances and
/// pushing both into `OptionsBuilder::mcp_server` would collide on
/// the duplicate name and the CLI would reject one - so the right
/// shape is to combine the (selected) tool sets into a single
/// builder here.
///
/// `slot` is the calling session's slot. Each tool holds its own clone
/// of it, which is safe because a slot is stable across `/new` and
/// `/resume` - those swap the occupant and leave the slot alone.
pub fn build_forge_server(
    facades: ForgeServerFacades,
    families: &BTreeSet<McpFamily>,
    slot: &SessionSlot,
    kind: SessionKind,
) -> McpServer {
    let ForgeServerFacades {
        workspace,
        worker,
        browser,
        terminal,
        documents,
        review,
        cron,
        gotify,
        slack,
        settings,
        tasks,
        systemone,
        voice,
        vault,
    } = facades;
    let mut builder = McpServerBuilder::new("forge", env!("CARGO_PKG_VERSION"));
    let dispatcher = Arc::new(AgentDispatcher::new(workspace, worker.clone()));
    builder = agents::add_shared_tools(builder, dispatcher, slot.clone());
    if matches!(kind, SessionKind::Lead) {
        builder = agents::add_lead_tools(builder, worker, slot.clone());
    }
    // Unconditional for both kinds: the browser is the SERVER's fleet rather
    // than a per-project scope, so every session may drive it, and a server
    // with no host answers with its own sentence rather than a tool that
    // varies by who is running. The one exception is `browser_end_host`: every
    // session is offered it, and only a lead may use it, because it ends a
    // host every session on the profile shares.
    builder = browser::add_tools(builder, browser, slot.clone());
    // Unconditional for the same reason: the terminal is one per seat on the
    // machine, not a per-project scope, and it carries no approval gate -
    // Bash through the CLI already reaches the shell here.
    builder = terminal::add_tools(builder, terminal, slot.clone());
    // Unconditional for the same reason: a hand-off reads the caller's own
    // tree, so every session may hand a document and no project has anything
    // to withhold. The tool still takes the caller's review family, because a
    // session without it can hand a document off but cannot read the review
    // back, so its answer says so.
    let review_available = families.contains(&McpFamily::Review);
    builder = documents::add_tools(builder, documents, slot.clone(), review_available);
    // Unconditional for the same reason: the config is every session's own
    // environment, so no project has anything to withhold and every write is
    // held for the reader regardless.
    builder = settings::add_tools(builder, settings, slot.clone());
    if review_available {
        builder = review::add_tools(builder, review, slot.clone());
    }
    if families.contains(&McpFamily::Cron) {
        builder = cron::add_tools(builder, cron, slot.clone());
    }
    if families.contains(&McpFamily::Gotify) {
        builder = gotify::add_tools(builder, gotify, slot.clone());
    }
    if families.contains(&McpFamily::Tasks) {
        builder = tasks::add_tools(builder, tasks, slot.clone(), matches!(kind, SessionKind::Lead));
    }
    // Doubly gated: the family is selected AND a client exists - a
    // disabled `[systemone]` leaves no tool a session could try.
    if families.contains(&McpFamily::Systemone)
        && let Some(systemone) = systemone
    {
        builder = systemone::add_tools(builder, systemone);
    }
    if families.contains(&McpFamily::Slack) {
        builder = slack::add_tools(builder, slack, slot.clone());
    }
    // Doubly gated like `systemone`: a switched-off `[tts]` leaves no tool a
    // session could try, even when the family is selected.
    if families.contains(&McpFamily::Voice) && voice.enabled() {
        builder = voice::add_tools(builder, voice, slot.clone());
    }
    // Doubly gated like `systemone`: an absent `[vault]` leaves no tool a
    // session could try, even when the family is selected.
    if families.contains(&McpFamily::Vault)
        && let Some(vault) = vault
    {
        builder = vault::add_tools(builder, &vault, slot);
    }
    builder.instructions(TASK_BOARD_INSTRUCTIONS).build()
}

/// What every session is told about the board at session start, through
/// the protocol's `instructions` field - the channel that reaches the
/// model without a tool call. Claude Code truncates it at 2048
/// characters, so the critical half leads; the shipped-text gate (rule
/// 17) covers the wording.
pub(crate) const TASK_BOARD_INSTRUCTIONS: &str = "\
forge's task board is the shared surface for work in flight. It is for running \
work: a landed row with no children and no epic above it is deleted in the same \
pass, never left completed; a landed child of an epic - open or already terminal \
- is completed and left terminal so the epic can read `to close` (a verify=user \
child parks in waiting on the user first). Read it \
with tasks__list: a `ready` mark means a row can be started, `worked` and \
`overdue` say how long it has run against its estimate, and an over-estimate \
message is an answer you owe. Claim an unassigned row \
before working: tasks__claim by `id`, or by `epic` to pull that epic's top \
ready row; one row in progress per worker. Keep your row true: tasks__update on every \
state change - the update is also your alive signal - and attach the PR \
the moment it exists. If you cannot proceed, tasks__wait: `kind` is \
decision (a question for the user, minted only by the lead - a hold they \
asked for, something ambiguous after the decision model, peers and your \
own review, or a look they should give when they return), dependency \
(another task - put its id \
in `on`) or resource (an account, a CI run, a machine); then move to your \
next held row, not sit still. A lead who can continue but wants \
the person's look raises the same wait - prose is not a surface. File what \
you find mid-flight at \
once with tasks__create, under your epic, owned or unowned, except a \
defect in a cut under review, which the lead fixes in line rather than \
filing; nothing else is deferred. A row with verify=user cannot complete until the user approves \
it, and that gate is minted on the row - never inherited from an epic, \
whose own gate governs only its own completion; a look the user already \
gave in chat is completed by the lead with tasks__approve and the approval \
quoted (never a decision, which is the user's to answer); completing the \
ROOT row of an epic closes it and archives the tree. \
The chase asks an over-estimate owner once and escalates to the lead once \
- answer with an update, not silence.";

#[cfg(test)]
mod tests {
    use super::*;
    use crate::mcp::browser::facade::MockBrowserFacade;
    use crate::mcp::cron::facade::MockCronFacade;
    use crate::mcp::documents::facade::MockDocumentFacade;
    use crate::mcp::gotify::facade::MockGotifyFacade;
    use crate::mcp::peers::facade::MockWorkspaceFacade;
    use crate::mcp::review::facade::MockReviewFacade;
    use crate::mcp::settings::facade::MockSettingsFacade;
    use crate::mcp::slack::facade::MockSlackFacade;
    use crate::mcp::systemone::facade::MockSystemOneFacade;
    use crate::mcp::tasks::facade::MockTasksFacade;
    use crate::mcp::workers::facade::MockWorkerFacade;

    fn fake_key(s: &str) -> SessionSlot {
        SessionSlot::from_str_for_test(s)
    }

    /// The configured shape: a systemone client exists, so its any-caller
    /// tools register for both kinds.
    fn forge_server(kind: SessionKind) -> McpServer {
        forge_server_with(kind, Some(MockSystemOneFacade::new().into_arc()))
    }

    fn forge_server_with(
        kind: SessionKind,
        systemone_facade: Option<Arc<dyn SystemOneFacade>>,
    ) -> McpServer {
        forge_server_families(kind, &McpFamily::all(), systemone_facade)
    }

    /// Claude Code truncates server instructions at 2048 characters, so
    /// the board's contract has to fit whole - a truncated tail would drop
    /// whatever came last, which is why the critical half leads.
    #[test]
    fn the_task_instructions_fit_the_client_cap() {
        assert!(
            TASK_BOARD_INSTRUCTIONS.len() < 2048,
            "the instructions are {} characters; the client truncates at 2048",
            TASK_BOARD_INSTRUCTIONS.len(),
        );
    }

    /// The built server hands the contract to every session: the constant
    /// reaches the real initialize result, not just the source.
    #[tokio::test]
    async fn the_built_server_carries_the_task_instructions() {
        let server = forge_server(SessionKind::Lead);
        let request: forge_sdk::mcp::protocol::JsonRpcRequest =
            serde_json::from_value(serde_json::json!({
                "jsonrpc": "2.0",
                "id": 1,
                "method": "initialize",
                "params": { "protocolVersion": "2025-06-18" },
            }))
            .expect("an initialize request");
        let response = server.dispatch(&request).await.expect("an id-bearing request is answered");
        let result = serde_json::to_value(response.result.expect("initialize succeeds"))
            .expect("serializes");
        assert_eq!(
            result["instructions"], TASK_BOARD_INSTRUCTIONS,
            "the built server's initialize carries the board's contract",
        );
    }

    /// The board contract is where a session first learns that
    /// `kind: decision` routes to the user, so the test for parking there
    /// rides the same line: without it the contract teaches the route and
    /// leaves out when taking it is right.
    #[test]
    fn the_task_instructions_carry_the_attention_rule() {
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains(
                "a hold they asked for, something ambiguous after the decision model, peers and \
                 your own review, or a look they should give when they return"
            ),
            "the parking test rides the kind: decision clause, channels and bar together",
        );
        assert!(
            TASK_BOARD_INSTRUCTIONS
                .contains("decision (a question for the user, minted only by the lead"),
            "the decision wait is the lead's to mint: {TASK_BOARD_INSTRUCTIONS}",
        );
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains(
                "A lead who can continue but wants the person's look raises the same wait - \
                 prose is not a surface"
            ),
            "the at-convenience channel rides the same rule: {TASK_BOARD_INSTRUCTIONS}",
        );
    }

    /// A finding of a cut under review is fixed in line, not filed: the
    /// instructions every session reads are where the filing habit was
    /// taught, so they carry the carve-out too.
    #[test]
    fn the_task_instructions_fix_a_cuts_finding_in_line() {
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains(
                "except a defect in a cut under review, which the lead fixes in line rather \
                 than filing"
            ),
            "the filing clause carries the in-line carve-out: {TASK_BOARD_INSTRUCTIONS}",
        );
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains("nothing else is deferred"),
            "the deferral ban still covers everything outside the cut",
        );
    }

    /// The board's shape is stated before any tool call (#2377): the
    /// board is for running work, so a landed row with no children and no
    /// epic above it is deleted in the same pass - the discipline the
    /// instructions owe a session that reads no description. The claim is
    /// the discipline rather than a filter: the drawn board keeps its
    /// terminal lanes, so "shows only running rows" would be false of the
    /// surface a caller is about to read. The epic carve-out rides here
    /// too, since the instructions are all some sessions read.
    #[test]
    fn the_task_instructions_name_the_board_shape() {
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains(
                "It is for running work: a landed row with no children and no epic above it \
                 is deleted in the same pass, never left completed; a landed child of an \
                 epic - open or already terminal - is completed and left terminal so the \
                 epic can read `to close` (a verify=user child parks in waiting on the user \
                 first)"
            ),
            "the instructions name the board's shape: {TASK_BOARD_INSTRUCTIONS}",
        );
        // The archive case rides the shape too (#2377): a later edit
        // dropping "completing the ROOT row ... archives the tree" would
        // leave the carve-out pointing at a close signal nothing acts on.
        assert!(
            TASK_BOARD_INSTRUCTIONS
                .contains("completing the ROOT row of an epic closes it and archives the tree"),
            "the instructions state the archive that closes an epic: {TASK_BOARD_INSTRUCTIONS}",
        );
    }

    /// The user gate is minted on the row and never inherited from its
    /// epic (#2423): the always-on block states it, so no session reads
    /// an epic's gate as its children's and parks a completed child on a
    /// look nobody owes.
    #[test]
    fn the_task_instructions_state_the_minted_gate() {
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains(
                "that gate is minted on the row - never inherited from an epic, whose own \
                 gate governs only its own completion"
            ),
            "the instructions state where the gate lives: {TASK_BOARD_INSTRUCTIONS}",
        );
    }

    /// The claim is scoped to unassigned rows (#2416): a lead assigns a
    /// worker's row at creation, and a worker reading only this block
    /// would otherwise pull a different row with `claim` by epic.
    #[test]
    fn the_task_instructions_claim_only_an_unassigned_row() {
        assert!(
            TASK_BOARD_INSTRUCTIONS.contains("Claim an unassigned row before working"),
            "the instructions scope the claim: {TASK_BOARD_INSTRUCTIONS}",
        );
    }

    struct SilentSink;
    impl crate::voice::AudioSink for SilentSink {
        fn push(&self, _seat: &SessionSlot, _chunk: forge_tts::Chunk) {}
    }

    struct SilentNotes;
    impl crate::voice::NoteDispatch for SilentNotes {
        fn note(&self, _seat: &SessionSlot, _text: &str) {}
    }

    fn silent_voice() -> Arc<crate::voice::VoiceService> {
        Arc::new(crate::voice::VoiceService::new(
            Arc::new(|| Err("no model loads in this test".to_owned())),
            crate::voice::VoiceSettings::default(),
            Arc::new(SilentSink),
            Arc::new(SilentNotes),
        ))
    }

    fn forge_server_families(
        kind: SessionKind,
        families: &std::collections::BTreeSet<McpFamily>,
        systemone_facade: Option<Arc<dyn SystemOneFacade>>,
    ) -> McpServer {
        build_forge_server(
            ForgeServerFacades {
                workspace: MockWorkspaceFacade::new().into_arc(),
                worker: MockWorkerFacade::new().into_arc(),
                browser: MockBrowserFacade::new().into_arc(),
                terminal: crate::mcp::terminal::facade::MockTerminalFacade::new().into_arc(),
                documents: MockDocumentFacade::new().into_arc(),
                review: MockReviewFacade::new().into_arc(),
                cron: MockCronFacade::new().into_arc(),
                gotify: MockGotifyFacade::new().into_arc(),
                slack: MockSlackFacade::new().into_arc(),
                settings: MockSettingsFacade::new().into_arc(),
                tasks: MockTasksFacade::new().into_arc(),
                systemone: systemone_facade,
                voice: silent_voice(),
                vault: Some(crate::mcp::vault::facade::MockVaultFacade::new().into_arc()),
            },
            families,
            &fake_key("test"),
            kind,
        )
    }

    /// Every tool name the server registered, read off its debug
    /// listing - which is exactly the set the LLM is offered.
    fn registered_names(kind: SessionKind) -> Vec<String> {
        names_of(&forge_server(kind))
    }

    fn names_of(server: &McpServer) -> Vec<String> {
        let debug = format!("{server:?}");
        let (_, tools) = debug.split_once("tools: [").expect("debug lists the tool names");
        let (tools, _) = tools.split_once(']').expect("the tool list is closed");
        tools
            .split(", ")
            .map(|name| name.trim_matches('"').to_owned())
            .filter(|name| !name.is_empty())
            .collect()
    }

    fn agents_tools(kind: SessionKind) -> Vec<String> {
        registered_names(kind).into_iter().filter(|name| name.starts_with("agents__")).collect()
    }

    /// The names the agents family has retired. None may survive: an
    /// alias would leave two names for one verb in the shipped text,
    /// which is the confusion the merge exists to remove.
    ///
    /// Two waves. The eleven `peers__*` / `workers__*` verbs the family
    /// replaced, and the two the family then folded into
    /// `agents__send_message` - a reply is another message, so the split
    /// between them was never a thing a message had to be.
    const OLD_NAMES: [&str; 13] = [
        "peers__whoami",
        "peers__list_agents",
        "peers__tell_agent",
        "peers__ask_agent",
        "workers__spawn",
        "workers__list",
        "workers__capacity",
        "workers__tell",
        "workers__ask",
        "workers__despawn",
        "workers__update",
        "agents__tell",
        "agents__ask",
    ];

    /// Every group that is any-caller BESIDE the browser: both session kinds
    /// manage their own project's reviews, crons, tasks, subscriptions and
    /// decisions. The browser's own names are read off its table instead -
    /// one list per family, so a tool added there cannot leave this behind.
    const ANY_CALLER_TOOLS: [&str; 52] = [
        "review__list",
        "review__get",
        "review__reply",
        "review__resolve",
        "cron__create",
        "cron__list",
        "cron__delete",
        "tasks__create",
        "tasks__update",
        "tasks__list",
        "tasks__delete",
        "gotify__subscribe",
        "gotify__list",
        "gotify__unsubscribe",
        "gotify__apps",
        "gotify__recent",
        "slack__list",
        "slack__subscribe",
        "slack__unsubscribe",
        "slack__post",
        "slack__edit",
        "slack__react",
        "slack__attachment",
        "slack__search",
        "slack__history",
        "slack__replies",
        "slack__user",
        "slack__users",
        "slack__me",
        "slack__pins",
        "slack__bookmarks",
        "settings__index",
        "settings__get",
        "settings__set",
        "settings__unset",
        "systemone__ask_noul",
        "systemone__ask_choice",
        "systemone__ask_score",
        "voice__say",
        "vault__search",
        "vault__get",
        "vault__create",
        "vault__update",
        "vault__trash",
        "vault__restore",
        "vault__totp_code",
        "vault__attachment_get",
        "vault__attachment_put",
        "vault__folder_list",
        "vault__folder_create",
        "vault__folder_update",
        "vault__folder_delete",
    ];

    #[test]
    fn a_lead_sees_all_eight() {
        assert_eq!(
            agents_tools(SessionKind::Lead),
            [
                "agents__capacity",
                "agents__despawn",
                "agents__handoff",
                "agents__list",
                "agents__send_message",
                "agents__spawn",
                "agents__update",
                "agents__whoami",
            ],
        );
    }

    #[test]
    fn a_worker_sees_only_the_shared_four() {
        // The role gate: a worker gains the cross-project reach the
        // merge adds, and must NOT gain a lead-only verb with it. The
        // handoff is shared because a seat is its own to hand over.
        assert_eq!(
            agents_tools(SessionKind::Worker),
            ["agents__handoff", "agents__list", "agents__send_message", "agents__whoami"],
        );
    }

    #[test]
    fn the_retired_names_are_gone() {
        for kind in [SessionKind::Lead, SessionKind::Worker] {
            let names = registered_names(kind);
            for old in OLD_NAMES {
                assert!(!names.contains(&old.to_owned()), "{old} survives for {kind:?}: {names:?}");
            }
        }
    }

    #[test]
    fn every_any_caller_group_registers_for_both_kinds() {
        let browser: Vec<String> =
            crate::mcp::browser::specs::specs().iter().map(|spec| spec.name.to_owned()).collect();
        for kind in [SessionKind::Lead, SessionKind::Worker] {
            let names = registered_names(kind);
            for expected in ANY_CALLER_TOOLS
                .iter()
                .map(|name| (*name).to_owned())
                .chain(browser.iter().cloned())
            {
                assert!(names.contains(&expected), "{expected} must register for {kind:?}");
            }
        }
    }

    /// The lead's attestation door is lead-only (#2423/B): a worker is not
    /// offered the verb at all, and a lead is.
    #[test]
    fn tasks_approve_registers_for_a_lead_only() {
        let lead = registered_names(SessionKind::Lead);
        let worker = registered_names(SessionKind::Worker);
        assert!(lead.contains(&"tasks__approve".to_owned()), "a lead misses the door: {lead:?}");
        assert!(
            !worker.contains(&"tasks__approve".to_owned()),
            "a worker is offered the lead's door: {worker:?}",
        );
    }

    /// The injection gate: without a configured `[systemone]` the decision
    /// tools must not appear at all - a session cannot try what forge
    /// chose not to offer.
    #[test]
    fn systemone_tools_absent_without_a_client() {
        for kind in [SessionKind::Lead, SessionKind::Worker] {
            let names = names_of(&forge_server_with(kind, None));
            for absent in ["systemone__ask_noul", "systemone__ask_choice", "systemone__ask_score"] {
                assert!(
                    !names.contains(&absent.to_owned()),
                    "{absent} must be absent without a client for {kind:?}: {names:?}"
                );
            }
        }
    }

    /// Withhold every toggleable family and only the always-on cores
    /// survive: the three shared verbs plus the browser surface for a
    /// worker, all seven for a lead.
    ///
    /// **The browser tools are here rather than in a family, and that is the
    /// rule this test now pins**: they register for a session whose every
    /// toggleable family was withheld, because the browser is one
    /// machine-global client rather than a scope a project can be denied.
    #[test]
    fn withholding_every_family_leaves_only_the_agents_core() {
        let none: std::collections::BTreeSet<McpFamily> = std::collections::BTreeSet::new();
        let mut worker = names_of(&forge_server_families(
            SessionKind::Worker,
            &none,
            Some(MockSystemOneFacade::new().into_arc()),
        ));
        worker.sort();
        let mut expected: Vec<String> =
            ["agents__handoff", "agents__list", "agents__send_message", "agents__whoami"]
                .into_iter()
                .map(str::to_owned)
                .chain(crate::mcp::browser::specs::specs().iter().map(|spec| spec.name.to_owned()))
                // The document hand-off and the settings tools are always-on
                // beside the browser.
                .chain(
                    [
                        "documents__hand_off",
                        "settings__index",
                        "settings__get",
                        "settings__set",
                        "settings__unset",
                    ]
                    .into_iter()
                    .map(str::to_owned),
                )
                // The terminal is any-caller and always on, like the browser.
                .chain(
                    [
                        "terminal__open",
                        "terminal__write",
                        "terminal__read",
                        "terminal__wait",
                        "terminal__resize",
                        "terminal__close",
                        "terminal__hand_off",
                        "terminal__run",
                    ]
                    .into_iter()
                    .map(str::to_owned),
                )
                .collect();
        expected.sort();
        assert_eq!(
            worker, expected,
            "a withheld family leaves no trace, and the browser core is not one"
        );

        let lead = names_of(&forge_server_families(SessionKind::Lead, &none, None));
        assert!(lead.contains(&"agents__spawn".to_owned()), "{lead:?}");
        assert!(
            !lead.iter().any(|name| {
                name.starts_with("cron__")
                    || name.starts_with("systemone__")
                    || name.starts_with("slack__")
            }),
            "no toggleable family registers for a lead with everything withheld: {lead:?}"
        );
    }

    /// The documents tool's own tests inject the flag, so only a built
    /// server proves it comes from the caller's families.
    #[tokio::test]
    async fn the_document_hand_off_knows_whether_the_session_has_review() {
        let withheld: std::collections::BTreeSet<McpFamily> =
            McpFamily::all().into_iter().filter(|family| *family != McpFamily::Review).collect();
        for (families, expected) in [
            (McpFamily::all(), "read them back with review__get"),
            (withheld, "spawned without the `review` MCP family"),
        ] {
            let documents = MockDocumentFacade::new();
            *documents.answer.lock() = Ok((
                "/proj/docs/plan.md".to_owned(),
                forge_primitives::document::DocumentHandOffEnding::Approve {
                    review_id: Some("r-9".to_owned()),
                    note: None,
                },
            ));
            let server = build_forge_server(
                ForgeServerFacades {
                    workspace: MockWorkspaceFacade::new().into_arc(),
                    worker: MockWorkerFacade::new().into_arc(),
                    browser: MockBrowserFacade::new().into_arc(),
                    terminal: crate::mcp::terminal::facade::MockTerminalFacade::new().into_arc(),
                    documents: documents.into_arc(),
                    review: MockReviewFacade::new().into_arc(),
                    cron: MockCronFacade::new().into_arc(),
                    gotify: MockGotifyFacade::new().into_arc(),
                    slack: MockSlackFacade::new().into_arc(),
                    settings: MockSettingsFacade::new().into_arc(),
                    tasks: MockTasksFacade::new().into_arc(),
                    systemone: None,
                    voice: silent_voice(),
                    vault: None,
                },
                &families,
                &fake_key("test"),
                SessionKind::Worker,
            );
            let answer = server
                .dispatch(&forge_sdk::mcp::protocol::JsonRpcRequest {
                    jsonrpc: "2.0".to_owned(),
                    id: Some(serde_json::json!(1)),
                    method: "tools/call".to_owned(),
                    params: Some(serde_json::json!({
                        "name": "documents__hand_off",
                        "arguments": { "path": "docs/plan.md", "reviewable": true },
                    })),
                })
                .await
                .expect("a tools/call is answered");
            let result = serde_json::to_value(answer.result.expect("the call is answered"))
                .expect("serializes");
            assert!(
                result["content"][0]["text"].as_str().is_some_and(|text| text.contains(expected)),
                "expected '{expected}' in {result}",
            );
        }
    }

    /// A narrow selection registers exactly the core plus the chosen
    /// family.
    #[test]
    fn a_cron_only_selection_registers_the_core_and_cron() {
        let families: std::collections::BTreeSet<McpFamily> =
            [McpFamily::Cron].into_iter().collect();
        let mut names = names_of(&forge_server_families(SessionKind::Worker, &families, None));
        names.sort();
        let mut expected: Vec<String> =
            ["agents__handoff", "agents__list", "agents__send_message", "agents__whoami"]
                .into_iter()
                .map(str::to_owned)
                .chain(crate::mcp::browser::specs::specs().iter().map(|spec| spec.name.to_owned()))
                .chain(
                    [
                        "documents__hand_off",
                        "settings__index",
                        "settings__get",
                        "settings__set",
                        "settings__unset",
                    ]
                    .into_iter()
                    .map(str::to_owned),
                )
                .chain(
                    ["cron__create", "cron__delete", "cron__list"].into_iter().map(str::to_owned),
                )
                // The terminal is any-caller and always on, so a cron-only
                // selection still carries its eight tools.
                .chain(
                    [
                        "terminal__open",
                        "terminal__write",
                        "terminal__read",
                        "terminal__wait",
                        "terminal__resize",
                        "terminal__close",
                        "terminal__hand_off",
                        "terminal__run",
                    ]
                    .into_iter()
                    .map(str::to_owned),
                )
                .collect();
        expected.sort();
        assert_eq!(names, expected, "{names:?}");
    }

    /// A stored selection resolves to the canonical set: absent and
    /// empty both mean every family, known names land in wire order, and
    /// a name no longer selectable is dropped rather than widening or
    /// narrowing the surface silently.
    #[test]
    fn stored_family_names_resolve_to_the_canonical_set() {
        assert_eq!(resolve_mcp_families(None), McpFamily::all(), "absent means every family");
        assert_eq!(resolve_mcp_families(Some(&[])), McpFamily::all(), "empty means every family");

        let stored = vec!["slack".to_owned(), "cron".to_owned()];
        assert_eq!(
            resolve_mcp_families(Some(&stored)),
            [McpFamily::Cron, McpFamily::Slack].into_iter().collect(),
            "known names resolve into the set"
        );

        let with_unknown = vec!["bogus".to_owned(), "tasks".to_owned()];
        assert_eq!(
            resolve_mcp_families(Some(&with_unknown)),
            [McpFamily::Tasks].into_iter().collect(),
            "an unknown name is dropped"
        );
    }

    /// One line per withheld family, in wire order; the present family
    /// gets none, and nothing withheld means no lines at all.
    #[test]
    fn withheld_lines_are_pinned_verbatim() {
        let none: BTreeSet<McpFamily> = BTreeSet::new();
        assert_eq!(
            withheld_family_lines(&none),
            [
                "This session has no `review__*` tools. Review threads for your work are handled through your lead - ask it to relay findings or to post your replies.",
                "This session has no `cron__*` tools. You cannot schedule durable work; ask your lead to set up any recurring task.",
                "This session has no `tasks__*` tools. The project task list is not yours to edit; report status to your lead instead.",
                "This session has no `gotify__*` tools. Notifications from Gotify do not reach you; your lead carries anything urgent.",
                "This session has no `slack__*` tools. Channel reads and posts go through your lead.",
                "This session has no `systemone__*` decision tools. When a decision is material and not obvious, route it to your lead instead of guessing.",
                "This session has no `voice__*` tools. The person listening cannot hear this session; put anything they should know in your message to your lead.",
                "This session has no `vault__*` tools. Credentials in the vault are not reachable from this session; ask your lead to read or change them.",
            ],
        );

        let slack_only: BTreeSet<McpFamily> = [McpFamily::Slack].into_iter().collect();
        let lines = withheld_family_lines(&slack_only);
        assert_eq!(
            lines.len(),
            McpFamily::ALL.len() - 1,
            "one family is present, so every other family is withheld",
        );
        for line in &lines {
            assert!(!line.contains("slack__"), "the present family gets no line: {line}");
        }
        assert!(withheld_family_lines(&McpFamily::all()).is_empty(), "nothing withheld, no lines");
    }

    /// The config gate reaches the EFFECTIVE set - what the build injects
    /// and what the prompt composer sees - so a selected-but-disabled
    /// systemone reads as withheld on both.
    #[test]
    fn the_config_gate_reaches_the_effective_set() {
        let selected = vec!["systemone".to_owned(), "tasks".to_owned()];
        assert_eq!(
            effective_mcp_families(Some(&selected), true, true, true),
            [McpFamily::Tasks, McpFamily::Systemone].into_iter().collect(),
        );
        assert_eq!(
            effective_mcp_families(Some(&selected), false, true, true),
            [McpFamily::Tasks].into_iter().collect(),
            "a disabled [systemone] cannot be part of the effective set",
        );

        let all_without_config = effective_mcp_families(None, false, true, true);
        assert!(!all_without_config.contains(&McpFamily::Systemone));
        assert_eq!(
            all_without_config.len(),
            McpFamily::ALL.len() - 1,
            "systemone is the only family this gate removes",
        );
    }

    /// `[tts]` off removes the voice family from the effective set too, so
    /// the prompt's withheld line and the tools agree.
    #[test]
    fn a_disabled_tts_removes_voice_from_the_effective_set() {
        let all_without_voice = effective_mcp_families(None, true, false, true);
        assert!(!all_without_voice.contains(&McpFamily::Voice));
        assert_eq!(
            all_without_voice.len(),
            McpFamily::ALL.len() - 1,
            "voice is the only family this gate removes",
        );
        assert!(
            withheld_family_lines(&all_without_voice).iter().any(|line| line.contains("voice__")),
            "the prompt says the family is absent",
        );
    }

    /// `[vault]` absent removes the vault family from the effective set too,
    /// so the tools and the worker's prompt agree on the double gate.
    #[test]
    fn an_absent_vault_removes_it_from_the_effective_set() {
        let all_without_vault = effective_mcp_families(None, true, true, false);
        assert!(!all_without_vault.contains(&McpFamily::Vault));
        assert_eq!(
            all_without_vault.len(),
            McpFamily::ALL.len() - 1,
            "vault is the only family this gate removes",
        );
        assert!(
            withheld_family_lines(&all_without_vault).iter().any(|line| line.contains("vault__")),
            "the prompt says the family is absent",
        );
    }

    /// The config gate reaches the COMPOSER too: a selected-but-disabled
    /// systemone produces its withheld line, which is what the spawn
    /// description promises a worker it was not given.
    #[test]
    fn a_disabled_systemone_still_produces_its_withheld_line() {
        let selected = vec!["systemone".to_owned()];
        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.";
        assert!(
            !withheld_family_lines(&effective_mcp_families(Some(&selected), true, true, true))
                .contains(&line),
            "with the section on, the family is present and gets no line",
        );
        assert!(
            withheld_family_lines(&effective_mcp_families(Some(&selected), false, true, true))
                .contains(&line),
            "[systemone] off is withheld for the worker's prompt as well as its tools",
        );
    }

    /// The two groups a spawn CANNOT list are refused by name, saying they
    /// are always on: a caller listing one is asking for a narrower surface
    /// than the one it already has, and `unknown family` would send it
    /// looking for a spelling.
    #[test]
    fn the_always_on_groups_are_refused_by_name() {
        for (name, why) in [("agents", "worker"), ("browser", "session")] {
            let refused = canonical_mcp_families(&[name.to_owned()])
                .expect_err("an always-on group cannot be listed");
            assert!(refused.contains(name), "the refusal names it: {refused}");
            assert!(
                refused.contains("always on") && refused.contains(why),
                "and says it is always on for every {why}: {refused}",
            );
            assert!(!refused.contains("unknown"), "it is not a spelling problem: {refused}");
        }
    }

    /// A stored row holding only unselectable names is corrupt, not a
    /// selection of nothing: it fails open to every family the way an
    /// unreadable row does, never to agents-only beside a withheld line
    /// per family.
    #[test]
    fn an_all_corrupt_selection_fails_open() {
        let corrupt = vec!["bogus".to_owned(), "agents".to_owned()];
        assert_eq!(
            resolve_mcp_families(Some(&corrupt)),
            McpFamily::all(),
            "a row nothing valid survives from reads as absent",
        );
    }

    /// The family set and the systemone client are independent gates: a
    /// set naming systemone injects nothing when the section is off, and
    /// a set omitting it injects nothing even when a client exists.
    #[test]
    fn the_family_set_and_the_systemone_client_gate_independently() {
        let without_systemone: std::collections::BTreeSet<McpFamily> =
            McpFamily::all().into_iter().filter(|family| *family != McpFamily::Systemone).collect();
        let names = names_of(&forge_server_families(
            SessionKind::Worker,
            &without_systemone,
            Some(MockSystemOneFacade::new().into_arc()),
        ));
        assert!(
            !names.iter().any(|name| name.starts_with("systemone__")),
            "a client alone does not inject the family: {names:?}"
        );

        let names = names_of(&forge_server_families(SessionKind::Worker, &McpFamily::all(), None));
        assert!(
            !names.iter().any(|name| name.starts_with("systemone__")),
            "[systemone] off injects nothing however the set reads: {names:?}"
        );
    }

    /// A `replay-only:` marker exempts the retired tools it NAMES, on one
    /// of the three lines around it.
    ///
    /// Two rules, and each closes a hole the other leaves. Naming: a marker
    /// exempts only the tools written after it, so an unlisted retired name
    /// beside it still fails - a marker naming something absent is merely
    /// inert, and what it cannot do is cover a name it does not list.
    /// Adjacency: the marker must sit on the exempted line, or the line
    /// directly above or below it, so a marker cannot launder a SECOND use
    /// of the same name elsewhere in the same comment block - which is a
    /// stale instruction wearing a replay marker's clothes. Three positions
    /// rather than one because the formatter moves a trailing comment
    /// between an arm's own line and its body, and the two neighbours mean
    /// one marker covers a line either side of it.
    ///
    /// It exists for text that cites a retired name as history: a reader of
    /// what a session recorded before the rename. Nothing can call a retired
    /// tool, so the marker cannot be an alias.
    const REPLAY_ONLY: &str = "replay-only:";

    /// The span of the `OLD_NAMES` declaration itself, which is the only
    /// place a bare quoted retired name is allowed to sit.
    ///
    /// **Scoped to the declaration rather than to a line's shape.** The list
    /// has to name the retired tools in order to assert them away, and a line
    /// that merely LOOKS like an entry is not the list: a retired name
    /// re-registered in a tool list has exactly that shape, and it is the
    /// alias this scan exists to refuse. `None` when the span will
    /// not read, which fails the scan loudly rather than exempting every
    /// entry.
    fn old_names_declaration(text: &str) -> Option<std::ops::RangeInclusive<usize>> {
        let lines: Vec<&str> = text.lines().collect();
        let start = lines.iter().position(|line| line.contains("const OLD_NAMES"))?;
        let end = start + lines[start..].iter().position(|line| line.trim() == "];")?;
        Some(start..=end)
    }

    /// The retired names a marker on, above or below line `at` exempts.
    fn exempted_names(lines: &[&str], at: usize) -> Vec<&'static str> {
        let adjacent = [at.checked_sub(1), Some(at), at.checked_add(1)]
            .into_iter()
            .flatten()
            .filter_map(|i| lines.get(i));
        let mut out = Vec::new();
        for line in adjacent {
            let Some((_, named)) = line.split_once(REPLAY_ONLY) else { continue };
            out.extend(OLD_NAMES.iter().copied().filter(|old| named.contains(old)));
        }
        out
    }

    /// The tracked source files, read from the working tree, paired with how
    /// many were listed.
    ///
    /// Tracked content, not a filesystem walk. A surface forge ships is a
    /// file in the repository, and a walk descends into everything git
    /// excludes - `docs/superpowers/`, `.claude/plans/`, another
    /// worktree's checkout - so it reports a clean tree or a red one
    /// depending on who else is using the machine. The recorded baselines
    /// are `.jsonl`, so the extension filter leaves them out: a capture
    /// holds whatever the capture machine printed.
    ///
    /// **An untracked file is the one blind spot**: `git ls-files` lists
    /// the index, so a source file added but not yet staged is not
    /// scanned. The mirror case - deleted but not staged - fails the
    /// caller's count assertion rather than passing quietly.
    ///
    /// **The client's own files count, and they are the ones this most
    /// rewrote.** A rename that reached `client/src/` and stopped there leaves
    /// the page calling a tool nothing registers, which is the failure the scan
    /// exists to catch - so `.ts` and `.svelte` are in, and the exemption is
    /// line-based like everything else.
    fn tracked_source_files(root: &std::path::Path) -> (usize, Vec<(String, String)>) {
        let listed = std::process::Command::new("git")
            .arg("-C")
            .arg(root)
            .args(["ls-files", "-z"])
            .output()
            .expect("git ls-files runs");
        assert!(listed.status.success(), "git ls-files failed: {listed:?}");
        let listing = String::from_utf8(listed.stdout).expect("git lists UTF-8 paths");
        let paths: Vec<&str> = listing
            .split('\0')
            .filter(|rel| {
                matches!(
                    std::path::Path::new(rel).extension().and_then(|ext| ext.to_str()),
                    Some("rs" | "md" | "ts" | "svelte")
                )
            })
            .collect();
        let listed_count = paths.len();
        let files = paths
            .into_iter()
            .filter_map(|rel| {
                std::fs::read_to_string(root.join(rel)).ok().map(|text| (rel.to_owned(), text))
            })
            .collect();
        (listed_count, files)
    }

    /// The names are gone rather than aliased, so a session that follows a
    /// stale instruction calls a tool that no longer exists, and nothing
    /// errors until it does.
    #[test]
    fn no_surface_still_names_a_retired_tool() {
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
        let (listed, files) = tracked_source_files(&root);
        // Two questions, because a scan that read nothing reports the same
        // clean verdict as a scan that read everything. The count is of
        // files that READ, against what git listed, so a partial failure
        // cannot pass; the second is a floor, so an empty listing cannot.
        assert!(
            !files.is_empty() && files.len() == listed,
            "read {} of {listed} tracked source files, so the scan is not the tree it claims",
            files.len(),
        );
        assert!(
            files.len() > 400,
            "the scan read only {} files, too few for its verdict to mean anything",
            files.len(),
        );
        let mut offenders = Vec::new();
        for (path, text) in files {
            let lines: Vec<&str> = text.lines().collect();
            let declaration = old_names_declaration(&text);
            for (number, line) in lines.iter().enumerate() {
                let exempt = exempted_names(&lines, number);
                let unexempted: Vec<&str> = OLD_NAMES
                    .iter()
                    .copied()
                    .filter(|old| line.contains(old) && !exempt.contains(old))
                    .collect();
                let declared = declaration.as_ref().is_some_and(|span| span.contains(&number));
                if !unexempted.is_empty() && !declared {
                    offenders.push(format!("{path}:{} names {unexempted:?}", number + 1));
                }
            }
        }
        assert!(
            offenders.is_empty(),
            "a retired tool name survives at: {offenders:?}. If the line cites one as history \
             rather than calling it, put a `{REPLAY_ONLY}` comment naming that tool on the line \
             itself or the one next to it.",
        );
    }

    /// The exemption has to REJECT, not only accept. Without this the helper
    /// could return every retired name unconditionally - or scan the whole
    /// file rather than the adjacent lines - and the gate would pass while
    /// exempting everything, which is how the pre-rewrite version went wrong
    /// when it skipped the file outright.
    ///
    /// The fixture is built from `OLD_NAMES` rather than repeating the names,
    /// so it cannot drift from what the gate scans for.
    #[test]
    fn the_replay_exemption_names_its_tools_and_only_those() {
        let marker_line = |tool: &str| format!("// {REPLAY_ONLY} {tool}");
        let used_line = |tool: &str| format!("\"mcp__forge__{tool}\",");
        let (wrapped, other) = (OLD_NAMES[9], OLD_NAMES[3]);
        let (mark_wrapped, use_wrapped) = (marker_line(wrapped), used_line(wrapped));
        let (mark_other, use_other) = (marker_line(other), used_line(other));
        let lines = [
            mark_wrapped.as_str(),
            use_wrapped.as_str(),
            "",
            mark_wrapped.as_str(),
            use_other.as_str(),
            "",
            mark_other.as_str(),
            "",
            "",
            use_other.as_str(),
        ];
        assert_eq!(exempted_names(&lines, 1), vec![wrapped], "a marker exempts the tool it names");
        assert!(
            !exempted_names(&lines, 4).contains(&other),
            "a marker naming another tool does not cover this line's tool",
        );
        assert!(
            exempted_names(&lines, 9).is_empty(),
            "a marker three lines away is not adjacent, whatever it names",
        );
        assert!(
            exempted_names(&[use_wrapped.as_str(), "// nothing here"], 0).is_empty(),
            "an unmarked line is exempt from nothing",
        );
    }

    /// **The entry exemption is scoped to the declaration, not to a line's
    /// shape.** A retired name registered as an alias has exactly the shape of
    /// an entry - a bare quoted string on a line of its own - so exempting by
    /// shape is how a re-created alias would pass this scan while being the
    /// thing the scan exists to refuse. The fixture is built from the list
    /// rather than from a literal, which is what keeps this file's own text
    /// from tripping the scan it tests.
    #[test]
    fn a_bare_quoted_name_is_exempt_only_inside_the_declaration() {
        let listing = format!("let tools = [\n    \"{}\",\n];\n", OLD_NAMES[0]);
        assert!(
            old_names_declaration(&listing).is_none(),
            "a text that declares no list exempts nothing at all",
        );

        let source = std::fs::read_to_string(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/mcp.rs"),
        )
        .expect("this file reads");
        let span = old_names_declaration(&source).expect("this file declares OLD_NAMES");
        let lines: Vec<&str> = source.lines().collect();
        assert_eq!(
            lines[span.start() + 1].trim().trim_end_matches(',').trim_matches('"'),
            OLD_NAMES[0],
            "the span opens on the first entry",
        );
        assert!(
            !span.contains(&(span.end() + 1)),
            "and a line past the declaration's close is not exempt",
        );
    }

    #[test]
    fn the_server_is_named_forge_for_every_session_kind() {
        // The SDK auto-approve fast-path matches `mcp__forge__` once, so
        // every group has to share the server name.
        for kind in [SessionKind::Lead, SessionKind::Worker] {
            let debug = format!("{:?}", forge_server(kind));
            assert!(
                debug.contains("name: \"forge\""),
                "server name must be 'forge'; debug: {debug}"
            );
        }
    }
}