Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
106 KB
Raw Blame
//! Native lifecycle-hook capture helpers.
//!
//! Mirrors the POSIX `hooks/lib/_lib.sh` logic so the native
//! `ai-memory hook` subcommand produces the same HTTP request the shell
//! scripts do: extract cwd from the payload, walk up for a
//! `.ai-memory.toml` marker, and build the query-string suffix. The two
//! request helpers are best-effort with shell-parity timeouts.

use std::io::Read;
use std::path::{Path, PathBuf};
use std::time::Duration;

use crate::commands::path_util::home_dir;
use crate::marker::{
    RoutingSelection, RoutingSource, find_marker, is_truthy, parse_toml_flag, parse_toml_key,
    repo_root_project, routing_selection,
};
use ai_memory_hooks::capture_policy::MAX_MARKER_BYTES;
use ai_memory_hooks::{
    CLIENT_MARKER_HEADER, CaptureConfig, CapturePolicy, CaptureSource, PolicyState,
    describe_invalid_capture_config,
};

/// Resolve the nearest marker's capture policy without changing routing parsing.
/// Root-level marker keys are intentionally ignored here; only `[capture]` is strict.
pub fn capture_policy(cwd: &str) -> CapturePolicy {
    let Some(marker) = find_marker(cwd) else {
        let home = home_dir();
        return CapturePolicy::resolve(
            CaptureSource::Absent,
            cwd,
            home.as_deref().and_then(Path::to_str),
        );
    };
    marker_capture_policy(&marker, cwd)
}

/// The capture policy one marker file declares; `cwd` stands in for its
/// directory only when that cannot be read as text.
pub(crate) fn marker_capture_policy(marker: &Path, cwd: &str) -> CapturePolicy {
    let home = home_dir();
    let marker_dir = marker.parent().and_then(Path::to_str).unwrap_or(cwd);
    match read_capture_config(marker) {
        Ok(config) => CapturePolicy::resolve(
            CaptureSource::Parsed(&config),
            marker_dir,
            home.as_deref().and_then(Path::to_str),
        ),
        Err(()) => CapturePolicy::resolve(
            CaptureSource::Invalid,
            marker_dir,
            home.as_deref().and_then(Path::to_str),
        ),
    }
}

fn read_capture_config(marker: &Path) -> Result<CaptureConfig, ()> {
    read_capture_config_verbose(marker).map_err(|_reason| ())
}

/// Same parse as [`read_capture_config`], but keeps the failure reason
/// instead of collapsing it to `()`. The hot hook path only needs "did this
/// parse" and discards the reason; diagnostics (`ai-memory doctor`) need it.
/// Note this only covers the TOML-parse / `[capture]`-shape stage — a config
/// that parses fine here can still be rejected later at compile time (see
/// [`ai_memory_hooks::describe_invalid_capture_config`]).
fn read_capture_config_verbose(marker: &Path) -> Result<CaptureConfig, String> {
    let mut bytes = Vec::with_capacity(MAX_MARKER_BYTES + 1);
    std::fs::File::open(marker)
        .map_err(|e| format!("could not open marker file: {e}"))?
        .take((MAX_MARKER_BYTES + 1) as u64)
        .read_to_end(&mut bytes)
        .map_err(|e| format!("could not read marker file: {e}"))?;
    if bytes.len() > MAX_MARKER_BYTES {
        return Err(format!(
            "marker file is larger than the {MAX_MARKER_BYTES}-byte capture-config limit"
        ));
    }
    let text =
        String::from_utf8(bytes).map_err(|e| format!("marker file is not valid UTF-8: {e}"))?;
    let document = text
        .parse::<toml_edit::DocumentMut>()
        .map_err(|e| format!("invalid TOML: {e}"))?;
    let Some(capture) = document.get("capture") else {
        return Ok(CaptureConfig::default());
    };
    let table = capture
        .as_table()
        .ok_or_else(|| "`[capture]` must be a table".to_owned())?;
    if let Some((key, _)) = table.iter().find(|(key, _)| *key != "ignore_paths") {
        return Err(format!(
            "`[capture]` has an unsupported key `{key}` (only `ignore_paths` is allowed)"
        ));
    }
    let ignore_paths = match table.get("ignore_paths") {
        None => Vec::new(),
        Some(item) => {
            item.as_array()
                .ok_or_else(|| "`[capture].ignore_paths` must be an array".to_owned())?
                .iter()
                .map(|value| {
                    value.as_str().map(str::to_owned).ok_or_else(|| {
                        "`[capture].ignore_paths` must contain only strings".to_owned()
                    })
                })
                .collect::<Result<Vec<_>, _>>()?
        }
    };
    Ok(CaptureConfig { ignore_paths })
}

/// Diagnostic for `ai-memory doctor`: does the nearest `.ai-memory.toml`'s
/// `[capture]` section actually resolve into an active policy?
///
/// Bases the check on [`capture_policy`]'s own resolution state -- the exact
/// state the live hook path uses -- rather than a parse-only check, because a
/// `[capture]` table can parse as valid TOML and still be rejected later at
/// compile time (too many patterns, an unsupported glob character, a `~/`
/// pattern with no home directory to expand it...), which a parse-only check
/// would miss entirely.
///
/// Returns `None` when there is no marker, or the marker's capture config
/// resolves (absent, empty, or a valid active policy). Returns
/// `Some((marker_path, reason))` when a marker exists and its `[capture]`
/// table is [`PolicyState::Invalid`] -- which fails CLOSED (every file and
/// shell tool event is reduced to metadata until the marker is fixed;
/// nothing leaks) but with no other signal anywhere that it happened.
pub fn capture_config_problem(cwd: &str) -> Option<(PathBuf, String)> {
    let marker = find_marker(cwd)?;
    if capture_policy(cwd).state() != PolicyState::Invalid {
        return None;
    }
    let marker_dir = marker.parent().and_then(Path::to_str).unwrap_or(cwd);
    let home = home_dir();
    let reason = match read_capture_config_verbose(&marker) {
        Err(reason) => reason,
        Ok(config) => describe_invalid_capture_config(
            &config,
            marker_dir,
            home.as_deref().and_then(Path::to_str),
        )
        .unwrap_or_else(|| {
            "the `[capture]` table did not resolve into an active policy".to_owned()
        }),
    };
    Some((marker, reason))
}

/// First top-level `cwd` string in the payload (parity with
/// `ai_memory_extract_cwd`: take the top-level value, ignore nested
/// `cwd` fields in tool payloads).
pub fn extract_cwd(payload: &serde_json::Value) -> Option<String> {
    payload
        .get("cwd")
        .and_then(|v| v.as_str())
        .map(str::to_owned)
}

/// Fixture-backed canonical routing context shared by native marker routing and
/// pre-spool capture. Only explicit agent payload shapes are accepted.
pub fn canonical_context(payload: &serde_json::Value) -> (Option<String>, Option<String>) {
    let direct = |keys: &[&str]| {
        keys.iter().find_map(|key| {
            payload
                .get(*key)
                .and_then(serde_json::Value::as_str)
                .filter(|value| !value.trim().is_empty())
                .map(str::to_owned)
        })
    };
    let nested = |path: &[&str]| {
        path.iter()
            .try_fold(payload, |value, key| value.get(*key))
            .and_then(serde_json::Value::as_str)
            .filter(|value| !value.trim().is_empty())
            .map(str::to_owned)
    };
    // `workspacePaths` is Antigravity's spelling, `workspace_roots` is
    // Cursor's, and `workspaceRoots` is Cline's. Cursor never sends a usable top-level `cwd` — `sessionStart`
    // / `sessionEnd` omit it and its tool events send `cwd: ""` — so without
    // this the whole session resolves to no cwd and lands in `default/scratch`.
    let first_array_path = |keys: &[&str]| {
        keys.iter().find_map(|key| {
            payload
                .get(*key)
                .and_then(serde_json::Value::as_array)
                .and_then(|paths| {
                    paths
                        .iter()
                        .filter_map(serde_json::Value::as_str)
                        .find(|value| !value.trim().is_empty())
                })
                .map(str::to_owned)
        })
    };
    let cwd = direct(&["cwd", "current_dir", "working_dir", "directory"])
        .or_else(|| first_array_path(&["workspacePaths", "workspace_roots", "workspaceRoots"]))
        .or_else(|| {
            [
                ["path", "cwd"].as_slice(),
                ["info", "directory"].as_slice(),
                ["properties", "info", "directory"].as_slice(),
                ["event", "properties", "info", "directory"].as_slice(),
                ["payload", "path", "cwd"].as_slice(),
                ["payload", "info", "directory"].as_slice(),
                ["payload", "properties", "info", "directory"].as_slice(),
            ]
            .iter()
            .find_map(|path| nested(path))
        });
    let session = direct(&[
        "session_id",
        "sessionId",
        "sessionID",
        "session",
        "conversationId",
        "taskId",
    ])
    .or_else(|| {
        [
            ["info", "id"].as_slice(),
            ["properties", "sessionID"].as_slice(),
            ["properties", "info", "id"].as_slice(),
            ["event", "properties", "sessionID"].as_slice(),
            ["event", "properties", "info", "id"].as_slice(),
            ["payload", "info", "id"].as_slice(),
            ["payload", "properties", "sessionID"].as_slice(),
            ["payload", "properties", "info", "id"].as_slice(),
        ]
        .iter()
        .find_map(|path| nested(path))
    });
    (cwd, session)
}

fn non_empty(value: Option<String>) -> Option<String> {
    value.filter(|s| !s.trim().is_empty())
}

/// Resolve the cwd for hook bridges whose native payload may omit it.
///
/// Ordered fallback:
///
/// 1. `cwd` in the payload, if present.
/// 2. `DEVIN_PROJECT_DIR`, when the launcher provides it.
/// 3. The native hook process current directory.
pub fn resolve_cwd_with_fallbacks(
    payload: &serde_json::Value,
    mut env_lookup: impl FnMut(&str) -> Option<String>,
    current_dir: impl FnOnce() -> Option<PathBuf>,
) -> Option<String> {
    non_empty(canonical_context(payload).0)
        .or_else(|| non_empty(env_lookup("DEVIN_PROJECT_DIR")))
        .or_else(|| {
            current_dir().and_then(|path| {
                let cwd = path.to_string_lossy().into_owned();
                non_empty(Some(cwd))
            })
        })
}

/// Percent-encode everything outside the RFC 3986 unreserved set
/// (`A-Z a-z 0-9 - _ . ~`), byte-wise, so multibyte UTF-8 is encoded
/// per byte. Parity with `ai_memory_url_encode` in `hooks/_lib.sh`.
///
/// An allow-list on purpose: the old deny-list missed `\` (and friends),
/// so a Windows cwd like `C:\dev\myproject` went into the query string
/// raw and the HTTP layer refused the request — the session-start hook
/// printed `{}` and the pending handoff was never fetched (#188).
/// Over-encoding is always safe; the server percent-decodes uniformly.
pub fn url_encode(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(b as char);
            }
            other => {
                out.push_str(&format!("%{other:02X}"));
            }
        }
    }
    out
}

/// Build `&cwd=…[&workspace=…&project=…&project_strategy=…]`, mirroring
/// `ai_memory_marker_qs`: always include cwd; append marker-declared
/// fields when a `.ai-memory.toml` is found walking up toward $HOME.
///
/// `default_strategy` is the install-time default baked into the native hook
/// command by `install-hooks --project-strategy` (passed via the `hook
/// --project-strategy` flag). It fills `project_strategy` only when no marker
/// pins one. A marker's explicit `project` or `identity` and operator-home
/// routing win; otherwise a valid remote's canonical path wins, and repo-root
/// is only the host-side no-valid-remote fallback.
pub fn marker_query_suffix(cwd: &str, default_strategy: Option<&str>) -> String {
    marker_query_suffix_impl(cwd, default_strategy, Some(BriefingKey::SessionStart))
}

/// [`marker_query_suffix`] whose `&briefing` pair carries the
/// `[briefing] inject_on_subagent_start` opt-in instead: the query a subagent
/// start sends to `GET /brief`.
pub fn marker_query_suffix_for_subagent_brief(cwd: &str, default_strategy: Option<&str>) -> String {
    marker_query_suffix_impl(cwd, default_strategy, Some(BriefingKey::SubagentStart))
}

