forge_workspace/

protocol.rs

//! Command + SessionUpdate channel envelopes between a view and
//! forge-workspace. A view dispatches Commands; workspace per-session
//! tasks emit SessionUpdates back through the workspace's fan-out.
//!
//! ## Dual Command shape (deliberate)
//!
//! Two `Command` enums exist in the workspace: this one, keyed by
//! [`SessionSlot`], and [`forge_primitives::AgentCommand`], keyed by
//! `session_id: String`. They overlap on variant names (Prompt,
//! Cancel, SetMode, …) but serve different boundary layers:
//!
//! - **`forge_workspace::protocol::Command`** is the view ↔ workspace
//!   envelope. SessionSlot routing, App-level variants (SpawnProject),
//!   the workspace-internal Respond* cluster.
//! - **`forge_primitives::AgentCommand`** is the workspace ↔ agent
//!   envelope. session_id-keyed, raw shapes the AgentHandle
//!   dispatcher recognises.
//!
//! Collapsing them would force the AgentHandle dispatcher to handle
//! App-level variants it has no business in (SpawnProject is a
//! workspace concern; SessionSlot is a routing concern; neither
//! belongs in the agent layer). The current split keeps each
//! envelope minimal at its respective boundary. The translation
//! happens in `session_task::execute_command_via_handle`.

use std::path::PathBuf;

use forge_agent::client::SessionLaunchSettings;
use forge_primitives::cloud::service_status::ServiceSeverity;
use forge_primitives::error::AppError;
use forge_primitives::permission::PermissionMode;
use forge_primitives::permission_interaction::{PermissionOutcome, PermissionRequest};
use forge_primitives::plugins::{
    PluginUpdateRun, PluginUpdateTrigger, PluginsCliActionSuccess, PluginsInventorySnapshot,
};
use forge_primitives::question::{QuestionOutcome, QuestionRequest};
use forge_primitives::review::{ReviewStatus, ReviewThread};
use forge_primitives::runtime::{AvailableModel, CurrentModel, ModeState, TerminalReason};
use forge_primitives::{ImageAttachment, McpOperationError, McpServerStatus, Message, SessionId};
use serde::{Deserialize, Serialize};
use tokio::sync::oneshot;
use uuid::Uuid;

use crate::SessionSlot;
use crate::mcp::peers::types::WrappedPrompt;

// `TurnErrorClass` lives in forge-primitives so the classifier (in
// forge-agent) and consumers (views, via this protocol module)
// share one enum. Re-exported here so existing call sites keep
// resolving via `forge_workspace::protocol::TurnErrorClass`.
pub use forge_primitives::TurnErrorClass;

/// One pending interaction response slot. Workspace stores these
/// keyed by `tool_id` in `DomainSession.pending_interactions`.
/// `Command::RespondPermission` / `RespondQuestion` look up the
/// matching slot and send the outcome down the oneshot.
///
/// The request rides beside the sender so a view that attached after the
/// prompt landed still draws what it offers. The stream is a mirror with no
/// backlog, so the update that carried it is gone by then, and the dock's
/// whole point is answering from a view that was not there when it arrived.
pub enum PendingInteractionSlot {
    Permission { tx: oneshot::Sender<PermissionOutcome>, request: Box<PermissionRequest> },
    Question { tx: oneshot::Sender<QuestionOutcome>, request: Box<QuestionRequest> },
}

/// What a seat is held on, as the core kept it: the prompt a view that
/// attached late has no other way to read.
///
/// The kinds are every member of the category, not the two the dock
/// happened to draw first: a Slack draft parks on a reply the same way a
/// permission and a question do - and a browser hand-off parks on a person -
/// so a record carrying two of them told a builder the category was covered
/// when it was not.
#[derive(Clone)]
pub enum PendingAsk {
    Permission(Box<PermissionRequest>),
    Question(Box<QuestionRequest>),
    SlackDraft(Box<forge_primitives::slack::SlackDraft>),
    BrowserHandOff(Box<forge_primitives::browser::HandOff>),
    TerminalHandOff(Box<forge_primitives::terminal::TerminalHandOff>),
    DocumentHandOff(Box<forge_primitives::document::DocumentHandOffAsk>),
    SettingsWrite(Box<forge_primitives::settings::SettingsWriteAsk>),
    Vault(Box<forge_primitives::vault::VaultDraft>),
}

impl PendingAsk {
    /// The tool call this prompt is about, which is the id an answer names.
    ///
    /// `None` for a Slack draft and a hand-off: each is answered by its own
    /// command with its own id, and names no tool call at all.
    pub fn tool_id(&self) -> Option<&str> {
        match self {
            Self::Permission(request) => Some(&request.tool_call.tool_call_id),
            Self::Question(request) => Some(&request.tool_call.tool_call_id),
            Self::SlackDraft(_)
            | Self::BrowserHandOff(_)
            | Self::TerminalHandOff(_)
            | Self::DocumentHandOff(_)
            | Self::SettingsWrite(_)
            | Self::Vault(_) => None,
        }
    }
}

impl PendingInteractionSlot {
    /// The request this slot is holding, which is what it offers.
    pub fn ask(&self) -> PendingAsk {
        match self {
            Self::Permission { request, .. } => PendingAsk::Permission(request.clone()),
            Self::Question { request, .. } => PendingAsk::Question(request.clone()),
        }
    }
}

impl std::fmt::Debug for PendingInteractionSlot {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Permission { .. } => f.write_str("PendingInteractionSlot::Permission"),
            Self::Question { .. } => f.write_str("PendingInteractionSlot::Question"),
        }
    }
}

/// Synchronous return from `Command::SpawnWorker` - the session_id
/// that the new worker was issued and the tag value applied. Threaded
/// back to the calling `agents__spawn` Tool impl via the oneshot
/// receiver so the LLM sees `{session_id, tag}` in the tool result.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct WorkerSpawnReply {
    pub session_id: String,
    pub tag: String,
    /// The worker's stored MCP-family selection, canonicalised; `None`
    /// means every family. The spawn tool echoes it so the lead sees
    /// exactly which families this worker got.
    pub mcp_families: Option<Vec<String>>,
    /// Set to the account name when the walk had to take an account
    /// that is saturated or bailed, because no other account in the pin
    /// declares the project's model. The spawn tool surfaces it as a
    /// `notice`, so the lead sees at spawn that the worker may hit a
    /// 429 right away instead of only finding out when it stalls.
    pub rate_limited_account: Option<String>,
    /// Set when persisting the worker's durable row failed (the store
    /// couldn't open, or the write errored). The worker still spawns, but
    /// it won't survive a forge restart. The spawn tool surfaces it as a
    /// warning so the lead knows the "durable" promise didn't hold for
    /// this one. Mirrors `worktree_cleanup_warning` on despawn.
    pub durability_warning: Option<String>,
    /// Where the worker landed: its worktree, or `None` when the project
    /// is not a git repo and the worker runs in the project root. Set by
    /// the spawn handler, which is the only place that knows both.
    pub worktree: Option<String>,
    /// Which session the spawn landed on. The handler states what its own
    /// arguments say; the MCP facade restates it with the resolution it
    /// made, which is the only place a `resume_session` fallback is known.
    pub session_choice: SessionChoice,
}

/// Which session a worker spawn landed on, as the spawn tool reports it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionChoice {
    /// The label's prior session was found and resumed.
    Resumed,
    /// A new session, because the caller did not ask to resume.
    Fresh,
    /// A new session, because the caller asked to resume and the label
    /// had no prior session to resume.
    FreshWithoutPrior,
}

/// Outcome of a [`Command::DespawnWorker`], sent back to the calling
/// `agents__despawn` Tool via the command's `respond` oneshot.
#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DespawnResult {
    /// The worker was torn down (subprocess killed, dropped from
    /// `live_workers`). `worktree_cleanup_warning`
    /// is `Some` when the post-teardown `git worktree remove` failed -
    /// the worker is still gone; only the worktree directory lingers.
    /// Teardown and worktree cleanup are independent: a cleanup failure
    /// never rolls back the kill.
    ///
    /// `branch_cleanup_warning` is `Some` when the worker's
    /// `worktree-<label>` branch was left in place - it holds commits
    /// reachable from no other ref, or the check itself failed.
    Despawned { worktree_cleanup_warning: Option<String>, branch_cleanup_warning: Option<String> },
    /// Despawn refused: the worktree has uncommitted/untracked changes
    /// or unpushed commits and `force` was not set. Nothing was torn
    /// down; the worker stays live. `reason` names what is dirty.
    Blocked { reason: String },
    /// No live worker matched `label` (already gone or never existed).
    NotFound,
    /// The despawn could not be carried out: the worker's durable row
    /// could not be read or removed, so whether one is there is unknown.
    /// Distinct from [`Self::NotFound`], which claims there is none.
    Failed { reason: String },
}

/// Mutation kind for a `SessionUpdate::WorkerStatusChanged` event.
/// `Added` and `StatusChanged` carry a fresh `WorkerStatus` snapshot;
/// `Removed` carries the last-known snapshot for symmetry but a view's
/// reducer treats it as a delete.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerStatusAction {
    Added,
    Removed,
    StatusChanged,
}

/// What has happened to a worker's git worktree as of the
/// `SessionUpdate::WorkerStatusChanged` event carrying it. Only the
/// `agents__despawn` path ever removes one. Among the spawn
/// rollbacks, the dividing line is `Connected`: one that fires before
/// the subprocess connected reports [`Self::Absent`], because claude
/// never ran to create a worktree, while a rollback after `Connected`
/// (a failed tag-write) reports [`Self::untouched`], because by then
/// the worktree is on disk. Every other emitter reports
/// [`Self::untouched`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WorktreeDisposition {
    /// Nothing to report on: either the worker was spawned outside a
    /// git repo, or its spawn failed before it had a worktree.
    Absent,
    /// On disk and untouched.
    Intact,
    /// Gone from disk by the time the despawn finished, whether or not
    /// the despawn is what removed it.
    Removed,
    /// The despawn's removal failed and the worktree is still on disk.
    RemovalFailed,
}

/// A reply channel for a command that carries none.
///
/// A command off the socket has no channel to answer down - its reply is a
/// socket message instead - so the handler is given this rather than being
/// made to ask: sending into it reports the closed channel it is, which
/// every call site already discards.
pub fn unanswerable<T>() -> oneshot::Sender<T> {
    oneshot::channel().0
}

impl WorktreeDisposition {
    /// The disposition when nothing has touched the worktree.
    pub fn untouched(is_git_repo_at_spawn: bool) -> Self {
        if is_git_repo_at_spawn { Self::Intact } else { Self::Absent }
    }
}

