agentmux_srv/identity/resolver/

inject.rs

// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! The credential-injection entry points and the layer-3 spawn gate.
//!
//! Split out of the single ~2193-line `resolver.rs` (pure relocation, no
//! behavior change): `inject_identity_env` / `inject_identity_env_async`
//! (thin public wrappers), `IdentityBinding` + `resolve_bindings_for_instance`
//! (direct-link lookup), and `inject_identity_env_with_broker` — the
//! security-critical credential-injection gate. Every test that exercises
//! `inject_identity_env_with_broker` moved here WITH it, as one atomic unit,
//! per the module split's constraint that this function and its tests must
//! never be separated.
//!
//! **Before touching `gate_oauth_failure` / `inject_identity_env_with_broker`:**
//! see the warning doc comment directly above `inject_identity_env_with_broker`
//! below.

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;

use crate::backend::providers::resolve_provider_alias;
use crate::backend::storage::store::{IdentityAccount, SecretRef, Store};
use crate::backend::storage::StoreError;
use crate::backend::mps::Broker;

use super::errors::SpawnGateError;
use super::oauth_probe::{oauth_status, probe_oauth_status};
use super::provider::{provider_class, ProviderClass};
use super::secret::resolve_secret;

/// Inject identity-derived env vars into the spawn map for a block.
///
/// Synchronous, broker-less entry point — in production only the durable-jekt
/// sign-in recheck (server/jekt_held.rs) calls it. The CLI-spawn paths use
/// [`inject_identity_env_async`] instead (via `build_persistent_spawn_env` in
/// server/agent_handlers/input.rs). Resolution flow:
///
/// 1. Look up the active `AgentInstance` for this block. If none
///    exists, the caller didn't go through the launch modal — return
///    immediately, no injection (unless the block names a deleted agent:
///    that is refused with `SpawnGateError::AgentDeleted`, #3577).
/// 2. Read its `identity_id`. Empty / "blank" no longer short-circuits to
///    ambient creds (see #2463 — this used to bypass the layer-3 gate
///    entirely, so whether a spawn required a bound account depended on
///    whether a stray ambient credential happened to exist on the test
///    machine). It now falls through to the same steps below, which gate
///    purely on the agent definition's own provider — identical to how a
///    non-empty-but-unresolvable `identity_id` (e.g. a legacy sentinel)
///    already behaved.
/// 3. Read the `db_agent_identity_links` rows for the instance's definition.
/// 4. For each binding: fetch the account, resolve its `SecretRef`,
///    look up the provider's env-var matrix, write each var into
///    `env_vars`.
///    - **Api-key-class** per-binding failures are logged and skipped —
///      other bindings still inject (historical behavior).
///    - **Oauth-class** failures (account row missing, lookup error,
///      non-OAuthConfigDir secret_ref) are always BLOCKING: the function
///      returns [`SpawnGateError`] before the CLI process is created.
///      `use_ambient_login` no longer exempts an agent and is not read
///      here (the opt-out was retired, see
///      m0017_ambient_login_grandfather.rs).
/// 5. If the agent definition's own provider is oauth-class and no binding
///    for it exists at all (fresh/never-bound or post-delete-cascade), the
///    same gate applies — implicit ambient fallback is how the
///    delete-doesn't-deauthenticate gap happened (spec §2.2 edge case).
///
/// Layer 3 of SPEC_ACCOUNT_DELETE_DEAUTH_LAYERS_2_4_2026_07_14.md. Before
/// it, this function was intentionally infallible ("the spawn never aborts
/// because a secret didn't resolve") — that is still true for api-key-class
/// bindings, but oauth-class resolution failures now fail the spawn by
/// default so account deletion is honest at the next spawn.
pub fn inject_identity_env(
    mstore: Arc<Store>,
    id_store: Arc<Store>,
    identity_store: Arc<Store>,
    block_id: &str,
    env_vars: &mut HashMap<String, String>,
) -> Result<(), SpawnGateError> {
    inject_identity_env_with_broker(mstore, id_store, identity_store, None, block_id, env_vars)
}

/// The optional broker lets the OAuth-class branch publish
/// `identityaccounts:changed` on a status change discovered by the expiry
/// probe. `None` skips the publish; the `agentinput` turn
/// (server/agent_handlers/input.rs) and `agent.send` (app_api/agent_io.rs)
/// pass `Some(broker.clone())` through `build_persistent_spawn_env` so any
/// live account list flips its status badge without a reload. Per spec §4.4.
///
/// Async wrapper around [`inject_identity_env_with_broker`] for use from
/// async spawn handlers. The underlying path does blocking I/O — synchronous
/// SQLite reads and, for `SecretRef::Keychain` accounts, a blocking
/// `keyring` (D-Bus Secret Service on Linux) read — so it runs on a blocking
/// thread via `spawn_blocking` rather than stalling an async runtime worker.
/// Takes ownership of `env_vars` and returns it with identity vars merged in.
///
/// `Err(SpawnGateError)` is the layer-3 spawn gate (see
/// [`inject_identity_env`]): the caller must NOT spawn the CLI and must
/// surface the error on the agent pane like any other spawn failure. A
/// task-join failure also fails CLOSED (`InjectionUnavailable`, blocking
/// the spawn) — see that variant's doc for why an open fallback would
/// systemically bypass the gate after any store panic.
pub async fn inject_identity_env_async(
    mstore: Arc<Store>,
    id_store: Arc<Store>,
    identity_store: Arc<Store>,
    broker: Option<Arc<Broker>>,
    block_id: String,
    env_vars: HashMap<String, String>,
) -> Result<HashMap<String, String>, SpawnGateError> {
    match tokio::task::spawn_blocking(move || {
        let mut env = env_vars;
        inject_identity_env_with_broker(mstore, id_store, identity_store, broker, &block_id, &mut env)
            .map(|()| env)
    })
    .await
    {
        Ok(result) => result,
        Err(e) => {
            // Fail CLOSED. A join failure means the closure panicked (or
            // was cancelled) — the gate never rendered a verdict, and the
            // panic has likely poisoned the Store mutex, so failing open
            // here would bypass the oauth gate for every later
            // spawn too (reagent P1, PR #2164 round 1). See
            // SpawnGateError::InjectionUnavailable.
            tracing::warn!(
                target: "identity",
                error = %e,
                "identity.spawn.blocked: injection task join failed — failing closed"
            );
            Err(SpawnGateError::InjectionUnavailable { detail: e.to_string() })
        }
    }
}

/// Resolved (provider, account) pair ready for env injection.
///
/// Historically a row of the `db_identity_bindings` table (retired in
/// Phase 4c of SPEC_PRESET_TO_BUNDLE_REFACTOR_2026_07_02.md); now purely
/// an internal shape built from `AgentIdentityLink` rows.
struct IdentityBinding {
    provider: String,
    account_id: String,
}

/// Resolve the identity bindings for an instance from the **direct**
/// agent↔account links only.
///
/// Phase 3 slice 2 PR-B (the flip): the resolver previously dual-read —
/// preferring `db_agent_identity_links` keyed on the instance's DEFINITION
/// id, falling back to the bundle bindings (`db_identity_bindings`) when no
/// direct links existed (PR-A, #1927). That fallback was removed here, and
/// Phase 4c of SPEC_PRESET_TO_BUNDLE_REFACTOR_2026_07_02.md later dropped
/// `db_identity_bundles`/`db_identity_bindings` entirely — every write path
/// (launch flow, per-agent Accounts tab, OAuth Connect/Reconnect) writes a
/// direct link, and the m0013/m0014 migrations (#1927/#1952) backfilled
/// direct links for every pre-existing bundle binding before the drop.
///
/// `parent_template_id`: the launch's eligible TEMPLATE parent's own id —
/// `""` unless the caller has already confirmed, via
/// `template_parent_id_if_seeded`, that `db_agents.parent_template_id`
/// actually points at a row with `is_seeded = 1`. That column is NOT
/// exclusively "which template was I launched from": `forkagentdefinition`
/// (`template.rs`) reuses the same column to record a plain agent fork's
/// SOURCE agent id, `is_seeded = 0`. reagent P0 on #3092 caught an earlier
/// version of this fallback trusting the column unconditionally — a fork
/// of any regular agent that had a bound identity would silently inherit
/// and spawn on the SOURCE agent's credentials, even though forks are
/// deliberately created with `accounts: ""` and no link of their own
/// (fail-closed by design, the same convention `conversation_visibility`
/// documents right next to `parent_id` in `template.rs`). Callers MUST
/// resolve this through `template_parent_id_if_seeded`, never pass
/// `d.parent_id` directly.
///
/// Agent-concept consolidation's definition flip
/// (`SPEC_AGENT_ARCHITECTURE_2026_05_27.md` Phase 3d) made `agent_def_get`
/// resolve a template launch's own row for the first time, which enabled
/// Step 5's definition-provider gate for that whole agent class — but
/// binding an identity to a TEMPLATE (the Agent Setup modal's supported
/// target) has always written the link under the TEMPLATE's id, never the
/// launch's own id, since nothing writes a launch-scoped link. Without
/// this fallback, enabling Step 5 would have converted every template
/// launch with a genuinely configured account into a hard spawn failure —
/// the direct link lookup below finds nothing under the launch's own id
/// regardless of whether an account is actually bound, because it never
/// was.
///
/// `broker` publishes `identity:no-direct-links` when the direct set is
/// empty — a standing diagnostic for a non-sentinel identity resolving to
/// zero links (e.g. a stale/migrated-away instance). `None` in tests /
/// call sites that don't have a broker handle.
/// `parent_id`'s eligible-template gate for `resolve_bindings_for_instance`
/// (see that function's doc comment for the P0 this closes): returns
/// `parent_id` back only when it names a row with `is_seeded = 1` — a
/// genuine template — never for a plain agent-to-agent fork, which reuses
/// the same `parent_id`/`parent_template_id` column for unrelated lineage.
/// `mstore` is the store `parent_id` was read from (the same one
/// `agent_def_get` resolved the launch's own row through); an empty
/// `parent_id`, a lookup failure, or a parent that resolves but isn't
/// seeded all return `""` — "no eligible template parent," not an error.
fn template_parent_id_if_seeded(mstore: &Store, parent_id: &str) -> String {
    if parent_id.is_empty() {
        return String::new();
    }
    match mstore.agent_def_get(parent_id) {
        Ok(Some(parent)) if parent.is_seeded == 1 => parent_id.to_string(),
        Ok(Some(_)) => String::new(), // a fork's source, not a template — reagent P0 on #3092
        Ok(None) => String::new(),
        Err(e) => {
            tracing::warn!(
                target: "identity",
                "template-parent lookup failed for {}: {} — treating as no eligible template parent",
                parent_id,
                e,
            );
            String::new()
        }
    }
}

fn resolve_bindings_for_instance(
    id_store: &Store,
    instance: &crate::backend::storage::store::AgentInstance,
    parent_template_id: &str,
    broker: Option<&Arc<Broker>>,
) -> Vec<IdentityBinding> {
    let direct = id_store
        .agent_identity_list_for_agent(&instance.definition_id)
        .unwrap_or_else(|e| {
            tracing::warn!(
                target: "identity",
                "direct-link lookup failed for definition {}: {}",
                instance.definition_id,
                e,
            );
            Vec::new()
        });

    if direct.is_empty() && !parent_template_id.is_empty() {
        let from_template = id_store
            .agent_identity_list_for_agent(parent_template_id)
            .unwrap_or_else(|e| {
                tracing::warn!(
                    target: "identity",
                    "template link fallback failed for template {}: {}",
                    parent_template_id,
                    e,
                );
                Vec::new()
            });
        if !from_template.is_empty() {
            return from_template
                .into_iter()
                .map(|l| IdentityBinding { provider: l.provider, account_id: l.account_id })
                .collect();
        }
    }

    if direct.is_empty() {
        // Distinct log line + event so a non-sentinel identity resolving
        // to zero links (e.g. an agent that was never linked to an
        // account) is visible, not silently indistinguishable from
        // routine "no accounts configured." Whether the spawn proceeds
        // is decided by the caller's layer-3 definition-provider gate
        // (oauth-class CLI provider with no bound account → blocked).
        tracing::warn!(
            target: "identity",
            "no direct account links for definition {} (identity {}) — \
             nothing to inject.",
            instance.definition_id,
            instance.identity_id,
        );
        if let Some(b) = broker {
            let event = crate::backend::mps_events::NoDirectLinksEvent {
                definition_id: instance.definition_id.clone(),
                identity_id: instance.identity_id.clone(),
            };
            // Persisted (unlike the rest of this file's ephemeral
            // events) — nothing subscribes live yet, so without
            // persistence a future frontend surface polling via
            // read_event_history would see nothing. Small window;
            // this is a diagnostic, not an audit log.
            b.publish_event::<crate::backend::mps_events::IdentityNoDirectLinks>(&event, vec![], 20);
        }
    }

    direct
        .into_iter()
        .map(|l| IdentityBinding {
            provider: l.provider,
            account_id: l.account_id,
        })
        .collect()
}