/// Which `[briefing]` opt-in a request forwards as its `&briefing` pair.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum BriefingKey {
    /// `inject_on_session_start`: the brief the session-start `/handoff`
    /// fetch appends.
    SessionStart,
    /// `inject_on_subagent_start`: the brief a subagent starts with, from
    /// `/brief`.
    SubagentStart,
}

impl BriefingKey {
    fn marker_key(self) -> &'static str {
        match self {
            Self::SessionStart => "inject_on_session_start",
            Self::SubagentStart => "inject_on_subagent_start",
        }
    }
}

/// [`marker_query_suffix`] without the `[briefing]` pair
/// (`&briefing=…&briefing_budget=…`).
///
/// Used by the kimi user-prompt handoff fetch: kimi discards SessionStart
/// hook stdout, so the compiled project brief is delivered on the FIRST user
/// prompt of a session (parity with Claude's once-per-SessionStart brief) and
/// later prompts re-fetch the handoff — kept on every prompt because it is
/// cheap and self-limiting (empty body when nothing is pending) — without the
/// briefing params, so the server does not recompose the brief per prompt.
pub fn marker_query_suffix_without_briefing(cwd: &str, default_strategy: Option<&str>) -> String {
    marker_query_suffix_impl(cwd, default_strategy, None)
}

/// Whether the marker that routes `cwd` explicitly enables the compiled
/// project brief. It is the selection [`marker_query_suffix`] reads its
/// `&briefing` params from, so the Kimi gate agrees with the query it gates:
/// the nearest settings-declaring marker (a nested capture-only marker does
/// not shadow an outer marker's `[briefing]` opt-in, #668), else the
/// operator-home marker, whether `cwd` is inside `$HOME` or not (#1665).
///
/// Kimi Code uses this before creating its local once-per-session marker so
/// repositories that did not opt in do not accumulate marker files.
pub fn marker_requests_briefing(cwd: &str) -> bool {
    marker_requests_briefing_with_home(cwd, home_dir().as_deref(), BriefingKey::SessionStart)
}

/// Whether the marker that routes `cwd` explicitly enables the subagent
/// brief (`[briefing] inject_on_subagent_start`), read from the selection
/// [`marker_query_suffix_for_subagent_brief`] reads, so a subagent start asks
/// `/brief` only when its query would carry the opt-in.
pub fn marker_requests_subagent_briefing(cwd: &str) -> bool {
    marker_requests_briefing_with_home(cwd, home_dir().as_deref(), BriefingKey::SubagentStart)
}

/// [`marker_requests_briefing`] for the opt-in `key`, resolved against `home`
/// instead of the operator's home directory.
fn marker_requests_briefing_with_home(cwd: &str, home: Option<&Path>, key: BriefingKey) -> bool {
    crate::marker::routing_selection_with_home(cwd, cwd, home, false)
        .ok()
        .flatten()
        .and_then(|selection| parse_toml_flag(&selection.path, key.marker_key()))
        .is_some_and(|value| is_truthy(&value))
}

/// Host-side routing hints sent with native lifecycle events.
/// Missing names are left to the server; this inspection creates no scope.
#[derive(Debug, PartialEq, Eq, serde::Serialize)]
pub struct HookScope {
    #[serde(serialize_with = "serialize_scope_hint")]
    workspace: Option<String>,
    #[serde(serialize_with = "serialize_scope_hint")]
    project: Option<String>,
    project_src: Option<&'static str>,
    #[serde(serialize_with = "serialize_scope_hint")]
    project_strategy: Option<String>,
    #[serde(serialize_with = "serialize_scope_hint")]
    identity: Option<String>,
    identity_src: Option<&'static str>,
    identity_style: Option<&'static str>,
    aliases: Option<String>,
    server_may_remap: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub(crate) struct RepositoryCoordinateEvidence {
    pub(crate) marker_status: &'static str,
    pub(crate) scope_source: &'static str,
    pub(crate) identity_source: Option<String>,
    pub(crate) identity_style: Option<String>,
    pub(crate) canonical_candidate: Option<String>,
    pub(crate) legacy_candidate: Option<String>,
    pub(crate) messages: Vec<String>,
}

pub(crate) struct RepositoryCoordinateInspection {
    pub(crate) evidence: RepositoryCoordinateEvidence,
    pub(crate) repository: Option<ai_memory_core::repository_identity::RepositoryIdentity>,
}

const MAX_SCOPE_HINT_BYTES: usize = 512;

fn serialize_scope_hint<S: serde::Serializer>(
    value: &Option<String>,
    serializer: S,
) -> Result<S::Ok, S::Error> {
    serde::Serialize::serialize(
        &value
            .as_deref()
            .filter(|value| value.len() <= MAX_SCOPE_HINT_BYTES),
        serializer,
    )
}

impl HookScope {
    /// Whether all routing hints fit the bounded inspection response.
    #[must_use]
    pub fn is_inspectable(&self) -> bool {
        [
            &self.workspace,
            &self.project,
            &self.project_strategy,
            &self.identity,
        ]
        .into_iter()
        .all(|value| {
            value
                .as_ref()
                .is_none_or(|value| value.len() <= MAX_SCOPE_HINT_BYTES)
        })
    }

    /// Whether only one name was explicitly declared in the marker.
    #[must_use]
    pub fn is_partial(&self) -> bool {
        (self.workspace.is_some() || self.project_src == Some("marker")) && !self.is_explicit()
    }

    /// Whether these hints alone decide the server's project: a project name,
    /// or an identity the server routes by. Otherwise the server derives the
    /// project from the event's cwd.
    pub(crate) const fn names_the_project(&self) -> bool {
        self.project.is_some() || self.identity.is_some()
    }

    /// Whether a project the server derives from the cwd follows the
    /// enclosing repository (`repo-root`) rather than the cwd's own folder,
    /// the default `basename`.
    pub(crate) fn derives_from_repo_root(&self) -> bool {
        matches!(
            self.project_strategy.as_deref(),
            Some("repo-root" | "repo_root")
        )
    }

    /// Whether both names were resolved on the host.
    #[must_use]
    pub fn is_explicit(&self) -> bool {
        self.workspace
            .as_deref()
            .is_some_and(|v| !v.trim().is_empty())
            && self
                .project
                .as_deref()
                .is_some_and(|v| !v.trim().is_empty())
    }
}

/// Inspect the same marker, worktree and repository identity as hook routing.
#[must_use]
pub fn hook_scope(cwd: &str, default_strategy: Option<&str>) -> HookScope {
    hook_scope_from_selection(cwd, default_strategy, routing_selection(cwd).ok().flatten())
}

/// [`hook_scope`] resolved against `home` instead of the operator's home
/// directory, so tests can keep a developer's `~/.ai-memory.toml` out.
#[cfg(test)]
pub(crate) fn hook_scope_with_home(
    cwd: &str,
    default_strategy: Option<&str>,
    home: Option<&std::path::Path>,
) -> HookScope {
    let selection = crate::marker::routing_selection_with_home(cwd, cwd, home, false);
    hook_scope_from_selection(cwd, default_strategy, selection.ok().flatten())
}

pub(crate) fn inspect_repository_coordinate(
    identity_cwd: &str,
    marker: &crate::marker::MarkerInspection,
    explicit_workspace: Option<&str>,
    explicit_project: Option<&str>,
) -> RepositoryCoordinateInspection {
    let declared_project = if explicit_project.is_some_and(|value| !value.is_empty()) {
        None
    } else {
        marker.fields.project.as_deref()
    };
    let repository = marker.route_identity.clone().or_else(|| {
        repository_identity(
            identity_cwd,
            marker.fields.identity.as_deref(),
            declared_project,
        )
    });
    let identity_style = repository.as_ref().and_then(|identity| {
        (identity.source == ai_memory_core::repository_identity::IdentitySource::GitRemote)
            .then(|| forwarded_identity_style(marker.fields.identity_style.as_deref()).to_owned())
    });
    RepositoryCoordinateInspection {
        evidence: RepositoryCoordinateEvidence {
            marker_status: marker.status,
            scope_source: match (
                explicit_workspace.is_some_and(|value| !value.is_empty()),
                explicit_project.is_some_and(|value| !value.is_empty()),
                marker.scope.is_some(),
            ) {
                (true, true, _) => "cli",
                (true, false, _) | (false, true, _) => "cli_and_marker_or_fallback",
                (false, false, true) => "marker_or_fallback",
                _ => "fallback",
            },
            identity_source: repository
                .as_ref()
                .map(|identity| identity.source.as_str().to_owned()),
            identity_style,
            canonical_candidate: repository
                .as_ref()
                .and_then(ai_memory_core::repository_identity::path_style_name),
            legacy_candidate: repository
                .as_ref()
                .and_then(ai_memory_core::repository_identity::legacy_basename_name),
            messages: match marker.status {
                "invalid_home_routes" => {
                    vec!["invalid home route map; marker routing was refused".to_owned()]
                }
                "invalid" => vec!["invalid marker TOML; marker routing was ignored".to_owned()],
                "unreadable" => vec!["unreadable marker; marker routing was ignored".to_owned()],
                "conflicting" => {
                    vec!["conflicting marker settings; marker routing was ignored".to_owned()]
                }
                "ignored" => vec!["marker ignored by configuration".to_owned()],
                _ => Vec::new(),
            },
        },
        repository,
    }
}

fn hook_scope_from_selection(
    cwd: &str,
    default_strategy: Option<&str>,
    selection: Option<RoutingSelection>,
) -> HookScope {
    let workspace = selection
        .as_ref()
        .and_then(|selection| selection.fields.workspace.clone());
    let mut project = selection
        .as_ref()
        .and_then(|selection| selection.fields.project.clone());
    let mut strategy = selection
        .as_ref()
        .and_then(|selection| selection.fields.project_strategy.clone());
    let explicit_identity = selection
        .as_ref()
        .and_then(|selection| selection.fields.identity.clone());
    let style = selection
        .as_ref()
        .and_then(|selection| selection.fields.identity_style.clone());
    let mut aliases =
        selection
            .as_ref()
            .and_then(|selection| match selection.fields.aliases.clone() {
                Ok(Some(aliases)) if !aliases.is_empty() => serde_json::to_string(&aliases).ok(),
                Ok(_) => None,
                Err(_) => Some("invalid".to_owned()),
            });
    let canonical_project = project.clone();
    let routed = selection.as_ref().is_some_and(|selection| {
        matches!(
            selection.source,
            RoutingSource::HomeIdentityRoute | RoutingSource::HomePathRoute
        )
    });
    let mut project_src = project.as_ref().map(|_| "marker");
    let identity = if routed {
        selection.and_then(|selection| selection.remote_identity)
    } else if aliases.is_none() {
        repository_identity(cwd, explicit_identity.as_deref(), project.as_deref())
    } else {
        repository_identity(cwd, None, None).filter(|identity| {
            identity.source == ai_memory_core::repository_identity::IdentitySource::GitRemote
        })
    };
    if aliases.is_some()
        && identity.as_ref().is_none_or(|identity| {
            identity.source != ai_memory_core::repository_identity::IdentitySource::GitRemote
        })
    {
        aliases = if routed {
            None
        } else {
            Some("invalid".to_owned())
        };
    } else if aliases.is_some() && canonical_project.is_none() {
        aliases = Some("invalid".to_owned());
    }
    if strategy.is_none() {
        strategy = default_strategy.map(str::to_owned);
    }
    if project.is_none() && matches!(strategy.as_deref(), Some("repo-root" | "repo_root")) {
        project = repo_root_project(cwd);
        project_src = project.as_ref().map(|_| "repo-root");
    }
    // Only a remote has a host to drop, so the style travels with a remote
    // identity and nothing else (#1033).
    let identity_style = identity.as_ref().and_then(|identity| {
        (identity.source == ai_memory_core::repository_identity::IdentitySource::GitRemote)
            .then(|| forwarded_identity_style(style.as_deref()))
    });
    let (identity, identity_src) = match identity {
        Some(identity) => (Some(identity.identity), Some(identity.source.as_str())),
        None => (None, None),
    };
    let server_may_remap = project_src != Some("marker") || identity.is_some();
    HookScope {
        workspace,
        project,
        project_src,
        project_strategy: strategy,
        identity,
        identity_src,
        identity_style,
        aliases,
        server_may_remap,
    }
}

/// The `identity_style` every Phase-5 client sends with a valid git remote.
/// Explicit marker/home-route values win; omission emits `path`. The server
/// keeps omitted wire input as legacy `host_path` for old-client compatibility.
fn forwarded_identity_style(raw: Option<&str>) -> &'static str {
    use ai_memory_core::repository_identity::IdentityStyle;
    raw.and_then(IdentityStyle::from_str_opt)
        .unwrap_or(IdentityStyle::Path)
        .as_str()
}