/// Command envelope: a view -> forge-workspace.
///
/// Every variant carries a `SessionSlot` identifying the target
/// session task. `Workspace::dispatch` fans the variant into the
/// matching task's command receiver.
///
/// A reply channel cannot cross a socket, so the fields carrying one are
/// `Option` and skipped on the wire: `#[serde(skip)]` reconstructs a field
/// on deserialize, which needs a `Default`, and a bare `oneshot::Sender` has
/// none while an `Option` does.
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Command {
    Prompt {
        key: SessionSlot,
        text: String,
        attachments: Vec<ImageAttachment>,
    },
    /// [`Self::Prompt`], under an id the caller already minted.
    ///
    /// A view mints its own so it can draw the prompt's row and key it to the
    /// CLI's `command_lifecycle` frames by id, without matching on order or
    /// text - two sends with a cron fire between them cannot be told apart any
    /// other way. Every other dispatcher uses [`Self::Prompt`] and lets the
    /// core mint.
    PromptUnder {
        key: SessionSlot,
        text: String,
        attachments: Vec<ImageAttachment>,
        uuid: String,
        /// Who dispatched it, for the queued row's label.
        source: PromptSource,
        /// The pressing view's own token for this press, like
        /// [`Self::MarketplaceAdd`]'s: a refusal of this prompt echoes it, so
        /// a composer with sends out on two seats marks the one that failed
        /// (#1583). `None` from a view that minted none.
        #[serde(default)]
        dispatch_id: Option<u64>,
    },
    Cancel {
        key: SessionSlot,
    },
    /// Drop one prompt still in the CLI's queue, by the uuid it was sent under.
    CancelQueuedPrompt {
        key: SessionSlot,
        uuid: String,
    },
    /// A view opened the row of a finished call and asks for the command's
    /// own output: the tail of the file the CLI streamed it to.
    ///
    /// Answered by the transport from its held conversation, which carries
    /// the frame that named the call's `output_file`. The answer is
    /// [`SessionUpdate::CallOutput`] - the tail, or a named reason there is
    /// none. Asking again re-reads, which is the whole of what a running
    /// tail would need.
    ReadCallOutput {
        key: SessionSlot,
        call_id: String,
    },
    SetMode {
        key: SessionSlot,
        mode: PermissionMode,
    },
    SetModel {
        key: SessionSlot,
        model: String,
    },
    NewSession {
        key: SessionSlot,
        cwd: String,
        launch_settings: SessionLaunchSettings,
        /// The id the new occupant must run under. `None` mints one, which
        /// is what `/new` wants; a handoff supplies the id it already
        /// recorded, because its row names the pair before the spawn.
        #[serde(default)]
        session_id: Option<String>,
    },
    ResumeSession {
        key: SessionSlot,
        session_id: String,
        cwd: String,
        launch_settings: SessionLaunchSettings,
    },
    /// Hand this seat over to a new session that continues its work.
    ///
    /// **Two halves of one handoff.** `brief: None` is the entry: the seat is
    /// asked for the judgment half in the procedure turn. `brief: Some(note)`
    /// is the exit: the turn's note, accepted only while a handoff is
    /// running. Either way the successor is started the way `/new` starts one.
    Handoff {
        key: SessionSlot,
        brief: Option<String>,
    },
    RespondPermission {
        key: SessionSlot,
        tool_id: String,
        outcome: PermissionOutcome,
    },
    /// Answer a held Slack draft. The blocked Slack handler is awaiting
    /// this answer: approving sends it, declining sends nothing, and a
    /// send-back carries the reader's words to the agent instead.
    /// App-level command (`key()` returns `None`): the registry is
    /// workspace state, and `key` names the owner the answer is
    /// checked against, not a SessionTask route.
    RespondSlackPost {
        key: SessionSlot,
        id: uuid::Uuid,
        answer: forge_primitives::slack::SlackDraftAnswer,
    },
    /// Answer a parked browser hand-off. The blocked `browser_hand_off`
    /// handler is awaiting this answer: what it means, the door in the client
    /// that sent it, and - stamped by the server - the connection that carried
    /// it. App-level like `RespondSlackPost`: the registry is workspace state,
    /// and `key` names the owner the answer is checked against.
    RespondBrowserHandOff {
        key: SessionSlot,
        id: uuid::Uuid,
        answer: forge_primitives::browser::HandOffAnswer,
    },
    /// Answer a parked terminal hand-off. The blocked `terminal__hand_off`
    /// handler is awaiting this answer: what it means, the door in the client
    /// that sent it, and - stamped by the server - the connection that carried
    /// it. App-level like `RespondBrowserHandOff`: the registry is workspace
    /// state, and `key` names the owner the answer is checked against.
    RespondTerminalHandOff {
        key: SessionSlot,
        id: uuid::Uuid,
        answer: forge_primitives::terminal::TerminalHandOffAnswer,
    },
    /// Answer a parked document hand-off: `NotNow` declines it, `Approve`
    /// and `Feedback` release it with the reader's decision, note and the
    /// review the finish filed. The blocked `hand_off_document` call is
    /// awaiting this; `key` names the owner the answer is checked against.
    AnswerDocumentHandOff {
        key: SessionSlot,
        id: uuid::Uuid,
        answer: forge_primitives::document::DocumentHandOffEnding,
    },
    /// Answer a held configuration write. The blocked `settings__set` /
    /// `settings__unset` handler is awaiting this decision; `approved:
    /// false` means nothing is written. App-level like `RespondSlackPost`:
    /// the registry is workspace state, and `key` names the owner the
    /// answer is checked against.
    RespondSettingsWrite {
        key: SessionSlot,
        id: uuid::Uuid,
        approved: bool,
    },
    /// Answer a held vault call. The blocked MCP handler is awaiting this
    /// answer; a decline runs nothing, a send-back carries the reader's note
    /// to the agent, and an approval runs the call after unlocking the shared
    /// session when the card asked for the master password. App-level like
    /// `RespondSettingsWrite`: the registry is workspace state, and `key`
    /// names the owner the answer is checked against.
    RespondVaultAsk {
        key: SessionSlot,
        id: uuid::Uuid,
        answer: forge_primitives::vault::VaultAskAnswer,
    },
    /// A client enrolled one purpose's wrapped secret under its device's
    /// enrolment. The blob is opaque: the client wrapped it under the platform
    /// authenticator's key, and the core stores the bytes without decoding
    /// them.
    ///
    /// `enrolment` is the id the client minted for the device; an id the core
    /// has not seen starts the enrolment, and a known one adds or replaces the
    /// purpose's blob - a rotation's rewrite is the same command again.
    /// App-level (`key()` returns `None`); the outcome rides
    /// [`SessionUpdate::BiometricEnrolmentsChanged`].
    BiometricEnrol {
        enrolment: uuid::Uuid,
        /// The device's own name for itself, as the settings page draws it.
        device: String,
        /// The consumer the blob belongs to (`"vault"` in v1).
        purpose: String,
        /// The wrapped secret, base64.
        blob: String,
        /// Answers `true` when the blob was stored. **A store failure is a
        /// dispatch refusal, never `false`**, so the two cannot be mistaken
        /// for each other. The rotation rewrite reads the answer to decide
        /// whether the vault must lock (decision 15).
        #[serde(skip)]
        respond: Option<oneshot::Sender<bool>>,
    },
    /// A rotation's rewrite of an **existing** enrolment: the same purpose
    /// and a fresh blob on an id the core already holds.
    ///
    /// **The person's press is what creates a row**; this may only update
    /// one. A device the person revoked has no row, so its rewrite answers
    /// `false` - the client then locks rather than re-registering itself.
    /// Answers `true` when the blob was replaced, `false` when the id or the
    /// purpose is gone, and a store failure is a dispatch refusal. App-level;
    /// the outcome rides [`SessionUpdate::BiometricEnrolmentsChanged`].
    BiometricRewrite {
        enrolment: uuid::Uuid,
        purpose: String,
        blob: String,
        #[serde(skip)]
        respond: Option<oneshot::Sender<bool>>,
    },
    /// A client asks for the blob it enrolled for one purpose, so its gate can
    /// unwrap it. Answers through `reply_to` with the blob, or `null` when that
    /// purpose is not enrolled on this device - the state a client falls back
    /// to the password on. A store failure is a dispatch refusal instead, so
    /// the two cannot read alike.
    BiometricRelease {
        enrolment: uuid::Uuid,
        purpose: String,
        #[serde(skip)]
        respond: Option<oneshot::Sender<Option<forge_primitives::biometric::BiometricBlob>>>,
    },
    /// The reader dropped one purpose's enrolment, or (`purpose: None`) the
    /// device's whole enrolment. App-level; the outcome rides
    /// [`SessionUpdate::BiometricEnrolmentsChanged`].
    BiometricRevoke {
        enrolment: uuid::Uuid,
        purpose: Option<String>,
    },
    /// The reader locked the shared vault now, rather than waiting for the
    /// idle clock. **App-level**: the process holds one vault session, so the
    /// settings page's vault card is where the press comes from and no seat
    /// has a better claim to it than another. Workspace state rather than
    /// agent traffic, and the parked cards are re-stamped so a dock that
    /// already drew one asks for the password again.
    VaultLock,
    /// The material a client wraps to enrol this device: the shared session's
    /// current refresh token and the account's user key, base64. Answers
    /// through `reply_to` with [`forge_primitives::vault::VaultReleased`],
    /// and `null` while the session is locked - the state a device cannot
    /// enrol from.
    ///
    /// **It is the vault's material, not the biometric gate's.** The gate
    /// stores and releases whatever blob a consumer wraps; only the vault
    /// knows what its own material is, so the command lives on the vault's
    /// surface.
    VaultEnrolmentMaterial {
        #[serde(skip)]
        respond: Option<oneshot::Sender<Option<forge_primitives::vault::VaultReleased>>>,
    },
    RespondQuestion {
        key: SessionSlot,
        tool_id: String,
        outcome: QuestionOutcome,
    },
    /// Set one `/dictate` overlay axis for this session, or clear
    /// every axis at once. Workspace state on the `DomainSession`,
    /// never routed to the agent; the echo lands as
    /// `SessionUpdate::DictateOverrides`.
    SetDictateOverride {
        key: SessionSlot,
        update: crate::dictate::DictateOverrideUpdate,
    },
    /// Clear every `/dictate` override this session holds.
    ResetDictateOverrides {
        key: SessionSlot,
    },
    /// Check the model catalogue now. App-level command (`key()` returns
    /// `None`); routed inline. Fire-and-forget: the outcome rides
    /// [`SessionUpdate::DictateModelsChanged`], so a client watches its
    /// own subscription rather than a reply.
    DictateCatalogueCheck,
    /// Download a feed variant into the models directory. App-level
    /// (`key()` returns `None`), and its outcome rides
    /// [`SessionUpdate::DictateModelsChanged`] the way a check's does.
    ///
    /// The variant is the feed's own verb for the model; its doc supplies
    /// the download link, and nothing here constructs one.
    DictateInstall {
        variant: String,
    },
    /// Load one installed model and make it the role's active model on the
    /// running forge. App-level, and its outcome rides
    /// [`SessionUpdate::DictateModelsChanged`].
    DictateActivate {
        role: crate::dictate::DictateRole,
        file: String,
    },
    /// Return one role to its `[dictate]` key or its compiled default.
    /// App-level, same outcome channel as activation.
    DictateDeactivate {
        role: crate::dictate::DictateRole,
    },
    /// Run one model over one tier of this machine's own material.
    /// App-level, and its outcome rides
    /// [`SessionUpdate::DictateModelsChanged`] like the others: ticks as
    /// it runs, then the result or the reason.
    DictateBench {
        target: crate::bench::BenchTarget,
        tier: forge_dictate::bench::Tier,
    },
    /// Stop the bench in flight. What ran so far is discarded: a partial
    /// corpus is not a result.
    DictateBenchStop,
    /// Score the speaking loop on the public corpus: synthesize each
    /// transcript, hear it back through the transcribing and cleanup pair,
    /// and report the round-trip words, the first-audio latency and the
    /// render's pace. App-level, same outcome channel as the words bench.
    VoiceBenchStart,
    /// Stop the speaking bench in flight: a partial corpus is not a result.
    VoiceBenchStop,
    /// Begin recording the read-aloud set: the connection that sent this
    /// feeds the audio as binary frames, like a take a client captures, and
    /// no session owns it. App-level; the recording's own state rides the
    /// models read.
    DictateReadAloudStart {
        /// The connection that sent this, stamped by the transport that
        /// received it, as [`Command::DictateStream`]'s is: only that
        /// connection can feed or stop the recording.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// Stop the read-aloud recording. `keep` writes it into the set; a stop
    /// that does not keeps nothing, which is the page's cancel.
    DictateReadAloudStop {
        keep: bool,
        /// Stamped like [`Command::DictateReadAloudStart`]'s.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// Drop one recording from the read-aloud set, by the id the page read.
    DictateReadAloudDelete {
        id: String,
    },
    /// Drop one saved bench result, named by its own key: the target, the
    /// tier, and the corpus it ran over.
    DictateBenchDelete {
        target: crate::bench::BenchTarget,
        tier: forge_dictate::bench::Tier,
        corpus: String,
    },
    /// Remove one downloaded model - the file and its record - which is what
    /// a sweep that scored a candidate it did not adopt leaves behind.
    DictateUninstall {
        file: String,
    },
    // --- Plugins / marketplaces (app-level; the Extensions page) ---
    //
    // These variants carry the work through the command bus so a view
    // can act. Every one is app-level (`key()` returns `None`), serialized
    // one at a time, and reports through the `Plugins*` updates a view
    // already listens to.
    /// Install one plugin at a scope. `project` names a declared project
    /// for the `project`/`local` scopes and is ignored for `user`, which
    /// runs in the home dir; it is a NAME rather than a path so the
    /// working directory always comes from `forge.toml`.
    PluginInstall {
        plugin_id: String,
        scope: String,
        project: Option<String>,
    },
    /// Update one installed plugin in its own scope and project, which the
    /// registry lookup resolves - the caller states no cwd.
    PluginUpdate {
        plugin_id: String,
        scope: String,
    },
    /// Update exactly the stale installed plugins, one CLI call per entry,
    /// continuing past failures. The set is computed from a fresh scan at
    /// dispatch, so it is what the marketplace reports NOW.
    PluginUpdateAll,
    /// Refresh the inventory through the CLI and report which installed
    /// plugins have a newer marketplace version, applying nothing.
    PluginCheckUpdates,
    /// Add a marketplace by `owner/repo` or URL, at user scope.
    ///
    /// `dispatch_id` is the pressing view's own token for this press - the
    /// add is the one plugin action whose answer disposes a draft a page is
    /// holding - and it rides back on the refusal of this dispatch and on
    /// the outcome frames that answer it, so the press can attribute its own
    /// answer to itself.
    MarketplaceAdd {
        source: String,
        dispatch_id: Option<u64>,
    },
    /// Repair a drifted marketplace with the CLI's remove-and-re-add pair.
    MarketplaceRepair {
        name: String,
    },
    /// User clicked an inactive project to wake it. No `key` - the
    /// session doesn't exist yet; workspace resolves the id it will run
    /// under and emits `SessionUpdate::Spawning` then `::Connected` on
    /// it. This is an App-level Command, not per-session.
    SpawnProject {
        project_name: String,
        launch_settings: SessionLaunchSettings,
    },
    /// The user's verdict on a row waiting on their look. App-level (no
    /// session route): the board is the user's, and the row names its
    /// own project. `approve` completes it (past the verify gate - this
    /// IS the verification); a send-back returns it to its owner with
    /// `words` appended to the detail and one message into that session.
    TaskVerdict {
        project: String,
        id: String,
        approve: bool,
        words: Option<String>,
    },
    /// The user answers a row waiting on a question: the words go into
    /// the detail, the row resumes in progress, and its owner hears once.
    TaskAnswer {
        project: String,
        id: String,
        words: String,
    },
    /// The user moves a row in its queue.
    TaskRank {
        project: String,
        id: String,
        to: RankMove,
    },
    /// The user gives a row an owner (a label in the project) or takes
    /// it back.
    TaskAssign {
        project: String,
        id: String,
        owner: Option<String>,
    },
    /// The user cuts a row from the board.
    TaskCreate {
        project: String,
        subject: String,
        parent: Option<String>,
    },
    /// The user moves a row's state directly - the drag across the board.
    /// `place` carries where a drop landed, so the position the user chose
    /// is the priority the row keeps; a keyboard lane step carries none.
    TaskMove {
        project: String,
        id: String,
        to: forge_primitives::tasks::TaskStatus,
        #[serde(default)]
        place: Option<RankMove>,
    },
    /// The user strikes a lead's attestation: the look gate is re-minted
    /// and the row parks on the user again. App-level like `TaskVerdict`.
    TaskReopen {
        project: String,
        id: String,
    },
    /// The user reserves a row's pick for themselves (or releases it): the
    /// sweep leaves a reserved row alone rather than dispatching it.
    TaskReserve {
        project: String,
        id: String,
        reserved: bool,
    },
    /// Cross-project delivery (#114 v1). Dispatched by the
    /// `mcp__forge__agents__send_message` tool impl via
    /// `WorkspaceFacade::deliver_peer_prompt`. Routed to
    /// `spawn::handle_deliver_peer_prompt` which: (a) resolves
    /// `target_project` to a `SessionSlot`; (b) if target is running,
    /// dispatches a plain `Command::Prompt` carrying the wrapper
    /// prose; (c) if sleeping, parks `wrapped` for target's owner and
    /// dispatches `Command::SpawnProject`.
    ///
    /// App-level command (`key()` returns `None`); workspace routes
    /// to the App-level handler in `spawn.rs`. The `caller` field is
    /// the source session's key, carried so a parking that never lands
    /// can route its delivery notice back.
    DeliverPeerPrompt {
        caller: SessionSlot,
        target_project: String,
        wrapped: WrappedPrompt,
        /// What happened to the prompt: `Ok(())` once it was accepted -
        /// handed to the target's running session, or parked for a spawn
        /// this handler kicked off - and `Err(reason)` when nothing could
        /// take it. The sender's ack is built from this answer alone, the
        /// way the worker engine's is (#2342).
        #[serde(skip)]
        respond: Option<oneshot::Sender<Result<(), String>>>,
    },
    /// Spawn a new worker session in `project_key`. Dispatched by
    /// the `agents__spawn` MCP Tool impl after caller-tag validation,
    /// or by the lead Connected hook when reviving
    /// across-restart workers.
    ///
    /// `resume_existing`: when `Some(session_id)`, the handler resumes
    /// the named session via `SessionTarget::Session` instead of
    /// spawning fresh. The session_id MUST already carry the
    /// `forge:worker:<label>` tag (the lead Connected hook verifies
    /// this before dispatching). `WorkerEntry::needs_tag` is set false
    /// on the resume path since the tag is already on disk. `None`
    /// preserves the original fresh-spawn path used by `agents__spawn`.
    ///
    /// `return_to` carries the spawn result back to the calling tool
    /// invocation; `Ok((session_id, tag))` on success, `Err(message)`
    /// on failure (e.g. tag-write failed; see spawn handler). On the
    /// resume path the lead Connected hook ignores the reply (the
    /// worker is for the lead's benefit, not in response to a tool
    /// call).
    SpawnWorker {
        project_key: crate::ProjectKey,
        label: String,
        charter: String,
        /// The slot of the session issuing the spawn - normally the
        /// project's lead.
        spawned_by: SessionSlot,
        resume_existing: Option<String>,
        /// First message delivered as the worker's user turn on Connected,
        /// via the rate-limited kick dispatcher. Either `agents__spawn`'s
        /// `kick`, or - on a re-spawn - the row's `resume_kick` or the
        /// generic restart note, which is the only thing that wakes a
        /// resuming worker. `None` -> no kick (the worker idles until
        /// told).
        kick: Option<String>,
        /// Re-orient message delivered instead of the generic restart
        /// note when this worker is later resumed. `None` on a re-spawn
        /// keeps whatever the row already holds.
        resume_kick: Option<String>,
        /// Whether this worker keeps the built-in `AskUserQuestion`
        /// tool. Read from the persisted row on a re-spawn, so it
        /// survives a forge restart.
        interactive: bool,
        /// The MCP families this spawn selects, exactly as
        /// `agents__spawn` validated them; `None`/empty means every
        /// family. Written to the row on a first spawn and read back
        /// from it on a re-spawn, so the selection survives restarts.
        mcp_families: Option<Vec<String>>,
        /// The tree this spawn runs the worker in, already resolved to
        /// its repo root by the facade: `None` means the project's own
        /// path. Written to the row, which is what every read-back
        /// composes from - so a defaulted field reads exactly as a
        /// spawn written before the key existed.
        #[serde(default)]
        cwd: Option<String>,
        /// True only for boot/reconnect re-spawns of persisted
        /// workers, which bypass the project's worker cap:
        /// they restore state the user already had, and their reply is
        /// dropped, so a refusal there would strand rows with no
        /// caller to hear it.
        from_boot_respawn: bool,
        #[serde(skip)]
        return_to: Option<oneshot::Sender<Result<WorkerSpawnReply, String>>>,
    },
    /// Close (terminate agent + remove from `live_workers`) the
    /// worker identified by `label` in `project_key`. Dispatched by
    /// a view's per-row close click. If duplicates exist, the latest-
    /// spawned matching entry is removed.
    CloseWorker {
        project_key: crate::ProjectKey,
        label: String,
    },
    /// Despawn the worker identified by `label` in `project_key`:
    /// terminate its agent, drop it from `live_workers`, AND clean up
    /// its git worktree. Dispatched by the
    /// `agents__despawn` MCP tool (lead-only). Unlike `CloseWorker`
    /// (a view's X-button), this also removes the worker's git worktree:
    /// a clean worktree is removed; a dirty one (uncommitted/untracked
    /// or unpushed commits) blocks the despawn unless `force`. The
    /// outcome flows back via `respond`.
    DespawnWorker {
        project_key: crate::ProjectKey,
        label: String,
        force: bool,
        #[serde(skip)]
        respond: Option<oneshot::Sender<DespawnResult>>,
    },
    /// Deliver a wrapped peer-style prompt to a worker. Same envelope
    /// as `DeliverPeerPrompt` but addressed by worker label within
    /// the caller's project rather than by cross-project name.
    ///
    /// `respond` carries what actually happened to the prompt: `Ok(())`
    /// once it 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 can only claim what the delivery really did.
    DeliverWorkerPrompt {
        caller: SessionSlot,
        project_key: crate::ProjectKey,
        target_label: String,
        wrapped: WrappedPrompt,
        #[serde(skip)]
        respond: Option<oneshot::Sender<Result<(), String>>>,
    },
    /// Deliver a wrapped prompt from a worker back to its lead.
    /// Dispatched by the `agents__send_message` Tool impl
    /// when the caller addresses `label="lead"`. The target
    /// `SessionSlot` is resolved at Tool dispatch time from the
    /// worker's `spawned_by_session_id` so the handler can deliver
    /// directly without re-doing the lookup against a possibly-mutated
    /// `live_workers` map. Wire shape is identical to
    /// `DeliverWorkerPrompt` (same PeerEnvelopeAppended echo + same
    /// `Command::Prompt` dispatch into the target session), and its
    /// `respond` carries the same acceptance answer.
    DeliverWorkerPromptToLead {
        caller: SessionSlot,
        target_lead_key: SessionSlot,
        wrapped: WrappedPrompt,
        #[serde(skip)]
        respond: Option<oneshot::Sender<Result<(), String>>>,
    },
    /// Deliver a matched Gotify notification into `project` as a plain
    /// user turn (spawning the project if asleep, exactly like a cron
    /// prompt). `team_role` targets a durable team worker when `Some`;
    /// `None` targets the project lead. Dispatched by the
    /// `GotifyHost::deliver` port impl, one per matching subscription;
    /// handled by `spawn::deliver_gotify_message`. `notification` carries
    /// the resolved app name, title, message, and priority - its
    /// `to_prose()` is the user-turn text, and the same struct drives the
    /// chat-echo. App-level command (`key()` returns `None`).
    DeliverGotifyMessage {
        project: String,
        team_role: Option<String>,
        notification: crate::mcp::gotify::types::GotifyNotification,
    },
    /// Begin a take the CLIENT captures: the connection that sent this
    /// feeds the audio as binary frames, so no device is opened here.
    /// Registered synchronously by the dispatch that receives it, so the
    /// frame a client sends next on the same ordered socket finds it.
    ///
    /// `options` are the axes that client's panel was showing; they
    /// normalize this take, where an in-process take reads the
    /// session's stored overrides at its stop.
    DictateStream {
        key: SessionSlot,
        options: crate::dictate::DictateAxes,
        /// The surface whose own capture began this take - `composer`,
        /// `review`, `files`, `doc` - carried so the landed words reach the
        /// surface that began them and no other. Absent from a client older
        /// than the field, which is the one case every surface reads as "the
        /// old rules decide", as it did before.
        ///
        /// **Read as an opaque name, never validated.** The vocabulary is the
        /// client's own, and under forge's trust model a client that misnames
        /// its take only mislabels its own words.
        #[serde(default)]
        surface: Option<String>,
        /// The connection that sent this, stamped by the transport that
        /// received it: the take belongs to that connection, so every
        /// update about it goes back there alone. `None` is this
        /// process's own take.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// Submit (`submit = true`) or abandon the take started by `key`.
    /// During recording this is release-to-submit vs discard; during a
    /// transcription in flight it abandons the ticket.
    DictateStop {
        key: SessionSlot,
        submit: bool,
        /// The connection whose take this stop addresses, stamped like
        /// [`Command::DictateStream`]'s: only the connection a take
        /// belongs to can stop it. `None` is this process's own.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// Set the status of one review thread by id, bumping its
    /// `updated_at`. App-level command (`key()` returns `None`);
    /// routed inline.
    SetReviewThreadStatus {
        project: String,
        branch: String,
        thread_id: String,
        status: ReviewStatus,
    },
    /// Release the session `session_key` (cascade-aware: a project
    /// lead's workers terminate first). Dispatched by a view's
    /// per-row close click; a view removes its own bucket around the
    /// dispatch. App-level command (`key()` returns `None`); routed
    /// inline.
    CloseSession {
        session_key: SessionSlot,
    },
    /// Insert or replace one review thread by id in `(project, branch)`.
    /// `respond` carries whether the write was confirmed, so the
    /// overlay's at-risk durability flag stays honest (the same
    /// value-returning shape as `SpawnWorker.return_to`). The handler
    /// runs inline in dispatch, so the response is present the moment
    /// dispatch returns. App-level command (`key()` returns `None`).
    UpsertReviewThread {
        project: String,
        branch: String,
        thread: ReviewThread,
        /// The seat whose words this write sends: a landed take's words are
        /// the seat's until a write carries them, and this is what tells the
        /// composer which take the comment spends (#2283). `None` from a
        /// client older than the field, and from a write no seat made.
        #[serde(default)]
        origin: Option<SessionSlot>,
        /// **The words this press sent**, as the ask's `answered_with` states
        /// its own: the thread carries every turn it ever had, so the composer
        /// cannot tell the new comment from an old one that happens to match a
        /// landed take (#2283). `None` from a client older than the field.
        #[serde(default)]
        sent_words: Option<String>,
        #[serde(skip)]
        respond: Option<oneshot::Sender<bool>>,
    },
    /// Delete one review thread from `(project, branch)` - the reviewer's
    /// own retraction, wherever its card is drawn. `respond` carries
    /// whether the store confirmed; `None` when the write failed.
    DeleteReviewThread {
        project: String,
        branch: String,
        thread_id: String,
        #[serde(skip)]
        respond: Option<oneshot::Sender<bool>>,
    },
    /// Submit (seal) the listed threads as one review round.
    /// `respond` carries the minted review, `None` when the store
    /// write failed. App-level command (`key()` returns `None`).
    SubmitReview {
        project: String,
        branch: String,
        summary: Option<String>,
        thread_ids: Vec<String>,
        origin: SessionSlot,
        #[serde(skip)]
        respond: Option<oneshot::Sender<Option<forge_primitives::ReviewSet>>>,
    },
    /// A client turned voice on or off for the seat. The listener set is per
    /// connection, so the transport stamps which one.
    VoiceMode {
        key: SessionSlot,
        on: bool,
        /// Whether this off is the reader's own, which is what tells the
        /// session it has stopped listening. A move to another seat pauses
        /// without the note, so a seat switch does not toggle the agent.
        #[serde(default)]
        explicit: bool,
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// Play one voice on the seat's own stream, so it can be heard before it
    /// is chosen. Refused when that seat's speaker switch is off.
    VoicePreview {
        key: SessionSlot,
        voice: String,
    },
}

impl Command {
    /// The `SessionSlot` this command routes to, or `None` for
    /// App-level commands (`SpawnProject`). `Workspace::dispatch`
    /// routes `None` commands to its app-level handler (which resolves
    /// the id the new session will run under and spawns the agent);
    /// `Some(key)` commands route to the matching SessionTask.
    pub fn key(&self) -> Option<&SessionSlot> {
        match self {
            Self::Prompt { key, .. }
            | Self::PromptUnder { key, .. }
            | Self::Cancel { key }
            | Self::CancelQueuedPrompt { key, .. }
            | Self::ReadCallOutput { key, .. }
            | Self::SetMode { key, .. }
            | Self::SetModel { key, .. }
            | Self::NewSession { key, .. }
            | Self::ResumeSession { key, .. }
            | Self::Handoff { key, .. }
            | Self::RespondPermission { key, .. }
            | Self::RespondQuestion { key, .. }
            | Self::SetDictateOverride { key, .. }
            | Self::ResetDictateOverrides { key }
            | Self::VoiceMode { key, .. }
            | Self::VoicePreview { key, .. } => Some(key),
            Self::SpawnProject { .. }
            | Self::DictateStream { .. }
            | Self::DictateStop { .. }
            | Self::DeliverPeerPrompt { .. }
            | Self::SpawnWorker { .. }
            | Self::CloseWorker { .. }
            | Self::DespawnWorker { .. }
            | Self::DeliverWorkerPrompt { .. }
            | Self::DeliverWorkerPromptToLead { .. }
            | Self::DeliverGotifyMessage { .. }
            | Self::DictateCatalogueCheck
            | Self::DictateInstall { .. }
            | Self::DictateActivate { .. }
            | Self::DictateDeactivate { .. }
            | Self::DictateBench { .. }
            | Self::DictateBenchStop
            | Self::VoiceBenchStart
            | Self::VoiceBenchStop
            | Self::DictateReadAloudStart { .. }
            | Self::DictateReadAloudStop { .. }
            | Self::DictateReadAloudDelete { .. }
            | Self::DictateBenchDelete { .. }
            | Self::DictateUninstall { .. }
            | Self::SetReviewThreadStatus { .. }
            | Self::CloseSession { .. }
            | Self::UpsertReviewThread { .. }
            | Self::DeleteReviewThread { .. }
            | Self::RespondSlackPost { .. }
            | Self::RespondBrowserHandOff { .. }
            | Self::RespondTerminalHandOff { .. }
            | Self::AnswerDocumentHandOff { .. }
            | Self::RespondSettingsWrite { .. }
            | Self::RespondVaultAsk { .. }
            | Self::SubmitReview { .. }
            | Self::TaskVerdict { .. }
            | Self::TaskAnswer { .. }
            | Self::TaskRank { .. }
            | Self::TaskAssign { .. }
            | Self::TaskCreate { .. }
            | Self::TaskMove { .. }
            | Self::TaskReopen { .. }
            | Self::TaskReserve { .. }
            | Self::PluginInstall { .. }
            | Self::PluginUpdate { .. }
            | Self::PluginUpdateAll
            | Self::PluginCheckUpdates
            | Self::MarketplaceAdd { .. }
            | Self::MarketplaceRepair { .. }
            | Self::BiometricEnrol { .. }
            | Self::BiometricRelease { .. }
            | Self::BiometricRevoke { .. }
            | Self::BiometricRewrite { .. }
            | Self::VaultLock
            | Self::VaultEnrolmentMaterial { .. } => None,
        }
    }

    /// The dispatch id the press that made this command minted, when it
    /// named one: what a refusal echoes and the outcome frames carry back.
    pub fn dispatch_id(&self) -> Option<u64> {
        match self {
            Self::MarketplaceAdd { dispatch_id, .. } | Self::PromptUnder { dispatch_id, .. } => {
                *dispatch_id
            }
            _ => None,
        }
    }
}

impl std::fmt::Debug for Command {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Custom Debug: discriminant + routing key (and a few cheap
        // identifying fields) only. `oneshot::Sender` on `SpawnWorker`
        // isn't Debug, so deriving isn't an option; payloads can be
        // bulky and aren't useful in trace output.
        match self {
            Self::Prompt { key, .. } => {
                f.debug_struct("Prompt").field("key", key).finish_non_exhaustive()
            }
            Self::PromptUnder { key, uuid, .. } => f
                .debug_struct("PromptUnder")
                .field("key", key)
                .field("uuid", uuid)
                .finish_non_exhaustive(),
            Self::Cancel { key } => f.debug_struct("Cancel").field("key", key).finish(),
            Self::CancelQueuedPrompt { key, uuid } => {
                f.debug_struct("CancelQueuedPrompt").field("key", key).field("uuid", uuid).finish()
            }
            Self::ReadCallOutput { key, call_id } => f
                .debug_struct("ReadCallOutput")
                .field("key", key)
                .field("call_id", call_id)
                .finish(),
            Self::SetMode { key, mode } => {
                f.debug_struct("SetMode").field("key", key).field("mode", mode).finish()
            }
            Self::SetModel { key, model } => {
                f.debug_struct("SetModel").field("key", key).field("model", model).finish()
            }
            Self::NewSession { key, cwd, .. } => f
                .debug_struct("NewSession")
                .field("key", key)
                .field("cwd", cwd)
                .finish_non_exhaustive(),
            Self::ResumeSession { key, session_id, cwd, .. } => f
                .debug_struct("ResumeSession")
                .field("key", key)
                .field("session_id", session_id)
                .field("cwd", cwd)
                .finish_non_exhaustive(),
            Self::Handoff { key, brief } => f
                .debug_struct("Handoff")
                .field("key", key)
                .field("brief", &brief.as_ref().map(|_| "exit"))
                .finish(),
            Self::RespondPermission { key, tool_id, .. } => f
                .debug_struct("RespondPermission")
                .field("key", key)
                .field("tool_id", tool_id)
                .finish_non_exhaustive(),
            Self::RespondQuestion { key, tool_id, .. } => f
                .debug_struct("RespondQuestion")
                .field("key", key)
                .field("tool_id", tool_id)
                .finish_non_exhaustive(),
            Self::RespondSlackPost { key, id, answer } => f
                .debug_struct("RespondSlackPost")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish_non_exhaustive(),
            Self::RespondBrowserHandOff { key, id, answer } => f
                .debug_struct("RespondBrowserHandOff")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish_non_exhaustive(),
            Self::RespondTerminalHandOff { key, id, answer } => f
                .debug_struct("RespondTerminalHandOff")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish_non_exhaustive(),
            Self::RespondSettingsWrite { key, id, approved } => f
                .debug_struct("RespondSettingsWrite")
                .field("key", key)
                .field("id", id)
                .field("approved", approved)
                .finish(),
            Self::RespondVaultAsk { key, id, answer } => f
                .debug_struct("RespondVaultAsk")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish_non_exhaustive(),
            Self::BiometricEnrol { enrolment, device, purpose, .. } => f
                .debug_struct("BiometricEnrol")
                .field("enrolment", enrolment)
                .field("device", device)
                .field("purpose", purpose)
                .finish_non_exhaustive(),
            Self::BiometricRelease { enrolment, purpose, .. } => f
                .debug_struct("BiometricRelease")
                .field("enrolment", enrolment)
                .field("purpose", purpose)
                .finish_non_exhaustive(),
            Self::BiometricRevoke { enrolment, purpose } => f
                .debug_struct("BiometricRevoke")
                .field("enrolment", enrolment)
                .field("purpose", purpose)
                .finish(),
            Self::BiometricRewrite { enrolment, purpose, .. } => f
                .debug_struct("BiometricRewrite")
                .field("enrolment", enrolment)
                .field("purpose", purpose)
                .finish_non_exhaustive(),
            Self::VaultLock => f.write_str("VaultLock"),
            Self::VaultEnrolmentMaterial { .. } => f.write_str("VaultEnrolmentMaterial"),
            Self::AnswerDocumentHandOff { key, id, answer } => f
                .debug_struct("AnswerDocumentHandOff")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish_non_exhaustive(),
            Self::SetDictateOverride { key, .. } => {
                f.debug_struct("SetDictateOverride").field("key", key).finish_non_exhaustive()
            }
            Self::ResetDictateOverrides { key } => {
                f.debug_struct("ResetDictateOverrides").field("key", key).finish()
            }
            Self::SpawnProject { project_name, .. } => f
                .debug_struct("SpawnProject")
                .field("project_name", project_name)
                .finish_non_exhaustive(),
            Self::DeliverPeerPrompt { caller, target_project, .. } => f
                .debug_struct("DeliverPeerPrompt")
                .field("caller", caller)
                .field("target_project", target_project)
                .finish_non_exhaustive(),
            Self::SpawnWorker { project_key, label, spawned_by, .. } => f
                .debug_struct("SpawnWorker")
                .field("project_key", project_key)
                .field("label", label)
                .field("spawned_by", spawned_by)
                .field("return_to", &"<oneshot::Sender>")
                .finish_non_exhaustive(),
            Self::CloseWorker { project_key, label } => f
                .debug_struct("CloseWorker")
                .field("project_key", project_key)
                .field("label", label)
                .finish(),
            Self::DespawnWorker { project_key, label, force, .. } => f
                .debug_struct("DespawnWorker")
                .field("project_key", project_key)
                .field("label", label)
                .field("force", force)
                .finish_non_exhaustive(),
            Self::DeliverWorkerPrompt { caller, project_key, target_label, .. } => f
                .debug_struct("DeliverWorkerPrompt")
                .field("caller", caller)
                .field("project_key", project_key)
                .field("target_label", target_label)
                .finish_non_exhaustive(),
            Self::DeliverWorkerPromptToLead { caller, target_lead_key, .. } => f
                .debug_struct("DeliverWorkerPromptToLead")
                .field("caller", caller)
                .field("target_lead_key", target_lead_key)
                .finish_non_exhaustive(),
            Self::DeliverGotifyMessage { project, team_role, notification } => f
                .debug_struct("DeliverGotifyMessage")
                .field("project", project)
                .field("team_role", team_role)
                .field("app", &notification.app)
                .field("priority", &notification.priority)
                .finish_non_exhaustive(),
            Self::DictateCatalogueCheck => f.write_str("DictateCatalogueCheck"),
            Self::DictateInstall { variant } => {
                f.debug_struct("DictateInstall").field("variant", variant).finish()
            }
            Self::DictateActivate { role, file } => {
                f.debug_struct("DictateActivate").field("role", role).field("file", file).finish()
            }
            Self::DictateDeactivate { role } => {
                f.debug_struct("DictateDeactivate").field("role", role).finish()
            }
            Self::DictateBench { target, tier } => {
                f.debug_struct("DictateBench").field("target", target).field("tier", tier).finish()
            }
            Self::DictateBenchStop => f.write_str("DictateBenchStop"),
            Self::VoiceBenchStart => f.write_str("VoiceBenchStart"),
            Self::VoiceBenchStop => f.write_str("VoiceBenchStop"),
            Self::DictateReadAloudStart { .. } => f.write_str("DictateReadAloudStart"),
            Self::DictateReadAloudStop { keep, .. } => {
                f.debug_struct("DictateReadAloudStop").field("keep", keep).finish()
            }
            Self::DictateReadAloudDelete { id } => {
                f.debug_struct("DictateReadAloudDelete").field("id", id).finish()
            }
            Self::DictateUninstall { file } => {
                f.debug_struct("DictateUninstall").field("file", file).finish()
            }
            Self::DictateBenchDelete { target, tier, corpus } => f
                .debug_struct("DictateBenchDelete")
                .field("target", target)
                .field("tier", tier)
                .field("corpus", corpus)
                .finish(),
            Self::DictateStream { key, .. } => {
                f.debug_struct("DictateStream").field("key", key).finish_non_exhaustive()
            }
            Self::DictateStop { key, submit, .. } => {
                f.debug_struct("DictateStop").field("key", key).field("submit", submit).finish()
            }
            Self::SetReviewThreadStatus { project, branch, thread_id, status } => f
                .debug_struct("SetReviewThreadStatus")
                .field("project", project)
                .field("branch", branch)
                .field("thread_id", thread_id)
                .field("status", status)
                .finish(),
            Self::CloseSession { session_key } => {
                f.debug_struct("CloseSession").field("session_key", session_key).finish()
            }
            Self::UpsertReviewThread { project, branch, thread, .. } => f
                .debug_struct("UpsertReviewThread")
                .field("project", project)
                .field("branch", branch)
                .field("thread_id", &thread.id)
                .finish_non_exhaustive(),
            Self::DeleteReviewThread { project, branch, thread_id, .. } => f
                .debug_struct("DeleteReviewThread")
                .field("project", project)
                .field("branch", branch)
                .field("thread_id", thread_id)
                .finish_non_exhaustive(),
            Self::SubmitReview { project, branch, thread_ids, .. } => f
                .debug_struct("SubmitReview")
                .field("project", project)
                .field("branch", branch)
                .field("thread_ids", thread_ids)
                .finish_non_exhaustive(),
            Self::TaskVerdict { project, id, approve, .. } => f
                .debug_struct("TaskVerdict")
                .field("project", project)
                .field("id", id)
                .field("approve", approve)
                .finish_non_exhaustive(),
            Self::TaskAnswer { project, id, .. } => f
                .debug_struct("TaskAnswer")
                .field("project", project)
                .field("id", id)
                .finish_non_exhaustive(),
            Self::TaskRank { project, id, to } => f
                .debug_struct("TaskRank")
                .field("project", project)
                .field("id", id)
                .field("to", to)
                .finish_non_exhaustive(),
            Self::TaskAssign { project, id, owner } => f
                .debug_struct("TaskAssign")
                .field("project", project)
                .field("id", id)
                .field("owner", owner)
                .finish_non_exhaustive(),
            Self::TaskCreate { project, subject, .. } => f
                .debug_struct("TaskCreate")
                .field("project", project)
                .field("subject", subject)
                .finish_non_exhaustive(),
            Self::TaskMove { project, id, to, place } => f
                .debug_struct("TaskMove")
                .field("project", project)
                .field("id", id)
                .field("to", to)
                .field("place", place)
                .finish_non_exhaustive(),
            Self::TaskReopen { project, id } => f
                .debug_struct("TaskReopen")
                .field("project", project)
                .field("id", id)
                .finish_non_exhaustive(),
            Self::TaskReserve { project, id, reserved } => f
                .debug_struct("TaskReserve")
                .field("project", project)
                .field("id", id)
                .field("reserved", reserved)
                .finish_non_exhaustive(),
            Self::PluginInstall { plugin_id, scope, project } => f
                .debug_struct("PluginInstall")
                .field("plugin_id", plugin_id)
                .field("scope", scope)
                .field("project", project)
                .finish(),
            Self::PluginUpdate { plugin_id, scope } => f
                .debug_struct("PluginUpdate")
                .field("plugin_id", plugin_id)
                .field("scope", scope)
                .finish(),
            Self::PluginUpdateAll => f.write_str("PluginUpdateAll"),
            Self::PluginCheckUpdates => f.write_str("PluginCheckUpdates"),
            Self::MarketplaceAdd { source, dispatch_id } => f
                .debug_struct("MarketplaceAdd")
                .field("source", source)
                .field("dispatch_id", dispatch_id)
                .finish(),
            Self::MarketplaceRepair { name } => {
                f.debug_struct("MarketplaceRepair").field("name", name).finish()
            }
            Self::VoiceMode { key, on, .. } => {
                f.debug_struct("VoiceMode").field("key", key).field("on", on).finish()
            }
            Self::VoicePreview { key, voice } => {
                f.debug_struct("VoicePreview").field("key", key).field("voice", voice).finish()
            }
        }
    }
}

/// Read a no-signal peak - a level's, or the one a `no_audio` outcome
/// carries - taking `null` as no signal rather than as a decode failure.
///
/// The counterpart of serde writing a non-finite float as `null`: a
/// window that heard nothing peaks at exactly zero, whose dBFS is
/// negative infinity. Without this, a Rust reader cannot decode the
/// message at all, and the failure names the type rather than the case.
fn no_signal_reads_as_negative_infinity<'de, D>(deserializer: D) -> Result<f32, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Ok(Option::<f32>::deserialize(deserializer)?.unwrap_or(f32::NEG_INFINITY))
}

/// What one finished dictation take produced. Plain data rather than
/// [`forge_dictate::Outcome`]: a view words the notices, so it gets
/// the observations and keeps the crate's error shapes.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DictateOutcome {
    /// Words to insert at the composer's caret. `truncated` means the
    /// take hit the capture cap or the decode budget and is partial.
    Landed { text: String, truncated: bool },
    /// The audio normalised to nothing - a valid answer, not a failure.
    Empty,
    /// Nothing rose above the silence floor. A finite `peak_db` is a
    /// quiet room and a retry is reasonable; negative infinity means
    /// every sample was exactly zero, which is structural and sticky.
    NoAudio {
        #[serde(default, deserialize_with = "no_signal_reads_as_negative_infinity")]
        peak_db: f32,
        seconds: u64,
    },
    /// The take never happened. Covers a busy microphone, a device that
    /// would not open, and dictation not being ready.
    Refused { message: String },
    /// Recognition failed. The response is the same whichever way.
    Failed,
    /// The user abandoned the take. Resets silently.
    Cancelled,
}

/// The role a caller states for a spawn: a project's lead, or a worker
/// named by its label.
///
/// Both the session's tool surface and its slot's label come from this
/// one value, so they cannot disagree - a caller that says `Worker`
/// gives a worker's tool surface AND a worker's slot. Every spawn
/// states one; forge has no keyless form, because a role it cannot
/// state is one it would have to guess.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SpawnRole {
    Lead,
    Worker {
        label: String,
        /// Whether this spawn wrote the worker's durable row rather than
        /// adopting one that was already there. A rollback may take the
        /// row away only when it did: a resume and a boot re-spawn are
        /// handed a row that holds the worker's charter, kick and the id
        /// being resumed, so the row is the worker, not this spawn's
        /// leftover.
        wrote_row: bool,
        /// The stored MCP-family selection this spawn composes its tool
        /// surface from; `None`/empty means every family. Carried here
        /// because the server is built inside `get_agent_handle_at_key`,
        /// which reads no store of its own.
        mcp_families: Option<Vec<String>>,
    },
}

/// Who dispatched a prompt, for a queued row's label.
///
/// This one is about the sender, and every frame forge writes as a
/// user message gets one. Serialised as the label itself.
#[derive(Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Debug)]
#[serde(rename_all = "snake_case")]
pub enum PromptSource {
    /// A person's own send - this view's or another's.
    You,
    Cron,
    Gotify,
    Slack,
    Peer,
    /// forge's own machinery: a worker kick, an auto-continue, a replayed
    /// parked delivery whose kind is no longer known.
    Forge,
}

/// Where the user moved a row in its queue.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RankMove {
    /// Above everything ranked.
    Top,
    /// One place toward the front.
    Up,
    /// One place toward the back.
    Down,
    /// Where a drag landed: the row this one should sit above in the queue,
    /// or nothing for the end of it.
    Before(Option<String>),
}

/// One prompt waiting in the CLI's queue, as a view reads it.
///
/// The pile holds only prompts that are still waiting: an entry is appended
/// where the prompt is sent (the only place that knows its source and words)
/// and leaves on a lifecycle state the core NAMES as settled.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize, Debug)]
pub struct QueuedPrompt {
    /// The uuid the prompt was sent under, which its lifecycle frames carry.
    pub uuid: String,
    /// Who dispatched it.
    pub source: PromptSource,
    /// The prompt's words, as they were written.
    pub text: String,
    /// What the prompt carried besides its words.
    ///
    /// **Core-side only, never on the wire.** The row is drawn at the CLI's
    /// start, long after the command that carried these is gone, so the task
    /// keeps them here to build that frame; the queue a view reads is the
    /// three fields above, and a base64 payload has no business riding every
    /// seat record read.
    #[serde(skip)]
    pub attachments: Vec<forge_primitives::ImageAttachment>,
}

/// How loudly a [`SessionUpdate::Notice`] reads.
///
/// Two levels rather than a scale: the core's own answer about a seat, and
/// the failures it owes the reader - a command that did not run, a session
/// that ended.
#[derive(Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Debug)]
#[serde(rename_all = "snake_case")]
pub enum NoticeSeverity {
    /// A command's own answer.
    Info,
    /// One that did not run.
    Error,
}

/// Update envelope: forge-workspace -> a view.
///
/// Permission/Question variants do NOT carry response oneshots -
/// responses flow back via `Command::Respond*`. The workspace stores
/// the oneshot in `DomainSession.pending_interactions` when emitting
/// these variants.
///
/// `Clone` is what lets the fan-out hand one emit to more than one
/// subscriber, so every variant's payload must stay cloneable.
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionUpdate {
    /// Workspace is spawning a session (in response to
    /// `Command::SpawnProject`). A view creates a placeholder
    /// under `key` and shows the "Waking {display_name}…" message. The
    /// matching `Connected` lands soon after, under the same key.
    Spawning {
        key: SessionSlot,
        project_name: String,
        cwd: String,
        display_name: String,
    },
    Connected {
        key: SessionSlot,
        session_id: SessionId,
        cwd: String,
        current_model: CurrentModel,
        available_models: Vec<AvailableModel>,
        mode: Option<ModeState>,
        history: Vec<Message>,
        /// Messages the read carried that `history`'s window left behind its
        /// front, which is the floor a page cursor below the window is
        /// measured against.
        ///
        /// **Carried because the window cannot say it.** The read is windowed
        /// before it crosses - a resume's whole transcript is gigabytes - so a
        /// consumer holding the window alone reads it as the conversation's
        /// front, and a walk below it would stop there instead of crossing
        /// into the transcript. Additive on the wire, and zero for a read the
        /// window holds whole.
        dropped: usize,
        /// Compactions the resumed transcript records. Seeds the
        /// per-session count, which has no other durable source.
        compaction_count: u32,
    },
    /// A call's own output, asked for by `Command::ReadCallOutput`: the tail
    /// of the file the CLI streamed the call's output to, or a named reason
    /// there is none.
    ///
    /// Emitted by the transport from its held copy of the seat's
    /// conversation, which carries the frame naming the call's `output_file`.
    CallOutput {
        key: SessionSlot,
        call_id: String,
        output: forge_primitives::CallOutput,
    },
    /// The slot's occupant changed under it - a `/new`, a `/resume`, a
    /// login or a logout. The slot keeps its bucket, in its place on
    /// screen; its contents reset, meaning the rendered conversation,
    /// the history, the per-session overrides and any waiter holding a
    /// tool call that is never coming back. `session_id` is the new
    /// occupant.
    SessionReplaced {
        key: SessionSlot,
        session_id: SessionId,
        cwd: String,
        current_model: CurrentModel,
        available_models: Vec<AvailableModel>,
        mode: Option<ModeState>,
        history: Vec<Message>,
        /// Messages the read carried that `history`'s window left behind its
        /// front: the same floor a `Connected` carries, for the same reason.
        dropped: usize,
        /// Compactions the resumed transcript records. Seeds the
        /// per-session count, which has no other durable source.
        compaction_count: u32,
    },
    /// The seat's occupant was replaced by a handoff rather than by a person
    /// asking for one, and this is the record of it - emitted before any
    /// frame from the new occupant, so the seat learns the swap before the
    /// successor's transcript starts. No view draws a row from it: the
    /// successor's own procedure row carries the handoff.
    Handoff {
        key: SessionSlot,
        handoff: forge_primitives::HandoffRecord,
    },
    /// The machine turn running on this seat changed: a handoff beginning or
    /// ending, and `None` for a seat taking input.
    ///
    /// **A record read is not pushed.** The record carries the same fact for a
    /// page that attaches mid-turn, but a page already open learns it here -
    /// and its composer stands down for exactly that span.
    MachineTurn {
        key: SessionSlot,
        machine: Option<forge_primitives::runtime::MachineTurn>,
    },
    ConnectionFailed {
        key: SessionSlot,
        message: String,
        fatal: bool,
    },
    /// The seat's release has begun: its session is being taken down, and a
    /// view draws the seat as going to sleep until the roster lands it asleep
    /// or gone.
    ///
    /// **Announced at the START of the release, not when the handles drop.**
    /// The teardown is what takes the seconds, so a viewer that hears only the
    /// end keeps the row reading as working through the whole gesture - and a
    /// close made from another view is heard by no one at all without this.
    Releasing {
        key: SessionSlot,
    },
    /// One line the core has for a view about `key`, which nothing else
    /// carries.
    ///
    /// A command answered where both views dispatch has no other way to say
    /// anything: the CLI emits no frame for a command it never saw, and the
    /// line is the core's own answer rather than a view's opinion - what a
    /// command found, or why it refused.
    ///
    /// **Live only, and that is intended.** The CLI writes no transcript row
    /// for a line it never produced, so a view draws this on arrival and a
    /// page that attaches afterwards has nothing to read it from. It is a
    /// statement about the moment a command ran, not a record of the
    /// conversation.
    Notice {
        key: SessionSlot,
        severity: NoticeSeverity,
        text: String,
    },
    /// The CLI refused (or failed) a `set_permission_mode` control
    /// request for `key`. `message` carries the underlying error text;
    /// the view rolls the optimistic mode chip back and surfaces it.
    SetModeFailed {
        key: SessionSlot,
        mode: PermissionMode,
        message: String,
    },
    /// The CLI refused (or failed) a `set_model` control request for
    /// `key`. `message` carries the underlying error text; the view
    /// rolls the optimistic model change back and surfaces it.
    SetModelFailed {
        key: SessionSlot,
        model: String,
        message: String,
    },
    /// Permission prompt. No response_tx - a view replies via
    /// `Command::RespondPermission { tool_id, outcome }`.
    PermissionRequest {
        key: SessionSlot,
        tool_id: String,
        request: PermissionRequest,
    },
    /// AskUserQuestion prompt. Same shape; reply via
    /// `Command::RespondQuestion { tool_id, outcome }`.
    QuestionRequest {
        key: SessionSlot,
        tool_id: String,
        request: QuestionRequest,
    },
    /// The interaction `tool_id` was answered, so every view holding the
    /// prompt can drop it. Answering leaves the pending set either way,
    /// and this is the only thing that says so on the stream: without it a
    /// second view keeps drawing a prompt that is already settled. A lone
    /// view never meets that, because it is the only one.
    ///
    /// **A question names its round as well as its call.** A batch reuses
    /// one tool call id and advances `question_index`, and the next round's
    /// request can land before this round's resolution - so a clear keyed
    /// on the id alone dropped the ask that had just parked, and every
    /// round after the first lost its opening question (Ved's live find;
    /// #1717). `None` on every interaction that is not a question, and on
    /// the frames of a core older than this field.
    PendingInteractionResolved {
        key: SessionSlot,
        tool_id: String,
        /// Absent from an older core's frames, so the default carries that.
        #[serde(default)]
        question_index: Option<u64>,
        /// The words the answer carried, where it carried any: the box's own
        /// notes, typed or dictated (#1360). `None` for a pick with no words,
        /// which is most of them.
        #[serde(default)]
        answered_with: Option<String>,
    },
    McpOperationError {
        key: SessionSlot,
        error: McpOperationError,
    },
    TurnComplete {
        key: SessionSlot,
        terminal_reason: Option<TerminalReason>,
    },
    TurnCancelled {
        key: SessionSlot,
    },
    TurnError {
        key: SessionSlot,
        message: String,
        /// The failure's class, where the producer that built the event could
        /// name one. **`None` is "not classified here" rather than "not
        /// auth"**: a producer that never classified and an auth failure are
        /// different facts, and a reader that folds them together holds a
        /// session on `/login` for an error that was never about login.
        class: Option<TurnErrorClass>,
        terminal_reason: Option<TerminalReason>,
    },
    ChatAppended {
        key: SessionSlot,
        msg: Message,
        /// Who dispatched the prompt this frame writes as a user turn: the
        /// same [`PromptSource`] the queue's own row carries.
        ///
        /// **This is the arm a reader's follow reads**, because the words'
        /// shape cannot say it: forge's own machinery - an auto-continue, a
        /// worker kick, a board notice - forges prose as the reader's own row
        /// on this frame, and arming for one carries a parked reader to the
        /// foot for words that are nobody's (#2198). Only `you` is a person's
        /// send.
        ///
        /// `None` on every frame the CLI sent; the turns a delivery forges
        /// carry the delivery's own kind, since their envelope row is not the
        /// reader's either.
        #[serde(default)]
        source: Option<PromptSource>,
    },
    HookObservation {
        key: SessionSlot,
        tool_use_id: Option<String>,
        permission_mode: Option<String>,
        effort: Option<String>,
        agent_id: Option<String>,
        agent_type: Option<String>,
    },
    ForgeAccountIdentity {
        key: SessionSlot,
        display_name: String,
    },
    /// The full override set a session holds after a `/dictate` edit
    /// landed. Sent after every `SetDictateOverride` and
    /// `ResetDictateOverrides` so the dialog's markers and its reset
    /// row read from this, not from a view-side copy.
    DictateOverrides {
        key: SessionSlot,
        overrides: crate::dictate::DictateOverrides,
    },
    ContextUsageSnapshot {
        key: SessionSlot,
        percentage: Option<u8>,
        /// Raw model context-window size in tokens (e.g. `1_000_000`
        /// for Opus 1M). `None` until the upstream probe reports it.
        max_tokens: Option<u64>,
    },
    McpSnapshot {
        key: SessionSlot,
        servers: Vec<McpServerStatus>,
        error: Option<String>,
    },
    /// The seat's process tree moved, as the whole walk the core holds.
    ///
    /// **Pushed rather than read.** The walk is a `sysinfo` refresh; the
    /// core runs it once a second for every seat a view is showing, and this
    /// carries the answer to whoever is drawing it. Emitted only when the
    /// tree's own entries moved - a walk that found the same processes says
    /// nothing.
    ProcessesChanged {
        key: SessionSlot,
        snapshot: forge_agent::env::processes::ProcessSnapshot,
    },
    /// The seat's monitors moved, as the whole set the core holds.
    ///
    /// **Pushed rather than read.** The set changes on discrete task frames -
    /// a `Monitor` call entering, a task stamping its id, a frame settling
    /// one, the drain that empties it - and never per output chunk, so the
    /// frame that moved it announces it and a frame that moved nothing says
    /// nothing.
    MonitorsChanged {
        key: SessionSlot,
        monitors: Vec<forge_primitives::MonitorRecord>,
    },
    /// The seat's live task set moved, as the whole set.
    ///
    /// Both halves move it: the CLI announces its background registry whole on
    /// each change, and a long foreground call enters on its `task_started`
    /// and leaves on its `task_notification`, a terminal `task_updated`, or
    /// the end of the turn that ran it. So this mirrors a task entering,
    /// leaving or being cleared by a dead connection.
    BackgroundTasksChanged {
        key: SessionSlot,
        tasks: Vec<crate::BackgroundTask>,
    },
    /// The seat's working tree moved, as the row a view draws it.
    ///
    /// **Pushed rather than read.** The three fields are the record's own -
    /// the branch and count, the open PR on the pushed sha, and the issues it
    /// closes - so a client applies them to the fields it already narrows. A
    /// seat nobody is showing is not scanned, so this is only sent for a seat
    /// somebody holds.
    WorkChanged {
        key: SessionSlot,
        work: crate::work::WorkState,
        /// The tree behind the row's depth: the uncommitted files with
        /// their marks and counts, the branch's chain ahead of its
        /// default, and which branch that is.
        git: forge_primitives::git_diff::GitWorkView,
        pr: Option<forge_primitives::git::GitPrInfo>,
        closes: Vec<forge_primitives::git::GitIssueRef>,
    },
    /// The project's task list moved, as the whole set the core holds.
    ///
    /// **Pushed rather than read.** The `tasks__*` writes are the only movers
    /// and the section a view draws sits on the board's project row - keyed by
    /// the project's lead seat, which exists for every declared project - so
    /// the write announces the set rather than leaving the row to the next
    /// unrelated read.
    TasksChanged {
        key: SessionSlot,
        tasks: Vec<forge_primitives::tasks::Task>,
    },
    /// The project's schedules moved, as the whole set the core holds.
    ///
    /// **Pushed rather than read.** Three doors move it - the `cron__*`
    /// writes, a fire that advances or removes an entry, and a worker's
    /// teardown - and the section draws the countdown, so each announces the
    /// set it left. `key` is the project's lead seat.
    CronSchedulesChanged {
        key: SessionSlot,
        crons: Vec<forge_primitives::CronEntry>,
    },
    /// The project's inbound connector subscriptions moved, as the two sets
    /// the core holds.
    ///
    /// **Pushed rather than read.** The `gotify__*` / `slack__*` writes move
    /// them, and so do the doors no tool call reaches: a mention's
    /// auto-subscribe, a watched conversation's name healing on its first
    /// message, and a worker's teardown taking its own with it. One update
    /// carries both connectors because they are one section of the board's
    /// project row, and a reader that patches it needs the pair. `key` is the
    /// project's lead seat.
    ConnectorSubscriptionsChanged {
        key: SessionSlot,
        gotify: Vec<forge_primitives::GotifySubscription>,
        slack: Vec<forge_primitives::slack::SlackSubscription>,
    },
    /// The `/` menu's catalogue moved, as the whole list the core holds.
    ///
    /// **Pushed rather than read.** The CLI advertises it on a turn's init and
    /// re-sends it when a plugin changes it (`commands_changed`), so the frame
    /// that moved it announces it and a turn's init repeating the same list
    /// says nothing.
    SlashCommandsChanged {
        key: SessionSlot,
        commands: Vec<forge_primitives::runtime::AvailableCommand>,
    },
    /// The agent-type catalogue moved, as the whole list the core holds.
    ///
    /// **Pushed rather than read.** The CLI advertises it on a turn's init,
    /// once per turn, so this is that one frame - and an init that repeats the
    /// list the last turn advertised says nothing.
    SubagentsChanged {
        key: SessionSlot,
        subagents: Vec<forge_primitives::runtime::AvailableAgent>,
    },
    /// The session's sub-agent instances moved, as the whole list the core
    /// folds from the frames it has seen.
    ///
    /// **Pushed rather than read.** The join lives in
    /// `forge_workspace::subagent_cards` and folds a frame at a time, so a
    /// live session announces the list it now holds rather than re-walking
    /// its conversation per frame. A client draws the instances from this -
    /// the raw frames stay on the conversation for whoever folds something
    /// else - and a page attaching later reads the same list off the record.
    SubagentCardsChanged {
        key: SessionSlot,
        cards: Vec<forge_primitives::runtime::SubagentCard>,
    },
    /// The tree's file index moved, as the whole index the core holds.
    ///
    /// **Pushed rather than read, and throttled here rather than by the
    /// socket.** The socket's batch folds only consecutive token appends, so
    /// a burst of index frames would go out one per change: the walk runs at
    /// most once per poke while the watch says the tree is moving - so a
    /// build's writes inside one poke become one walk - and once per
    /// `INDEX_STALENESS` when it is still. The frame goes out only when the
    /// index actually differs from the one last announced.
    FileIndexChanged {
        key: SessionSlot,
        index: std::sync::Arc<crate::file_index::FileIndex>,
    },
    ServiceStatus {
        severity: ServiceSeverity,
        message: String,
    },
    /// The background catalog scan finished and `Workspace`'s project
    /// catalog is populated. A view reads the roster itself, so nothing
    /// needs carrying: the event exists to wake the render loop so
    /// session counts appear when the scan lands rather than on the next
    /// unrelated frame.
    CatalogLoaded,
    /// A claude version probe landed and moved what the views draw. The
    /// snapshot itself is not carried, so this is only the wake-up: a view
    /// re-reads through the surface's `cli_version` verb.
    CliVersionChanged,
    /// The account pool moved: an account's loading state, its last probe
    /// failure, its cached usage snapshot, or the gateway listener's
    /// readiness.
    ///
    /// **The frame carries the pool's drawn state**, flattened so its fields
    /// are the ones `HomeWire::accounts` states - the same values, built by
    /// [`crate::Workspace::account_pool_view`], so a client that folds the frame
    /// and a client that reads the snapshot cannot disagree (rule 25). That
    /// is what lets a usage move reach the badge without a home read.
    ///
    /// It carries no seat because the pool belongs to none, which is also
    /// what routes it to a home subscriber and to nobody else.
    AccountsChanged {
        #[serde(flatten)]
        accounts: crate::views::AccountPoolView,
    },
    PluginsInventoryUpdated {
        cwd_raw: String,
        snapshot: PluginsInventorySnapshot,
        claude_path: PathBuf,
    },
    PluginsInventoryRefreshFailed {
        cwd_raw: String,
        message: String,
        /// Whether the failed refresh served a boot auto-update run -
        /// app-scoped, so its failure bypasses the cwd gate.
        trigger: PluginUpdateTrigger,
    },
    PluginsCliActionSucceeded {
        cwd_raw: String,
        result: PluginsCliActionSuccess,
        /// The dispatch this outcome answers, when the press that made it
        /// named one - `None` for an internal dispatch no press owns.
        dispatch_id: Option<u64>,
    },
    PluginsCliActionFailed {
        cwd_raw: String,
        message: String,
        /// As on the succeeded frame above: the dispatch this failure
        /// answers, when the press that made it named one.
        dispatch_id: Option<u64>,
    },
    /// A section-level update run or check moved: one or more rows
    /// changed state. Carries the whole run so the pane replaces its
    /// copy wholesale.
    PluginsUpdateRunProgress {
        cwd_raw: String,
        run: PluginUpdateRun,
    },
    /// The run (or check) is over. The record batch is persisted by
    /// the run task itself; this event is reporting only.
    PluginsUpdateRunFinished {
        cwd_raw: String,
        run: PluginUpdateRun,
        snapshot: Option<PluginsInventorySnapshot>,
        claude_path: Option<PathBuf>,
    },
    PluginsRollbackSucceeded {
        cwd_raw: String,
        plugin_id: String,
        scope: String,
        message: String,
        snapshot: PluginsInventorySnapshot,
        claude_path: PathBuf,
    },
    PluginsRollbackFailed {
        cwd_raw: String,
        plugin_id: String,
        message: String,
        /// The refreshed inventory when the rollback ran but did not
        /// verify, so the pane still reflects the real state.
        snapshot: Option<PluginsInventorySnapshot>,
    },
    /// Workspace pushed a change to `live_workers[project_key]`. A
    /// view's reducer updates the projects pane's tree-children based
    /// on `action`. `status` is the snapshot at the moment of the
    /// change (relevant for Added and StatusChanged; ignored for
    /// Removed but carried for symmetry). `worktree` is what has
    /// become of the worker's worktree, read on `Removed` events
    /// (after which the `WorkerEntry` is gone from `live_workers`, so a
    /// lookup-by-label would fail).
    WorkerStatusChanged {
        project_key: crate::ProjectKey,
        action: WorkerStatusAction,
        status: forge_primitives::WorkerStatus,
        worktree: WorktreeDisposition,
    },
    /// A peer-coordination envelope arrived at `key`.
    /// Carries the typed `WrappedPrompt` so a view's reducer can build
    /// the chat-side echo from real fields instead of having the
    /// workspace forge a `Message::User` carrying prose for a view to
    /// re-parse (audit I11). The recipient's LLM still receives the
    /// prose via a separate `Command::Prompt` dispatch - that's the
    /// CLI's input channel and stays text-shaped.
    PeerEnvelopeAppended {
        key: SessionSlot,
        wrapped: crate::mcp::peers::types::WrappedPrompt,
        /// The id the delivered prompt was dispatched under, which the
        /// drawn row carries: a view holds the row while that prompt waits in
        /// the pile and draws it when it starts.
        uuid: String,
    },
    /// A matched Gotify notification arrived at `key`.
    /// Carries the typed `GotifyNotification` so a view's reducer builds
    /// the chat-side echo from real fields (mirrors PeerEnvelopeAppended).
    /// The session's LLM receives the same prose via a separate
    /// `Command::Prompt` - this update only drives the visible echo.
    GotifyNotificationAppended {
        key: SessionSlot,
        notification: crate::mcp::gotify::types::GotifyNotification,
        /// The id the delivered prompt was dispatched under, which the drawn
        /// row carries - see `PeerEnvelopeAppended`.
        uuid: String,
    },
    /// A due cron fired into `key`. Carries the fired
    /// prompt text so a view's reducer builds the chat-side echo (mirrors
    /// GotifyNotificationAppended). The session's LLM receives the same
    /// text via a separate `Command::Prompt` - this update only drives
    /// the visible echo.
    CronPromptAppended {
        key: SessionSlot,
        text: String,
        /// The id the delivered prompt was dispatched under, which the drawn
        /// row carries - see `PeerEnvelopeAppended`.
        uuid: String,
        /// The cron entry that fired, so a view can name the schedule the
        /// prompt came from - the entry is gone from the store by the time
        /// a run-once fire is drawn.
        cron_id: String,
        /// The entry's human summary; `None` when none was registered, and
        /// the row falls back to the prompt's first line.
        description: Option<String>,
    },
    /// A matched Slack message arrived at `key`. Carries the
    /// prose rather than the typed message: the prose builder is `pub(crate)`
    /// to forge-workspace, so a typed message would force a view to rebuild
    /// the very format it parses. The session's LLM receives the same prose
    /// via a separate `Command::Prompt` - this update only drives the visible
    /// echo (mirrors GotifyNotificationAppended).
    SlackMessageAppended {
        key: SessionSlot,
        prose: String,
        /// The id the delivered prompt was dispatched under, which the drawn
        /// row carries - see `PeerEnvelopeAppended`.
        uuid: String,
    },
    /// A composed Slack message is waiting for the user's decision in the
    /// dock prompt. The authoring tool handler is blocked on a oneshot
    /// until `Command::RespondSlackPost` answers it, so nothing posts
    /// while this is outstanding.
    SlackPostPending {
        key: SessionSlot,
        draft: forge_primitives::slack::SlackDraft,
    },
    /// A held Slack draft left the core's registry: answered in some view,
    /// or its asking session gone. Each view keeps its own copy of the
    /// parked draft, so this is the only update that clears it - and
    /// `ending` is what a view that did not answer it says happened.
    SlackDraftResolved {
        key: SessionSlot,
        id: Uuid,
        ending: forge_primitives::slack::SlackDraftEnding,
    },
    /// A browser hand-off waits for the person at a client: the session asked
    /// them to act in a browser tab, and its tool handler is blocked on a
    /// oneshot until `Command::RespondBrowserHandOff` answers it.
    ///
    /// **No timeout rides this one.** The ask dock's own timelines say a held
    /// prompt sits for hours, and the session is meant to wait as long as it
    /// takes; the handler's drop, not a clock, is what ends the wait.
    BrowserHandOffPending {
        key: SessionSlot,
        handoff: forge_primitives::browser::HandOff,
    },
    /// A browser hand-off left the core's registry: answered in some view, or
    /// its asking session gone. `answer` is the ending, the door that sent it
    /// and the connection that carried it - what a view that did not answer it
    /// reads, and what the log names.
    BrowserHandOffResolved {
        key: SessionSlot,
        id: Uuid,
        answer: forge_primitives::browser::HandOffAnswer,
    },
    /// A terminal hand-off waits for the person at a client: the session asked
    /// them to type into the seat's terminal, and its tool handler is blocked
    /// on a oneshot until `Command::RespondTerminalHandOff` answers it.
    ///
    /// **No timeout rides this one**, and the agent is blind while it is
    /// parked: `terminal__read` and `terminal__write` are refused.
    TerminalHandOffPending {
        key: SessionSlot,
        handoff: forge_primitives::terminal::TerminalHandOff,
    },
    /// A terminal hand-off left the core's registry: answered in some view, or
    /// its asking session gone. `answer` is the ending, the door that sent it
    /// and the connection that carried it.
    TerminalHandOffResolved {
        key: SessionSlot,
        id: Uuid,
        answer: forge_primitives::terminal::TerminalHandOffAnswer,
    },
    /// A seat's terminal opened, changed or closed, as the strip and the
    /// session record read it. `None` means the terminal is gone.
    TerminalChanged {
        key: SessionSlot,
        terminal: Option<forge_primitives::terminal::TerminalSummary>,
    },
    /// A prompt entered the CLI's queue: the row a view draws as waiting,
    /// with the words and the sender the lifecycle frames do not carry.
    ///
    /// Emitted where the prompt is dispatched, keyed by the uuid it was sent
    /// under - so a view keys its own optimistic row to this one by id rather
    /// than by order or text.
    PromptQueued {
        key: SessionSlot,
        uuid: String,
        source: PromptSource,
        text: String,
    },
    /// Where one prompt is in the CLI's queue, as the CLI itself reports it:
    /// `queued`, `started`, `completed` and the terminal states
    /// (`cancelled`, `discarded`, `refused`). Keyed by the uuid the prompt was
    /// sent under, which is what lets a view key its queued row to its own
    /// send by id rather than by order or text.
    ///
    /// `state` stays a free-form string so a state this build has not seen
    /// reaches a view rather than being dropped.
    PromptLifecycle {
        key: SessionSlot,
        uuid: String,
        state: String,
    },
    /// The CLI answered a `cancel_async_message`: `cancelled: false` means the
    /// prompt was already dequeued for execution, so a reader that asked to
    /// drop it has to say it is on its way instead.
    PromptCancelResolved {
        key: SessionSlot,
        uuid: String,
        cancelled: bool,
    },
    /// A worker's review turn addressed review comments; `key` is the
    /// session that authored the review (the submit origin). A view drops
    /// `message` as a system line into that session's chat so the reviewer
    /// sees the batched tally, and parks `waiting` - how many threads on
    /// `branch` now await a reviewer turn - as the persistent signal both
    /// the Inspector GIT badge and the NEEDS ATTENTION band read.
    ReviewActivityNotice {
        key: SessionSlot,
        branch: String,
        waiting: usize,
        message: String,
    },
    /// Dictation models are loaded and the composer may offer to
    /// dictate. App-global (no key): the engine is process-wide and
    /// every session's composer shares the availability; the event's
    /// existence is the signal. Never emitted when `[dictate]` is
    /// disabled, so sessions that cannot dictate render nothing.
    DictateAvailability,
    /// A recording started for the composer at `key`. `floor_db` is the
    /// silence floor the level meter maps onto its zero glyph, so the
    /// bar and the `NoAudio` verdict agree by construction. `generation`
    /// identifies this take among the key's takes: a resolver that
    /// arrives after a newer take started carries a stale one, and the
    /// composer resets on its own generation only.
    ///
    /// `initiator` names the connection the take belongs to, as its
    /// `dictate_stream` carried it: every `Dictate*` update about a take
    /// goes to that connection alone, so no other subscriber draws its
    /// meter, its phases or its words. `None` is this process's own
    /// take.
    DictateStarted {
        key: SessionSlot,
        floor_db: f32,
        generation: u64,
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// One level reading for the recording at `key`: the peak over the
    /// window since the previous reading, in dBFS. Emitted on the
    /// meter clock, not the repaint clock.
    ///
    /// **A window with no signal reads as `null` on the wire, and `null`
    /// reads back as negative infinity.** A peak that heard nothing is
    /// exactly zero, whose dBFS is negative infinity, and serde writes a
    /// non-finite float as `null` - so a reader that takes the field as an
    /// `f32` cannot decode the message at all, which is the state this
    /// tolerance exists to close. Nothing about the value a view draws
    /// changes: the client narrows `null` itself, and this only lets a
    /// Rust reader do the same.
    DictateLevel {
        key: SessionSlot,
        #[serde(default, deserialize_with = "no_signal_reads_as_negative_infinity")]
        peak_db: f32,
        /// The take's own, as [`SessionUpdate::DictateStarted`] announced it:
        /// a reading that arrives after a newer take started is the older
        /// one's and belongs in no live meter.
        generation: u64,
        /// The take's own, as [`SessionUpdate::DictateStarted`] announced
        /// it.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// The take from `key` was submitted and a transcript is in flight.
    DictateTranscribing {
        key: SessionSlot,
        /// The take's own, as [`SessionUpdate::DictateStarted`] announced it:
        /// a stale one must not move a newer take to `transcribing` while its
        /// microphone still records.
        generation: u64,
        /// The take's own, as [`SessionUpdate::DictateStarted`] announced
        /// it.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// A take from `key` has settled `done` segments of its
    /// transcription. `total` is `None` while the recording is still
    /// open, because a live take cannot know how many segments it will
    /// produce, and the final count once the take was stopped and its
    /// tail submitted. Single-segment takes report at stop only; a
    /// composer renders only what it wants to. `generation` is the
    /// take's own, as handed out by [`SessionUpdate::DictateStarted`].
    DictateProgress {
        key: SessionSlot,
        generation: u64,
        done: usize,
        total: Option<usize>,
        /// The take's own, as [`SessionUpdate::DictateStarted`] announced
        /// it.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// A take from `key` is done: insert, notice or reset per
    /// [`DictateOutcome`]. `generation` is the take's own, as handed
    /// out by [`SessionUpdate::DictateStarted`].
    DictateEnded {
        key: SessionSlot,
        outcome: DictateOutcome,
        generation: u64,
        /// The surface whose own capture began the take, as
        /// [`Command::DictateStream`] carried it: the landed words are that
        /// surface's to place, and no other's. `None` for a take
        /// begun in process or by a client older than the field.
        #[serde(default)]
        surface: Option<String>,
        /// The take's own - and for a refusal, the connection that was
        /// refused, so only it learns why. `None` is this process's own.
        #[serde(skip)]
        initiator: Option<u64>,
    },
    /// The core's fatal: the app is going away. `message` is what a
    /// view draws on exit - `AppError::user_message()` - so a view that
    /// draws the line words it the same way without a second copy.
    FatalError {
        error: AppError,
        message: String,
    },
    /// The catalogue check landed: the models page's whole view, re-read.
    /// Carries no slot - the feed belongs to the machine, not a seat - and
    /// a session page ignores it. Sentinel rows the page draws (the
    /// check's freshness, every candidate row, the per-model updates) are
    /// all here, so a subscriber that was already attached never has to
    /// ask again for what this frame just changed.
    DictateModelsChanged {
        models: crate::catalogue::DictateModelsSnapshot,
    },
    /// A session handed the reader a document: the ask a client draws -
    /// **open** or **not now** - with the resolved path it opens at.
    ///
    /// **The call parks on this**, like the browser hand-off: `id` names the
    /// parked call, and the reader's answer releases it - `NotNow` here, or
    /// `Approve` / `Feedback` when the viewer's finish files the reading.
    /// `path` is the
    /// resolved absolute path, the viewer's stable address; `reviewable` is
    /// what the hand-off asked for - the ask's own fact rather than the
    /// document's, because a readable document offers its review either way.
    DocumentHandOffPending {
        key: SessionSlot,
        id: Uuid,
        path: String,
        reviewable: bool,
    },
    /// A document hand-off left the core's registry: finished in some view,
    /// declined, or its asking session gone. `ending` is what a view that
    /// did not answer it says happened.
    DocumentHandOffResolved {
        key: SessionSlot,
        id: Uuid,
        ending: forge_primitives::document::DocumentHandOffEnding,
    },
    /// A configuration write waits for the reader's approval in the dock:
    /// the session's `settings__set` / `settings__unset` handler is blocked
    /// on a oneshot until `Command::RespondSettingsWrite` answers it, so
    /// nothing reaches `forge.toml` while this is outstanding.
    SettingsWritePending {
        key: SessionSlot,
        ask: forge_primitives::settings::SettingsWriteAsk,
    },
    /// A held configuration write left the core's registry: answered in some
    /// view, or its asking session gone. `ending` is what a view that did
    /// not answer it says happened.
    SettingsWriteResolved {
        key: SessionSlot,
        id: Uuid,
        ending: forge_primitives::settings::SettingsWriteEnding,
    },
    /// A vault call waits for the reader's approval in the dock: the family's
    /// tool handler is blocked on a oneshot until `Command::RespondVaultAsk`
    /// answers it, so no operation runs in the vault while this is outstanding.
    /// `needs_unlock` on the draft is stamped from the live session as the
    /// card is built, so a sibling that unlocked first re-bases this one.
    VaultAskPending {
        key: SessionSlot,
        draft: forge_primitives::vault::VaultDraft,
    },
    /// A held vault call left the core's registry: answered in some view, or
    /// its asking session gone. `ending` is what a view that did not answer
    /// it says happened; the tool result carries the operation's own outcome.
    VaultAskResolved {
        key: SessionSlot,
        id: Uuid,
        ending: forge_primitives::vault::VaultAskEnding,
    },
    /// The device enrolments moved, as the whole set the core holds. Pushed
    /// rather than read: an enrol, a release's stamp and a revoke each leave a
    /// set the settings page draws, and the card reads the same set - so a
    /// second client redraws without asking. No wrapped blob rides here; see
    /// [`forge_primitives::biometric::BiometricEnrolment`].
    BiometricEnrolmentsChanged {
        enrolments: Vec<forge_primitives::biometric::BiometricEnrolment>,
    },
    /// The shared vault session rotated its refresh token, so the copy an
    /// enrolment blob holds is spent. A client that holds the material from
    /// its last release rewrites its blob with this one (decision 15); one
    /// that cannot falls back to the password on its next start.
    ///
    /// **Slot-less**: the session is process-wide, and only the client that
    /// owns the enrolment acts on it. The token is a secret on the socket -
    /// it never reaches a transcript or the live fold, and the manual `Debug`
    /// redacts it.
    VaultRotated {
        refresh_token: String,
    },
    /// The shared vault session locked or unlocked outside a held card - the
    /// idle bound passed, a refresh or a decryption failed, or an unlock
    /// landed. Slot-less like the rotation: the session is process-wide, and
    /// the settings page's vault card is what redraws.
    VaultLockChanged {
        locked: bool,
    },
    /// One rendered clip of the seat's speech, mono 16-bit samples at
    /// `sample_rate`. Chunks arrive in `seq` order and every client with
    /// voice on for the seat plays them; a client with voice off receives
    /// them and stays silent.
    VoiceAudio {
        key: SessionSlot,
        seq: u32,
        sample_rate: u32,
        pcm: Vec<i16>,
    },
    /// The seat's voice state: how many clients are listening, which is what
    /// the control draws and what a listener note is injected on.
    VoiceModeState {
        key: SessionSlot,
        listeners: u32,
    },
}

impl SessionUpdate {
    /// The [`SessionSlot`] this update routes to, or `None` for
    /// updates that target App-level state (`ServiceStatus`, catalog,
    /// plugin, fatal-error). Every identity-carrying variant names a
    /// slot, so nothing is synthesized here.
    pub fn slot(&self) -> Option<&SessionSlot> {
        match self {
            Self::Spawning { key, .. }
            | Self::Connected { key, .. }
            | Self::CallOutput { key, .. }
            | Self::SessionReplaced { key, .. }
            | Self::Handoff { key, .. }
            | Self::MachineTurn { key, .. }
            | Self::ConnectionFailed { key, .. }
            | Self::Releasing { key }
            | Self::Notice { key, .. }
            | Self::SetModeFailed { key, .. }
            | Self::SetModelFailed { key, .. }
            | Self::PermissionRequest { key, .. }
            | Self::QuestionRequest { key, .. }
            | Self::PendingInteractionResolved { key, .. }
            | Self::McpOperationError { key, .. }
            | Self::TurnComplete { key, .. }
            | Self::TurnCancelled { key }
            | Self::TurnError { key, .. }
            | Self::ForgeAccountIdentity { key, .. }
            | Self::DictateOverrides { key, .. }
            | Self::ReviewActivityNotice { key, .. }
            | Self::DictateStarted { key, .. }
            | Self::DictateLevel { key, .. }
            | Self::DictateTranscribing { key, .. }
            | Self::DictateProgress { key, .. }
            | Self::PromptQueued { key, .. }
            | Self::PromptLifecycle { key, .. }
            | Self::PromptCancelResolved { key, .. }
            | Self::DictateEnded { key, .. }
            | Self::SlackPostPending { key, .. }
            | Self::SlackDraftResolved { key, .. }
            | Self::BrowserHandOffPending { key, .. }
            | Self::BrowserHandOffResolved { key, .. }
            | Self::TerminalHandOffPending { key, .. }
            | Self::TerminalHandOffResolved { key, .. }
            | Self::TerminalChanged { key, .. }
            | Self::DocumentHandOffPending { key, .. }
            | Self::DocumentHandOffResolved { key, .. }
            | Self::SettingsWritePending { key, .. }
            | Self::SettingsWriteResolved { key, .. }
            | Self::VaultAskPending { key, .. }
            | Self::VaultAskResolved { key, .. }
            | Self::VoiceAudio { key, .. }
            | Self::VoiceModeState { key, .. }
            | Self::ChatAppended { key, .. }
            | Self::HookObservation { key, .. }
            | Self::ContextUsageSnapshot { key, .. }
            | Self::McpSnapshot { key, .. }
            | Self::WorkChanged { key, .. }
            | Self::TasksChanged { key, .. }
            | Self::CronSchedulesChanged { key, .. }
            | Self::ConnectorSubscriptionsChanged { key, .. }
            | Self::SlashCommandsChanged { key, .. }
            | Self::SubagentsChanged { key, .. }
            | Self::SubagentCardsChanged { key, .. }
            | Self::FileIndexChanged { key, .. }
            | Self::ProcessesChanged { key, .. }
            | Self::MonitorsChanged { key, .. }
            | Self::BackgroundTasksChanged { key, .. }
            | Self::PeerEnvelopeAppended { key, .. }
            | Self::GotifyNotificationAppended { key, .. }
            | Self::CronPromptAppended { key, .. }
            | Self::SlackMessageAppended { key, .. } => Some(key),
            Self::ServiceStatus { .. }
            | Self::CatalogLoaded
            | Self::CliVersionChanged
            | Self::AccountsChanged { .. }
            | Self::PluginsInventoryUpdated { .. }
            | Self::PluginsInventoryRefreshFailed { .. }
            | Self::PluginsCliActionSucceeded { .. }
            | Self::PluginsCliActionFailed { .. }
            | Self::PluginsUpdateRunProgress { .. }
            | Self::PluginsUpdateRunFinished { .. }
            | Self::PluginsRollbackSucceeded { .. }
            | Self::PluginsRollbackFailed { .. }
            | Self::WorkerStatusChanged { .. }
            | Self::DictateAvailability { .. }
            | Self::FatalError { .. }
            | Self::DictateModelsChanged { .. }
            | Self::BiometricEnrolmentsChanged { .. }
            | Self::VaultRotated { .. }
            | Self::VaultLockChanged { .. } => None,
        }
    }
}

impl std::fmt::Debug for SessionUpdate {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Custom Debug - discriminant + key/session_id only.
        // Payloads can be large or non-Debug-friendly; the
        // discriminant + routing key is sufficient for trace logs.
        match self {
            Self::Spawning { key, project_name, .. } => f
                .debug_struct("Spawning")
                .field("key", key)
                .field("project_name", project_name)
                .finish_non_exhaustive(),
            Self::Connected { key, .. } => {
                f.debug_struct("Connected").field("key", key).finish_non_exhaustive()
            }
            Self::CallOutput { key, call_id, .. } => f
                .debug_struct("CallOutput")
                .field("key", key)
                .field("call_id", call_id)
                .finish_non_exhaustive(),
            Self::SessionReplaced { key, .. } => {
                f.debug_struct("SessionReplaced").field("key", key).finish_non_exhaustive()
            }
            Self::Handoff { key, handoff } => f
                .debug_struct("Handoff")
                .field("key", key)
                .field("pair", &handoff.pair())
                .field("reason", &handoff.reason)
                .finish_non_exhaustive(),
            Self::MachineTurn { key, machine } => f
                .debug_struct("MachineTurn")
                .field("key", key)
                .field("machine", machine)
                .finish_non_exhaustive(),
            Self::ConnectionFailed { key, .. } => {
                f.debug_struct("ConnectionFailed").field("key", key).finish_non_exhaustive()
            }
            Self::Releasing { key } => {
                f.debug_struct("Releasing").field("key", key).finish_non_exhaustive()
            }
            Self::Notice { key, .. } => {
                f.debug_struct("Notice").field("key", key).finish_non_exhaustive()
            }
            Self::SetModeFailed { key, .. } => {
                f.debug_struct("SetModeFailed").field("key", key).finish_non_exhaustive()
            }
            Self::SetModelFailed { key, .. } => {
                f.debug_struct("SetModelFailed").field("key", key).finish_non_exhaustive()
            }
            Self::PermissionRequest { key, tool_id, .. } => f
                .debug_struct("PermissionRequest")
                .field("key", key)
                .field("tool_id", tool_id)
                .finish_non_exhaustive(),
            Self::QuestionRequest { key, tool_id, .. } => f
                .debug_struct("QuestionRequest")
                .field("key", key)
                .field("tool_id", tool_id)
                .finish_non_exhaustive(),
            Self::PendingInteractionResolved { key, tool_id, question_index, answered_with } => f
                .debug_struct("PendingInteractionResolved")
                .field("key", key)
                .field("tool_id", tool_id)
                .field("answered_with", answered_with)
                .field("question_index", question_index)
                .finish(),
            Self::McpOperationError { key, .. } => {
                f.debug_struct("McpOperationError").field("key", key).finish_non_exhaustive()
            }
            Self::TurnComplete { key, .. } => {
                f.debug_struct("TurnComplete").field("key", key).finish_non_exhaustive()
            }
            Self::TurnCancelled { key } => {
                f.debug_struct("TurnCancelled").field("key", key).finish()
            }
            Self::TurnError { key, .. } => {
                f.debug_struct("TurnError").field("key", key).finish_non_exhaustive()
            }
            Self::ChatAppended { key, .. } => {
                f.debug_struct("ChatAppended").field("key", key).finish_non_exhaustive()
            }
            Self::HookObservation { key, .. } => {
                f.debug_struct("HookObservation").field("key", key).finish_non_exhaustive()
            }
            Self::ForgeAccountIdentity { key, .. } => {
                f.debug_struct("ForgeAccountIdentity").field("key", key).finish_non_exhaustive()
            }
            Self::DictateOverrides { key, .. } => {
                f.debug_struct("DictateOverrides").field("key", key).finish_non_exhaustive()
            }
            Self::ContextUsageSnapshot { key, .. } => {
                f.debug_struct("ContextUsageSnapshot").field("key", key).finish_non_exhaustive()
            }
            Self::McpSnapshot { key, .. } => {
                f.debug_struct("McpSnapshot").field("key", key).finish_non_exhaustive()
            }
            Self::WorkChanged { key, .. } => {
                f.debug_struct("WorkChanged").field("key", key).finish_non_exhaustive()
            }
            Self::TasksChanged { key, tasks } => f
                .debug_struct("TasksChanged")
                .field("key", key)
                .field("count", &tasks.len())
                .finish(),
            Self::CronSchedulesChanged { key, crons } => f
                .debug_struct("CronSchedulesChanged")
                .field("key", key)
                .field("count", &crons.len())
                .finish(),
            Self::ConnectorSubscriptionsChanged { key, gotify, slack } => f
                .debug_struct("ConnectorSubscriptionsChanged")
                .field("key", key)
                .field("gotify", &gotify.len())
                .field("slack", &slack.len())
                .finish(),
            Self::SlashCommandsChanged { key, commands } => f
                .debug_struct("SlashCommandsChanged")
                .field("key", key)
                .field("count", &commands.len())
                .finish(),
            Self::SubagentsChanged { key, subagents } => f
                .debug_struct("SubagentsChanged")
                .field("key", key)
                .field("count", &subagents.len())
                .finish(),
            Self::SubagentCardsChanged { key, cards } => f
                .debug_struct("SubagentCardsChanged")
                .field("key", key)
                .field("count", &cards.len())
                .finish(),
            Self::FileIndexChanged { key, index } => f
                .debug_struct("FileIndexChanged")
                .field("key", key)
                .field("count", &index.entries.len())
                .finish(),
            Self::ProcessesChanged { key, snapshot } => f
                .debug_struct("ProcessesChanged")
                .field("key", key)
                .field("count", &snapshot.processes.len())
                .finish(),
            Self::MonitorsChanged { key, monitors } => f
                .debug_struct("MonitorsChanged")
                .field("key", key)
                .field("count", &monitors.len())
                .finish(),
            Self::BackgroundTasksChanged { key, tasks } => f
                .debug_struct("BackgroundTasksChanged")
                .field("key", key)
                .field("count", &tasks.len())
                .finish(),
            Self::ServiceStatus { .. } => f.debug_struct("ServiceStatus").finish_non_exhaustive(),
            Self::PluginsInventoryUpdated { cwd_raw, .. } => f
                .debug_struct("PluginsInventoryUpdated")
                .field("cwd_raw", cwd_raw)
                .finish_non_exhaustive(),
            Self::PluginsInventoryRefreshFailed { cwd_raw, .. } => f
                .debug_struct("PluginsInventoryRefreshFailed")
                .field("cwd_raw", cwd_raw)
                .finish_non_exhaustive(),
            Self::PluginsCliActionSucceeded { cwd_raw, .. } => f
                .debug_struct("PluginsCliActionSucceeded")
                .field("cwd_raw", cwd_raw)
                .finish_non_exhaustive(),
            Self::PluginsCliActionFailed { cwd_raw, .. } => f
                .debug_struct("PluginsCliActionFailed")
                .field("cwd_raw", cwd_raw)
                .finish_non_exhaustive(),
            Self::PluginsUpdateRunProgress { cwd_raw, run } => f
                .debug_struct("PluginsUpdateRunProgress")
                .field("cwd_raw", cwd_raw)
                .field("rows", &run.rows.len())
                .finish(),
            Self::PluginsUpdateRunFinished { cwd_raw, run, .. } => f
                .debug_struct("PluginsUpdateRunFinished")
                .field("cwd_raw", cwd_raw)
                .field("rows", &run.rows.len())
                .finish(),
            Self::PluginsRollbackSucceeded { cwd_raw, plugin_id, .. } => f
                .debug_struct("PluginsRollbackSucceeded")
                .field("cwd_raw", cwd_raw)
                .field("plugin_id", plugin_id)
                .finish_non_exhaustive(),
            Self::PluginsRollbackFailed { cwd_raw, plugin_id, .. } => f
                .debug_struct("PluginsRollbackFailed")
                .field("cwd_raw", cwd_raw)
                .field("plugin_id", plugin_id)
                .finish_non_exhaustive(),
            Self::WorkerStatusChanged { project_key, action, status, worktree } => f
                .debug_struct("WorkerStatusChanged")
                .field("project_key", project_key)
                .field("action", action)
                .field("label", &status.label)
                .field("worktree", worktree)
                .finish_non_exhaustive(),
            Self::PeerEnvelopeAppended { key, wrapped, .. } => f
                .debug_struct("PeerEnvelopeAppended")
                .field("key", key)
                .field("id", &wrapped.id)
                .field("kind", &wrapped.kind)
                .finish_non_exhaustive(),
            Self::GotifyNotificationAppended { key, notification, .. } => f
                .debug_struct("GotifyNotificationAppended")
                .field("key", key)
                .field("app", &notification.app)
                .field("priority", &notification.priority)
                .finish_non_exhaustive(),
            Self::CronPromptAppended { key, .. } => {
                f.debug_struct("CronPromptAppended").field("key", key).finish_non_exhaustive()
            }
            Self::SlackMessageAppended { key, .. } => {
                f.debug_struct("SlackMessageAppended").field("key", key).finish_non_exhaustive()
            }
            Self::SlackPostPending { key, draft } => f
                .debug_struct("SlackPostPending")
                .field("key", key)
                .field("workspace", &draft.workspace)
                .field("conversation", &draft.conversation)
                .finish_non_exhaustive(),
            Self::SlackDraftResolved { key, id, ending } => f
                .debug_struct("SlackDraftResolved")
                .field("key", key)
                .field("id", id)
                .field("ending", ending)
                .finish(),
            Self::BrowserHandOffPending { key, handoff } => f
                .debug_struct("BrowserHandOffPending")
                .field("key", key)
                .field("id", &handoff.id)
                .field("tab", &handoff.tab)
                .finish_non_exhaustive(),
            Self::BrowserHandOffResolved { key, id, answer } => f
                .debug_struct("BrowserHandOffResolved")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish(),
            Self::TerminalHandOffPending { key, handoff } => f
                .debug_struct("TerminalHandOffPending")
                .field("key", key)
                .field("id", &handoff.id)
                .field("terminal", &handoff.terminal)
                .finish_non_exhaustive(),
            Self::TerminalHandOffResolved { key, id, answer } => f
                .debug_struct("TerminalHandOffResolved")
                .field("key", key)
                .field("id", id)
                .field("answer", answer)
                .finish(),
            Self::TerminalChanged { key, terminal } => f
                .debug_struct("TerminalChanged")
                .field("key", key)
                .field("terminal", &terminal.as_ref().map(|summary| summary.id))
                .finish_non_exhaustive(),
            Self::PromptQueued { key, uuid, .. } => f
                .debug_struct("PromptQueued")
                .field("key", key)
                .field("uuid", uuid)
                .finish_non_exhaustive(),
            Self::PromptLifecycle { key, uuid, state } => f
                .debug_struct("PromptLifecycle")
                .field("key", key)
                .field("uuid", uuid)
                .field("state", state)
                .finish(),
            Self::PromptCancelResolved { key, uuid, cancelled } => f
                .debug_struct("PromptCancelResolved")
                .field("key", key)
                .field("uuid", uuid)
                .field("cancelled", cancelled)
                .finish(),
            Self::ReviewActivityNotice { key, branch, waiting, .. } => f
                .debug_struct("ReviewActivityNotice")
                .field("key", key)
                .field("branch", branch)
                .field("waiting", waiting)
                .finish_non_exhaustive(),
            Self::DictateAvailability => f.write_str("DictateAvailability"),
            Self::DictateStarted { key, .. } => {
                f.debug_struct("DictateStarted").field("key", key).finish_non_exhaustive()
            }
            Self::DictateLevel { key, peak_db, .. } => {
                f.debug_struct("DictateLevel").field("key", key).field("peak_db", peak_db).finish()
            }
            Self::DictateTranscribing { key, .. } => {
                f.debug_struct("DictateTranscribing").field("key", key).finish()
            }
            Self::DictateProgress { key, generation, done, total, .. } => f
                .debug_struct("DictateProgress")
                .field("key", key)
                .field("generation", generation)
                .field("done", done)
                .field("total", total)
                .finish(),
            Self::DictateEnded { key, outcome, .. } => f
                .debug_struct("DictateEnded")
                .field("key", key)
                .field("outcome", outcome)
                .finish_non_exhaustive(),
            Self::FatalError { error, .. } => {
                f.debug_struct("FatalError").field("error", error).finish()
            }
            Self::DictateModelsChanged { models } => f
                .debug_struct("DictateModelsChanged")
                .field("in_use", &models.in_use.len())
                .field("rows", &models.rows.len())
                .finish(),
            Self::DocumentHandOffPending { key, .. } => {
                f.debug_struct("DocumentHandOffPending").field("key", key).finish_non_exhaustive()
            }
            Self::DocumentHandOffResolved { key, .. } => {
                f.debug_struct("DocumentHandOffResolved").field("key", key).finish_non_exhaustive()
            }
            Self::SettingsWritePending { key, ask } => f
                .debug_struct("SettingsWritePending")
                .field("key", key)
                .field("id", &ask.id)
                .field("key_paths", &ask.edits.iter().map(|edit| &edit.key).collect::<Vec<_>>())
                .finish_non_exhaustive(),
            Self::SettingsWriteResolved { key, id, ending } => f
                .debug_struct("SettingsWriteResolved")
                .field("key", key)
                .field("id", id)
                .field("ending", ending)
                .finish_non_exhaustive(),
            Self::VaultAskPending { key, draft } => f
                .debug_struct("VaultAskPending")
                .field("key", key)
                .field("id", &draft.id)
                .field("tool", &draft.tool)
                .finish_non_exhaustive(),
            Self::VaultAskResolved { key, id, ending } => f
                .debug_struct("VaultAskResolved")
                .field("key", key)
                .field("id", id)
                .field("ending", ending)
                .finish_non_exhaustive(),
            Self::BiometricEnrolmentsChanged { enrolments } => f
                .debug_struct("BiometricEnrolmentsChanged")
                .field("enrolments", &enrolments.len())
                .finish(),
            // The token is redacted: a Debug line must never carry it.
            Self::VaultRotated { .. } => f.write_str("VaultRotated"),
            Self::VaultLockChanged { locked } => {
                f.debug_struct("VaultLockChanged").field("locked", locked).finish()
            }
            Self::CatalogLoaded => f.write_str("CatalogLoaded"),
            Self::CliVersionChanged => f.write_str("CliVersionChanged"),
            Self::AccountsChanged { accounts } => f
                .debug_struct("AccountsChanged")
                .field("loading", &accounts.loading.len())
                .finish_non_exhaustive(),
            Self::VoiceAudio { key, seq, sample_rate, pcm } => f
                .debug_struct("VoiceAudio")
                .field("key", key)
                .field("seq", seq)
                .field("sample_rate", sample_rate)
                .field("samples", &pcm.len())
                .finish(),
            Self::VoiceModeState { key, listeners } => f
                .debug_struct("VoiceModeState")
                .field("key", key)
                .field("listeners", listeners)
                .finish(),
        }
    }
}

/// Errors from the dispatch boundary. `UnknownSession` and
/// `SessionClosed` are returned by `Workspace::dispatch`;
/// `NoActiveSession` is for a caller with no slot to name.
#[derive(Debug, thiserror::Error)]
pub enum DispatchError {
    #[error("no active session")]
    NoActiveSession,
    #[error("no session task registered for key {}", .0.display())]
    UnknownSession(SessionSlot),
    #[error("session task for key {} has closed its command channel", .0.display())]
    SessionClosed(SessionSlot),
    #[error(
        "no prompt of that kind is waiting on {tool_id} for key {}: it has been answered, or it asked something else",
        .key.display()
    )]
    NoPromptWaiting { key: SessionSlot, tool_id: String },
    /// A Slack answer named a draft the registry does not hold. Its own
    /// word rather than [`Self::NoPromptWaiting`]'s: a draft is answered by
    /// its own id and names no tool call, and this line is drawn where the
    /// dock stood. Answering and the asking session going away are the
    /// endings that leave nothing waiting, which is the condition this line
    /// names - a send-back is an answer too, and resolves the draft just the
    /// same.
    #[error(
        "that Slack draft is no longer waiting: it has been answered, or its asking session went away"
    )]
    NoDraftWaiting { key: SessionSlot, id: Uuid },
    /// A send-back carried no words. There is nothing to hand the agent,
    /// and resolving the draft would drop the reader's card for nothing -
    /// so the draft stays waiting and the field can be sent again.
    #[error("the feedback was empty, so the draft is still waiting")]
    EmptySlackFeedback { key: SessionSlot, id: Uuid },
    /// A browser hand-off answer named a hand-off the registry does not hold:
    /// answered in another view, or its asking session went away. Its own
    /// word for the same reason [`Self::NoDraftWaiting`] has one.
    #[error(
        "that browser hand-off is no longer waiting: it has been answered, or its asking session went away"
    )]
    NoBrowserHandOffWaiting { key: SessionSlot, id: Uuid },
    /// A terminal hand-off answer named a hand-off the registry does not
    /// hold: answered in another view, or its asking session went away.
    #[error(
        "that terminal hand-off is no longer waiting: it has been answered, or its asking session went away"
    )]
    NoTerminalHandOffWaiting { key: SessionSlot, id: Uuid },
    /// A document hand-off answer named a hand-off the registry does not
    /// hold: finished in another view, declined, or its asking session went
    /// away. Its own word for the same reason [`Self::NoDraftWaiting`] has
    /// one.
    #[error(
        "that document hand-off is no longer waiting: it has been answered, or its asking session went away"
    )]
    NoDocumentHandOffWaiting { key: SessionSlot, id: Uuid },
    /// A settings answer named a held write the registry does not hold:
    /// answered in another view, or its asking session went away. Its own
    /// word for the same reason [`Self::NoDraftWaiting`] has one.
    #[error(
        "that configuration write is no longer waiting: it has been answered, or its asking session went away"
    )]
    NoSettingsWriteWaiting { key: SessionSlot, id: Uuid },
    /// A vault answer named a held call the registry does not hold: answered
    /// in another view, or its asking session went away. Its own word for the
    /// same reason [`Self::NoDraftWaiting`] has one.
    #[error(
        "that vault call is no longer waiting: it has been answered, or its asking session went away"
    )]
    NoVaultAskWaiting { key: SessionSlot, id: Uuid },
    /// A biometric enrolment write was refused before anything was stored, in
    /// the core's own words: a blob that is not base64, an empty or oversized
    /// one, a nameless purpose, or a store that could not be written.
    #[error("the biometric enrolment was refused: {reason}")]
    BiometricRefused { reason: String },
    /// A catalogue check was asked for with `[dictate]` switched off:
    /// there are no pinned models for a check to be about.
    #[error("dictation is off, so there is no catalogue to check")]
    DictateOff,
    /// A speaking action was asked for with `[tts]` switched off or no
    /// model files resolving: there is nothing to speak with.
    #[error("speech is off: {reason}")]
    VoiceOff { reason: String },
    /// An install is already running: one at a time, like a check.
    #[error("a model install is already running")]
    Installing,
    /// An activation is already running; a second engine build would race
    /// the first one's swap.
    #[error("a model activation is already running")]
    Activating,
    /// A take is in flight on `holder` (a slot's display string), so the
    /// engine cannot be swapped under it.
    #[error("a dictation take is live on {holder}; wait for it to finish")]
    TakeLive { holder: String },
    /// `forge.toml` pins this role, so the runtime cannot move it; `section`
    /// and `key` name the table and key that do.
    #[error("[{section}] {key} pins this model in forge.toml; remove the key to change it here")]
    PinnedRole { section: &'static str, key: String },
    /// A bench holds the machine: it is measuring an engine, so a swap or
    /// a second run waits for it to finish or stops it.
    #[error("a bench is running; stop it before changing models")]
    BenchRunning,
    /// A stop arrived and nothing was running to stop.
    #[error("no bench is running")]
    BenchNotRunning,
    /// No read-aloud recording is running, or it is another connection's:
    /// only the connection that started one can stop it.
    #[error("no read-aloud recording is running here")]
    ReadAloudNotRecording,
    /// The read-aloud set would not take the change, in the core's own words.
    #[error("the read-aloud set could not be changed: {reason}")]
    ReadAloudUnavailable { reason: String },
    /// The model is what a role runs right now, and the engine holds it
    /// loaded: the role has to be moved off it first.
    #[error("the {role} runs this file; switch it first", role = role.label())]
    ModelInUse { role: crate::dictate::DictateRole },
    /// The model could not be removed, in the core's own words.
    #[error("the model could not be removed: {reason}")]
    UninstallRefused { reason: String },
    /// A check is already in flight; the one that lands is the answer,
    /// and a second fetch would answer the same thing twice.
    #[error("a catalogue check is already running")]
    CatalogueChecking,
    /// A plugin action is already running: the CLI serializes one at a
    /// time, so a second press waits rather than racing the first.
    #[error("a plugin action is already running; wait for it to finish")]
    PluginActionRunning,
    /// No home directory resolves, so a plugin call with no project
    /// context has nowhere to run. Refused rather than substituting a
    /// cwd-derived directory (hard rule 14).
    #[error("no home directory resolves; plugin actions with no project context cannot run")]
    PluginHomeUnavailable,
    /// A `project`/`local` install named no project; those scopes install
    /// into a project's own config, so the project is the caller's to say.
    #[error("a project-scoped plugin install needs a project")]
    PluginProjectRequired,
    /// A project-named install or update names a project `forge.toml`
    /// does not declare.
    #[error("no project named '{name}' is declared in forge.toml")]
    ProjectNotFound { name: String },
}