/// Resolve an account by id, checking `id_store` first — the
/// authoritative, per-account-isolatable primary, which is what preserves
/// the disposable-test-account isolation guarantee — and falling
/// back to `identity_store`'s read-through mirror
/// (`IDENTITY_STORE_SCHEMA_VERSION` v2,
/// `docs/specs/SPEC_IDENTITY_STORE_SPLIT_2026_08_17.md` §3.1) only when the
/// primary lookup misses. Returns the account alongside WHICH store it
/// came from, so a caller that later writes a status update (the OAuth
/// expiry probe below) writes it back to the SAME store instead of always
/// assuming `id_store` — writing to the wrong store would silently create
/// a second, never-read copy.
///
/// reagentx P0 review on PR #2632: before this, the link resolved via
/// `identity_store` (always global) but the account it pointed at could
/// still only exist in `id_store`, which is empty on a fresh, isolated
/// channel — the reported continuity bug wasn't actually fixed end to end
/// without this fallback.
pub fn resolve_account(
    id_store: &Arc<Store>,
    identity_store: &Arc<Store>,
    account_id: &str,
) -> Result<Option<(IdentityAccount, Arc<Store>)>, StoreError> {
    if let Some(a) = id_store.identity_get(account_id)? {
        return Ok(Some((a, id_store.clone())));
    }
    if let Some(a) = identity_store.identity_get(account_id)? {
        return Ok(Some((a, identity_store.clone())));
    }
    Ok(None)
}

/// SPAWN-PATH account lookup — **current channel's `id_store` only, never the
/// global mirror.**
///
/// Deliberately NOT [`resolve_account`]: that function's global fallback is
/// correct for read-only/display callers (the Connectors → Accounts list, link
/// summaries — they should still describe an account that exists elsewhere),
/// but using it to satisfy a *spawn* lets an agent in a fresh channel launch
/// against a credential authenticated in a DIFFERENT channel. That is exactly
/// the per-channel-isolation bypass the operator asked to close:
///
/// > "we want per-channel isolation. a user needs a login anytime in the
/// > channel. the problem is agents are able to login in a channel without a
/// > claude auth."
///
/// **This intentionally reverses part of reagentx's P0 on PR #2632.** That
/// review added the fallback to preserve binding continuity across a
/// version/channel switch, which was the right call under the then-current
/// requirement. The requirement has since changed: per-channel isolation is a
/// wanted feature, and re-login-per-channel is the accepted cost. The fallback
/// is retained for display paths precisely so that continuity fix isn't lost
/// where it was actually about *describing* an account rather than *launching*
/// with one. See
/// `docs/analysis/ANALYSIS_PER_CHANNEL_AUTH_BYPASSES_2026_08_31.md` §2 (#1).
///
/// No dangling-link deadlock results from the stricter lookup:
/// `db_agent_identity_links` is `PRIMARY KEY (agent_id, provider)`, so a
/// re-login in the new channel REPLACES the link rather than leaving a stale
/// one that would block every future spawn.
pub fn resolve_account_for_spawn(
    id_store: &Arc<Store>,
    account_id: &str,
) -> Result<Option<(IdentityAccount, Arc<Store>)>, StoreError> {
    Ok(id_store
        .identity_get(account_id)?
        .map(|a| (a, id_store.clone())))
}

/// Read-only lookup of a block's identity-bound OAuth config dir — the same
/// directory `inject_identity_env_with_broker`'s OAuth branch would inject,
/// without any of that function's side effects (no token-expiry probe, no
/// account-status upsert, no `identityaccounts:changed` publish, no
/// `SpawnGateError` on failure). For a background caller that only needs to
/// know WHERE to look (e.g. `subagent_watcher` deciding which directory to
/// watch at agent registration, not spawn) rather than what to inject.
///
/// Deliberately does not call `inject_identity_env`/`inject_identity_env_with_broker`:
/// those also resolve API-key-class secrets into the caller's env map (a
/// leak risk for a caller that only wants a path) and perform real writes —
/// none of which belong on every registration, only on an actual spawn/turn.
/// See `SPEC_SUBAGENT_WATCHER_IDENTITY_BOUND_CONFIG_DIR_2026_08_22.md`.
///
/// Returns `None` (never an error) for: no instance for this block, no
/// definition, a non-OAuth-class (or unrecognized) provider, no direct
/// binding for that provider, an account row that doesn't resolve, or a
/// `secret_ref` that isn't `OAuthConfigDir` — every one of these is exactly
/// "nothing bound, fall back to the old behavior" for a caller that isn't
/// gating a spawn.
pub fn resolve_bound_oauth_config_dir(
    mstore: &Arc<Store>,
    id_store: &Arc<Store>,
    identity_store: &Arc<Store>,
    block_id: &str,
) -> Option<PathBuf> {
    let instance = mstore.instance_get_active_for_block(block_id).ok().flatten()?;
    bound_oauth_config_dir(mstore, id_store, identity_store, &instance)
}

/// [`resolve_bound_oauth_config_dir`] for a **Claude** agent row by its id,
/// with no block — memory resolution's question (#3603): where does this
/// agent's Claude run, so where are its memories (`projects/<cwd>/memory`,
/// a Claude layout). `None` for any other provider, and for an account bound
/// to the ambient `~/.claude` — the spawn refuses that dir, and memory
/// writes must never land in the user's own Claude projects.
pub fn resolve_bound_claude_config_dir_for_agent(
    mstore: &Store,
    id_store: &Arc<Store>,
    identity_store: &Arc<Store>,
    agent_id: &str,
) -> Option<PathBuf> {
    let instance = mstore.instance_get(agent_id).ok().flatten()?;
    let def = mstore.agent_def_get(&instance.definition_id).ok().flatten()?;
    let provider = id_store.resolve_effective_provider_id(&def);
    if resolve_provider_alias(&provider) != "claude" {
        return None;
    }
    let dir = bound_oauth_config_dir(mstore, id_store, identity_store, &instance)?;
    let claude = crate::backend::providers::get_provider("claude")?;
    if crate::backend::providers::is_provider_ambient_home_dir(claude, &dir.to_string_lossy()) {
        return None;
    }
    Some(dir)
}

/// Whether an agent has any identity binding — its own links, or its
/// template's when it has none — checked without the binding resolver's
/// "no links" warning. For callers that ask on every sweep (memory), so an
/// unlinked agent costs a lookup, not a log line.
pub fn agent_has_identity_binding(mstore: &Store, identity_store: &Store, agent_id: &str) -> bool {
    let direct = identity_store
        .agent_identity_list_for_agent(agent_id)
        .map(|l| !l.is_empty())
        .unwrap_or(false);
    if direct {
        return true;
    }
    let Some(def) = mstore.agent_def_get(agent_id).ok().flatten() else {
        return false;
    };
    let parent = template_parent_id_if_seeded(mstore, &def.parent_id);
    !parent.is_empty()
        && identity_store
            .agent_identity_list_for_agent(&parent)
            .map(|l| !l.is_empty())
            .unwrap_or(false)
}

fn bound_oauth_config_dir(
    mstore: &Store,
    id_store: &Arc<Store>,
    identity_store: &Arc<Store>,
    instance: &crate::backend::storage::store::AgentInstance,
) -> Option<PathBuf> {
    let def = mstore.agent_def_get(&instance.definition_id).ok().flatten()?;
    let effective_provider = id_store.resolve_effective_provider_id(&def);
    let canonical_provider = resolve_provider_alias(&effective_provider).to_string();
    if !matches!(provider_class(&canonical_provider), Some(ProviderClass::OAuth { .. })) {
        return None;
    }

    let template_parent_id = template_parent_id_if_seeded(mstore, &def.parent_id);
    let bindings = resolve_bindings_for_instance(identity_store, instance, &template_parent_id, None);
    let binding = bindings
        .iter()
        .find(|b| resolve_provider_alias(&b.provider) == canonical_provider)?;
    // Per-channel only, matching the spawn gate exactly: this function's whole
    // contract is "where WOULD the spawn inject," so resolving an account the
    // spawn itself would now refuse would point a watcher at a directory no
    // agent can actually launch against.
    let (account, _store) = resolve_account_for_spawn(id_store, &binding.account_id).ok().flatten()?;
    match account.secret_ref {
        SecretRef::OAuthConfigDir { dir } => Some(PathBuf::from(dir)),
        _ => None,
    }
}

/// The agent a block names (`agentId`, or legacy `agent:id`), if any.
pub(crate) fn block_agent_id(mstore: &Store, block_id: &str) -> Option<String> {
    let block: crate::backend::obj::Block = mstore.get(block_id).ok().flatten()?;
    crate::backend::obj::block_meta_agent_id(&block.meta)
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::to_string)
}