/// A resolved marker's `[profile]` flag as the explicit value the hook
/// forwards: `0` for a falsy value, `1` for anything else, an absent key
/// included.
fn profile_flag_value(raw: Option<String>) -> &'static str {
    if raw.as_deref().is_some_and(crate::marker::is_falsy) {
        "0"
    } else {
        "1"
    }
}

fn marker_query_suffix_impl(
    cwd: &str,
    default_strategy: Option<&str>,
    briefing_key: Option<BriefingKey>,
) -> String {
    let selection = match routing_selection(cwd) {
        Ok(selection) => selection,
        Err(_) => return String::new(),
    };
    marker_query_suffix_impl_from_selection(cwd, default_strategy, briefing_key, selection)
}

fn marker_query_suffix_impl_from_selection(
    cwd: &str,
    default_strategy: Option<&str>,
    briefing_key: Option<BriefingKey>,
    selection: Option<RoutingSelection>,
) -> String {
    let mut qs = format!("&cwd={}", url_encode(cwd));
    let marker = selection.as_ref().map(|selection| selection.path.clone());
    let scope = hook_scope_from_selection(cwd, default_strategy, selection);
    let (mut drop_subagent, mut default_global) = (None, None);
    let (mut briefing, mut briefing_budget) = (None, None);
    let (mut profile_contribute, mut profile_consume) = (None, None);
    let mut handoff_off = false;
    // The nearest marker that declares more than `[capture]` (#668): a
    // nested capture-only marker (e.g. one that only sets `ignore_paths`)
    // must not shadow an outer marker's workspace/project/briefing/etc.
    if let Some(marker) = marker {
        drop_subagent = parse_toml_key(&marker, "drop_subagent_captures");
        // `[recall] default_global = true` (or top-level; quoted or bare) —
        // a meta-repo opts every default-scoped read into a global search.
        default_global = parse_toml_flag(&marker, "default_global");
        // `[briefing] inject_on_session_start = true` + optional
        // `max_chars = N` — opt this repo into the compiled project brief
        // appended to the session-start handoff fetch (#176); the subagent
        // brief reads `inject_on_subagent_start` instead.
        if let Some(key) = briefing_key {
            briefing = parse_toml_flag(&marker, key.marker_key());
            briefing_budget = parse_toml_flag(&marker, "max_chars");
        }
        // `[profile] contribute` / `consume` (quoted or bare), always sent
        // explicitly once a marker resolved: a falsy value sends `0`, anything
        // else (an absent key included) `1`. Removing the key re-enables; no
        // marker sends nothing, so the server keeps what it stored.
        profile_contribute = Some(profile_flag_value(parse_toml_flag(&marker, "contribute")));
        profile_consume = Some(profile_flag_value(parse_toml_flag(&marker, "consume")));
        // `[handoff] deliver_on_session_start = false` keeps this project's
        // handoffs out of its session starts. Sent only when explicitly
        // falsy, so an absent key leaves the request byte-identical.
        handoff_off = parse_toml_flag(&marker, "deliver_on_session_start")
            .as_deref()
            .is_some_and(crate::marker::is_falsy);
    }
    if let Some(val) = scope.workspace {
        qs.push_str(&format!("&workspace={}", url_encode(&val)));
    }
    if let Some(val) = scope.project {
        qs.push_str(&format!("&project={}", url_encode(&val)));
    }
    if let Some(val) = scope.project_src {
        qs.push_str(&format!("&project_src={val}"));
    }
    if let Some(val) = scope.project_strategy {
        qs.push_str(&format!("&project_strategy={}", url_encode(&val)));
    }
    if let (Some(identity), Some(source)) = (scope.identity, scope.identity_src) {
        qs.push_str(&format!(
            "&identity={}&identity_src={}",
            url_encode(&identity),
            source
        ));
    }
    if let Some(style) = scope.identity_style {
        qs.push_str(&format!("&identity_style={style}"));
    }
    if let Some(aliases) = scope.aliases {
        qs.push_str(&format!("&aliases={}", url_encode(&aliases)));
    }
    // Per-project `drop_subagent_captures` opt-in: forward the marker's value as
    // the `drop_subagent` flag so the server scopes the drop to this project.
    // The server interprets truthiness (`1`/`true`/…).
    if let Some(val) = drop_subagent.filter(|v| !v.is_empty()) {
        qs.push_str(&format!("&drop_subagent={}", url_encode(&val)));
    }
    // Per-repo `default_global` opt-in: forward the marker's value so the
    // server can publish it on the ActiveProject and make default-scoped read
    // tools search globally. Truthiness is decided server-side.
    if let Some(val) = default_global.filter(|v| !v.is_empty()) {
        qs.push_str(&format!("&default_global={}", url_encode(&val)));
    }
    // Per-project `[profile]` settings: the server records `contribute` on the
    // project for harvesting, and `consume = false` suppresses the digest and
    // the profile union for this project.
    if let Some(val) = profile_contribute {
        qs.push_str(&format!("&profile_contribute={val}"));
    }
    if let Some(val) = profile_consume {
        qs.push_str(&format!("&profile_consume={val}"));
    }
    if handoff_off {
        qs.push_str("&handoff=0");
    }
    // Per-repo brief opt-in: forwarded on every request for simplicity (the
    // capture path ignores it); only the `/handoff` GET at session start, or
    // `/brief` at a subagent start, acts on it. Truthiness and the
    // char-budget clamp are decided server-side. Callers that deliver the
    // brief once per session (the kimi user-prompt path) pass no key after
    // the first delivery so the server stops recomposing the brief per
    // request.
    if let Some(val) = briefing.filter(|v| !v.is_empty()) {
        qs.push_str(&format!("&briefing={}", url_encode(&val)));
    }
    if let Some(val) = briefing_budget.filter(|v| !v.is_empty()) {
        qs.push_str(&format!("&briefing_budget={}", url_encode(&val)));
    }
    qs
}

/// The repository identity to send with this checkout's events (#708), or
/// `None` to let the server route by project name as it always has.
///
/// Only the rungs that route by identity are sent: an explicit `identity`
/// from the marker, or — when the marker declares no `project` — the
/// `upstream`/`origin` remote. A declared `project` outranks the remote and
/// routes by name, so git is not consulted at all when one is present; that
/// also keeps the lookup off the hot path for every repository that declares
/// itself. The remote is normalised here, so credentials embedded in its URL
/// never leave the machine.
fn repository_identity(
    cwd: &str,
    explicit_identity: Option<&str>,
    declared_project: Option<&str>,
) -> Option<ai_memory_core::repository_identity::RepositoryIdentity> {
    use ai_memory_core::repository_identity::{IdentityInputs, resolve};
    let declared = |value: Option<&str>| value.is_some_and(|v| !v.trim().is_empty());
    let (upstream, origin) = if declared(explicit_identity) || declared(declared_project) {
        (None, None)
    } else {
        ai_memory_consolidate::read_identity_remotes(std::path::Path::new(cwd))
    };
    resolve(&IdentityInputs {
        explicit_identity,
        manifest_name: declared_project,
        upstream_remote: upstream.as_deref(),
        origin_remote: origin.as_deref(),
        folder_name: None,
    })
    .filter(|identity| identity.source.routes_by_identity())
}

/// [`CLIENT_MARKER_HEADER`] value the native hook sends on
/// every request to the server. Set per request rather than as a client
/// default because the same client also refreshes OIDC tokens with a third
/// party, which has no use for it.
const NATIVE_HOOK_CLIENT_KIND: &str = "hook";

/// Build a reqwest client for the hook's one-shot requests. `no_proxy`
/// ignores `HTTP_PROXY`, `HTTPS_PROXY` and `ALL_PROXY`, which have no
/// business on a loopback/LAN POST; reqwest is built without its
/// `system-proxy` feature, so no OS proxy setting is read either way.
/// Redirects are disabled so a 3xx from an SSO portal or proxy never drops
/// spooled events, replays payloads, or injects foreign HTML into context.
/// Built once per invocation and reused for both the event POST and the
/// handoff GET. Default root certs are kept so HTTPS targets (e.g. a TLS
/// proxy) still work.
pub fn build_client() -> reqwest::Client {
    reqwest::Client::builder()
        .no_proxy()
        .redirect(reqwest::redirect::Policy::none())
        .build()
        .unwrap_or_else(|_| reqwest::Client::new())
}

/// Outcome of one spooled-event POST — enough for the drain loop to decide
/// whether a miss should cost the entry a retry attempt. Never errors, so a
/// hook/flush never fails the agent.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PostOutcome {
    /// Server acknowledged with a 2xx (the engine answers `202 queued`): the
    /// entry was delivered and can be removed from the spool.
    Delivered,
    /// Server answered `429 Too Many Requests` (`hook queue full`): transient
    /// backpressure, the event was never processed. Keep it queued WITHOUT
    /// bumping attempts so saturation never burns the entry's retry budget.
    Saturated,
    /// Any other non-2xx: the server answered and refused. A genuine miss
    /// that should count against the retry limit.
    Failed,
    /// The request never reached a server — connection refused, DNS failure,
    /// or timeout. Distinguished from [`Self::Failed`] because it says
    /// something about the *endpoint* rather than the entry: every other
    /// spooled event addressed to the same endpoint will fail the same way,
    /// so the drain can skip past them instead of stopping at the first one
    /// (#493).
    Unreachable,
    /// `403` — the server understood the request and will never accept it.
    /// Today that means the author may not write the project
    /// the event belongs to.
    ///
    /// Terminal, and that is the whole point of separating it from
    /// [`Self::Failed`]. A refusal that counts as a failure gets re-sent until
    /// it exhausts the retry limit, and every one of those attempts is
    /// guaranteed to be refused for the same reason. Retrying something that
    /// cannot succeed is how a parse failure once cost this project 10.7M
    /// tokens in a day. The entry is dropped on the spot.
    Refused,
    /// `401` — the server rejected the bearer. Distinguished from
    /// [`Self::Failed`] because it says something about the *credential*
    /// rather than the entry: a spooled event carries the token frozen at
    /// capture time, so after a rotation every entry captured under the old
    /// one fails identically and is recoverable by retrying with the current
    /// token (#542).
    Unauthorized,
}

/// POST the payload as JSON, best-effort. `timeout` is caller-chosen: the
/// per-tool-call hot path no longer POSTs at all (it spools); the drain calls
/// this with a budget that tolerates a remote/slow server. Returns a
/// [`PostOutcome`] (never errors) so the drain can give a 429 (saturation) a
/// free retry while still bounding genuine failures by `MAX_ATTEMPTS`.
pub async fn post_hook(
    client: &reqwest::Client,
    url: &str,
    body: &str,
    token: Option<&str>,
    timeout: Duration,
) -> PostOutcome {
    let mut req = client
        .post(url)
        .header("Content-Type", "application/json")
        .header(CLIENT_MARKER_HEADER, NATIVE_HOOK_CLIENT_KIND)
        .timeout(timeout)
        .body(body.to_owned());
    if let Some(t) = token {
        req = req.bearer_auth(t);
    }
    match req.send().await {
        Ok(resp) if resp.status().is_success() => PostOutcome::Delivered,
        Ok(resp) if resp.status() == reqwest::StatusCode::TOO_MANY_REQUESTS => {
            PostOutcome::Saturated
        }
        Ok(resp) if resp.status() == reqwest::StatusCode::UNAUTHORIZED => PostOutcome::Unauthorized,
        Ok(resp) if resp.status() == reqwest::StatusCode::FORBIDDEN => PostOutcome::Refused,
        Ok(_) => PostOutcome::Failed,
        Err(_) => PostOutcome::Unreachable,
    }
}