#[cfg(test)]
mod session_update_variants {
    /// The client's reducer classifies a `SessionUpdate` by the name it crosses
    /// under, and a name it has no line for is a lookup that misses: the session
    /// page stops following its seat and keeps drawing the last record it read,
    /// with nothing to say it has fallen behind.
    ///
    /// **Both ends are parsed, and both ends are the tables themselves.** A
    /// hand-typed list is a copy no rename moves - the first version of this
    /// test read `turn_cancelled` from a literal while serde had already moved
    /// to `turn_cancelled_probe`, and it stayed green. The enum's names are
    /// derived from its own source by the rule it declares; the client's are
    /// read out of the three tables that classify, and not out of the file at
    /// large, where a payload key or a status word would answer for a variant
    /// nothing classifies.
    ///
    /// The client's census of variants is read back as well, rather than
    /// trusted because its length is asserted: a count binds it to nothing.
    /// **`IGNORED` has no runtime reader at all** - nothing but these tests
    /// consults it - so what it holds is only as right as this control.
    ///
    /// What it does not reach: `client/src/wire/fleet.ts` keeps a table of its
    /// own for the fleet's redraws. That is a different question and is
    /// deliberately partial, so this binding stops at `apply.ts`.
    #[test]
    fn every_session_update_variant_is_classified_for_the_client() {
        let source = include_str!("protocol.rs");
        let client = include_str!("../../../client/src/session/apply.ts");
        let declared = wire_names(source);
        let classified = classified_names(client);

        // The derivation implements ONE `rename_all` rule, so it is only as good
        // as the enum declaring that rule: changing the attribute moves every
        // name at once, and nothing else here would notice.
        assert_eq!(
            rename_all(source).as_deref(),
            Some("snake_case"),
            "this control derives wire names with serde's snake_case rule and the enum no longer \
             declares it: extend the derivation before trusting anything below",
        );

        // The denominator, and it is the enum's own: a parse that stops matching
        // never reaches its closing brace, and finding nothing is what a clean
        // run looks like - so this is what tells the two apart.
        assert!(
            declared.closed,
            "the parse never reached the end of `SessionUpdate`, so it is the parse that moved \
             and not the client",
        );

        let missing: Vec<&String> =
            declared.names.iter().filter(|name| !classified.contains(name)).collect();
        assert!(
            missing.is_empty(),
            "client/src/session/apply.ts has no line for {missing:?}, and a variant the client \
             does not classify stops the session page following its seat: add each to HANDLERS \
             when the record has a field for it, and to REPLACES or IGNORED when it does not",
        );

        let stale: Vec<&String> =
            classified.iter().filter(|name| !declared.names.contains(name)).collect();
        assert!(
            stale.is_empty(),
            "client/src/session/apply.ts classifies {stale:?}, which the enum does not declare: \
             a line for a name the wire never sends is one nobody can tell from a live one",
        );

        // **And the census the client's own assertions filter over is read
        // too**, rather than trusted because its count is asserted. That count
        // binds it to nothing; this is what binds it to the enum. It lives in
        // the client's TEST file, beside the assertions that filter over it.
        let census_source = include_str!("../../../client/src/session/apply.test.ts");
        let mut census = array_entries(census_source, "EVERY_VARIANT");
        let mut declared_names = declared.names.clone();
        census.sort();
        declared_names.sort();
        assert_eq!(
            census, declared_names,
            "the client's `EVERY_VARIANT` and the enum's variants are not the same set: the \
             census is what the client's own assertions filter over, so a variant missing from \
             it is a variant nothing checks",
        );
    }