/// **Before touching `gate_oauth_failure` / `inject_identity_env_with_broker`:**
/// this module is where `SPEC_PROVIDER_ISOLATION_2026_06_20.md`'s INV-A
/// ("never the user's global `~/.<P>` dir") is enforced — or, once already,
/// silently stopped being enforced. Read
/// `docs/retro/retro-auth-isolation-invariant-silently-orphaned-2026-07-14.md`
/// first. Short version: an unbound oauth-class provider used to
/// auto-route to an AgentMux-owned isolated dir (no user action, no global
/// exposure); a 2026-07-08 refactor orphaned that path without meaning to,
/// and it was never restored. Today's gate always blocks an unbound
/// oauth-class provider; the per-agent "true ambient" opt-out
/// (`use_ambient_login`) is no longer read.
pub fn inject_identity_env_with_broker(
    mstore: Arc<Store>,
    id_store: Arc<Store>,
    identity_store: Arc<Store>,
    broker: Option<Arc<Broker>>,
    block_id: &str,
    env_vars: &mut HashMap<String, String>,
) -> Result<(), SpawnGateError> {
    // Step 1: instance lookup — per-channel, always reads from mstore.
    let instance = match mstore.instance_get_active_for_block(block_id) {
        Ok(Some(i)) => i,
        Ok(None) => {
            // #3577: a block that names an agent which was DELETED — its pane
            // survived the delete (another window, or mid-spawn) — is refused,
            // not spawned on the shared login with no identity. Only a
            // positive "deleted" signal refuses; every other row-less block
            // keeps today's behaviour.
            if let Some(agent_id) = block_agent_id(&mstore, block_id) {
                if mstore.agent_was_deleted(&agent_id) {
                    return Err(SpawnGateError::AgentDeleted { agent_id });
                }
            }
            // Otherwise the block has no agent instance row — nothing to
            // inject, and no gating either: template sessions and quick-launch
            // panes are outside the managed-credentials contract.
            return Ok(());
        }
        Err(e) => {
            tracing::warn!(target: "identity", "instance lookup failed for block {}: {}", block_id, e);
            return Ok(());
        }
    };

    // Step 2: identity_id check.
    //
    // #2463 Finding 2: this used to `return Ok(())` here (silent ambient-
    // creds fallback), which bypassed the layer-3 "must have a bound
    // account" gate below entirely — a genuinely brand-new agent launched
    // with no account selected got identity_id="" and spawned on whatever
    // ambient credential happened to be sitting on disk, with nothing
    // bound in Connectors. Observed behavior therefore depended on whether the
    // test machine happened to have a stray credential file, not on any
    // actual policy decision. The UI no longer produces empty/"blank"
    // identity_id for new launches (identity is required at submit-time —
    // SPEC_LAUNCH_MODAL_STATE_MACHINE_2026_05_19.md), so seeing one here
    // means a legacy continuation row or a UI regression; either way it
    // must be gated the same as any other unresolvable identity_id rather
    // than silently bypassed. `resolve_bindings_for_instance` below keys
    // strictly off `instance.definition_id`, not `identity_id`, so falling
    // through here is safe regardless of what identity_id contains.
    if instance.identity_id.is_empty() || instance.identity_id == "blank" {
        tracing::warn!(
            target: "identity",
            "instance {} has empty/blank identity_id — falling through to the \
             layer-3 gate instead of ambient creds. Legacy row or UI regression?",
            block_id
        );
    }

    // Layer-3 gate input: the agent definition's own CLI provider (the
    // oauth-class provider every launch of this agent uses, whether or not
    // a binding row exists for it). A missing definition row reads as no
    // expected provider — the per-binding gate still applies to whatever
    // links exist.
    //
    // Provider is resolved via `id_store.resolve_effective_provider_id`
    // (`backend/storage/agents/definition.rs`), the one resolver `agent_open.rs`'s
    // spawn path also uses, so this gate checks credentials for exactly the
    // provider that will run: the agent's own, read-only after creation, or
    // its bundle's when it has none (SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md
    // §3.1). One resolver for both call sites so they can't disagree (#2587).
    //
    // Canonicalized via `resolve_provider_alias` (codex P1 on PR #2377): a
    // definition's own `provider` field predates this alias table in rare
    // cases, and this value is compared below against `injected_oauth` /
    // `bindings`' raw (possibly aliased) provider strings — comparing
    // uncanonicalized would let a genuinely-injected alias-only binding
    // still trip the "no account bound" gate. Applied to the bundle-
    // resolved value, not the raw column, so an aliased definition whose
    // bundle already carries the canonical id doesn't get re-aliased
    // incorrectly (resolve_provider_alias is idempotent on an
    // already-canonical id, so this is safe either way).
    let (def_provider, parent_template_id) = match mstore.agent_def_get(&instance.definition_id) {
        Ok(Some(d)) => {
            let effective_provider = id_store.resolve_effective_provider_id(&d);
            let template_parent_id = template_parent_id_if_seeded(&mstore, &d.parent_id);
            (
                Some(resolve_provider_alias(&effective_provider).to_string()),
                template_parent_id,
            )
        }
        Ok(None) => (None, String::new()),
        Err(e) => {
            tracing::warn!(
                target: "identity",
                "definition lookup failed for {}: {}",
                instance.definition_id,
                e,
            );
            (None, String::new())
        }
    };

    // Step 3: bindings — global, reads from id_store. Direct-links-only
    // as of Phase 3 slice 2 PR-B (the flip) — see resolve_bindings_for_instance's
    // doc comment for the transitional gap this closes and the one it
    // doesn't (#1624 PR-C). Falls back to the launch's TEMPLATE's own links
    // when the launch has none of its own (codex P1 on #3092) — binding an
    // identity to a template has always written the link under the
    // template's id, never a launch's.
    //
    // NOTE: an empty set no longer short-circuits — it falls through to the
    // definition-provider gate below (spec §2.2 edge case: an agent whose
    // oauth-class CLI provider has no binding at all is blocked).
    let bindings = resolve_bindings_for_instance(&identity_store, &instance, &parent_template_id, broker.as_ref());

    // Step 4: per-binding resolution + env injection.
    //
    // Each binding's provider determines HOW its account contributes
    // to the agent's env (SPEC_OAUTH_IDENTITY_BUNDLES §4.3):
    //   - ApiKey  — resolve secret_ref to a string, inject as env var(s).
    //   - OAuth   — expect SecretRef::OAuthConfigDir, inject its dir
    //               as the provider's config-dir env var.
    //
    // Api-key-class per-binding failures (unknown provider, account row
    // missing, mismatched secret_ref, secret resolution failed) are logged
    // and skipped — other bindings still inject. Oauth-class failures go
    // through the layer-3 gate, which always blocks.
    let mut injected_oauth: std::collections::HashSet<String> =
        std::collections::HashSet::new();

    // Gate helper for an unresolvable oauth-class binding/provider. Always
    // blocks the spawn — an oauth-class provider must resolve to a real
    // bound IdentityAccount, full stop.
    //
    // `use_ambient_login` used to let this fall through to the user's
    // global/ambient CLI login instead of blocking. That escape hatch is
    // retired (PLAN_LOGIN_SINGLE_PATH_CONSOLIDATION_2026_07_20.md §7,
    // "single point, not global"): a credential the app can't attribute to
    // a specific account is exactly the state that left Marks
    // silently working with an untracked, unrefreshed shared-dir credential
    // and no visible account anywhere in Connectors. The flag is no longer read.
    let gate_oauth_failure = |provider: &str, detail: &str| -> Result<(), SpawnGateError> {
        tracing::warn!(
            target: "identity",
            "identity.spawn.blocked: no credentials for provider {} \
             (definition {}, identity {}) — {}; spawn refused \
             (single-point enforcement)",
            provider,
            instance.definition_id,
            instance.identity_id,
            detail,
        );
        Err(SpawnGateError::MissingCredentials {
            provider: provider.to_string(),
        })
    };

    for binding in &bindings {
        let class = match provider_class(&binding.provider) {
            Some(c) => c,
            None => {
                tracing::warn!(
                    target: "identity",
                    "no provider class for {} (binding for identity {}) — skipping",
                    binding.provider,
                    instance.identity_id,
                );
                continue;
            }
        };
        let is_oauth_class = matches!(class, ProviderClass::OAuth { .. });

        // Per-channel ONLY (see `resolve_account_for_spawn`) — a credential
        // authenticated in another channel must not satisfy this spawn.
        let (account, account_store) = match resolve_account_for_spawn(&id_store, &binding.account_id) {
            Ok(Some(pair)) => pair,
            Ok(None) => {
                // The post-delete case (analysis §2.3): the link survived
                // (or was cascaded and re-created stale) but the account
                // row is gone. For oauth-class providers this is the
                // load-bearing layer-3 gate — no more silent fallback to
                // the user's global login.
                if is_oauth_class {
                    gate_oauth_failure(
                        &binding.provider,
                        &format!("account {} row not found", binding.account_id),
                    )?;
                    continue;
                }
                tracing::warn!(
                    target: "identity",
                    "account {} bound to identity {} but row not found — skipping",
                    binding.account_id,
                    instance.identity_id,
                );
                continue;
            }
            Err(e) => {
                if is_oauth_class {
                    gate_oauth_failure(
                        &binding.provider,
                        &format!("account lookup failed for {}: {}", binding.account_id, e),
                    )?;
                    continue;
                }
                tracing::warn!(
                    target: "identity",
                    "account lookup failed for {}: {}",
                    binding.account_id,
                    e,
                );
                continue;
            }
        };

        match class {
            ProviderClass::ApiKey { env_vars: env_keys } => {
                let secret = match resolve_secret(&account.secret_ref) {
                    Ok(s) => s,
                    Err(e) => {
                        tracing::warn!(
                            target: "identity",
                            "secret resolution failed for account {} (provider {}): {} — skipping",
                            binding.account_id,
                            binding.provider,
                            e,
                        );
                        continue;
                    }
                };
                let env_key_count = env_keys.len();
                for key in env_keys {
                    env_vars.insert(key.to_string(), secret.clone());
                }
                tracing::info!(
                    target: "identity",
                    "injected {} env var(s) for api-key provider {} (identity={}, account={})",
                    env_key_count,
                    binding.provider,
                    instance.identity_id,
                    binding.account_id,
                );
            }
            ProviderClass::OAuth { config_dir_env_var } => {
                // OAuth-class bindings expect SecretRef::OAuthConfigDir.
                // Any other variant is a misconfiguration — the account is
                // unresolvable for this provider, so it goes through the
                // layer-3 gate rather than silently leaving the CLI on the
                // user's global login.
                let dir = match &account.secret_ref {
                    SecretRef::OAuthConfigDir { dir } => dir.clone(),
                    other => {
                        gate_oauth_failure(
                            &binding.provider,
                            &format!(
                                "non-OAuthConfigDir secret_ref ({:?}) on account {}",
                                other, binding.account_id,
                            ),
                        )?;
                        continue;
                    }
                };
                // Block unconditionally if this account's config dir IS the
                // provider's literal ambient home (e.g. `~/.claude`) rather
                // than an AgentMux-isolated dir — nothing upstream of this
                // point validates that, and a real, currently-live account
                // configured exactly this way was found in this repo's own
                // data (docs/status/STATUS_IDENTITY_ISOLATION_GATE_NOT_ENFORCING_2026_08_20.md
                // §8). See docs/specs/SPEC_BLOCK_AMBIENT_HOME_DIR_IDENTITY_BINDING_2026_08_25.md.
                if let Some(provider_cfg) =
                    crate::backend::providers::get_provider(&resolve_provider_alias(&binding.provider))
                {
                    if crate::backend::providers::is_provider_ambient_home_dir(provider_cfg, &dir) {
                        tracing::warn!(
                            target: "identity",
                            "identity.spawn.blocked: account {} for provider {} \
                             resolves to the ambient home dir ({}) — refusing to \
                             spawn (identity {})",
                            binding.account_id,
                            binding.provider,
                            dir,
                            instance.identity_id,
                        );
                        return Err(SpawnGateError::AmbientHomeDirNotAllowed {
                            provider: binding.provider.clone(),
                            dir: dir.clone(),
                        });
                    }
                    // `dir` is confirmed NOT the ambient home at this point —
                    // but a genuinely separate isolated dir can still lack a
                    // CLAUDE.md of its own, which Claude Code CLI treats as
                    // "fall through to the real $HOME/.claude/CLAUDE.md,"
                    // not "no user-level memory file." Idempotent — cheap
                    // no-op after the first call. Fail closed (same as the
                    // ambient-home-dir check above) rather than warn-and-
                    // continue: Codex P1 + ReAgent P1 on PR #2854 — a
                    // warn-only failure here would launch the agent with
                    // exactly the unprotected condition this fix exists to
                    // close. See SPEC_ISOLATE_HOST_CLAUDE_MD_2026_08_31.md.
                    if let Err(e) =
                        crate::backend::providers::seed_claude_md_placeholder_if_missing(provider_cfg, &dir)
                    {
                        tracing::warn!(
                            target: "identity",
                            "identity.spawn.blocked: account {} for provider {} \
                             failed CLAUDE.md isolation seed ({}) — refusing to \
                             spawn (identity {})",
                            binding.account_id,
                            binding.provider,
                            e,
                            instance.identity_id,
                        );
                        return Err(SpawnGateError::ClaudeMdSeedFailed {
                            provider: binding.provider.clone(),
                            dir: dir.clone(),
                            error: e.to_string(),
                        });
                    }
                    // Soft-fail: a missing retention setting costs old
                    // transcripts, not isolation, so it never blocks a spawn.
                    if let Err(e) =
                        crate::backend::providers::seed_transcript_retention_if_missing(provider_cfg, &dir)
                    {
                        tracing::warn!(
                            target: "identity",
                            "account {} for provider {}: could not set transcript retention in {} ({}) — \
                             Claude Code's 30-day default will sweep this account's shared history",
                            binding.account_id,
                            binding.provider,
                            dir,
                            e,
                        );
                    }
                }
                env_vars.insert(config_dir_env_var.to_string(), dir.clone());
                // Canonicalized (codex P1 on PR #2377) — see def_provider's
                // doc comment above; def_provider is now canonical too, so
                // this must match it on the same terms.
                injected_oauth.insert(resolve_provider_alias(&binding.provider).to_string());
                tracing::info!(
                    target: "identity",
                    "injected {} for oauth provider {} (identity={}, account={})",
                    config_dir_env_var,
                    binding.provider,
                    instance.identity_id,
                    binding.account_id,
                );

                // reagentx P1 on PR #2605: `dir` above is read from this
                // account's PREVIOUSLY STORED SecretRef::OAuthConfigDir —
                // this is the ordinary spawn path, not `auth.start`, which
                // is the only place that used to (re-)create the history
                // link. An account provisioned before this whole feature
                // shipped, or since its last `auth.start`, would otherwise
                // never get linked at all. Re-verify/re-create it on every
                // spawn instead, same best-effort, non-blocking guarantee
                // as the rest of this function.
                if let Some(paths) = agentmux_common::DataPaths::from_env() {
                    if let Some(provider_cfg) =
                        crate::backend::providers::get_provider(&resolve_provider_alias(&binding.provider))
                    {
                        crate::server::identity_auth_dirs::link_history_if_isolated(
                            &paths,
                            std::path::Path::new(&dir),
                            provider_cfg,
                            &binding.account_id,
                            "inject_identity_env (spawn)",
                        );
                    }
                }

                // Per spec §4.4 — cheap on-disk expiry probe. Reads the
                // CLI's token file inside the bundle dir and refines
                // the IdentityAccount's `status` so the UI can show
                // valid/expired/needs_reauth. Best-effort: probe and
                // upsert failures are logged + ignored (mirrors the
                // per-binding "log + skip" pattern). The probe runs at
                // every spawn but is a single `fs::read_to_string` +
                // JSON parse — negligible overhead.
                let now_ms = agentmux_common::time::now_ms();
                // Canonicalized (codex P2 on PR #2377): probe_oauth_status
                // only recognizes the canonical "claude"/"codex"/"openclaw"
                // strings — passing a raw alias like "claude-code" always
                // returned None, silently never refreshing an alias-bound
                // account's status or publishing identityaccounts:changed.
                let canonical_provider = resolve_provider_alias(&binding.provider);
                let probed = probe_oauth_status(canonical_provider, &dir, now_ms);
                // Self-heal a stale false-positive (Codex P1, PR #2645): the
                // macOS Keychain carve-out in oauth_probe.rs makes a missing
                // token file return `None` for `claude` on macOS instead of
                // `needs_reauth` — but an account probed BEFORE that
                // carve-out existed may already have `needs_reauth`
                // persisted from the old, buggy behavior. A `None` probe
                // never upserts anything, so without this, an already-
                // mislabeled account would stay stuck showing "reconnect"
                // forever, even though this fix landed specifically to stop
                // that. Correcting to "unknown" rather than "valid" — the
                // probe genuinely can't tell on macOS, and a false "valid"
                // would be exactly as dishonest as the "needs_reauth" this
                // is fixing. Scoped tightly to the exact carve-out
                // condition (not "any None"), so an unsupported provider's
                // genuinely-earned needs_reauth (set by some other path)
                // is never touched by this.
                let new_status: Option<&'static str> = match probed {
                    Some(p) => Some(p.as_str()),
                    None if canonical_provider == "claude"
                        && cfg!(target_os = "macos")
                        && account.status == oauth_status::NEEDS_REAUTH =>
                    {
                        Some("unknown")
                    }
                    None => None,
                };
                if let Some(new_status) = new_status {
                    if account.status != new_status {
                        let mut updated = account.clone();
                        updated.status = new_status.to_string();
                        updated.updated_at = now_ms;
                        // Write back to whichever store the account was
                        // actually resolved from (resolve_account above) —
                        // not always id_store, since a fallback-mirror hit
                        // must update the mirror, not silently create a
                        // second, never-read copy in id_store.
                        match account_store.identity_upsert(&updated) {
                            Ok(()) => {
                                tracing::info!(
                                    target: "identity",
                                    provider = %binding.provider,
                                    account_id = %binding.account_id,
                                    old_status = %account.status,
                                    new_status,
                                    "oauth probe: status updated"
                                );
                                // Publish accounts-changed so any live
                                // account list (Connectors → Accounts,
                                // launch modal) refreshes its Status
                                // column without a reload — the account
                                // row itself is what changed.
                                if let Some(b) = broker.as_ref() {
                                    b.publish_event::<crate::backend::mps_events::IdentityAccountsChanged>(&(), vec![], 0);
                                }
                            }
                            Err(e) => {
                                tracing::warn!(
                                    target: "identity",
                                    provider = %binding.provider,
                                    account_id = %binding.account_id,
                                    error = %e,
                                    "oauth probe: identity_upsert failed — status not persisted",
                                );
                            }
                        }
                    }
                }
            }
        }
    }

    // Step 5: definition-provider gate (spec §2.2 edge case). The agent's
    // own CLI provider is an oauth-class provider it is "supposed to have
    // credentials for" whether or not a binding row exists — an agent with
    // NO binding for it (never bound, or the link was cascaded away by an
    // account delete) must not silently launch on the user's global login.
    // Bindings that existed but failed were already gated inside the loop,
    // so this only fires for the genuinely-unbound case (no double logs).
    if let Some(p) = def_provider {
        if matches!(provider_class(&p), Some(ProviderClass::OAuth { .. }))
            && !injected_oauth.contains(&p)
            // Canonicalized (codex P1 on PR #2377): `b.provider` is the raw
            // DB value and may still be a legacy alias even though `p` is
            // canonical — without this, a binding that failed injection for
            // an unrelated reason (already gated above) would be
            // misclassified as "no binding at all" here whenever it's
            // stored under an alias.
            && !bindings.iter().any(|b| resolve_provider_alias(&b.provider) == p)
        {
            gate_oauth_failure(&p, "no account bound for the agent's provider")?;
        }
    }

    // #3577, re-checked at the gate's own exit: the instance resolved above,
    // but the agent can be deleted while this function reads its definition
    // and bindings — then `def_provider` is `None`, `bindings` is empty, and
    // the checks above pass vacuously (ReAgent P0 / Codex P1 on #3591). The
    // only caller, `build_persistent_spawn_env`, re-checks again at its own
    // last store read; this keeps the gate correct on its own.
    if mstore.agent_was_deleted(&instance.id) {
        return Err(SpawnGateError::AgentDeleted {
            agent_id: instance.id.clone(),
        });
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use super::super::oauth_probe::oauth_status;
    use crate::backend::storage::store::{
        AgentInstance, IdentityAccount, InstanceStatus, Bundle, SecretRef,
    };

    fn make_store() -> Arc<Store> {
        Arc::new(Store::open_in_memory().unwrap())
    }

    /// A store with a shared definition registry (in `tmp`) — the thing that
    /// remembers a deleted agent as a retired record.
    fn store_with_def_registry(tmp: &tempfile::TempDir) -> Arc<Store> {
        let store = make_store();
        let defs = crate::registry::DefinitionStore::open(tmp.path().join("definitions")).unwrap();
        store.set_def_registry(Arc::new(defs));
        store
    }

    /// #3577: a pane whose agent was deleted (row gone, registry record
    /// retired) is refused at the gate instead of spawning on the shared
    /// login with no identity.
    #[test]
    fn a_block_naming_a_deleted_agent_is_refused() {
        let tmp = tempfile::tempdir().unwrap();
        let store = store_with_def_registry(&tmp);
        let mut def = crate::backend::storage::agents::test_agent_def(
            "agent-deleted-3577",
            "Gone",
            "claude",
            "agent",
            1,
            "",
        );
        store.agent_def_insert(&mut def).unwrap();
        assert!(
            store
                .shared_def_registry()
                .unwrap()
                .exists("agent-deleted-3577"),
            "precondition: mirrored"
        );
        assert!(store.agent_def_delete("agent-deleted-3577").unwrap());
        insert_block_for_agent(&store, "block-deleted-3577", "agent-deleted-3577");

        let mut env = HashMap::new();
        let res = inject_identity_env_with_broker(
            store.clone(),
            store.clone(),
            store.clone(),
            None,
            "block-deleted-3577",
            &mut env,
        );
        assert_eq!(
            res,
            Err(SpawnGateError::AgentDeleted {
                agent_id: "agent-deleted-3577".to_string()
            })
        );
    }

    /// Only a positive "deleted" signal refuses. A block naming a template
    /// id (a template session, a quick-launch provider key), a live
    /// cross-channel agent (active registry record, no local row), or
    /// anything at all when there is no registry to ask, keeps today's
    /// ungated behaviour.
    #[test]
    fn a_row_less_block_not_naming_a_deleted_agent_is_not_refused() {
        let tmp = tempfile::tempdir().unwrap();
        let store = store_with_def_registry(&tmp);
        let mut tpl = crate::backend::storage::agents::test_agent_def(
            "claude", "Claude", "claude", "agent", 1, "",
        );
        tpl.is_seeded = 1;
        store.agent_def_insert(&mut tpl).unwrap();
        store
            .shared_def_registry()
            .unwrap()
            .upsert(&crate::registry::DefinitionRecord {
                schema_version: crate::registry::DEF_MAX_SUPPORTED_SCHEMA,
                data: crate::registry::DefinitionRecordV1 {
                    id: "agent-elsewhere-3577".to_string(),
                    name: "Elsewhere".to_string(),
                    provider: "claude".to_string(),
                    ..Default::default()
                },
            })
            .unwrap();
        insert_block_for_agent(&store, "block-template-3577", "claude");
        insert_block_for_agent(&store, "block-cross-3577", "agent-elsewhere-3577");
        insert_block_for_agent(&store, "block-unknown-3577", "never-existed");
        for block in [
            "block-template-3577",
            "block-cross-3577",
            "block-unknown-3577",
        ] {
            let mut env = HashMap::new();
            let res = inject_identity_env_with_broker(
                store.clone(),
                store.clone(),
                store.clone(),
                None,
                block,
                &mut env,
            );
            assert_eq!(res, Ok(()), "{block}");
        }

        // No registry at all: a deleted agent cannot be told apart, so the
        // gate stays open rather than guessing.
        let bare = make_store();
        insert_block_for_agent(&bare, "block-bare-3577", "agent-deleted-anywhere");
        let mut env = HashMap::new();
        assert_eq!(
            inject_identity_env_with_broker(
                bare.clone(),
                bare.clone(),
                bare.clone(),
                None,
                "block-bare-3577",
                &mut env
            ),
            Ok(())
        );
    }

    fn make_account(
        id: &str,
        provider: &str,
        secret_ref: SecretRef,
    ) -> IdentityAccount {
        IdentityAccount {
            id: id.to_string(),
            name: format!("{}-{}", provider, id),
            provider: provider.to_string(),
            kind: "pat".to_string(),
            display_name: String::new(),
            secret_ref,
            context: serde_json::json!({}),
            status: "unknown".to_string(),
            created_at: 0,
            updated_at: 0,
        }
    }

    /// Insert a Block row whose `meta.agentId` points at the agent
    /// def. Phase 3b.4 made `instance_get_active_for_block` resolve
    /// via the block→agent reference (instead of filtering instance
    /// rows by status), so every resolver test that exercises the
    /// inject path needs a real block in the store.
    fn insert_block_for_agent(store: &Store, block_id: &str, agent_id: &str) {
        use crate::backend::obj::{Block, MetaMapType};
        let mut block = Block {
            oid: block_id.to_string(),
            parentoref: String::new(),
            version: 0,
            runtimeopts: None,
            stickers: None,
            meta: {
                let mut m = MetaMapType::new();
                m.insert("view".to_string(), serde_json::json!("agent"));
                m.insert("agentId".to_string(), serde_json::json!(agent_id));
                m
            },
            subblockids: None,
        };
        store.insert(&mut block).unwrap();
    }

    /// A genuinely writable temp path for a test's `SecretRef::OAuthConfigDir`.
    ///
    /// `inject_identity_env` now really seeds a `CLAUDE.md` into the bound dir
    /// and FAILS CLOSED if it can't (SPEC_ISOLATE_HOST_CLAUDE_MD_2026_08_31.md),
    /// so these tests need a dir that actually exists/can be created rather
    /// than a synthetic absolute path. The previous `/var/agentmux/...`
    /// literals were unwritable on Linux CI (`Permission denied`) while
    /// silently resolving to the current drive on Windows — green locally,
    /// red on the ubuntu leg.
    fn test_config_dir(name: &str) -> String {
        std::env::temp_dir()
            .join(format!("agentmux-inject-test-{}-{name}", std::process::id()))
            .to_string_lossy()
            .into_owned()
    }

    fn make_instance(block_id: &str, identity_id: &str) -> AgentInstance {
        AgentInstance {
            id: format!("inst-{block_id}"),
            definition_id: "def-1".to_string(),
            parent_instance_id: String::new(),
            block_id: block_id.to_string(),
            session_id: String::new(),
            status: InstanceStatus::Running.as_str().to_string(),
            github_context: String::new(),
            started_at: 0,
            ended_at: 0,
            created_at: 0,
            identity_id: identity_id.to_string(),
            memory_id: String::new(),
            instance_name: String::new(),
            working_directory: String::new(),
            display_hidden: false,
        }
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_sets_config_dir_env_var() {
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-claude",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-oauth"),
            },
        );
        store.identity_upsert(&claude).unwrap();
        store
            .agent_identity_link("def-1", "acct-claude", "claude")
            .unwrap();

        insert_block_for_agent(&store, "block-oauth", "def-1");
        let inst = make_instance("block-oauth", "id-oauth");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        // Spec §2.5 regression: a resolvable oauth account injects
        // unchanged — the layer-3 gate never fires.
        inject_identity_env(store.clone(), store.clone(), store, "block-oauth", &mut env).unwrap();

        // OAuth dispatch sets the provider's config-dir env var.
        assert_eq!(
            env.get("CLAUDE_CONFIG_DIR").cloned(),
            Some(test_config_dir("id-oauth")),
        );
        // And does NOT set the anthropic api-key env var — dispatch
        // is by provider class, not by token shape.
        assert!(env.get("ANTHROPIC_API_KEY").is_none());
    }

    /// docs/specs/SPEC_BLOCK_AMBIENT_HOME_DIR_IDENTITY_BINDING_2026_08_25.md —
    /// the enforcement that closes the real, currently-live gap found in
    /// docs/status/STATUS_IDENTITY_ISOLATION_GATE_NOT_ENFORCING_2026_08_20.md
    /// §8 (an account whose `secret_ref.dir` was the literal ambient home).
    /// Uses the REAL `get_home_dir()` (not a mock) so this exercises the
    /// exact same resolution production code does — deterministic
    /// regardless of whether `~/.claude` actually exists on the test
    /// machine, since `paths_resolve_to_same_dir`'s lexical fallback
    /// handles "doesn't exist" and its canonicalize branch handles
    /// "exists" identically correctly (see providers.rs's own tests).
    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_blocks_spawn_when_config_dir_is_the_ambient_home() {
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let ambient_claude_dir = crate::backend::base::get_home_dir()
            .join(".claude")
            .to_string_lossy()
            .into_owned();
        let claude = make_account(
            "acct-ambient",
            "claude",
            SecretRef::OAuthConfigDir { dir: ambient_claude_dir.clone() },
        );
        store.identity_upsert(&claude).unwrap();
        store
            .agent_identity_link("def-1", "acct-ambient", "claude")
            .unwrap();

        insert_block_for_agent(&store, "block-ambient", "def-1");
        let inst = make_instance("block-ambient", "id-ambient");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let err = inject_identity_env(store.clone(), store.clone(), store, "block-ambient", &mut env)
            .expect_err("spawn must be refused when the bound account's config dir is the ambient home");

        match err {
            SpawnGateError::AmbientHomeDirNotAllowed { provider, dir } => {
                assert_eq!(provider, "claude");
                assert_eq!(dir, ambient_claude_dir);
            }
            other => panic!("expected AmbientHomeDirNotAllowed, got {other:?}"),
        }
        // The gate must block BEFORE anything is injected — no partial
        // env-var leak from the refused binding.
        assert!(env.get("CLAUDE_CONFIG_DIR").is_none());
    }

    /// Codex P1 + ReAgent P1 on PR #2854: seeding the CLAUDE.md isolation
    /// placeholder must fail closed, not warn-and-continue — otherwise the
    /// agent spawns with a CLAUDE_CONFIG_DIR that still has no CLAUDE.md,
    /// exactly the condition that falls through to the ambient home. An
    /// empty `dir` (rejected by seed_claude_md_placeholder_if_missing's own
    /// InvalidInput guard) is a deterministic, cross-platform way to
    /// trigger a seed failure without relying on real filesystem
    /// permissions. It is also NOT the ambient home, so this exercises the
    /// seed check specifically, not the AmbientHomeDirNotAllowed path
    /// covered by the test above.
    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_blocks_spawn_when_claude_md_seed_fails() {
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-empty-dir",
            "claude",
            SecretRef::OAuthConfigDir { dir: String::new() },
        );
        store.identity_upsert(&claude).unwrap();
        store
            .agent_identity_link("def-1", "acct-empty-dir", "claude")
            .unwrap();

        insert_block_for_agent(&store, "block-empty-dir", "def-1");
        let inst = make_instance("block-empty-dir", "id-empty-dir");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let err = inject_identity_env(store.clone(), store.clone(), store, "block-empty-dir", &mut env)
            .expect_err("spawn must be refused when the CLAUDE.md isolation seed fails");

        match err {
            SpawnGateError::ClaudeMdSeedFailed { provider, dir, .. } => {
                assert_eq!(provider, "claude");
                assert_eq!(dir, "");
            }
            other => panic!("expected ClaudeMdSeedFailed, got {other:?}"),
        }
        // The gate must block BEFORE anything is injected — no partial
        // env-var leak from the refused binding.
        assert!(env.get("CLAUDE_CONFIG_DIR").is_none());
    }

    /// **Behavior deliberately REVERSED 2026-08-31 (operator instruction).**
    ///
    /// This test previously asserted the opposite: that a spawn MUST succeed
    /// by falling back to the global mirror when the per-channel `id_store`
    /// lacks the account (reagentx P0 on PR #2632, protecting binding
    /// continuity across a version/channel switch).
    ///
    /// Per-channel isolation is a wanted feature, and that fallback is exactly
    /// what let an agent in a fresh channel launch against another channel's
    /// credential with no account of its own. The operator's requirement:
    ///
    /// > "we want per-channel isolation. a user needs a login anytime in the
    /// > channel."
    ///
    /// So the same scenario must now BLOCK, surfacing the ordinary
    /// `MissingCredentials` auth card, and the user logs in for this channel.
    /// The old continuity guarantee is intentionally given up here; the
    /// fallback survives only for read-only/display callers.
    /// See `docs/analysis/ANALYSIS_PER_CHANNEL_AUTH_BYPASSES_2026_08_31.md`.
    #[cfg(debug_assertions)]
    #[test]
    fn inject_refuses_an_account_that_only_exists_in_the_global_mirror() {
        let mstore = make_store();
        // Deliberately EMPTY of the account and link — simulates a fresh,
        // isolated per-channel id_store on a new channel/version.
        let id_store = make_store();
        // Real identity-store schema (no account_id/agent_id FK, matching
        // production's Store::open_identity_store — NOT open_in_memory's
        // channel schema, which still has both FKs and would reject this
        // link since "def-1" only exists in mstore's own definitions
        // table, a different physical store). Simulates the post-migration
        // state: both the link AND the account mirror row live here,
        // exactly what m0022_identity_store_links_backfill produces.
        let identity_store_tmp = tempfile::NamedTempFile::new().unwrap();
        let identity_store = Arc::new(Store::open_identity_store(identity_store_tmp.path()).unwrap());

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        mstore.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-migrated",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-migrated"),
            },
        );
        identity_store.identity_upsert(&claude).unwrap();
        identity_store
            .agent_identity_link("def-1", "acct-migrated", "claude")
            .unwrap();

        insert_block_for_agent(&mstore, "block-continuing", "def-1");
        let inst = make_instance("block-continuing", "id-continuing");
        mstore.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(mstore, id_store, identity_store, "block-continuing", &mut env);

        assert!(
            matches!(res, Err(SpawnGateError::MissingCredentials { .. })),
            "an account that exists ONLY in the global mirror must NOT satisfy a spawn in \
             this channel — that is the per-channel-isolation bypass; expected \
             MissingCredentials, got {res:?}"
        );
        assert!(
            env.get("CLAUDE_CONFIG_DIR").is_none(),
            "nothing may be injected from a refused cross-channel account"
        );
    }

    /// **Behavior deliberately REVERSED 2026-08-31 (operator instruction)** —
    /// companion to the test above, closing the same bypass from the other
    /// direction.
    ///
    /// Originally reagentx round-3 P0 on PR #2632: it proved that an account
    /// written through `identity_upsert_with_mirror` (every live write path —
    /// `identity.account.upsert`, OAuth persist) still resolved after a
    /// channel switch, not just migration-backfilled ones.
    ///
    /// That is now precisely the wrong outcome: it made the bypass apply to
    /// *newly created* accounts too, so every fresh channel silently inherited
    /// the last one's credential. The dual-write itself is retained (display
    /// callers still use `resolve_account`'s fallback to describe an account);
    /// what changed is that a mirror row can no longer authorize a SPAWN.
    #[cfg(debug_assertions)]
    #[test]
    fn inject_refuses_a_mirror_written_account_after_a_channel_switch() {
        let mstore = make_store();
        let id_store = make_store();
        let identity_store_tmp = tempfile::NamedTempFile::new().unwrap();
        let identity_store = Arc::new(Store::open_identity_store(identity_store_tmp.path()).unwrap());

        // `make_instance` below hardcodes `definition_id: "def-1"` — match it
        // rather than parameterizing a helper shared with other tests.
        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        mstore.agent_def_insert(&mut def).unwrap();

        // "Before the channel switch": the account is created live, via the
        // same helper `identity.account.upsert`/OAuth persist use — writing
        // to id_store (the then-current, then-primary store) AND dual-
        // writing the mirror into identity_store.
        let claude = make_account(
            "acct-fresh",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-fresh"),
            },
        );
        id_store.identity_upsert_with_mirror(&identity_store, &claude).unwrap();
        identity_store
            .agent_identity_link("def-1", "acct-fresh", "claude")
            .unwrap();

        insert_block_for_agent(&mstore, "block-fresh", "def-1");
        let inst = make_instance("block-fresh", "id-fresh");
        mstore.instance_create(&inst).unwrap();

        // "After the channel switch": a brand-new, empty id_store — the
        // account row created above must be unreachable here, exactly like
        // a fresh per-channel-isolated store on a new channel.
        let id_store_after_switch = make_store();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(mstore, id_store_after_switch, identity_store, "block-fresh", &mut env);

        assert!(
            matches!(res, Err(SpawnGateError::MissingCredentials { .. })),
            "REVERSED 2026-08-31: a mirror row must no longer carry a spawn across a channel \
             switch, however it was written — dual-writing the mirror is not a substitute for \
             logging in on this channel; expected MissingCredentials, got {res:?}"
        );
        assert!(env.get("CLAUDE_CONFIG_DIR").is_none());
    }

    // reagentx P1 on PR #2605: this is the ordinary spawn path (not
    // `auth.start`) — it reads a PREVIOUSLY STORED OAuthConfigDir, which
    // is exactly the case an account provisioned before the history-link
    // feature existed (or since its last `auth.start`) is in. Proves the
    // link now gets (re-)created here too, not only at auth.start.
    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_links_conversation_history_on_the_ordinary_spawn_path() {
        let _lock = crate::test_support::ISOLATED_AUTH_ENV_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());
        let tmp = tempfile::TempDir::new().unwrap();
        std::env::set_var("AGENTMUX_HOME_OVERRIDE", tmp.path());
        std::env::set_var("AGENTMUX_ISOLATED_AUTH", "1");
        let paths = agentmux_common::DataPaths::resolve(
            "0.0.0-test",
            &agentmux_common::RuntimeMode::Installed,
        )
        .unwrap();
        paths.ensure_dirs().unwrap();
        for (k, v) in paths.to_env_vars() {
            std::env::set_var(k, v);
        }

        // A credential dir that ALREADY exists on disk, under the isolated
        // (per-channel) tree, with real pre-existing history in it — the
        // account was provisioned (auth.start ran) before this test's
        // spawn-time call, exactly like a real already-connected account.
        let isolated_dir = paths.instance_dir.join("identities").join("acct-claude").join("claude");
        std::fs::create_dir_all(isolated_dir.join("projects")).unwrap();
        std::fs::write(
            isolated_dir.join("projects").join("existing-session.jsonl"),
            b"pre-existing history",
        )
        .unwrap();

        let store = make_store();
        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-claude",
            "claude",
            SecretRef::OAuthConfigDir { dir: isolated_dir.to_string_lossy().to_string() },
        );
        store.identity_upsert(&claude).unwrap();
        store.agent_identity_link("def-1", "acct-claude", "claude").unwrap();
        insert_block_for_agent(&store, "block-oauth-history", "def-1");
        let inst = make_instance("block-oauth-history", "id-oauth");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-oauth-history", &mut env).unwrap();

        let global_history = paths.identity_history_dir("acct-claude", "claude", "projects");
        let via_link = std::fs::read(global_history.join("existing-session.jsonl"))
            .expect("pre-existing history must have been migrated to the global location by the spawn-time link");
        assert_eq!(via_link, b"pre-existing history");

        std::env::remove_var("AGENTMUX_HOME_OVERRIDE");
        std::env::remove_var("AGENTMUX_ISOLATED_AUTH");
        for (k, _) in paths.to_env_vars() {
            std::env::remove_var(k);
        }
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_blocks_account_with_non_oauth_secret_ref() {
        // An oauth-class provider (claude) bound to an account whose
        // SecretRef is the API-key shape (Env) is a misconfiguration:
        // the account is unresolvable for the provider, so the layer-3
        // gate blocks the spawn instead of
        // mis-injecting the wrong secret or silently launching on the
        // user's global login.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let bad = make_account(
            "acct-bad",
            "claude",
            SecretRef::Env {
                env_var: "CLAUDE_TOKEN_NOT_A_DIR".to_string(),
            },
        );
        store.identity_upsert(&bad).unwrap();
        store
            .agent_identity_link("def-1", "acct-bad", "claude")
            .unwrap();

        insert_block_for_agent(&store, "block-bad", "def-1");
        let inst = make_instance("block-bad", "id-bad");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-bad", &mut env);

        // Blocking spawn-gate error — and nothing injected.
        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
        );
        assert!(env.get("CLAUDE_CONFIG_DIR").is_none());
        assert!(env.is_empty());
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_succeeds_when_the_only_binding_is_under_a_legacy_alias() {
        // codex P1 on PR #2377: a definition's own `provider` is canonical
        // ("claude"), but its only db_agent_identity_links row is still
        // under a legacy alias ("claude-code") — carried forward from
        // before providers.rs's alias table existed, or a definition/link
        // pair that otherwise drifted. The binding injects successfully
        // (provider_class already resolves aliases), but before this fix
        // the def-provider gate compared the raw `injected_oauth`/binding
        // provider strings against the canonical def_provider and treated
        // the alias-bound account as "no account bound at all" — blocking
        // a spawn that had already successfully injected valid credentials
        // moments earlier in the same function.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-alias",
            "claude-code",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-alias"),
            },
        );
        store.identity_upsert(&claude).unwrap();
        // Bound under the alias, not the canonical "claude".
        store
            .agent_identity_link("def-1", "acct-alias", "claude-code")
            .unwrap();

        insert_block_for_agent(&store, "block-alias", "def-1");
        let inst = make_instance("block-alias", "id-alias");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-alias", &mut env);

        assert!(res.is_ok(), "expected Ok, got {res:?}");
        assert_eq!(
            env.get("CLAUDE_CONFIG_DIR").cloned(),
            Some(test_config_dir("id-alias")),
        );
    }

    // ── Layer 3 — spawn gating (SPEC_ACCOUNT_DELETE_DEAUTH_LAYERS_2_4
    //    _2026_07_14.md §2.2/§2.5) ────────────────────────────────────

    /// Fixture def for the gating tests — oauth-class CLI provider
    /// (claude). `use_ambient_login` is settable only to prove it is inert.
    fn gate_def(use_ambient_login: i64) -> crate::backend::storage::store::AgentDefinition {
        crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        }
    }

    /// Delete an account row while KEEPING its link — the post-delete
    /// shape on a legacy DB (analysis §2.4: real installs got the links
    /// table via ALTER RENAME with no FK cascade clause, so orphan links
    /// are real). FKs are toggled off for the surgical delete so the
    /// test store's DDL-level cascade doesn't fire.
    fn delete_account_row_keep_link(store: &Store, account_id: &str) {
        let conn = store.conn().lock().unwrap();
        conn.execute_batch(&format!(
            "PRAGMA foreign_keys=OFF;
             DELETE FROM db_accounts WHERE id = '{account_id}';
             PRAGMA foreign_keys=ON;"
        ))
        .unwrap();
    }

    #[test]
    fn spawn_blocked_when_bound_oauth_account_missing_and_flag_false() {
        // Spec §2.5 test 1: binding → missing account → flag false →
        // spawn-assembly returns the blocking error (not a skip).
        let store = make_store();
        let mut def = gate_def(0);
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-gone",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-x"),
            },
        );
        store.identity_upsert(&claude).unwrap();
        store
            .agent_identity_link("def-1", "acct-gone", "claude")
            .unwrap();
        // Delete the account row out from under the link — the exact
        // post-`deleteidentityaccount` shape the resolver used to
        // log-and-skip ("row not found — skipping", analysis §2.3).
        delete_account_row_keep_link(&store, "acct-gone");

        insert_block_for_agent(&store, "block-gate-1", "def-1");
        let inst = make_instance("block-gate-1", "id-x");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-gate-1", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
        );
        // Nothing was injected — the CLI process must never be created.
        assert!(env.is_empty());
        // The error's Display is the user-facing pane message (spec §2.2
        // wording) — pin the load-bearing pieces.
        let msg = res.unwrap_err().to_string();
        assert!(msg.contains("no credentials for claude"), "got: {msg}");
        assert!(msg.contains("Bind an account for this provider in Connectors → Accounts"), "got: {msg}");
    }

    #[test]
    fn spawn_still_blocked_when_bound_oauth_account_missing_and_flag_true() {
        // Was spawn_proceeds_ambient_when_bound_oauth_account_missing_and_flag_true
        // — the ambient opt-in it exercised is retired
        // (PLAN_LOGIN_SINGLE_PATH_CONSOLIDATION_2026_07_20.md §7). A missing
        // account now blocks the spawn unconditionally; `use_ambient_login`
        // no longer changes the outcome. This test pins that the flag is
        // truly inert, not just untested.
        let store = make_store();
        let mut def = gate_def(1);
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-gone-2",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-y"),
            },
        );
        store.identity_upsert(&claude).unwrap();
        store
            .agent_identity_link("def-1", "acct-gone-2", "claude")
            .unwrap();
        delete_account_row_keep_link(&store, "acct-gone-2");

        insert_block_for_agent(&store, "block-gate-2", "def-1");
        let inst = make_instance("block-gate-2", "id-y");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-gate-2", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
        );
        assert!(env.is_empty());
    }

    #[test]
    fn spawn_blocked_when_oauth_def_provider_has_no_binding_and_flag_false() {
        // Spec §2.2 edge case: an agent whose oauth-class CLI provider has
        // NO binding at all (never bound, or the link was cascaded away by
        // an account delete) is blocked without the opt-in — implicit
        // ambient is how the delete-doesn't-deauthenticate gap happened.
        // (The m0017 migration grandfathers pre-existing linkless agents
        // to flag=1; `inject_no_direct_links_injects_nothing` covers that
        // side.)
        //
        // THIS TEST IS THE INV-A REGRESSION CANARY
        // (`docs/retro/retro-auth-isolation-invariant-silently-orphaned-2026-07-14.md`):
        // a completely unconfigured agent (zero bindings, default flag)
        // is the exact shape that used to fall through to the user's
        // global `~/.claude` before commit `e5ab2d09` orphaned the
        // isolated-auto-provision path. If a future refactor makes this
        // assert start failing (env no longer empty, or `res` becomes
        // `Ok`), read that retro before "fixing" the test — the failure
        // is very likely the invariant regressing a second time, not the
        // test being wrong.
        let store = make_store();
        let mut def = gate_def(0);
        store.agent_def_insert(&mut def).unwrap();

        insert_block_for_agent(&store, "block-gate-3", "def-1");
        let inst = make_instance("block-gate-3", "id-z");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-gate-3", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
        );
        assert!(env.is_empty());
    }

    /// Regression guard for the definition flip (agent-concept
    /// consolidation, `SPEC_AGENT_ARCHITECTURE_2026_05_27.md` Phase 3d).
    ///
    /// `agent_def_get(&instance.definition_id)` used to be scoped to
    /// `db_agent_definitions` and 404 for ANY template launch, since a
    /// launch's own row lives only in `db_agents` with no legacy
    /// counterpart. `def_provider` (Step 2, above) was therefore always
    /// `None` for a template launch — and Step 5's definition-provider gate
    /// (`if let Some(p) = def_provider { ... }`) is a no-op when
    /// `def_provider` is `None`. So a template-launched agent whose CLI
    /// provider is oauth-class, with genuinely ZERO identity binding, was
    /// launching WITHOUT ever being checked by the one gate that exists
    /// specifically to block exactly that — the definition flip closes
    /// this by letting `agent_def_get` resolve the launch's own row, so
    /// `def_provider` is `Some("claude")` and Step 5 applies to it like any
    /// other agent. (`use_ambient_login` is confirmed inert for this gate
    /// either way, per `gate_oauth_failure`'s own doc comment and
    /// `spawn_still_blocked_when_bound_oauth_account_missing_and_flag_true`
    /// above — this test does not depend on it and sets it to demonstrate
    /// that non-effect explicitly.)
    ///
    /// This template genuinely has NO identity link either — the sibling
    /// test `spawn_proceeds_when_a_template_launch_inherits_the_templates_
    /// own_identity_link` covers the case that made enabling Step 5 for
    /// launches unsafe on its own (codex P1 on #3092): a template WITH a
    /// real bound account must still let its launches spawn.
    #[test]
    fn spawn_is_gated_for_a_template_launch_with_no_binding_where_it_used_to_be_invisible_to_the_gate() {
        let store = make_store();
        let mut tpl = gate_def(1); // use_ambient_login=1 — must NOT matter, see doc comment.
        tpl.id = "tpl-ambient".to_string();
        tpl.is_seeded = 1;
        store.agent_def_insert(&mut tpl).unwrap();

        // A launch of the template: `is_seeded = 1` means `instance_create`
        // creates a NEW row keyed by the launch id, not the template's —
        // exactly the shape that used to be invisible to `agent_def_get`.
        let inst = crate::backend::storage::store::AgentInstance {
            id: "launch-ambient".to_string(),
            definition_id: "tpl-ambient".to_string(),
            parent_instance_id: String::new(),
            block_id: "block-gate-ambient".to_string(),
            session_id: String::new(),
            status: InstanceStatus::Running.as_str().to_string(),
            github_context: String::new(),
            started_at: 0,
            ended_at: 0,
            created_at: 0,
            identity_id: "id-ambient".to_string(),
            memory_id: String::new(),
            instance_name: String::new(),
            working_directory: String::new(),
            display_hidden: false,
        };
        let canonical = store.instance_create(&inst).unwrap();
        assert_eq!(canonical.id, "launch-ambient", "sanity: a template launch creates its own row");

        insert_block_for_agent(&store, "block-gate-ambient", "launch-ambient");

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-gate-ambient", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
            "a template launch's zero-binding oauth-class provider must now reach Step 5's gate, not skip it",
        );
        assert!(env.is_empty());
    }

    /// Codex P1 on #3092: enabling Step 5 for launch rows (the previous
    /// test) would have converted every LEGITIMATELY-configured template
    /// launch into a hard spawn failure, without this fallback. Binding an
    /// identity to a template — the Agent Setup modal's supported target —
    /// has always written the link under the TEMPLATE's id; nothing writes
    /// a launch-scoped link. `resolve_bindings_for_instance` now falls back
    /// to the template's own links when the launch has none of its own, so
    /// a template's real binding still resolves (and injects) once launched.
    #[test]
    fn spawn_proceeds_when_a_template_launch_inherits_the_templates_own_identity_link() {
        let store = make_store();
        let mut tpl = gate_def(0);
        tpl.id = "tpl-bound".to_string();
        tpl.is_seeded = 1;
        store.agent_def_insert(&mut tpl).unwrap();

        let claude = make_account(
            "acct-tpl",
            "claude",
            SecretRef::OAuthConfigDir { dir: test_config_dir("id-tpl-bound") },
        );
        store.identity_upsert(&claude).unwrap();
        // The link is bound to the TEMPLATE's own id, exactly as the Agent
        // Setup modal does today — never the launch's.
        store.agent_identity_link("tpl-bound", "acct-tpl", "claude").unwrap();

        let inst = crate::backend::storage::store::AgentInstance {
            id: "launch-bound".to_string(),
            definition_id: "tpl-bound".to_string(),
            parent_instance_id: String::new(),
            block_id: "block-gate-bound".to_string(),
            session_id: String::new(),
            status: InstanceStatus::Running.as_str().to_string(),
            github_context: String::new(),
            started_at: 0,
            ended_at: 0,
            created_at: 0,
            identity_id: "id-tpl-bound".to_string(),
            memory_id: String::new(),
            instance_name: String::new(),
            working_directory: String::new(),
            display_hidden: false,
        };
        let canonical = store.instance_create(&inst).unwrap();
        assert_eq!(canonical.id, "launch-bound", "sanity: a template launch creates its own row");
        // Sanity: the launch's own row genuinely has no direct link — any
        // pass here must come from the template fallback, not a stray
        // direct one.
        assert!(store.agent_identity_list_for_agent("launch-bound").unwrap().is_empty());

        insert_block_for_agent(&store, "block-gate-bound", "launch-bound");

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-gate-bound", &mut env);

        assert_eq!(res, Ok(()), "a template's own real binding must still let its launches spawn");
        assert_eq!(
            env.get("CLAUDE_CONFIG_DIR").map(String::as_str),
            Some(test_config_dir("id-tpl-bound").as_str()),
            "the template's bound config dir must actually be injected, not just pass the gate",
        );
    }

    /// reagent P0 on #3092: `db_agents.parent_template_id` is NOT
    /// exclusively "which template was I launched from" —
    /// `forkagentdefinition` (`template.rs`) reuses the same column to
    /// record a plain agent fork's SOURCE agent id, `is_seeded = 0`. An
    /// earlier version of the template-link fallback above trusted the
    /// column unconditionally: a fork of ANY regular agent with a bound
    /// identity would silently inherit and spawn on the SOURCE agent's
    /// credentials, even though forks are deliberately created with
    /// `accounts: ""` and no link of their own — a credential-scope leak
    /// across agents. `template_parent_id_if_seeded` closes this by only
    /// falling back when the parent actually has `is_seeded = 1`.
    #[test]
    fn a_fork_of_a_regular_agent_does_not_inherit_the_sources_identity_link() {
        let store = make_store();
        let mut source = gate_def(0);
        source.id = "agent-source".to_string();
        source.is_seeded = 0; // a regular agent, NOT a template
        store.agent_def_insert(&mut source).unwrap();

        let claude = make_account(
            "acct-source",
            "claude",
            SecretRef::OAuthConfigDir { dir: test_config_dir("id-source-only") },
        );
        store.identity_upsert(&claude).unwrap();
        store.agent_identity_link("agent-source", "acct-source", "claude").unwrap();

        // Mirrors forkagentdefinition's actual shape (template.rs): a
        // plain, non-template fork with parent_id = the source's id,
        // accounts reset to empty, and — critically — no identity link of
        // its own (fail-closed by design).
        let mut fork = gate_def(0);
        fork.id = "agent-fork".to_string();
        fork.is_seeded = 0;
        fork.parent_id = "agent-source".to_string();
        fork.accounts = String::new();
        store.agent_def_insert(&mut fork).unwrap();

        let inst = crate::backend::storage::store::AgentInstance {
            id: "agent-fork".to_string(),
            definition_id: "agent-fork".to_string(),
            parent_instance_id: String::new(),
            block_id: "block-gate-fork".to_string(),
            session_id: String::new(),
            status: InstanceStatus::Running.as_str().to_string(),
            github_context: String::new(),
            started_at: 0,
            ended_at: 0,
            created_at: 0,
            identity_id: "id-fork".to_string(),
            memory_id: String::new(),
            instance_name: String::new(),
            working_directory: String::new(),
            display_hidden: false,
        };
        let canonical = store.instance_create(&inst).unwrap();
        assert_eq!(canonical.id, "agent-fork", "sanity: a fork of a non-template agent folds into its own row");
        assert!(store.agent_identity_list_for_agent("agent-fork").unwrap().is_empty(), "sanity: the fork has no link of its own");

        insert_block_for_agent(&store, "block-gate-fork", "agent-fork");

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-gate-fork", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
            "a fork must NOT silently inherit and spawn on its source agent's credentials",
        );
        assert!(env.is_empty(), "nothing must be injected — especially not the source's config dir");
    }

    #[test]
    fn inject_no_instance_does_nothing() {
        let store = make_store();
        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-no-instance", &mut env).unwrap();
        assert!(env.is_empty());
    }

    #[test]
    fn inject_blank_identity_is_gated_same_as_any_other_unresolvable_identity() {
        // #2463 Finding 2: this test used to assert the OPPOSITE — that a
        // blank identity_id was NOT gated by layer 3 and silently fell
        // back to ambient creds even with use_ambient_login=0. That let a
        // brand-new agent launch with no account selected spawn on
        // whatever ambient credential happened to be on disk, with
        // nothing bound in Connectors — observably different behavior on two
        // machines running the identical code, purely as a function of
        // which one had a stray credential file. A blank/empty
        // identity_id must be gated exactly like any other unresolvable
        // one (see `spawn_blocked_when_oauth_def_provider_has_no_binding_
        // and_flag_false`, the non-blank equivalent of this test).
        let store = make_store();
        let mut def = gate_def(0);
        store.agent_def_insert(&mut def).unwrap();

        insert_block_for_agent(&store, "block-blank", "def-1");
        let inst = make_instance("block-blank", "blank");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-blank", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
        );
        assert!(env.is_empty());
    }

    #[test]
    fn inject_empty_identity_is_gated_same_as_blank() {
        // Same as the blank case above, but the genuinely-empty string —
        // what a real brand-new-agent launch with no account selected
        // actually produces (#2463 Finding 2's exact repro), as opposed to
        // the legacy "blank" singleton literal.
        let store = make_store();
        let mut def = gate_def(0);
        store.agent_def_insert(&mut def).unwrap();

        insert_block_for_agent(&store, "block-empty", "def-1");
        let inst = make_instance("block-empty", "");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(store.clone(), store.clone(), store, "block-empty", &mut env);

        assert_eq!(
            res,
            Err(SpawnGateError::MissingCredentials { provider: "claude".to_string() }),
        );
        assert!(env.is_empty());
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_full_round_trip_plaintext_dev() {
        let store = make_store();

        // Agent definition.
        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Not oauth-class — the layer-3 gate only applies to providers
            // `provider_class` classifies as OAuth-class (claude / codex /
            // openclaw / gemini / copilot as of
            // REPORT_AUTH_ARCHITECTURE_STATE_AND_RETHINK_2026_07_21.md
            // §2.5/§6), so a non-oauth def here keeps this test focused on
            // the api-key round trip below without a claude account fixture
            // it doesn't otherwise need.
            provider: "kimi".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        // GitHub account (PlaintextDev for test simplicity).
        let github = make_account(
            "acct-gh",
            "github",
            SecretRef::PlaintextDev {
                plaintext_dev: "ghp_round_trip".to_string(),
            },
        );
        store.identity_upsert(&github).unwrap();
        store
            .agent_identity_link("def-1", "acct-gh", "github")
            .unwrap();

        // Anthropic account.
        let anthropic = make_account(
            "acct-anth",
            "anthropic",
            SecretRef::PlaintextDev {
                plaintext_dev: "sk-ant-round_trip".to_string(),
            },
        );
        store.identity_upsert(&anthropic).unwrap();
        store
            .agent_identity_link("def-1", "acct-anth", "anthropic")
            .unwrap();

        // Instance for the block, pointing at id-work.
        insert_block_for_agent(&store, "block-1", "def-1");
        let inst = make_instance("block-1", "id-work");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-1", &mut env).unwrap();

        // GitHub writes both standard env-var names from one secret.
        assert_eq!(env.get("GITHUB_TOKEN").map(String::as_str), Some("ghp_round_trip"));
        assert_eq!(env.get("GH_TOKEN").map(String::as_str), Some("ghp_round_trip"));
        // Anthropic writes its single env var.
        assert_eq!(
            env.get("ANTHROPIC_API_KEY").map(String::as_str),
            Some("sk-ant-round_trip"),
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_via_direct_link_round_trip() {
        // A DIRECT agent<->account link resolves and injects the
        // account's env vars. Mirrors `inject_full_round_trip_plaintext_dev`.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Not oauth-class (§4.3) — see the identical note in
            // inject_full_round_trip_plaintext_dev above.
            provider: "kimi".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let github = make_account(
            "acct-gh",
            "github",
            SecretRef::PlaintextDev {
                plaintext_dev: "ghp_direct".to_string(),
            },
        );
        store.identity_upsert(&github).unwrap();
        store
            .agent_identity_link("def-1", "acct-gh", "github")
            .unwrap();

        insert_block_for_agent(&store, "block-direct", "def-1");
        let inst = make_instance("block-direct", "id-direct");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-direct", &mut env).unwrap();

        assert_eq!(env.get("GITHUB_TOKEN").map(String::as_str), Some("ghp_direct"));
        assert_eq!(env.get("GH_TOKEN").map(String::as_str), Some("ghp_direct"));
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_no_direct_links_injects_nothing() {
        // An instance with a non-sentinel identity_id but no
        // db_agent_identity_links row for its definition — e.g. an
        // account exists but was never linked — injects nothing.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Not oauth-class (§4.3) — this test targets the zero-direct-
            // links path itself, which is a distinct concern from the
            // layer-3 oauth gate (covered separately by the spawn_blocked_*
            // tests below).
            provider: "kimi".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let github = make_account(
            "acct-unlinked",
            "github",
            SecretRef::PlaintextDev {
                plaintext_dev: "ghp_unlinked".to_string(),
            },
        );
        store.identity_upsert(&github).unwrap();

        insert_block_for_agent(&store, "block-unlinked", "def-1");
        let inst = make_instance("block-unlinked", "id-unused");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-unlinked", &mut env).unwrap();

        // Nothing injected — an account with no direct link is invisible
        // to the resolver.
        assert!(env.get("GITHUB_TOKEN").is_none());
        assert!(env.is_empty());
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_no_direct_links_publishes_event() {
        // Same setup as inject_no_direct_links_injects_nothing, but
        // asserts the diagnostic MuxEvent fires — the standing signal
        // for #1624 so a future frontend surface (or just log triage) can
        // see when a non-sentinel identity resolves to zero direct links.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Not oauth-class (§4.3) — same rationale as
            // inject_no_direct_links_injects_nothing above.
            provider: "kimi".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let github = make_account(
            "acct-unlinked-2",
            "github",
            SecretRef::PlaintextDev {
                plaintext_dev: "ghp_unlinked_2".to_string(),
            },
        );
        store.identity_upsert(&github).unwrap();

        insert_block_for_agent(&store, "block-unlinked-2", "def-1");
        let inst = make_instance("block-unlinked-2", "id-unused-2");
        store.instance_create(&inst).unwrap();

        let broker = Arc::new(Broker::new());
        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env_with_broker(
            store.clone(),
            store.clone(),
            store,
            Some(broker.clone()),
            "block-unlinked-2",
            &mut env,
        )
        .unwrap();

        // The event is persisted (see resolve_bindings_for_instance's
        // publish) precisely so it's readable here without needing a live
        // subscriber wired up at publish time.
        let history = broker.read_event_history("identity:no-direct-links", "", 10);
        let event = history.last().expect("expected identity:no-direct-links event");
        assert_eq!(
            event.data.as_ref().and_then(|d| d.get("definition_id")).and_then(|v| v.as_str()),
            Some("def-1"),
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_partial_success_skips_failed_bindings() {
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Not oauth-class (§4.3) — this test targets partial-success
            // skip behavior across api-key bindings, unrelated to the
            // layer-3 oauth gate.
            provider: "kimi".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        // Working account.
        let good = make_account(
            "acct-good",
            "github",
            SecretRef::PlaintextDev {
                plaintext_dev: "ghp_good".to_string(),
            },
        );
        store.identity_upsert(&good).unwrap();
        store
            .agent_identity_link("def-1", "acct-good", "github")
            .unwrap();

        // Account whose Env-backed secret references a missing var.
        let bad = make_account(
            "acct-bad",
            "anthropic",
            SecretRef::Env {
                env_var: "AGENTMUX_TEST_DEFINITELY_NOT_SET_4242".to_string(),
            },
        );
        store.identity_upsert(&bad).unwrap();
        store
            .agent_identity_link("def-1", "acct-bad", "anthropic")
            .unwrap();

        insert_block_for_agent(&store, "block-mixed", "def-1");
        let inst = make_instance("block-mixed", "id-mixed");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-mixed", &mut env).unwrap();

        // GitHub injection succeeded.
        assert_eq!(env.get("GITHUB_TOKEN").map(String::as_str), Some("ghp_good"));
        assert_eq!(env.get("GH_TOKEN").map(String::as_str), Some("ghp_good"));
        // Anthropic was skipped (env var missing) but didn't abort.
        assert!(env.get("ANTHROPIC_API_KEY").is_none());
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_unknown_provider_is_skipped() {
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Not oauth-class (§4.3) — this test targets the unknown-
            // provider skip path, unrelated to the layer-3 oauth gate.
            provider: "kimi".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let custom = make_account(
            "acct-custom",
            "custom",
            SecretRef::PlaintextDev {
                plaintext_dev: "ignored".to_string(),
            },
        );
        store.identity_upsert(&custom).unwrap();
        store
            .agent_identity_link("def-1", "acct-custom", "custom")
            .unwrap();

        insert_block_for_agent(&store, "block-future", "def-1");
        let inst = make_instance("block-future", "id-future");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store, "block-future", &mut env).unwrap();
        // No env-var matrix for "custom" — nothing injected, no panic.
        assert!(env.is_empty());
    }

    /// Helper: write a Claude-shape `.credentials.json` into a temp dir
    /// and return the dir path. `expires_ms` controls validity; `with_refresh`
    /// toggles the refreshToken field so the resolver can distinguish
    /// `Expired` (refresh present) from `NeedsReauth` (no refresh).
    ///
    /// Duplicated from `oauth_probe::tests` (same helper, different file)
    /// rather than shared cross-module — kept the modularization split a
    /// pure relocation with no new cross-file test-only visibility surface.
    fn write_claude_creds(
        dir: &std::path::Path,
        expires_ms: i64,
        with_refresh: bool,
    ) {
        std::fs::create_dir_all(dir).unwrap();
        let body = serde_json::json!({
            "claudeAiOauth": {
                "accessToken": "test-access",
                "refreshToken": if with_refresh { "test-refresh" } else { "" },
                "expiresAt": expires_ms,
            }
        });
        std::fs::write(
            dir.join(".credentials.json"),
            serde_json::to_string(&body).unwrap(),
        )
        .unwrap();
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_probes_and_flips_status_to_needs_reauth() {
        // Full integration: an oauth-class binding pointing at a
        // bundle dir with NO token file → the probe surfaces
        // `needs_reauth` and the resolver upserts the account row
        // with the new status. Spec §4.4.
        //
        // Uses "codex", not "claude": the macOS Keychain carve-out added
        // in oauth_probe.rs (retro-macos-keychain-credential-isolation-gap-
        // 2026-08-17.md) makes a missing token file for "claude" return
        // `None` (no status change) on macOS specifically, since Claude
        // Code never writes `.credentials.json` there regardless of the
        // config dir. "codex" isn't covered by that carve-out, so it keeps
        // this test's original, platform-independent needs_reauth signal.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "codex".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        // Bundle dir intentionally empty — probe should report
        // needs_reauth (no token file).
        let tmp = tempfile::tempdir().unwrap();
        let bundle_dir = tmp.path().to_str().unwrap().to_string();

        let codex_acct = IdentityAccount {
            id: "acct-codex".to_string(),
            name: "codex-acct-codex".to_string(),
            provider: "codex".to_string(),
            kind: "oauth".to_string(),
            display_name: String::new(),
            secret_ref: SecretRef::OAuthConfigDir { dir: bundle_dir },
            context: serde_json::json!({}),
            // Start as "valid" — the probe should flip it to
            // "needs_reauth".
            status: oauth_status::VALID.to_string(),
            created_at: 0,
            updated_at: 0,
        };
        store.identity_upsert(&codex_acct).unwrap();
        store
            .agent_identity_link("def-1", "acct-codex", "codex")
            .unwrap();

        insert_block_for_agent(&store, "block-probe", "def-1");
        let inst = make_instance("block-probe", "id-probe");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store.clone(), "block-probe", &mut env).unwrap();

        // Env injection still happened (resolver doesn't block on
        // probe outcome — the CLI launches with the dir env var set
        // and will trigger OAuth itself when it sees no tokens).
        assert!(env.get("CODEX_HOME").is_some());

        // Status row was UPDATED to needs_reauth.
        let after = store.identity_get("acct-codex").unwrap().unwrap();
        assert_eq!(after.status, oauth_status::NEEDS_REAUTH);
    }

    #[cfg(target_os = "macos")]
    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_self_heals_stale_needs_reauth_for_claude_on_macos() {
        // Codex P1 on PR #2645: an account probed BEFORE the macOS
        // Keychain carve-out existed may already have `needs_reauth`
        // persisted from the old, buggy behavior. Without a self-heal,
        // that account stays stuck showing "reconnect" forever, since a
        // `None` probe never upserts anything — this proves the resolver
        // corrects it back to "unknown" (not a fabricated "valid") the
        // next time the agent spawns.
        let store = make_store();

        // gate_def's own provider is already "claude" — see its doc comment.
        let mut def = gate_def(0);
        store.agent_def_insert(&mut def).unwrap();

        // Bundle dir intentionally empty, same as the pre-fix broken case —
        // but the account already carries the stale needs_reauth status
        // the old probe would have written.
        let tmp = tempfile::tempdir().unwrap();
        let bundle_dir = tmp.path().to_str().unwrap().to_string();

        let stale = IdentityAccount {
            id: "acct-stale".to_string(),
            name: "claude-acct-stale".to_string(),
            provider: "claude".to_string(),
            kind: "oauth".to_string(),
            display_name: String::new(),
            secret_ref: SecretRef::OAuthConfigDir { dir: bundle_dir },
            context: serde_json::json!({}),
            status: oauth_status::NEEDS_REAUTH.to_string(),
            created_at: 0,
            updated_at: 0,
        };
        store.identity_upsert(&stale).unwrap();
        store
            .agent_identity_link("def-1", "acct-stale", "claude")
            .unwrap();

        insert_block_for_agent(&store, "block-self-heal", "def-1");
        let inst = make_instance("block-self-heal", "id-self-heal");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store.clone(), "block-self-heal", &mut env).unwrap();

        let after = store.identity_get("acct-stale").unwrap().unwrap();
        assert_eq!(
            after.status, "unknown",
            "a stale pre-carve-out needs_reauth must self-heal to unknown, not stay stuck"
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_probe_canonicalizes_a_legacy_alias_binding() {
        // codex P2 on PR #2377 (third round): probe_oauth_status only
        // recognizes canonical provider strings ("claude"/"codex"/
        // "openclaw") — passing the raw alias ("claude-code") a
        // migrated/legacy binding may still carry always returned None,
        // silently never refreshing that account's status. Same fixture
        // as inject_oauth_class_probes_and_flips_status_to_needs_reauth
        // above, but bound under the alias instead of the canonical id.
        //
        // Uses "codex-cli" → "codex", not "claude-code" → "claude": the
        // macOS Keychain carve-out (oauth_probe.rs) means a missing token
        // file for "claude" returns `None` on macOS regardless of whether
        // canonicalization ran, which would make this test unable to
        // distinguish "canonicalization is broken" from "hit the carve-out"
        // on that platform. "codex" isn't covered by the carve-out, so it
        // keeps the original, platform-independent needs_reauth signal.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "codex".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let tmp = tempfile::tempdir().unwrap();
        let bundle_dir = tmp.path().to_str().unwrap().to_string();

        let codex_acct = IdentityAccount {
            id: "acct-alias".to_string(),
            name: "codex-cli-acct-alias".to_string(),
            provider: "codex-cli".to_string(),
            kind: "oauth".to_string(),
            display_name: String::new(),
            secret_ref: SecretRef::OAuthConfigDir { dir: bundle_dir },
            context: serde_json::json!({}),
            status: oauth_status::VALID.to_string(),
            created_at: 0,
            updated_at: 0,
        };
        store.identity_upsert(&codex_acct).unwrap();
        // Bound under the alias, not the canonical "codex".
        store
            .agent_identity_link("def-1", "acct-alias", "codex-cli")
            .unwrap();

        insert_block_for_agent(&store, "block-probe-alias", "def-1");
        let inst = make_instance("block-probe-alias", "id-probe-alias");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store.clone(), "block-probe-alias", &mut env).unwrap();

        assert!(env.get("CODEX_HOME").is_some());
        // Status row was UPDATED to needs_reauth — proves the probe ran
        // with the canonicalized provider id, not the raw alias (which
        // would have returned None and left status untouched at "valid").
        let after = store.identity_get("acct-alias").unwrap().unwrap();
        assert_eq!(after.status, oauth_status::NEEDS_REAUTH);
    }

    #[cfg(debug_assertions)]
    #[test]
    fn inject_oauth_class_probe_preserves_status_when_valid() {
        // Future-dated token + status already "valid" → no-op
        // upsert (no spurious updated_at churn). The assertion is
        // that the status remains "valid" — proving the probe
        // didn't misclassify a working session.
        let store = make_store();

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        };
        store.agent_def_insert(&mut def).unwrap();

        let tmp = tempfile::tempdir().unwrap();
        let now_ms = agentmux_common::time::now_ms();
        write_claude_creds(tmp.path(), now_ms + 3_600_000, true);

        let claude = IdentityAccount {
            id: "acct-ok".to_string(),
            name: "claude-acct-ok".to_string(),
            provider: "claude".to_string(),
            kind: "oauth".to_string(),
            display_name: String::new(),
            secret_ref: SecretRef::OAuthConfigDir {
                dir: tmp.path().to_str().unwrap().to_string(),
            },
            context: serde_json::json!({}),
            status: oauth_status::VALID.to_string(),
            created_at: 0,
            updated_at: 0,
        };
        store.identity_upsert(&claude).unwrap();
        store
            .agent_identity_link("def-1", "acct-ok", "claude")
            .unwrap();

        insert_block_for_agent(&store, "block-ok", "def-1");
        let inst = make_instance("block-ok", "id-ok");
        store.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        inject_identity_env(store.clone(), store.clone(), store.clone(), "block-ok", &mut env).unwrap();

        let after = store.identity_get("acct-ok").unwrap().unwrap();
        assert_eq!(after.status, oauth_status::VALID);
        // updated_at unchanged — the resolver only upserts when the
        // probed status differs from the stored value.
        assert_eq!(after.updated_at, 0);
    }

    // P0 regression test (found in a follow-up scoping pass after
    // agent_open.rs's identical bug was fixed in PR #2587 round 3):
    // the layer-3 gate must resolve the definition's provider through
    // its bound ABF bundle (`id_store.resolve_effective_provider_id`),
    // not `d.provider` directly. Uses two genuinely separate stores —
    // mstore (definition, block, instance) and id_store (bundle,
    // account, link) — so the test can't pass by accident the way it
    // would if both roles were backed by the same `Arc<Store>`, which
    // every OTHER test in this module does (matching production's
    // AppState.mstore/id_store split, but meaning none of them could
    // have caught this class of bug).
    //
    // Scenario: the agent says "codex"; its bound bundle, from before
    // bundles stopped carrying a harness, says "claude", and the agent has
    // a Claude account bound. The agent owns its harness
    // (SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md §3.1), so the gate checks
    // codex, finds no codex account, and refuses; the bundle's value never
    // decides. (The §3.3 migration makes the two agree before this rule
    // takes effect, so a real agent doesn't land here.)
    #[test]
    fn spawn_gate_checks_the_agents_own_provider_not_its_bundles() {
        let mstore = make_store();
        // Real shared-store schema, not open_in_memory's channel schema —
        // db_agent_identity_links only has a `db_agents` FK in the
        // channel schema (`run_object_schema` in migrations.rs); the
        // shared-store schema (`run_shared_store_schema`) deliberately
        // omits it, since agent
        // definitions never live in the shared store. Using two
        // open_in_memory() stores here would incorrectly enforce an FK
        // that doesn't exist in production's real id_store.
        let id_store_tmp = tempfile::NamedTempFile::new().unwrap();
        let id_store = Arc::new(Store::open_shared(id_store_tmp.path()).unwrap());
        // Same reasoning as id_store above, for the new always-global
        // identity store (SPEC_IDENTITY_STORE_SPLIT_2026_08_17.md):
        // open_identity_store's real schema (no db_accounts FK at all — see
        // its own doc comment) rather than open_in_memory's channel schema.
        let identity_store_tmp = tempfile::NamedTempFile::new().unwrap();
        let identity_store = Arc::new(Store::open_identity_store(identity_store_tmp.path()).unwrap());

        let mut def = crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "def-1".to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            // Drifted: the definition's own column says codex...
            provider: "codex".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            // ...but its bound bundle (below, in id_store) says claude.
            memory_id: "bundle-1".to_string(),
        };
        mstore.agent_def_insert(&mut def).unwrap();

        let bundle = Bundle {
            id: "bundle-1".to_string(),
            name: "Drift Test Bundle".to_string(),
            description: String::new(),
            is_blank: false,
            is_global: false,
            provider: "claude".to_string(),
            model: "anthropic".to_string(),
            instructions: String::new(),
            instructions_by_provider: "{}".to_string(),
            context_files: "[]".to_string(),
            mcp_servers: "[]".to_string(),
            skills: "[]".to_string(),
            sort_order: 0,
            created_at: 0,
            updated_at: 0,
            is_system: false,
        };
        id_store.bundle_upsert(&bundle).unwrap();

        let claude = make_account(
            "acct-drift",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-drift"),
            },
        );
        id_store.identity_upsert_with_mirror(&identity_store, &claude).unwrap();
        identity_store
            .agent_identity_link("def-1", "acct-drift", "claude")
            .unwrap();

        insert_block_for_agent(&mstore, "block-drift", "def-1");
        let inst = make_instance("block-drift", "id-drift");
        mstore.instance_create(&inst).unwrap();

        let mut env: HashMap<String, String> = HashMap::new();
        let res = inject_identity_env(mstore, id_store, identity_store, "block-drift", &mut env);

        // The gate checks the agent's own provider (codex), which has no
        // account bound; the bundle's claude is only a hint.
        assert!(
            matches!(&res, Err(SpawnGateError::MissingCredentials { provider }) if provider == "codex"),
            "the agent owns its harness; the bundle's provider is a hint (SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md §3.1): {res:?}"
        );
    }

    fn make_agent_def_with_provider(id: &str, provider: &str) -> crate::backend::storage::store::AgentDefinition {
        crate::backend::storage::store::AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: id.to_string(),
            slug: String::new(),
            name: "T".to_string(),
            icon: "✦".to_string(),
            provider: provider.to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: String::new(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        }
    }

    // SPEC_SUBAGENT_WATCHER_IDENTITY_BOUND_CONFIG_DIR_2026_08_22.md
    #[cfg(debug_assertions)]
    #[test]
    fn resolve_bound_oauth_config_dir_resolves_the_identity_bound_dir() {
        let store = make_store();
        let mut def = make_agent_def_with_provider("def-1", "claude");
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-claude",
            "claude",
            SecretRef::OAuthConfigDir {
                dir: test_config_dir("id-bound"),
            },
        );
        store.identity_upsert(&claude).unwrap();
        store.agent_identity_link("def-1", "acct-claude", "claude").unwrap();

        insert_block_for_agent(&store, "block-bound", "def-1");
        let inst = make_instance("block-bound", "id-bound");
        store.instance_create(&inst).unwrap();

        let resolved = resolve_bound_oauth_config_dir(&store, &store, &store, "block-bound");
        assert_eq!(
            resolved,
            Some(std::path::PathBuf::from(test_config_dir("id-bound"))),
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn resolve_bound_oauth_config_dir_none_when_no_instance_for_block() {
        let store = make_store();
        let resolved = resolve_bound_oauth_config_dir(&store, &store, &store, "no-such-block");
        assert_eq!(resolved, None);
    }

    #[cfg(debug_assertions)]
    #[test]
    fn resolve_bound_oauth_config_dir_none_for_api_key_class_provider() {
        let store = make_store();
        // github is API-key class, not OAuth — never resolves to a config dir.
        let mut def = make_agent_def_with_provider("def-1", "github");
        store.agent_def_insert(&mut def).unwrap();

        let github = make_account(
            "acct-gh",
            "github",
            SecretRef::PlaintextDev { plaintext_dev: "ghp_x".to_string() },
        );
        store.identity_upsert(&github).unwrap();
        store.agent_identity_link("def-1", "acct-gh", "github").unwrap();

        insert_block_for_agent(&store, "block-gh", "def-1");
        let inst = make_instance("block-gh", "id-gh");
        store.instance_create(&inst).unwrap();

        let resolved = resolve_bound_oauth_config_dir(&store, &store, &store, "block-gh");
        assert_eq!(resolved, None);
    }

    #[cfg(debug_assertions)]
    #[test]
    fn resolve_bound_oauth_config_dir_none_when_oauth_provider_has_no_binding() {
        let store = make_store();
        let mut def = make_agent_def_with_provider("def-1", "claude");
        store.agent_def_insert(&mut def).unwrap();
        // No account, no link — an ambient/unbound agent.

        insert_block_for_agent(&store, "block-unbound", "def-1");
        let inst = make_instance("block-unbound", "");
        store.instance_create(&inst).unwrap();

        let resolved = resolve_bound_oauth_config_dir(&store, &store, &store, "block-unbound");
        assert_eq!(resolved, None, "ambient/unbound agents must fall through, not error");
    }

    // Proves the "no side effects" claim in the doc comment, not just states
    // it: an oauth probe on the real path would flip this account's status
    // from "unknown" (probe_oauth_status sees no token file at this
    // nonexistent dir and returns needs_reauth) — resolve_bound_oauth_config_dir
    // must leave it untouched since it never calls the probe/upsert at all.
    #[cfg(debug_assertions)]
    #[test]
    fn resolve_bound_oauth_config_dir_does_not_mutate_account_status() {
        let store = make_store();
        let mut def = make_agent_def_with_provider("def-1", "claude");
        store.agent_def_insert(&mut def).unwrap();

        let claude = make_account(
            "acct-claude",
            "claude",
            SecretRef::OAuthConfigDir { dir: "/nonexistent/dir/for/probe".to_string() },
        );
        store.identity_upsert(&claude).unwrap();
        store.agent_identity_link("def-1", "acct-claude", "claude").unwrap();

        insert_block_for_agent(&store, "block-status", "def-1");
        let inst = make_instance("block-status", "id-status");
        store.instance_create(&inst).unwrap();

        let _ = resolve_bound_oauth_config_dir(&store, &store, &store, "block-status");

        let reread = store.identity_get("acct-claude").unwrap().unwrap();
        assert_eq!(reread.status, "unknown", "status must be untouched — no probe/upsert side effect");
    }
}