/// Outcome of one `POST /hook/batch` request — many spooled events delivered in
/// a single round-trip, so a draining client amortizes TLS + network RTT + the
/// edge auth hop over the whole batch instead of paying it per event.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BatchOutcome {
    /// Modern server returned one terminal result for each acknowledged item.
    Detailed {
        /// Per-item processing outcomes in request order.
        outcomes: Vec<String>,
        /// Item that failed after any earlier acknowledged items.
        failed_index: Option<usize>,
    },
    /// Server committed the leading `usize` items (contiguous prefix, oldest
    /// first). Equals the request length on full success; a smaller value means
    /// the server stopped on that item (fail-fast) — the caller deletes the
    /// prefix and charges the next item a retry.
    Accepted(usize),
    /// Server committed these item indexes, which may be non-contiguous when it
    /// skipped per-source rate-limited events and continued with later sources.
    /// If `failed_index` is present, that item failed processing and should be
    /// charged instead of assuming the first unaccepted item failed.
    AcceptedIndices {
        indices: Vec<usize>,
        failed_index: Option<usize>,
    },
    /// `429` — ingest saturated after committing this many leading items. The
    /// caller deletes that prefix and retries the rest later WITHOUT bumping
    /// attempts (saturation isn't a failure).
    Saturated(usize),
    /// `429` with a non-contiguous committed set. New servers can include this
    /// when a global saturation happens after earlier skipped items.
    SaturatedIndices(Vec<usize>),
    /// The request never reached a server — connection refused, DNS failure,
    /// or timeout. Says something about the *endpoint*, not the batch: every
    /// other entry addressed there will fail identically, so the drain skips
    /// past them rather than stopping at the first (#493).
    Unreachable,
    /// `404`/`405` — the server has no `/hook/batch` (a pre-upgrade build). The
    /// caller falls back to per-event `POST /hook` for the rest of the drain.
    Unsupported,
    /// `401` — the server rejected the batch's bearer. See
    /// [`PostOutcome::Unauthorized`]; the whole batch shares one identity, so
    /// a rejected credential fails all of it and none of it was processed.
    Unauthorized,
    /// Transport error or any other non-2xx: the batch outcome is unknown. The
    /// drain charges conservatively so trailing events that may never have been
    /// attempted do not burn retry budget.
    Failed,
}

/// POST a pre-serialized JSON array of `{url, body}` events to `<batch_url>`.
/// `bearer` authenticates the whole batch (every item shares the drain's single
/// identity). Best-effort: never errors. Reads `{"accepted": K}` from a 2xx
/// body; a 2xx whose body can't be read is treated as `Failed` (re-send rather
/// than risk dropping undelivered events).
pub async fn post_batch(
    client: &reqwest::Client,
    batch_url: &str,
    payload: &str,
    token: Option<&str>,
    timeout: Duration,
) -> BatchOutcome {
    let mut req = client
        .post(batch_url)
        .header("Content-Type", "application/json")
        .header(CLIENT_MARKER_HEADER, NATIVE_HOOK_CLIENT_KIND)
        .timeout(timeout)
        .body(payload.to_owned());
    if let Some(t) = token {
        req = req.bearer_auth(t);
    }
    match req.send().await {
        Ok(resp) => {
            let status = resp.status();
            if status.is_success() {
                match resp.json::<serde_json::Value>().await {
                    Ok(v) => {
                        if let Some(outcomes) = batch_outcomes(&v) {
                            BatchOutcome::Detailed {
                                outcomes,
                                failed_index: failed_index(&v),
                            }
                        } else if let Some(indices) = accepted_indices(&v) {
                            BatchOutcome::AcceptedIndices {
                                indices,
                                failed_index: failed_index(&v),
                            }
                        } else {
                            let accepted = v
                                .get("accepted")
                                .and_then(serde_json::Value::as_u64)
                                .unwrap_or(0) as usize;
                            BatchOutcome::Accepted(accepted)
                        }
                    }
                    Err(_) => BatchOutcome::Failed,
                }
            } else if status == reqwest::StatusCode::TOO_MANY_REQUESTS {
                let body = resp.json::<serde_json::Value>().await.ok();
                if let Some(indices) = body.as_ref().and_then(accepted_indices) {
                    BatchOutcome::SaturatedIndices(indices)
                } else {
                    let accepted = body
                        .and_then(|v| {
                            v.get("accepted")
                                .and_then(serde_json::Value::as_u64)
                                .map(|n| n as usize)
                        })
                        .unwrap_or(0);
                    BatchOutcome::Saturated(accepted)
                }
            } else if status == reqwest::StatusCode::NOT_FOUND
                || status == reqwest::StatusCode::METHOD_NOT_ALLOWED
            {
                BatchOutcome::Unsupported
            } else if status == reqwest::StatusCode::UNAUTHORIZED {
                BatchOutcome::Unauthorized
            } else {
                BatchOutcome::Failed
            }
        }
        Err(_) => BatchOutcome::Unreachable,
    }
}

fn batch_outcomes(v: &serde_json::Value) -> Option<Vec<String>> {
    let results = v.get("results")?.as_array()?;
    let mut outcomes = Vec::with_capacity(results.len());
    for (position, result) in results.iter().enumerate() {
        if result.get("index")?.as_u64()? as usize != position {
            return None;
        }
        outcomes.push(result.get("outcome")?.as_str()?.to_owned());
    }
    Some(outcomes)
}

fn failed_index(v: &serde_json::Value) -> Option<usize> {
    v.get("failed_index")?.as_u64().map(|n| n as usize)
}

fn accepted_indices(v: &serde_json::Value) -> Option<Vec<usize>> {
    let arr = v.get("accepted_indices")?.as_array()?;
    let mut indices = Vec::with_capacity(arr.len());
    for item in arr {
        indices.push(item.as_u64()? as usize);
    }
    Some(indices)
}

/// GET the handoff text with a caller-chosen budget. Returns None on any error
/// or an empty body. This is the one synchronous read on the agent's critical
/// path (session-start injects it as context), so the budget is larger than a
/// loopback default to tolerate a remote server.
pub async fn get_handoff(
    client: &reqwest::Client,
    url: &str,
    token: Option<&str>,
    timeout: Duration,
) -> Option<String> {
    let mut req = client
        .get(url)
        .header(CLIENT_MARKER_HEADER, NATIVE_HOOK_CLIENT_KIND)
        .timeout(timeout);
    if let Some(t) = token {
        req = req.bearer_auth(t);
    }
    // Warn on stderr instead of failing silently: the hook still exits 0 (a
    // hook must never break the agent), but an unreachable server would
    // otherwise be indistinguishable from "no pending handoff" (#188).
    let resp = match req.send().await {
        Ok(r) => r,
        Err(e) => {
            eprintln!(
                "ai-memory hook warning: handoff fetch failed ({e}); \
                 a pending handoff (if any) was NOT injected"
            );
            return None;
        }
    };
    if resp.status() == reqwest::StatusCode::FORBIDDEN {
        // Not authorized for this repository (#708). Same reasoning as the
        // transport warning above: silence here would read as "nothing was
        // handed off", when the truth is "you cannot see what was". The body
        // is the server's reason and goes to stderr, never into context.
        let reason = resp.text().await.unwrap_or_default();
        eprintln!(
            "ai-memory hook warning: not authorized for this project's memory ({}); \
             nothing was injected",
            reason.trim()
        );
        return None;
    }
    if !resp.status().is_success() {
        return None;
    }
    let body = resp.text().await.ok()?;
    if body.is_empty() { None } else { Some(body) }
}

#[cfg(test)]
mod tests {
    use super::*;
    use tokio::io::{AsyncReadExt, AsyncWriteExt};

    /// Shadows [`super::marker_query_suffix`] for every test in this module,
    /// resolving against an empty operator home: the real one reads
    /// `home_dir()`, and a developer's own `~/.ai-memory.toml` applies to
    /// every cwd, so it would leak into the assertions. Tests that exercise a
    /// home marker pass one to `routing_selection_with_home` themselves.
    fn marker_query_suffix(cwd: &str, default_strategy: Option<&str>) -> String {
        let home = tempfile::TempDir::new().unwrap();
        match super::super::super::marker::routing_selection_with_home(
            cwd,
            cwd,
            Some(home.path()),
            false,
        ) {
            Ok(selection) => marker_query_suffix_impl_from_selection(
                cwd,
                default_strategy,
                Some(BriefingKey::SessionStart),
                selection,
            ),
            Err(_) => String::new(),
        }
    }

    /// Shadows [`super::hook_scope`] the same way, for the same reason.
    fn hook_scope(cwd: &str, default_strategy: Option<&str>) -> HookScope {
        let home = tempfile::TempDir::new().unwrap();
        hook_scope_with_home(cwd, default_strategy, Some(home.path()))
    }

    /// Shadows [`super::marker_requests_briefing`] the same way, for the same
    /// reason.
    fn marker_requests_briefing(cwd: &str) -> bool {
        let home = tempfile::TempDir::new().unwrap();
        marker_requests_briefing_with_home(cwd, Some(home.path()), BriefingKey::SessionStart)
    }