    /// The draft ending crosses as the core's own externally tagged enum, and
    /// `draftEndingLine` narrows exactly that shape - a unit variant as its
    /// name, the answered one as a name around its field. Neither side
    /// compiles the link, so this is what holds serde's output and the
    /// client's narrowing together.
    #[test]
    fn a_draft_ending_serialises_as_the_client_narrows_it() {
        use crate::SessionSlot;
        use forge_primitives::slack::SlackDraftEnding;
        use uuid::Uuid;

        let ending = |ending: SlackDraftEnding| {
            let update = super::SessionUpdate::SlackDraftResolved {
                key: SessionSlot::from_str_for_test("k"),
                id: Uuid::nil(),
                ending,
            };
            serde_json::to_value(update).expect("an update serialises")["slack_draft_resolved"]
                ["ending"]
                .clone()
        };

        assert_eq!(ending(SlackDraftEnding::Abandoned), serde_json::json!("abandoned"));
        assert_eq!(ending(SlackDraftEnding::SentBack), serde_json::json!("sent_back"));
        assert_eq!(
            ending(SlackDraftEnding::Answered { approved: true }),
            serde_json::json!({ "answered": { "approved": true } }),
        );
    }

    /// The voice frames are additive and rename no field, so a round trip is
    /// the whole contract. `sample_rate` is a plain number rather than a
    /// closed set, so a model rendering at a rate this build has never seen
    /// still reaches a client.
    #[test]
    fn the_voice_frames_round_trip() {
        use crate::SessionSlot;

        let key = SessionSlot::from_str_for_test("voice");
        let mode = super::Command::VoiceMode {
            key: key.clone(),
            on: true,
            explicit: false,
            initiator: None,
        };
        let json = serde_json::to_string(&mode).expect("a command serialises");
        let super::Command::VoiceMode { key: decoded, on, .. } =
            serde_json::from_str(&json).expect("a command decodes")
        else {
            panic!("a voice mode came back as another command");
        };
        assert_eq!(decoded, key);
        assert!(on);

        let audio = super::SessionUpdate::VoiceAudio {
            key: key.clone(),
            seq: 7,
            sample_rate: 24_000,
            pcm: vec![5, 6],
        };
        let json = serde_json::to_string(&audio).expect("an update serialises");
        let super::SessionUpdate::VoiceAudio { key: decoded, seq, sample_rate, pcm } =
            serde_json::from_str(&json).expect("an update decodes")
        else {
            panic!("a voice audio frame came back as another update");
        };
        assert_eq!(decoded, key);
        assert_eq!((seq, sample_rate, pcm), (7, 24_000, vec![5, 6]));

        let state = super::SessionUpdate::VoiceModeState { key: key.clone(), listeners: 2 };
        let json = serde_json::to_string(&state).expect("an update serialises");
        let super::SessionUpdate::VoiceModeState { key: decoded, listeners } =
            serde_json::from_str(&json).expect("an update decodes")
        else {
            panic!("a voice mode frame came back as another update");
        };
        assert_eq!((decoded, listeners), (key.clone(), 2));

        let unknown = serde_json::json!({
            "voice_audio": {
                "key": serde_json::to_value(&key).expect("a slot renders"),
                "seq": 0,
                "sample_rate": 12_345,
                "pcm": [],
            }
        });
        let super::SessionUpdate::VoiceAudio { sample_rate, .. } =
            serde_json::from_value(unknown).expect("an unknown rate decodes")
        else {
            panic!("a voice audio frame came back as another update");
        };
        assert_eq!(sample_rate, 12_345);
    }

    /// What one parse of the enum found.
    struct Census {
        names: Vec<String>,
        /// Whether the parse reached the enum's closing brace.
        closed: bool,
    }

    /// The names the client's classifying tables hold.
    ///
    /// The handler table's keys, and the quoted entries of the two lists. An
    /// export of anything else is skipped rather than read: a table of the
    /// record's FIELD names would answer a variant check with names the enum
    /// never declares.
    fn classified_names(client: &str) -> Vec<String> {
        let mut names = Vec::new();
        let mut table = "";
        // Whether a list's `[` has been seen and its `]` has not.
        let mut open = false;
        for line in client.lines() {
            let trimmed = line.trim();
            if trimmed.starts_with("export const HANDLERS") {
                table = "handlers";
                open = false;
                continue;
            }
            if trimmed.starts_with("export const REPLACES")
                || trimmed.starts_with("export const IGNORED")
            {
                table = "list";
                open = false;
            } else if trimmed.starts_with("export const") {
                table = "";
                open = false;
                continue;
            }
            match table {
                // A key of the handler table. The INDENT is the anchor: entries
                // sit at exactly two spaces, and an object literal inside a
                // handler's body is deeper. What follows the colon is not read,
                // so a key written against a bare function name - `turn_error:
                // settled,` - counts the same as an inline arrow.
                "handlers" => {
                    if let Some(rest) =
                        line.strip_prefix("  ").filter(|rest| !rest.starts_with(' '))
                        && let Some(key) = rest.split_once(':').map(|(key, _)| key)
                        && is_wire_name(key)
                    {
                        names.push(key.to_owned());
                    }
                }
                // `['spawning', 'connected']`, one line or many. **Only an
                // array is read, and only its entries**: the span between two
                // exports also carries prose, and a comment quoting a name must
                // not answer for a line that classifies it.
                "list" => {
                    if !open {
                        // The LAST bracket on the line: the declaration's own
                        // type carries a `[]` before the array opens.
                        let Some((_, after)) = trimmed.rsplit_once('[') else {
                            continue;
                        };
                        if let Some((entries, _)) = after.split_once(']') {
                            names.extend(quoted_names(entries).map(str::to_owned));
                            // Opened and closed on one line: the export carried
                            // its whole list, and what follows is not it.
                            table = "";
                        } else {
                            open = true;
                            names.extend(quoted_names(after).map(str::to_owned));
                        }
                    } else if trimmed.starts_with(']') {
                        open = false;
                        // **The array is the whole of what its export
                        // classifies.** The mode used to end at the next
                        // `export const`, which made the LAST list in the file
                        // read every `[` below it - a client helper's own
                        // literals answering as variants.
                        table = "";
                    } else if trimmed.starts_with('\'') {
                        names.extend(quoted_names(trimmed).map(str::to_owned));
                    }
                }
                _ => {}
            }
        }
        names
    }