    async fn serve_once(status: &'static str, body: &'static str) -> String {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            let (mut stream, _) = listener.accept().await.unwrap();
            let mut buf = [0_u8; 1024];
            let _ = stream.read(&mut buf).await;
            let response = format!(
                "HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
                body.len()
            );
            let _ = stream.write_all(response.as_bytes()).await;
        });
        format!("http://{addr}/handoff")
    }

    #[test]
    fn extracts_top_level_cwd() {
        let p: serde_json::Value =
            serde_json::from_str(r#"{"cwd":"/d/proj","tool_input":{"cwd":"/nested"}}"#).unwrap();
        assert_eq!(extract_cwd(&p).as_deref(), Some("/d/proj"));
    }

    #[test]
    fn missing_cwd_is_none() {
        let p: serde_json::Value = serde_json::from_str(r#"{"x":1}"#).unwrap();
        assert_eq!(extract_cwd(&p), None);
    }

    #[test]
    fn resolve_cwd_prefers_payload_over_env_and_process_cwd() {
        let p: serde_json::Value = serde_json::from_str(r#"{"cwd":"/payload"}"#).unwrap();

        let cwd = resolve_cwd_with_fallbacks(
            &p,
            |_| Some("/env".into()),
            || Some(PathBuf::from("/process")),
        );

        assert_eq!(cwd.as_deref(), Some("/payload"));
    }

    #[test]
    fn resolve_cwd_uses_devin_project_dir_when_payload_omits_cwd() {
        let p: serde_json::Value = serde_json::from_str(r#"{"source":"startup"}"#).unwrap();

        let cwd = resolve_cwd_with_fallbacks(
            &p,
            |name| (name == "DEVIN_PROJECT_DIR").then(|| "/env-project".into()),
            || Some(PathBuf::from("/process")),
        );

        assert_eq!(cwd.as_deref(), Some("/env-project"));
    }

    #[test]
    fn resolve_cwd_uses_process_cwd_when_payload_and_env_omit_cwd() {
        let p: serde_json::Value = serde_json::from_str(r#"{"source":"startup"}"#).unwrap();

        let cwd =
            resolve_cwd_with_fallbacks(&p, |_| None, || Some(PathBuf::from("process-project")));

        assert_eq!(cwd.as_deref(), Some("process-project"));
    }

    #[test]
    fn query_suffix_without_marker_has_only_cwd() {
        let qs = marker_query_suffix("/nonexistent/path/xyz", None);
        assert_eq!(qs, "&cwd=%2Fnonexistent%2Fpath%2Fxyz");
    }

    #[test]
    fn url_encode_escapes_reserved() {
        assert_eq!(url_encode("a b&c=d"), "a%20b%26c%3Dd");
    }

    #[tokio::test]
    async fn post_hook_unreachable_when_server_is_not_listening() {
        // Port 1 is unroutable. Best-effort means this resolves to an outcome
        // rather than panicking — and specifically to `Unreachable`, not
        // `Failed`: the request never reached a server, so the result says
        // something about the endpoint rather than about this event. The drain
        // relies on that distinction to skip past a dead address instead of
        // stalling the whole spool behind it (#493).
        let client = build_client();
        let outcome = post_hook(
            &client,
            "http://127.0.0.1:1/hook?event=pre-tool-use",
            "{}",
            None,
            Duration::from_millis(500),
        )
        .await;
        assert_eq!(outcome, PostOutcome::Unreachable);
    }

    #[tokio::test]
    async fn post_hook_saturated_on_429() {
        // 429 = server backpressure; the event was never processed, so the
        // drain must treat it as a free retry, not a failed attempt.
        let url = serve_once("429 Too Many Requests", "hook queue full").await;
        let outcome = post_hook(&build_client(), &url, "{}", None, Duration::from_secs(1)).await;
        assert_eq!(outcome, PostOutcome::Saturated);
    }

    #[tokio::test]
    async fn post_hook_delivered_on_2xx() {
        let url = serve_once("202 Accepted", "queued").await;
        let outcome = post_hook(&build_client(), &url, "{}", None, Duration::from_secs(1)).await;
        assert_eq!(outcome, PostOutcome::Delivered);
    }

    #[tokio::test]
    async fn post_hook_refused_on_403_is_terminal_not_a_failure() {
        // 403 means the server will never accept this event. Classifying it as
        // `Failed` would re-send it until it burnt the retry limit, and every
        // attempt would be refused identically — the shape of retry loop that
        // once cost this project 10.7M tokens in a day. It must be its own
        // outcome so the drain can drop it on the spot.
        let url = serve_once("403 Forbidden", "capture not authorized").await;
        let outcome = post_hook(&build_client(), &url, "{}", None, Duration::from_secs(1)).await;
        assert_eq!(outcome, PostOutcome::Refused);
        assert_ne!(
            outcome,
            PostOutcome::Failed,
            "a refusal must never be charged a retry attempt"
        );
    }

    #[tokio::test]
    async fn post_hook_408_and_425_are_retryable_failed_not_refused() {
        // 408 (request timeout) and 425 (too early) say "retry me", not
        // "never": they must fall through to `Failed` so the spool keeps the
        // entry queued subject to the attempt limit. Classifying every 4xx as
        // a terminal refusal deleted such events on the spot (#1092
        // regression).
        for status in ["408 Request Timeout", "425 Too Early"] {
            let url = serve_once(status, "retry later").await;
            let outcome =
                post_hook(&build_client(), &url, "{}", None, Duration::from_secs(1)).await;
            assert_ne!(
                outcome,
                PostOutcome::Refused,
                "{status} is retryable and must not be terminal"
            );
            assert_eq!(outcome, PostOutcome::Failed, "{status} is a retryable miss");
        }
    }

    #[tokio::test]
    async fn post_batch_unhandled_4xx_is_retryable_failed() {
        // Base semantics: only 401/404/405/429 are special-cased for batches;
        // every other status — 400, and retryable timeouts like 408/425 — is
        // a `Failed` with an unknown outcome, never a terminal refusal.
        for status in ["400 Bad Request", "408 Request Timeout", "425 Too Early"] {
            let url = serve_once(status, "invalid batch").await;
            let outcome =
                post_batch(&build_client(), &url, "[]", None, Duration::from_secs(1)).await;
            assert_eq!(outcome, BatchOutcome::Failed, "{status} is retryable");
        }
    }

    #[tokio::test]
    async fn get_handoff_never_injects_a_refusal() {
        // A 403 carries the server's reason (#708). It is reported on stderr
        // and must not reach the agent as context.
        let url = serve_once(
            "403 Forbidden",
            "not authorized for scratch. This is an access problem, not an empty memory",
        )
        .await;
        let got = get_handoff(&build_client(), &url, None, Duration::from_secs(1)).await;
        assert!(got.is_none(), "a refusal must not become context");
    }

    #[tokio::test]
    async fn get_handoff_ignores_non_success_status() {
        let url = serve_once("401 Unauthorized", "unauthorized").await;
        let got = get_handoff(&build_client(), &url, None, Duration::from_secs(1)).await;
        assert!(got.is_none(), "non-2xx body must not become context");
    }

    async fn redirect_server(status: &'static str, target_url: &str) -> String {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let target = target_url.to_owned();
        tokio::spawn(async move {
            let (mut stream, _) = listener.accept().await.unwrap();
            let mut buf = [0_u8; 1024];
            let _ = stream.read(&mut buf).await;
            let response = format!(
                "HTTP/1.1 {status}\r\nLocation: {target}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
            );
            let _ = stream.write_all(response.as_bytes()).await;
        });
        format!("http://{addr}/redirect")
    }

    #[tokio::test]
    async fn build_client_refuses_redirects() {
        let target = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let target_url = format!("http://{}/target", target.local_addr().unwrap());
        let source_url = redirect_server("307 Temporary Redirect", &target_url).await;

        let response = build_client().get(&source_url).send().await.unwrap();
        assert_eq!(response.status(), reqwest::StatusCode::TEMPORARY_REDIRECT);
        assert!(
            tokio::time::timeout(Duration::from_millis(100), target.accept())
                .await
                .is_err(),
            "redirect target must never be contacted"
        );
    }

    #[tokio::test]
    async fn post_hook_does_not_follow_redirect() {
        let target = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let target_url = format!("http://{}/target", target.local_addr().unwrap());
        let source_url = redirect_server("307 Temporary Redirect", &target_url).await;

        let outcome = post_hook(
            &build_client(),
            &source_url,
            "{}",
            None,
            Duration::from_secs(1),
        )
        .await;
        assert_eq!(outcome, PostOutcome::Failed);
        assert!(
            tokio::time::timeout(Duration::from_millis(100), target.accept())
                .await
                .is_err(),
            "redirect target must never be contacted"
        );
    }

    #[tokio::test]
    async fn post_batch_does_not_follow_redirect() {
        let target = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let target_url = format!("http://{}/target", target.local_addr().unwrap());
        let source_url = redirect_server("307 Temporary Redirect", &target_url).await;

        let outcome = post_batch(
            &build_client(),
            &source_url,
            "[]",
            None,
            Duration::from_secs(1),
        )
        .await;
        assert_eq!(outcome, BatchOutcome::Failed);
        assert!(
            tokio::time::timeout(Duration::from_millis(100), target.accept())
                .await
                .is_err(),
            "redirect target must never be contacted"
        );
    }

    #[tokio::test]
    async fn get_handoff_does_not_follow_redirect() {
        let target = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let target_url = format!("http://{}/login", target.local_addr().unwrap());
        let source_url = redirect_server("302 Found", &target_url).await;

        let got = get_handoff(&build_client(), &source_url, None, Duration::from_secs(1)).await;
        assert!(got.is_none(), "redirect must not inject target content");
        assert!(
            tokio::time::timeout(Duration::from_millis(100), target.accept())
                .await
                .is_err(),
            "redirect target must never be contacted"
        );
    }

    /// Like `serve_once`, but answers 200 and hands back the raw request.
    async fn capture_once() -> (String, tokio::task::JoinHandle<String>) {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let handle = tokio::spawn(async move {
            let (mut stream, _) = listener.accept().await.unwrap();
            // Read until the end of the headers; the body is irrelevant.
            let mut head = Vec::new();
            let mut buf = [0_u8; 4096];
            while !head.windows(4).any(|w| w == b"\r\n\r\n") {
                let n = stream.read(&mut buf).await.unwrap();
                if n == 0 {
                    break;
                }
                head.extend_from_slice(&buf[..n]);
            }
            let body = "ok";
            let response = format!(
                "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
                body.len()
            );
            let _ = stream.write_all(response.as_bytes()).await;
            String::from_utf8_lossy(&head).to_ascii_lowercase()
        });
        (format!("http://{addr}"), handle)
    }

    #[tokio::test]
    async fn every_native_hook_request_carries_the_client_marker() {
        // An unauthenticated server reached by a LAN name refuses a handoff
        // fetch without it, and hook events ride the same contract.
        let marker = format!("{CLIENT_MARKER_HEADER}: hook\r\n");
        let (base, request) = capture_once().await;
        get_handoff(
            &build_client(),
            &format!("{base}/handoff?agent=claude-code"),
            None,
            Duration::from_secs(2),
        )
        .await;
        let request = request.await.unwrap();
        assert!(request.starts_with("get /handoff?"), "{request}");
        assert!(request.contains(&marker), "handoff GET: {request}");

        let (base, request) = capture_once().await;
        post_hook(
            &build_client(),
            &format!("{base}/hook?event=stop"),
            "{}",
            None,
            Duration::from_secs(2),
        )
        .await;
        assert!(request.await.unwrap().contains(&marker), "hook POST");

        let (base, request) = capture_once().await;
        post_batch(
            &build_client(),
            &format!("{base}/hook/batch"),
            "[]",
            None,
            Duration::from_secs(2),
        )
        .await;
        assert!(request.await.unwrap().contains(&marker), "batch POST");
    }

    // The marker parser's own tests (`parse_toml_key`, `find_marker`) moved to
    // `crate::marker` along with the code. What stays here is hook-specific:
    // the strict `[capture]` section and the query-string suffix.

    #[test]
    fn capture_section_is_strict_and_marker_read_is_bounded() {
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        std::fs::write(
            &marker,
            "workspace = \"allowed\"\n[capture]\nignore_paths = [\"secret/**\"]\n",
        )
        .unwrap();
        assert_eq!(
            read_capture_config(&marker).unwrap().ignore_paths,
            ["secret/**"]
        );
        std::fs::write(&marker, "[capture]\nunknown = true\n").unwrap();
        assert!(read_capture_config(&marker).is_err());
        std::fs::write(&marker, "[capture\n").unwrap();
        assert!(read_capture_config(&marker).is_err());
        std::fs::write(&marker, "x".repeat(MAX_MARKER_BYTES + 1)).unwrap();
        assert!(read_capture_config(&marker).is_err());
    }

    /// Every TOML spelling of `[capture]` the native parser honours, and the
    /// ones it rejects, from the shared fixture the generated TypeScript
    /// reader's Node runtime evidence runs too: a dotted top-level key or a
    /// quoted table name must not escape either reader, and a shape toml_edit
    /// rejects (an inline table, `[[capture]]`) fails closed in both.
    #[test]
    fn capture_section_spellings_match_toml_semantics() {
        let fixture: serde_json::Value = serde_json::from_str(include_str!(
            "../../../ai-memory-hooks/tests/fixtures/capture-policy.json"
        ))
        .unwrap();
        let spellings = &fixture["marker_spellings"];
        let texts = |kind: &str| {
            spellings[kind]
                .as_array()
                .unwrap()
                .iter()
                .map(|text| text.as_str().unwrap().to_owned())
                .collect::<Vec<_>>()
        };
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        let read = |text: &str| {
            std::fs::write(&marker, text).unwrap();
            read_capture_config(&marker).map(|config| config.ignore_paths)
        };
        for honoured in texts("honoured") {
            assert_eq!(
                read(&honoured),
                Ok(vec!["secret/**".to_owned()]),
                "{honoured}"
            );
        }
        for rejected in texts("rejected") {
            assert!(read(&rejected).is_err(), "{rejected}");
        }
        for unrelated in texts("unrelated") {
            assert_eq!(read(&unrelated), Ok(Vec::new()), "{unrelated}");
        }
    }

    #[test]
    fn canonical_context_matches_supported_routing_shapes() {
        let agy =
            serde_json::json!({"workspacePaths":["/workspace/project"],"conversationId":"conv"});
        assert_eq!(
            canonical_context(&agy),
            (Some("/workspace/project".into()), Some("conv".into()))
        );
        let generated = serde_json::json!({"payload":{"properties":{"info":{"directory":"/generated"},"sessionID":"nested"}}});
        assert_eq!(
            canonical_context(&generated),
            (Some("/generated".into()), Some("nested".into()))
        );
    }

    /// Cursor routes the workspace directory through `workspace_roots`:
    /// `sessionStart` omits `cwd` entirely and tool events send `cwd: ""`.
    /// Both must resolve, or every Cursor event reaches the server with no
    /// cwd and is filed under the default `scratch` project. Shapes captured
    /// live from Cursor CLI 2026.09.02-c22c1a3.
    #[test]
    fn canonical_context_reads_cursor_workspace_roots() {
        let session_start = serde_json::json!({
            "session_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
            "hook_event_name": "sessionStart",
            "cursor_version": "2026.09.02-c22c1a3",
            "workspace_roots": ["/checkouts/repo-a"]
        });
        assert_eq!(
            canonical_context(&session_start),
            (
                Some("/checkouts/repo-a".into()),
                Some("cf111450-8c45-4da1-a384-7a48e08099c3".into())
            )
        );

        let tool_event = serde_json::json!({
            "session_id": "cf111450-8c45-4da1-a384-7a48e08099c3",
            "hook_event_name": "postToolUse",
            "cursor_version": "2026.09.02-c22c1a3",
            "cwd": "",
            "workspace_roots": ["/checkouts/repo-a"]
        });
        assert_eq!(
            canonical_context(&tool_event).0,
            Some("/checkouts/repo-a".into())
        );
    }

    /// Cline file hooks send no top-level `cwd` and no `session_id`: the
    /// checkout arrives as `workspaceRoots` and the session as `taskId`
    /// (#1888). Routing already reads both, so the capture gate must too, or
    /// allowlist mode finds no marker and drops every Cline event. Shape
    /// abridged from a Cline CLI 3.0.74 `TaskStart` payload.
    #[test]
    fn canonical_context_reads_cline_workspace_roots_and_task_id() {
        let task_start = serde_json::json!({
            "taskId": "conv_cline-task",
            "hookName": "agent_start",
            "sessionContext": {"rootSessionId": "root"},
            "workspaceRoots": ["/checkouts/repo-a", "/checkouts/repo-b"],
            "workspaceInfo": {"rootPath": "/checkouts/repo-a", "latestGitBranchName": "main"}
        });
        assert_eq!(
            canonical_context(&task_start),
            (
                Some("/checkouts/repo-a".into()),
                Some("conv_cline-task".into())
            )
        );
        let routing = ai_memory_hooks::payload::hook_payload_context(&task_start);
        assert_eq!(
            canonical_context(&task_start),
            (routing.cwd, routing.session_id)
        );
    }

    /// `marker_query_suffix` appends `&workspace=…&project=…` (and
    /// `&project_strategy=…`, `&drop_subagent=…`) when the marker declares them.
    /// Each value is URL-encoded, so a workspace with a space round-trips as `%20`.
    /// Regression for #188: a Windows cwd must be fully percent-encoded or
    /// the HTTP layer refuses the request URL and the session-start hook
    /// silently returns `{}` while the handoff stays pending.
    #[test]
    fn url_encode_is_an_unreserved_allow_list() {
        // The reported case: raw `\` and `:` broke the request outright.
        assert_eq!(url_encode(r"C:\dev\myproject"), "C%3A%5Cdev%5Cmyproject");
        // RFC 3986 unreserved passes through untouched.
        assert_eq!(url_encode("abc-XYZ_0.9~"), "abc-XYZ_0.9~");
        // Previous deny-list behavior is preserved (space, slash, etc.).
        assert_eq!(url_encode("/home/u/my repo"), "%2Fhome%2Fu%2Fmy%20repo");
        // Multibyte UTF-8 is encoded per byte.
        assert_eq!(url_encode("r\u{e9}po"), "r%C3%A9po");
    }

    /// The full marker suffix built from a Windows cwd must parse as a real
    /// URL query — the end-to-end guarantee behind the #188 fix.
    #[test]
    fn marker_query_suffix_windows_cwd_yields_parseable_url() {
        let qs = marker_query_suffix(r"C:\dev\myproject", None);
        assert!(qs.contains("cwd=C%3A%5Cdev%5Cmyproject"), "{qs}");
        let url = format!("http://127.0.0.1:49374/handoff?agent=claude-code{qs}");
        let parsed = reqwest::Url::parse(&url).expect("must be a valid URL");
        let cwd = parsed
            .query_pairs()
            .find(|(k, _)| k == "cwd")
            .map(|(_, v)| v.into_owned())
            .expect("cwd param present");
        assert_eq!(
            cwd, r"C:\dev\myproject",
            "round-trips through percent-decoding"
        );
    }

    /// A throwaway repository with the given remotes, or `None` when there is
    /// no `git` binary to build one with. The host is not a real forge, so a
    /// developer's global `url.<base>.insteadOf` rules cannot rewrite it.
    fn repo_with_remotes(remotes: &[(&str, &str)]) -> Option<tempfile::TempDir> {
        let git = |args: &[&str], dir: &std::path::Path| {
            std::process::Command::new("git")
                .arg("-C")
                .arg(dir)
                .args(args)
                .status()
                .ok()
                .filter(std::process::ExitStatus::success)
        };
        let tmp = tempfile::TempDir::new().unwrap();
        git(&["init", "-q"], tmp.path())?;
        for (name, url) in remotes {
            git(&["remote", "add", name, url], tmp.path())?;
        }
        Some(tmp)
    }

    /// An undeclared checkout sends the identity of its remote — `upstream`
    /// over `origin` — normalised on this side, so the credentials in the URL
    /// never reach the query string.
    #[test]
    fn marker_query_suffix_sends_the_remote_identity_of_an_undeclared_checkout() {
        let Some(repo) = repo_with_remotes(&[
            (
                "origin",
                "https://someone:[email protected]/Fork/API.git",
            ),
            ("upstream", "[email protected]:Acme/API.git"),
        ]) else {
            return;
        };
        let qs = marker_query_suffix(repo.path().to_str().unwrap(), None);
        assert!(
            qs.contains("&identity=git.example.test%2Facme%2Fapi&identity_src=git_remote&identity_style=path"),
            "{qs}"
        );
        assert!(
            !qs.contains("s3cret"),
            "credentials must not leave the machine: {qs}"
        );

        let Some(origin_only) = repo_with_remotes(&[(
            "origin",
            "https://someone:[email protected]/Fork/API.git",
        )]) else {
            return;
        };
        let qs = marker_query_suffix(origin_only.path().to_str().unwrap(), None);
        assert!(
            qs.contains("&identity=git.example.test%2Ffork%2Fapi"),
            "{qs}"
        );
        assert!(!qs.contains("s3cret"), "{qs}");
        let scope =
            serde_json::to_value(hook_scope(origin_only.path().to_str().unwrap(), None)).unwrap();
        assert_eq!(scope["identity"], "git.example.test/fork/api");
        assert_eq!(scope["identity_src"], "git_remote");
        assert!(!scope.to_string().contains("s3cret"));
    }

    /// A declared `project` outranks the remote and routes by name, so nothing
    /// is sent for it; an explicit `identity` outranks both.
    #[test]
    fn marker_query_suffix_lets_declarations_decide_the_identity() {
        let Some(repo) = repo_with_remotes(&[("upstream", "[email protected]:acme/tool.git")])
        else {
            return;
        };
        let cwd = repo.path().to_str().unwrap();
        let marker = repo.path().join(".ai-memory.toml");

        std::fs::write(&marker, "project = \"my-fork\"\n").unwrap();
        let qs = marker_query_suffix(cwd, None);
        assert!(qs.contains("&project=my-fork"), "{qs}");
        assert!(
            !qs.contains("&identity="),
            "a declared project routes by name: {qs}"
        );

        std::fs::write(
            &marker,
            "project = \"my-fork\"\nidentity = \"Acme/Platform\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(cwd, None);
        assert!(
            qs.contains("&identity=acme%2Fplatform&identity_src=explicit"),
            "{qs}"
        );
    }

    #[test]
    fn marker_aliases_keep_project_canonical_and_forward_remote_identity() {
        let Some(repo) = repo_with_remotes(&[("origin", "[email protected]:acme/api.git")])
        else {
            return;
        };
        let cwd = repo.path().to_str().unwrap();
        std::fs::write(
            repo.path().join(".ai-memory.toml"),
            "project = \"acme-api\"\naliases = [\" former-name \", \"legacy_name\", \"former-name\"]\n",
        )
        .unwrap();
        let qs = marker_query_suffix(cwd, None);
        let url = reqwest::Url::parse(&format!("http://localhost/handoff?agent=test{qs}")).unwrap();
        let params = url
            .query_pairs()
            .into_owned()
            .collect::<std::collections::HashMap<_, _>>();
        assert_eq!(params.get("project").map(String::as_str), Some("acme-api"));
        assert_eq!(
            params.get("identity").map(String::as_str),
            Some("git.example.test/acme/api")
        );
        assert_eq!(
            params.get("identity_src").map(String::as_str),
            Some("git_remote")
        );
        assert_eq!(
            params.get("aliases").map(String::as_str),
            Some("[\"former-name\",\"legacy_name\"]")
        );
    }

    /// #1033: every valid remote carries a style. Omission and invalid marker
    /// values send `path`; explicit `host_path` remains the opt-out. A declared
    /// project or identity has no inferred remote style.
    #[test]
    fn marker_query_suffix_forwards_the_path_style_with_a_remote_identity() {
        let Some(repo) = repo_with_remotes(&[("origin", "[email protected]:acme/api.git")])
        else {
            return;
        };
        let cwd = repo.path().to_str().unwrap();
        let marker = repo.path().join(".ai-memory.toml");

        std::fs::write(&marker, "").unwrap();
        let qs = marker_query_suffix(cwd, None);
        assert!(
            qs.contains("&identity_src=git_remote&identity_style=path"),
            "{qs}"
        );

        std::fs::write(&marker, "identity_style = \"path\"\n").unwrap();
        let qs = marker_query_suffix(cwd, None);
        assert!(
            qs.contains("&identity_src=git_remote&identity_style=path"),
            "{qs}"
        );
        let scope = serde_json::to_value(hook_scope(cwd, None)).unwrap();
        assert_eq!(scope["identity_style"], "path");

        std::fs::write(&marker, "identity_style = \"host_path\"\n").unwrap();
        let qs = marker_query_suffix(cwd, None);
        assert!(
            qs.contains("&identity_src=git_remote&identity_style=host_path"),
            "{qs}"
        );

        std::fs::write(&marker, "identity_style = \"Path\"\n").unwrap();
        let qs = marker_query_suffix(cwd, None);
        assert!(qs.contains("&identity_style=path"), "{qs}");

        for (body, why) in [
            (
                "identity_style = \"path\"\nproject = \"api\"\n",
                "a declared project routes by name",
            ),
            (
                "identity_style = \"path\"\nidentity = \"acme/api\"\n",
                "a declared identity keeps its own name",
            ),
        ] {
            std::fs::write(&marker, body).unwrap();
            let qs = marker_query_suffix(cwd, None);
            assert!(!qs.contains("identity_style"), "{why}: {qs}");
        }
    }

    /// The forwarding decision every client makes, against the shared fixture.
    #[test]
    fn forwarded_identity_style_matches_the_shared_fixture() {
        let cases: serde_json::Value = serde_json::from_str(include_str!(
            "../../../ai-memory-core/fixtures/remote_identity_cases.json"
        ))
        .unwrap();
        for case in cases["identity_style"].as_array().unwrap() {
            let value = case["value"].as_str().unwrap();
            let expected = case["style"].as_str().unwrap_or("path");
            assert_eq!(forwarded_identity_style(Some(value)), expected, "{value:?}");
        }
        assert_eq!(forwarded_identity_style(None), "path");
    }

    /// No repository, no remote, no declaration: nothing to send, and the
    /// server routes by folder name exactly as before.
    #[test]
    fn marker_query_suffix_sends_no_identity_outside_a_repository() {
        let tmp = tempfile::TempDir::new().unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(!qs.contains("identity"), "{qs}");
    }

    #[test]
    fn matched_home_route_keeps_root_behavior_flags() {
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = home.join("src/api/lib");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            home.join(".ai-memory.toml"),
            "workspace=\"wrong\"\nproject=\"wrong\"\nproject_strategy=\"repo-root\"\ndrop_subagent_captures=\"true\"\n[recall]\ndefault_global=true\n[briefing]\ninject_on_session_start=true\nmax_chars=3210\n[profile]\ncontribute=true\nconsume=false\n[routes.path.\"~/src/api\"]\nroute_workspace=\"right\"\nroute_project=\"api\"\n",
        )
        .unwrap();
        let selection = super::super::super::marker::routing_selection_with_home(
            repo.to_str().unwrap(),
            repo.to_str().unwrap(),
            Some(&home),
            false,
        )
        .unwrap();
        let query = marker_query_suffix_impl_from_selection(
            repo.to_str().unwrap(),
            None,
            Some(BriefingKey::SessionStart),
            selection,
        );
        for expected in [
            "&workspace=right",
            "&project=api",
            "&drop_subagent=true",
            "&default_global=true",
            "&briefing=true",
            "&briefing_budget=3210",
            "&profile_contribute=1",
            "&profile_consume=0",
        ] {
            assert!(query.contains(expected), "{expected}: {query}");
        }
        assert!(!query.contains("project_strategy="), "{query}");
        assert!(!query.contains("workspace=wrong"), "{query}");
    }

    #[test]
    fn non_git_home_path_route_omits_aliases() {
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = home.join("src/api");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            home.join(".ai-memory.toml"),
            "[routes.path.\"~/src/api\"]\nroute_workspace=\"path\"\nroute_project=\"api\"\nroute_aliases=[\"old-api\"]\n",
        )
        .unwrap();
        let selection = super::super::super::marker::routing_selection_with_home(
            repo.to_str().unwrap(),
            repo.to_str().unwrap(),
            Some(&home),
            false,
        )
        .unwrap();
        let query =
            marker_query_suffix_impl_from_selection(repo.to_str().unwrap(), None, None, selection);
        assert!(query.contains("&workspace=path&project=api"), "{query}");
        assert!(!query.contains("aliases="), "{query}");
        assert!(!query.contains("identity_src="), "{query}");
    }

    #[test]
    fn invalid_home_routes_produce_no_hook_scope_or_query() {
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = home.join("repo");
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            home.join(".ai-memory.toml"),
            "workspace=\"wrong\"\nproject=\"wrong\"\n[routes.path.\"relative\"]\nroute_workspace=\"route\"\nroute_project=\"route\"\n",
        )
        .unwrap();
        let result = super::super::super::marker::routing_selection_with_home(
            repo.to_str().unwrap(),
            repo.to_str().unwrap(),
            Some(&home),
            false,
        );
        assert!(result.is_err());
    }

    #[test]
    fn marker_query_suffix_appends_marker_fields() {
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        std::fs::write(
            &marker,
            r#"
workspace = "acme corp"
project = "infra"
project_strategy = "repo-root"
drop_subagent_captures = "true"
"#,
        )
        .unwrap();
        let cwd = tmp.path().to_str().unwrap();
        let qs = marker_query_suffix(cwd, None);
        // cwd is encoded first; marker fields follow in the iteration order
        // of the loop in `marker_query_suffix`.
        assert!(qs.contains("&workspace=acme%20corp"), "{qs}");
        assert!(qs.contains("&project=infra"), "{qs}");
        assert!(qs.contains("&project_strategy=repo-root"), "{qs}");
        assert!(qs.contains("&drop_subagent=true"), "{qs}");
    }

    /// `[profile] contribute` / `consume` are forwarded as written (quoted or
    /// bare) for the server to interpret, and a marker that sets only them is
    /// a settings boundary; a marker without them forwards nothing.
    #[test]
    fn marker_query_suffix_forwards_the_profile_flags() {
        let tmp = tempfile::TempDir::new().unwrap();
        let inner = tmp.path().join("inner");
        std::fs::create_dir(&inner).unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"outer\"\n",
        )
        .unwrap();
        std::fs::write(
            inner.join(".ai-memory.toml"),
            "[profile]\ncontribute = false\nconsume = \"no\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(inner.to_str().unwrap(), None);
        assert!(qs.contains("&profile_contribute=0"), "{qs}");
        assert!(qs.contains("&profile_consume=0"), "{qs}");
        assert!(
            !qs.contains("workspace=outer"),
            "a [profile] marker is a boundary: {qs}"
        );
        // A resolved marker without the keys states the defaults explicitly,
        // so removing an opt-out from the marker turns it back on.
        let outer = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(
            outer.contains("&profile_contribute=1&profile_consume=1"),
            "{outer}"
        );
        // No marker at all: nothing is sent, so the server keeps what it stored.
        let bare = tempfile::TempDir::new().unwrap();
        let none = marker_query_suffix(bare.path().to_str().unwrap(), None);
        assert!(!none.contains("profile_"), "{none}");
    }

    /// `[handoff] deliver_on_session_start` is forwarded as `&handoff=0` only
    /// when explicitly falsy; every other shape leaves the request unchanged,
    /// and a `[handoff]`-only marker is a settings boundary.
    #[test]
    fn marker_query_suffix_forwards_the_handoff_opt_out_only_when_falsy() {
        let tmp = tempfile::TempDir::new().unwrap();
        let inner = tmp.path().join("inner");
        std::fs::create_dir(&inner).unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"outer\"\n",
        )
        .unwrap();
        for off in ["false", "\"no\"", "0", "\"OFF\""] {
            std::fs::write(
                inner.join(".ai-memory.toml"),
                format!("[handoff]\ndeliver_on_session_start = {off}\n"),
            )
            .unwrap();
            let qs = marker_query_suffix(inner.to_str().unwrap(), None);
            assert!(qs.contains("&handoff=0"), "{off}: {qs}");
            assert!(
                !qs.contains("workspace=outer"),
                "a [handoff] marker is a boundary: {qs}"
            );
        }
        for on in ["true", "\"yes\"", "banana"] {
            std::fs::write(
                inner.join(".ai-memory.toml"),
                format!("[handoff]\ndeliver_on_session_start = {on}\n"),
            )
            .unwrap();
            let qs = marker_query_suffix(inner.to_str().unwrap(), None);
            assert!(!qs.contains("handoff"), "{on}: {qs}");
        }
        // The sibling project keeps delivering: the opt-out is read from the
        // nearest settings marker only.
        let outer = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(!outer.contains("handoff"), "{outer}");
    }

    /// A marker WITHOUT `drop_subagent_captures` does not forward the flag, so
    /// the server keeps that project's subagent captures (opt-in only).
    #[test]
    fn marker_query_suffix_omits_drop_subagent_when_unset() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\nproject = \"infra\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(!qs.contains("drop_subagent"), "{qs}");
    }

    /// A `[recall] default_global` marker (bare `true`, under a section)
    /// forwards the flag so the server can broaden default-scoped reads.
    #[test]
    fn marker_query_suffix_appends_default_global() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\n[recall]\ndefault_global = true\n",
        )
        .unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(qs.contains("&default_global=true"), "{qs}");
    }

    #[test]
    fn marker_query_suffix_omits_default_global_when_unset() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\nproject = \"infra\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(!qs.contains("default_global"), "{qs}");
    }

    /// A `[briefing]` section (bare or quoted values) forwards the opt-in
    /// and the char budget so the session-start `/handoff` GET can compose
    /// the project brief (#176).
    #[test]
    fn marker_query_suffix_appends_briefing_opt_in() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\n[briefing]\ninject_on_session_start = true\nmax_chars = 6000\n",
        )
        .unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(qs.contains("&briefing=true"), "{qs}");
        assert!(qs.contains("&briefing_budget=6000"), "{qs}");
    }

    #[test]
    fn marker_query_suffix_omits_briefing_when_unset() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\nproject = \"infra\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), None);
        assert!(!qs.contains("briefing"), "{qs}");
    }

    /// `[briefing] inject_on_subagent_start` is its own opt-in: it rides only
    /// the subagent-start query, and the session-start query keeps forwarding
    /// `inject_on_session_start` alone, so neither turns the other on.
    #[test]
    fn subagent_brief_query_forwards_only_its_own_opt_in() {
        let tmp = tempfile::TempDir::new().unwrap();
        let cwd = tmp.path().to_str().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        let subagent_query = || {
            let home = tempfile::TempDir::new().unwrap();
            let selection = super::super::super::marker::routing_selection_with_home(
                cwd,
                cwd,
                Some(home.path()),
                false,
            );
            marker_query_suffix_impl_from_selection(
                cwd,
                None,
                Some(BriefingKey::SubagentStart),
                selection.unwrap(),
            )
        };

        std::fs::write(
            &marker,
            "[briefing]\ninject_on_subagent_start = true\nmax_chars = 6000\n",
        )
        .unwrap();
        let qs = subagent_query();
        assert!(qs.contains("&cwd="), "{qs}");
        assert!(qs.contains("&briefing=true"), "{qs}");
        assert!(qs.contains("&briefing_budget=6000"), "{qs}");
        // `max_chars` rides along with or without an opt-in, as it always has;
        // only `&briefing=` turns a brief on.
        let qs = marker_query_suffix(cwd, None);
        assert!(
            !qs.contains("&briefing="),
            "session start must not inherit it: {qs}"
        );

        std::fs::write(
            &marker,
            "[briefing]\ninject_on_session_start = true\nmax_chars = 6000\n",
        )
        .unwrap();
        let qs = subagent_query();
        assert!(
            !qs.contains("&briefing="),
            "subagents must not inherit it: {qs}"
        );
        assert!(marker_query_suffix(cwd, None).contains("&briefing=true"));
    }

    #[test]
    fn marker_requests_subagent_briefing_only_for_its_own_truthy_opt_in() {
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        let cwd = tmp.path().to_str().unwrap();
        let home = tempfile::TempDir::new().unwrap();
        let requested = || {
            marker_requests_briefing_with_home(cwd, Some(home.path()), BriefingKey::SubagentStart)
        };

        assert!(!requested());
        std::fs::write(&marker, "[briefing]\ninject_on_session_start = true\n").unwrap();
        assert!(!requested());
        std::fs::write(&marker, "[briefing]\ninject_on_subagent_start = off\n").unwrap();
        assert!(!requested());
        std::fs::write(&marker, "[briefing]\ninject_on_subagent_start = \"yes\"\n").unwrap();
        assert!(requested());
    }

    #[test]
    fn marker_requests_briefing_only_for_truthy_opt_in() {
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        let cwd = tmp.path().to_str().unwrap();

        assert!(!marker_requests_briefing(cwd));
        std::fs::write(
            &marker,
            "[briefing]\ninject_on_session_start = false\nmax_chars = 6000\n",
        )
        .unwrap();
        assert!(!marker_requests_briefing(cwd));
        std::fs::write(
            &marker,
            "[briefing]\ninject_on_session_start = YeS\nmax_chars = 6000\n",
        )
        .unwrap();
        assert!(marker_requests_briefing(cwd));
    }

    /// The Kimi once-per-session gate reads the marker the query it gates
    /// reads. A home marker's `[briefing]` applies to every cwd, so a checkout
    /// outside the home with no marker of its own opens the gate too;
    /// otherwise no brief marker is written and every prompt asks for the
    /// brief again (#1665).
    #[test]
    fn briefing_gate_and_query_agree_on_the_home_marker_outside_the_home() {
        let home = tempfile::TempDir::new().unwrap();
        std::fs::write(
            home.path().join(".ai-memory.toml"),
            "[briefing]\ninject_on_session_start = true\nmax_chars = 4000\n",
        )
        .unwrap();
        let repo = tempfile::TempDir::new().unwrap();
        let cwd = repo.path().to_str().unwrap();
        let query = || {
            let selection = super::super::super::marker::routing_selection_with_home(
                cwd,
                cwd,
                Some(home.path()),
                false,
            );
            marker_query_suffix_impl_from_selection(
                cwd,
                None,
                Some(BriefingKey::SessionStart),
                selection.unwrap(),
            )
        };

        let qs = query();
        assert!(qs.contains("&briefing=true"), "{qs}");
        assert!(marker_requests_briefing_with_home(
            cwd,
            Some(home.path()),
            BriefingKey::SessionStart
        ));

        // The repo's own settings marker wins over the home marker for both.
        std::fs::write(repo.path().join(".ai-memory.toml"), "project = \"repo\"\n").unwrap();
        let qs = query();
        assert!(!qs.contains("briefing"), "{qs}");
        assert!(!marker_requests_briefing_with_home(
            cwd,
            Some(home.path()),
            BriefingKey::SessionStart
        ));
    }

    #[test]
    fn marker_query_suffix_repo_root_non_git_keeps_project_implicit() {
        let tmp = tempfile::TempDir::new().unwrap();
        let child = tmp.path().join("plain-dir");
        std::fs::create_dir_all(&child).unwrap();
        std::fs::write(
            child.join(".ai-memory.toml"),
            "workspace = \"oss\"\nproject_strategy = \"repo-root\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(child.to_str().unwrap(), None);
        assert!(qs.contains("&workspace=oss"), "{qs}");
        assert!(!qs.contains("&project="), "{qs}");
        assert!(qs.contains("&project_strategy=repo-root"), "{qs}");
    }

    #[test]
    fn marker_query_suffix_repo_root_collapses_out_of_tree_worktree() {
        if std::process::Command::new("git")
            .arg("--version")
            .status()
            .is_err()
        {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let repo = tmp.path().join("repos/acme-api");
        std::fs::create_dir_all(&repo).unwrap();
        assert!(
            std::process::Command::new("git")
                .args(["init", "-q"])
                .arg(&repo)
                .status()
                .unwrap()
                .success()
        );
        // The commit exists only because `git worktree add` refuses a repo with
        // no commits. --no-gpg-sign: a global `commit.gpgsign = true` would
        // otherwise make git sign as this throwaway identity, and fail.
        assert!(
            std::process::Command::new("git")
                .arg("-C")
                .arg(&repo)
                .args([
                    "-c",
                    "[email protected]",
                    "-c",
                    "user.name=t",
                    "commit",
                    "-q",
                    "--no-gpg-sign",
                    "--allow-empty",
                    "-m",
                    "init",
                ])
                .status()
                .unwrap()
                .success()
        );

        let worktrees = tmp.path().join("worktrees");
        std::fs::create_dir_all(&worktrees).unwrap();
        let wt = worktrees.join("acme-api/wt-feature");
        std::fs::create_dir_all(wt.parent().unwrap()).unwrap();
        if !std::process::Command::new("git")
            .arg("-C")
            .arg(&repo)
            .args(["worktree", "add", "-q", "-b", "feat/worktree-inspection"])
            .arg(&wt)
            .status()
            .unwrap()
            .success()
        {
            return;
        }
        std::fs::write(
            wt.join(".ai-memory.toml"),
            "workspace = \"oss\"\nproject_strategy = \"repo-root\"\n",
        )
        .unwrap();

        let qs = marker_query_suffix(wt.to_str().unwrap(), None);
        assert!(qs.contains("&workspace=oss"), "{qs}");
        assert!(qs.contains("&project=acme-api"), "{qs}");
        assert!(qs.contains("&project_strategy=repo-root"), "{qs}");
        let scope = hook_scope(wt.to_str().unwrap(), None);
        assert!(scope.is_explicit());
        let scope = serde_json::to_value(scope).unwrap();
        assert_eq!(scope["workspace"], "oss");
        assert_eq!(scope["project"], "acme-api");
        assert_eq!(scope["project_src"], "repo-root");
        assert_eq!(scope["server_may_remap"], true);
    }

    // ── install-time default strategy (#128), no marker required ──────

    #[test]
    fn marker_query_suffix_default_repo_root_non_git_keeps_project_implicit() {
        // Baked repo-root default, no marker, not a git tree: the strategy is
        // forwarded but no project is derived (server falls back to basename).
        let tmp = tempfile::TempDir::new().unwrap();
        let child = tmp.path().join("plain-dir");
        std::fs::create_dir_all(&child).unwrap();
        let qs = marker_query_suffix(child.to_str().unwrap(), Some("repo-root"));
        assert!(!qs.contains("&project="), "{qs}");
        assert!(qs.contains("&project_strategy=repo-root"), "{qs}");
    }

    #[test]
    fn marker_query_suffix_default_repo_root_collapses_git_subdir() {
        // Baked repo-root default, no marker, inside a git subdir: the project
        // collapses to the repo-root basename.
        if std::process::Command::new("git")
            .arg("--version")
            .status()
            .is_err()
        {
            return;
        }
        let tmp = tempfile::TempDir::new().unwrap();
        let repo = tmp.path().join("contentcreator");
        std::fs::create_dir_all(&repo).unwrap();
        assert!(
            std::process::Command::new("git")
                .args(["init", "-q"])
                .arg(&repo)
                .status()
                .unwrap()
                .success()
        );
        let sub = repo.join("transcripts");
        std::fs::create_dir_all(&sub).unwrap();
        let qs = marker_query_suffix(sub.to_str().unwrap(), Some("repo-root"));
        assert!(qs.contains("&project=contentcreator"), "{qs}");
        assert!(qs.contains("&project_strategy=repo-root"), "{qs}");
        // Host-derived, so the server may let a session overrule it (#394).
        assert!(qs.contains("&project_src=repo-root"), "{qs}");
    }

    // `project_src` must faithfully separate the two ways a `project` override
    // is produced — that distinction is the whole basis for `[routing]
    // mid_session = "sticky"` honoring markers while overruling derivation.
    /// A nested capture-only marker (only `[capture]`) must not shadow an
    /// outer marker's `workspace`/`project` — `marker_query_suffix` forwards
    /// those from the OUTER marker — while `capture_policy` for the SAME cwd
    /// still resolves the INNER (nearest) marker's `ignore_paths`: scope and
    /// capture deliberately read different markers (#668).
    #[test]
    fn marker_query_suffix_skips_nested_capture_only_marker_for_scope() {
        use ai_memory_core::AgentKind;
        use ai_memory_hooks::CaptureDisposition;

        let tmp = tempfile::TempDir::new().unwrap();
        // A `.git` dir makes tmp.path() the checkout boundary the walk-up
        // stops at, so it is actually consulted (a plain non-git directory
        // outside $HOME only checks its exact cwd — see `checkout_root`).
        std::fs::create_dir_all(tmp.path().join(".git")).unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\nproject = \"infra\"\n",
        )
        .unwrap();
        let inner = tmp.path().join("sub");
        std::fs::create_dir_all(&inner).unwrap();
        std::fs::write(
            inner.join(".ai-memory.toml"),
            "[capture]\nignore_paths = [\"secret/**\"]\n",
        )
        .unwrap();
        let inner_str = inner.to_str().unwrap();

        let qs = marker_query_suffix(inner_str, None);
        assert!(qs.contains("&workspace=acme"), "{qs}");
        assert!(qs.contains("&project=infra"), "{qs}");

        // Same cwd: capture policy still comes from the INNER (nearest)
        // marker, so its `ignore_paths` still applies.
        let policy = capture_policy(inner_str);
        let raw = serde_json::json!({
            "hook_event_name": "PostToolUse",
            "tool_name": "Edit",
            "tool_input": {"file_path": format!("{inner_str}/secret/token.txt")},
            "session_id": "s",
            "cwd": inner_str,
        });
        let decision = policy.inspect(AgentKind::ClaudeCode, &raw, inner_str);
        assert_eq!(decision.protocol().disposition(), CaptureDisposition::Drop);
    }

    /// The predicate is conservative: a marker declaring `[capture]` PLUS a
    /// scope key is a settings boundary, not capture-only, so its own
    /// `project` wins rather than an outer marker's.
    #[test]
    fn marker_query_suffix_capture_plus_project_is_a_boundary() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "workspace = \"acme\"\nproject = \"infra\"\n",
        )
        .unwrap();
        let inner = tmp.path().join("sub");
        std::fs::create_dir_all(&inner).unwrap();
        std::fs::write(
            inner.join(".ai-memory.toml"),
            "project = \"x\"\n[capture]\nignore_paths = [\"secret/**\"]\n",
        )
        .unwrap();

        let qs = marker_query_suffix(inner.to_str().unwrap(), None);
        assert!(qs.contains("&project=x"), "{qs}");
        assert!(!qs.contains("&workspace=acme"), "{qs}");
    }

    #[test]
    fn marker_query_suffix_tags_project_provenance() {
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("workdir");
        std::fs::create_dir_all(&dir).unwrap();

        // No override at all: nothing to describe.
        let qs = marker_query_suffix(dir.to_str().unwrap(), None);
        assert!(!qs.contains("&project="), "{qs}");
        assert!(!qs.contains("&project_src="), "{qs}");

        // Marker-declared project: a deliberate rescope.
        std::fs::write(dir.join(".ai-memory.toml"), "project = \"pinned\"\n").unwrap();
        let qs = marker_query_suffix(dir.to_str().unwrap(), None);
        assert!(qs.contains("&project=pinned"), "{qs}");
        assert!(qs.contains("&project_src=marker"), "{qs}");

        // A marker project wins over the baked repo-root default, and keeps
        // reporting `marker` — the provenance must follow the value that
        // actually shipped, not the strategy that was configured.
        let qs = marker_query_suffix(dir.to_str().unwrap(), Some("repo-root"));
        assert!(qs.contains("&project=pinned"), "{qs}");
        assert!(qs.contains("&project_src=marker"), "{qs}");
        assert!(!qs.contains("project_src=repo-root"), "{qs}");
    }

    #[test]
    fn marker_query_suffix_marker_strategy_overrides_default() {
        // A marker that pins `project_strategy = "basename"` wins over the
        // install-time repo-root default — no repo-root derivation happens.
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "project_strategy = \"basename\"\n",
        )
        .unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), Some("repo-root"));
        assert!(qs.contains("&project_strategy=basename"), "{qs}");
        assert!(!qs.contains("repo-root"), "{qs}");
        assert!(!qs.contains("&project="), "{qs}");
    }

    #[test]
    fn marker_query_suffix_marker_project_overrides_default_repo_root() {
        // A marker's explicit `project` wins over repo-root derivation, while
        // the baked default strategy is still forwarded.
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(tmp.path().join(".ai-memory.toml"), "project = \"pinned\"\n").unwrap();
        let qs = marker_query_suffix(tmp.path().to_str().unwrap(), Some("repo-root"));
        assert!(qs.contains("&project=pinned"), "{qs}");
        assert!(qs.contains("&project_strategy=repo-root"), "{qs}");
    }

    #[test]
    fn capture_config_problem_is_none_without_a_marker() {
        let tmp = tempfile::TempDir::new().unwrap();
        assert!(capture_config_problem(tmp.path().to_str().unwrap()).is_none());
    }

    #[test]
    fn capture_config_problem_is_none_for_a_well_formed_capture_table() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "project = \"ok\"\n\n[capture]\nignore_paths = [\"**/.env\"]\n",
        )
        .unwrap();
        assert!(capture_config_problem(tmp.path().to_str().unwrap()).is_none());
    }

    /// The exact failure mode found in practice: a dropped `#` turns a
    /// wrapped comment into a stray token right after a `[capture]` header,
    /// which is invalid TOML.
    #[test]
    fn capture_config_problem_reports_a_toml_syntax_error() {
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        std::fs::write(
            &marker,
            "project = \"example\"\n\n\
             [capture] this used to be a comment, now it is a stray token\n\
             project_strategy = \"repo-root\"\n\n\
             [capture]\nignore_paths = [\"**/.env\"]\n",
        )
        .unwrap();
        let (reported_marker, reason) =
            capture_config_problem(tmp.path().to_str().unwrap()).expect("malformed TOML");
        assert_eq!(reported_marker, marker);
        assert!(reason.contains("invalid TOML"), "{reason}");
    }

    #[test]
    fn capture_config_problem_reports_an_unsupported_capture_key() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "[capture]\nallowlist = [\"**\"]\n",
        )
        .unwrap();
        let (_, reason) =
            capture_config_problem(tmp.path().to_str().unwrap()).expect("unsupported key");
        assert!(reason.contains("allowlist"), "{reason}");
    }

    /// The gap the parse-only check missed: a `[capture]` table that is
    /// perfectly valid TOML, and a `[capture]` shape `read_capture_config`
    /// accepts, but whose `ignore_paths` entry `compile` itself rejects (an
    /// unsupported glob character). `capture_policy(cwd).state()` must still
    /// catch this as `Invalid` even though the TOML parse alone would not.
    #[test]
    fn capture_config_problem_reports_a_pattern_compile_failure() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join(".ai-memory.toml"),
            "[capture]\nignore_paths = [\"secrets/{a,b}\"]\n",
        )
        .unwrap();
        let (_, reason) = capture_config_problem(tmp.path().to_str().unwrap())
            .expect("a rejected glob must still surface as a problem");
        assert!(reason.contains("secrets/{a,b}"), "{reason}");
        assert!(reason.contains("unsupported glob character"), "{reason}");
    }

    #[test]
    fn read_capture_config_and_verbose_agree_on_success() {
        let tmp = tempfile::TempDir::new().unwrap();
        let marker = tmp.path().join(".ai-memory.toml");
        std::fs::write(&marker, "[capture]\nignore_paths = [\"**/*.pem\"]\n").unwrap();
        let terse = read_capture_config(&marker).expect("valid marker parses");
        let verbose = read_capture_config_verbose(&marker).expect("valid marker parses");
        assert_eq!(terse.ignore_paths, verbose.ignore_paths);
    }
}