    /// The quoted entries of one `const NAME = [ ... ]` block, exported or not,
    /// which is how the client's census of variants is written.
    fn array_entries(client: &str, name: &str) -> Vec<String> {
        let heading = format!("const {name}");
        let mut entries = Vec::new();
        let mut open = false;
        for line in client.lines() {
            let trimmed = line.trim();
            if !open {
                let declared = trimmed.strip_prefix("export ").unwrap_or(trimmed);
                if !declared.starts_with(&heading) {
                    continue;
                }
                let Some((_, after)) = trimmed.rsplit_once('[') else {
                    continue;
                };
                if let Some((inside, _)) = after.split_once(']') {
                    entries.extend(quoted_names(inside).map(str::to_owned));
                } else {
                    open = true;
                    entries.extend(quoted_names(after).map(str::to_owned));
                }
            } else if trimmed.starts_with(']') {
                break;
            } else if trimmed.starts_with('\'') {
                entries.extend(quoted_names(trimmed).map(str::to_owned));
            }
        }
        entries
    }

    /// The names quoted in a run of text: the odd segments of a split on `'`.
    fn quoted_names(text: &str) -> impl Iterator<Item = &str> {
        text.split('\'').skip(1).step_by(2).filter(|entry| is_wire_name(entry))
    }

    /// Whether a token reads as a wire name, which is what keeps a bare word in
    /// a declaration from being taken for an entry.
    fn is_wire_name(token: &str) -> bool {
        !token.is_empty()
            && token.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
    }

    /// The `rename_all` the enum itself declares, which is what turns a variant
    /// name into the name it crosses under.
    fn rename_all(source: &str) -> Option<String> {
        let mut nearest = None;
        for line in source.lines() {
            let trimmed = line.trim();
            if trimmed.starts_with("pub enum SessionUpdate {") {
                return nearest;
            }
            // Comments and blank lines do not break the run above the enum: a
            // doc comment between the attribute and the enum says the same
            // thing, and reading it as "no rename_all" would red a control on a
            // reformatting.
            if trimmed.is_empty() || trimmed.starts_with("//") {
                continue;
            }
            nearest = trimmed
                .strip_prefix("#[serde(rename_all = \"")
                .and_then(|rest| rest.split('"').next())
                .map(str::to_owned);
        }
        None
    }

    /// Every wire name the enum declares, in the order it declares them.
    ///
    /// The derivation serde applies to it: `rename_all` on the enum, and an
    /// explicit `#[serde(rename = "...")]` on the variant above it.
    fn wire_names(source: &str) -> Census {
        let mut names = Vec::new();
        let mut closed = false;
        let mut inside = false;
        let mut renamed: Option<String> = None;
        for line in source.lines() {
            if !inside {
                inside = line.starts_with("pub enum SessionUpdate {");
                continue;
            }
            if line == "}" {
                closed = true;
                break;
            }
            let trimmed = line.trim();
            if let Some(rest) = trimmed.strip_prefix("#[serde(rename = \"") {
                renamed = rest.split('"').next().map(str::to_owned);
                continue;
            }
            if trimmed.is_empty() || trimmed.starts_with("//") || trimmed.starts_with("#[") {
                continue;
            }
            let variant: String =
                trimmed.chars().take_while(|c| c.is_ascii_alphanumeric() || *c == '_').collect();
            if !variant.starts_with(|c: char| c.is_ascii_uppercase()) {
                // A field inside a variant's body, or the brace closing one. A
                // rename attribute above a field belongs to the FIELD, so it is
                // dropped here rather than carried onto the next variant.
                renamed = None;
                continue;
            }
            names.push(renamed.take().unwrap_or_else(|| snake_case(&variant)));
        }
        Census { names, closed }
    }

    /// The book's variant counts are read from the enums, not trusted: a
    /// variant added without the page moving leaves a published number wrong.
    #[test]
    fn the_book_counts_match_the_enums() {
        let source = include_str!("protocol.rs");
        let book = include_str!("../../../docs/book/src/socket.md");
        let flat = book.split_whitespace().collect::<Vec<_>>().join(" ");

        let (command_total, command_struct, command_unit) =
            variant_counts(source, "pub enum Command {");
        assert!(
            flat.contains(&format!(
                "`Command` has {command_total} variants, {command_struct} of them struct variants; the {} unit variants",
                spell(command_unit),
            )),
            "the book's Command count is not the enum's: {command_total} total, {command_struct} struct, {command_unit} unit",
        );

        let (update_total, update_struct, update_unit) =
            variant_counts(source, "pub enum SessionUpdate {");
        assert!(
            flat.contains(&format!(
                "{update_struct} of `SessionUpdate`'s {update_total} variants are struct variants"
            )),
            "the book's SessionUpdate count is not the enum's: {update_total} total, {update_struct} struct, {update_unit} unit",
        );
    }

    /// A small count as the book spells it.
    fn spell(n: usize) -> String {
        match n {
            0 => "zero",
            1 => "one",
            2 => "two",
            3 => "three",
            4 => "four",
            5 => "five",
            6 => "six",
            7 => "seven",
            8 => "eight",
            9 => "nine",
            10 => "ten",
            _ => return n.to_string(),
        }
        .to_owned()
    }

    /// Count an enum's variants, and how many carry a struct body.
    fn variant_counts(source: &str, header: &str) -> (usize, usize, usize) {
        let mut total = 0;
        let mut structs = 0;
        let mut units = 0;
        let mut inside = false;
        for line in source.lines() {
            if !inside {
                inside = line.starts_with(header);
                continue;
            }
            if line == "}" {
                break;
            }
            let trimmed = line.trim();
            if trimmed.is_empty() || trimmed.starts_with("//") || trimmed.starts_with("#[") {
                continue;
            }
            let variant: String =
                trimmed.chars().take_while(|c| c.is_ascii_alphanumeric() || *c == '_').collect();
            if !variant.starts_with(|c: char| c.is_ascii_uppercase()) {
                continue;
            }
            total += 1;
            if trimmed.contains('{') {
                structs += 1;
            } else {
                units += 1;
            }
        }
        (total, structs, units)
    }

    /// serde's own rule for this enum's `rename_all`, for a variant with no
    /// explicit rename over it.
    fn snake_case(name: &str) -> String {
        let mut out = String::new();
        for (at, c) in name.chars().enumerate() {
            if c.is_ascii_uppercase() {
                if at != 0 {
                    out.push('_');
                }
                out.push(c.to_ascii_lowercase());
            } else {
                out.push(c);
            }
        }
        out
    }
}

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

    /// A level whose window heard nothing carries a non-finite dB, which
    /// serde writes as `null` - and must read back, or a Rust reader
    /// cannot decode the message at all. The wire value stays `null`: the
    /// tolerance is on the read side, so nothing a client narrows moves.
    #[test]
    fn a_level_with_no_signal_round_trips_as_null() {
        let key = SessionSlot::from_str_for_test("dictate-level".to_owned());
        let silent = SessionUpdate::DictateLevel {
            key: key.clone(),
            peak_db: f32::NEG_INFINITY,
            generation: 1,
            initiator: None,
        };
        let encoded = serde_json::to_value(&silent).expect("a level encodes");
        assert!(
            encoded["dictate_level"]["peak_db"].is_null(),
            "a no-signal reading crosses as null, got {encoded}"
        );

        let back: SessionUpdate = serde_json::from_value(encoded).expect("a level decodes");
        let SessionUpdate::DictateLevel { peak_db, .. } = back else {
            panic!("the level decoded into another update")
        };
        assert_eq!(peak_db, f32::NEG_INFINITY, "null must read back as no signal");

        // And a reading that IS a signal is untouched by the tolerance.
        let heard =
            SessionUpdate::DictateLevel { key, peak_db: -22.5, generation: 1, initiator: None };
        let encoded = serde_json::to_value(&heard).expect("a level encodes");
        let back: SessionUpdate = serde_json::from_value(encoded).expect("a level decodes");
        let SessionUpdate::DictateLevel { peak_db, .. } = back else {
            panic!("the level decoded into another update")
        };
        assert_eq!(peak_db, -22.5);
    }

    /// **A reading and a transcribing name the take they belong to.** They
    /// are the two frames a client uses to draw a live take, and a frame
    /// that arrived after a newer start is the older take's: without the
    /// number the client cannot tell, and writes it into the live meter
    /// (#839).
    #[test]
    fn a_reading_and_a_transcribing_cross_with_their_generation() {
        let key = SessionSlot::from_str_for_test("take-generation".to_owned());
        let level = SessionUpdate::DictateLevel {
            key: key.clone(),
            peak_db: -20.0,
            generation: 7,
            initiator: None,
        };
        let encoded = serde_json::to_value(&level).expect("a level encodes");
        assert_eq!(
            encoded["dictate_level"]["generation"],
            serde_json::json!(7),
            "a reading carries its take's own number: {encoded}"
        );

        let transcribing =
            SessionUpdate::DictateTranscribing { key, generation: 7, initiator: None };
        let encoded = serde_json::to_value(&transcribing).expect("a transcribing encodes");
        assert_eq!(
            encoded["dictate_transcribing"]["generation"],
            serde_json::json!(7),
            "and so does the frame that says it is transcribing: {encoded}"
        );
    }

    /// A take that heard nothing crosses the peak in its END the same way a
    /// level's crosses, so the same tolerance has to read it: a reader that
    /// decodes the level and then fails on the end of the same take is just
    /// as broken, and the failure names the type rather than the case.
    #[test]
    fn a_no_audio_end_with_no_signal_round_trips() {
        let key = SessionSlot::from_str_for_test("no-audio-end".to_owned());
        let silent = SessionUpdate::DictateEnded {
            key: key.clone(),
            outcome: DictateOutcome::NoAudio { peak_db: f32::NEG_INFINITY, seconds: 3 },
            generation: 1,
            surface: None,
            initiator: None,
        };
        let encoded = serde_json::to_value(&silent).expect("an end encodes");
        assert!(
            encoded["dictate_ended"]["outcome"]["no_audio"]["peak_db"].is_null(),
            "a no-signal end crosses as null, got {encoded}"
        );

        let back: SessionUpdate = serde_json::from_value(encoded).expect("an end decodes");
        let SessionUpdate::DictateEnded { outcome, .. } = back else {
            panic!("the end decoded into another update")
        };
        assert_eq!(
            outcome,
            DictateOutcome::NoAudio { peak_db: f32::NEG_INFINITY, seconds: 3 },
            "null must read back as no signal"
        );

        // And a reading that IS a signal is untouched by the tolerance.
        let quiet = SessionUpdate::DictateEnded {
            key,
            outcome: DictateOutcome::NoAudio { peak_db: -41.5, seconds: 3 },
            generation: 1,
            surface: None,
            initiator: None,
        };
        let encoded = serde_json::to_value(&quiet).expect("an end encodes");
        let back: SessionUpdate = serde_json::from_value(encoded).expect("an end decodes");
        let SessionUpdate::DictateEnded { outcome, .. } = back else {
            panic!("the end decoded into another update")
        };
        assert_eq!(outcome, DictateOutcome::NoAudio { peak_db: -41.5, seconds: 3 });
    }
}

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

    /// The initiator is transport-side state and never crosses: a take's
    /// updates serialize exactly as v4's frames did. Catches a `serde(skip)`
    /// dropped from any of the five - a token on the wire is a contract
    /// change a client would read as an unknown field.
    #[test]
    fn no_dictate_update_carries_its_initiator_across() {
        let key = SessionSlot::from_str_for_test("initiator-wire".to_owned());
        let updates = [
            SessionUpdate::DictateStarted {
                key: key.clone(),
                floor_db: -50.0,
                generation: 1,
                initiator: Some(7),
            },
            SessionUpdate::DictateLevel {
                key: key.clone(),
                peak_db: -20.0,
                generation: 1,
                initiator: Some(7),
            },
            SessionUpdate::DictateTranscribing {
                key: key.clone(),
                generation: 1,
                initiator: Some(7),
            },
            SessionUpdate::DictateProgress {
                key: key.clone(),
                generation: 1,
                done: 1,
                total: Some(2),
                initiator: Some(7),
            },
            SessionUpdate::DictateEnded {
                key,
                outcome: DictateOutcome::Cancelled,
                generation: 1,
                surface: None,
                initiator: Some(7),
            },
        ];
        for update in &updates {
            let encoded = serde_json::to_value(update).expect("an update encodes");
            let body = encoded
                .as_object()
                .and_then(|wrapper| wrapper.values().next())
                .expect("an update encodes as its own name around its body");
            assert!(
                body.get("initiator").is_none(),
                "{update:?} carried its initiator across the wire: {encoded}"
            );
        }
    }
}

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

    #[test]
    fn worker_spawn_reply_constructs() {
        let r = WorkerSpawnReply {
            session_id: "abc".into(),
            tag: "forge:worker:reviewer".into(),
            mcp_families: None,
            rate_limited_account: None,
            durability_warning: None,
            worktree: None,
            session_choice: SessionChoice::Fresh,
        };
        assert_eq!(r.tag, "forge:worker:reviewer");
    }

    /// The board's edits are the user's own: no session routes them, so a
    /// command with no key must reach the app-level path rather than be
    /// dropped as unroutable.
    #[test]
    fn the_board_commands_are_app_level() {
        for command in [
            Command::TaskVerdict {
                project: "p".to_owned(),
                id: "t".to_owned(),
                approve: true,
                words: None,
            },
            Command::TaskAnswer {
                project: "p".to_owned(),
                id: "t".to_owned(),
                words: "w".to_owned(),
            },
            Command::TaskRank { project: "p".to_owned(), id: "t".to_owned(), to: RankMove::Top },
            Command::TaskAssign { project: "p".to_owned(), id: "t".to_owned(), owner: None },
            Command::TaskCreate { project: "p".to_owned(), subject: "s".to_owned(), parent: None },
            Command::TaskMove {
                project: "p".to_owned(),
                id: "t".to_owned(),
                to: forge_primitives::tasks::TaskStatus::InProgress,
                place: None,
            },
        ] {
            assert!(command.key().is_none(), "app-level: {command:?}");
        }
    }

    /// The add's dispatch id crosses, and a press that named none still
    /// parses: the accessor is what a refusal echoes and the outcome frames
    /// carry, which is the identity a page keys its own answer on.
    #[test]
    fn a_marketplace_add_names_the_dispatch_its_press_made() {
        let named: Command =
            serde_json::from_str(r#"{"marketplace_add":{"source":"owner/repo","dispatch_id":41}}"#)
                .expect("a press that names its dispatch");
        assert_eq!(named.dispatch_id(), Some(41), "the accessor reads the press's own id");

        let bare: Command = serde_json::from_str(r#"{"marketplace_add":{"source":"owner/repo"}}"#)
            .expect("a press that named none still parses");
        assert_eq!(bare.dispatch_id(), None, "and answers none");

        assert_eq!(
            Command::PluginCheckUpdates.dispatch_id(),
            None,
            "a command no press names a dispatch for carries none",
        );
    }

    /// **A prompt's press names itself too** (#1583). The refusal of a
    /// prompt echoes the dispatch id it carried, so a composer with sends
    /// out on two seats marks the one the core refused rather than both -
    /// and a view that minted none, which is every view before this field,
    /// still parses.
    #[test]
    fn a_prompt_under_names_the_dispatch_its_press_made() {
        let named: Command = serde_json::from_str(
            r#"{"prompt_under":{"key":{"org":"Org","project":"p","label":"lead"},"text":"hi","attachments":[],"uuid":"u1","source":"you","dispatch_id":9}}"#,
        )
        .expect("a press that names its dispatch");
        assert_eq!(named.dispatch_id(), Some(9), "the accessor reads the press's own id");

        let bare: Command = serde_json::from_str(
            r#"{"prompt_under":{"key":{"org":"Org","project":"p","label":"lead"},"text":"hi","attachments":[],"uuid":"u1","source":"you"}}"#,
        )
        .expect("a press that named none still parses");
        assert_eq!(bare.dispatch_id(), None, "and answers none");
    }

    /// A move WITHOUT a place parses: the keyboard's lane step sends the
    /// state alone, and the default on the field is what keeps that frame
    /// from coming back as an unknown message. A place that IS there comes
    /// through rather than being dropped.
    #[test]
    fn a_task_move_carries_an_optional_place() {
        let bare: Command =
            serde_json::from_str(r#"{"task_move":{"project":"p","id":"t","to":"in_progress"}}"#)
                .expect("a place-less move");
        match bare {
            Command::TaskMove { place, to, .. } => {
                assert_eq!(place, None, "an absent place is None");
                assert_eq!(to, forge_primitives::tasks::TaskStatus::InProgress);
            }
            other => panic!("parsed as {other:?}"),
        }
        let placed: Command = serde_json::from_str(
            r#"{"task_move":{"project":"p","id":"t","to":"waiting","place":{"before":"a"}}}"#,
        )
        .expect("a move with a place");
        match placed {
            Command::TaskMove { place, .. } => {
                assert_eq!(place, Some(RankMove::Before(Some("a".to_owned()))));
            }
            other => panic!("parsed as {other:?}"),
        }
    }

    /// A spawn frame written before `cwd` existed parses: the recorded
    /// frames and the in-repo client's own payloads predate the key, and
    /// the default on the field is what keeps one from coming back as an
    /// unknown message. A key that IS there comes through rather than
    /// being dropped.
    #[test]
    fn a_spawn_worker_carries_an_optional_cwd() {
        let frame = |cwd: &str| {
            format!(
                r#"{{"spawn_worker":{{"project_key":"proj","label":"w","charter":"c","spawned_by":{{"org":"o","project":"p","label":"lead"}},"resume_existing":null,"kick":null,"resume_kick":null,"interactive":false,"mcp_families":null{cwd},"from_boot_respawn":false}}}}"#
            )
        };
        let bare: Command =
            serde_json::from_str(&frame("")).expect("a frame written before the key");
        match bare {
            Command::SpawnWorker { cwd, .. } => {
                assert_eq!(cwd, None, "an absent tree is None, which is the project's own path");
            }
            other => panic!("parsed as {other:?}"),
        }

        let stated: Command =
            serde_json::from_str(&frame(r#","cwd":"/tmp/nazar""#)).expect("a frame with a tree");
        match stated {
            Command::SpawnWorker { cwd, .. } => {
                assert_eq!(cwd.as_deref(), Some("/tmp/nazar"), "a stated tree crosses whole");
            }
            other => panic!("parsed as {other:?}"),
        }
    }
}