Skip to content

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

Rust
39.0 KB
Raw Blame
//! Subcommand implementations.

use anyhow::{Context, Result, anyhow, bail};

use crate::config::Config;

/// Whether a server error is a no-create scope lookup missing its
/// `(workspace, project)` — a `404`. Read/count endpoints fail closed on an
/// unknown scope (invariant: reads never create), so a project that has never
/// been written to answers `404` rather than "empty". Callers that ask "does
/// this project have anything?" must treat that as **nothing there**, not a
/// hard error — otherwise the brand-new-project case (exactly the one
/// `doctor` and `backfill` exist for) fails on itself.
pub(crate) fn is_scope_not_found(error: &anyhow::Error) -> bool {
    error
        .downcast_ref::<crate::http_client::ServerResponseError>()
        .is_some_and(|response| response.status() == reqwest::StatusCode::NOT_FOUND)
}

pub(crate) fn is_scope_ambiguous(error: &anyhow::Error) -> bool {
    error
        .downcast_ref::<crate::http_client::ServerResponseError>()
        .is_some_and(|response| {
            response.status() == reqwest::StatusCode::BAD_REQUEST
                && response.body().contains("ambiguous")
        })
}

pub(crate) mod agent_plugins;
pub(crate) mod agentmemory_residue;
pub mod api_key;
pub mod apply_shared;
pub mod audit_contamination;
pub mod auth;
pub mod auth_enable;
pub mod auto_improve;
pub mod auto_improve_report;
pub mod backfill;
pub mod backup;
pub mod backup_agents;
pub mod bootstrap;
pub mod checkpoints;
pub mod codex_hook_trust;
pub mod commit;
pub mod compact;
pub mod completions;
pub mod continue_session;
pub mod curator;
pub mod data_purge;
pub mod delete_page;
pub mod doctor;
pub mod embed;
pub mod export_okf;
pub mod finalize_session;
pub mod forget_sweep;
pub mod generate_auth_token;
pub mod grant;
pub mod handoffs;
pub mod hook;
pub mod hook_capture;
pub mod hook_drain_process;
pub mod hook_spool;
pub mod init;
pub mod install_hooks;
pub mod install_instructions;
pub mod install_mcp;
pub mod install_skills;
pub mod lint;
pub mod list_projects;
pub mod llm_test;
mod managed_project;
pub mod mcp_bridge;
pub mod merge_project;
pub mod message;
pub mod move_project;
pub mod move_session;
pub mod openclaw_plugin;
pub mod opencode_dialect;
pub mod path_util;
pub mod pending_writes;
pub(crate) mod plugin_origin;
pub mod profile;
pub mod project;
pub mod project_init;
pub mod project_registry;
pub mod purge_preview;
pub mod purge_project;
pub mod purge_session;
pub mod read_page;
pub mod recent;
pub mod reclaim_ledger_versions;
pub mod recovery;
pub mod reindex;
pub mod rename_project;
pub mod rename_workstream;
pub mod render_plugins;
pub mod render_shared;
pub mod reorg;
pub mod repair_backfill_timestamps;
pub mod reset;
pub mod restore;
pub mod restore_agents;
pub mod restore_page;
pub mod resume;
pub mod run;
pub mod run_autowire;
pub mod search;
pub mod serve;
pub mod server;
pub mod service_host;
pub mod session_usage;
pub mod setup;
pub mod setup_agent;
pub(crate) mod setup_web;
pub mod show;
pub mod status;
pub mod transcript_capture;
pub mod uninstall;
pub mod upgrade;
pub mod user;
pub mod user_service;
pub mod workstream_search;
pub mod workstreams;
pub mod write_page;

/// Resolve the effective `(workspace, project)` pair for a client command.
///
/// Each field is resolved independently, in this order:
///
/// 1. The explicit flag (`--workspace` / `--project`) when non-empty.
/// 2. The nearest `.ai-memory.toml` marker: `workspace` and an explicit
///    `project`/`identity`; otherwise a valid remote supplies its canonical path
///    name even when the unpinned strategy is `repo-root`.
/// 3. Without a valid remote, an explicit marker `repo-root` strategy derives
///    the main repo root; otherwise use [`crate::config::DEFAULT_WORKSPACE`] and
///    [`resolve_project_name`]'s cwd-basename fallback.
///
/// Rung 2 is why this function exists. Before it, only the lifecycle hooks
/// read the marker, so a checkout declaring `workspace = "acme"` still had
/// every CLI command resolve into `default` — the same repository ended up
/// split across two scopes, with `run`'s managed workstream on one side and
/// the hook-captured sessions on the other.
///
/// Resolution is announced on stderr whenever the marker decides a field, so
/// a scope that differs from the flags the user typed is never silent.
/// Render an elapsed time the way the read-only listings say it.
///
/// `ai-memory workstreams` and `ai-memory handoffs` both answer "how long
/// ago", and each shipped its own renderer a day apart — one saying
/// `3 hours ago`, the other `3h ago` — so the same quantity read differently
/// depending on which command you ran.
///
/// Deliberately does **not** cover `status`'s spool line. That renders a
/// duration (`oldest: 2h 10m`), not an "ago", and is a stable surface people
/// read; folding it in here would change output that no fix requires.
///
/// Clamps negatives to "just now": server and client clocks can disagree, and
/// a skewed timestamp must not render as an enormous age.
pub(crate) fn humanize_age_secs(seconds: i64) -> String {
    let seconds = seconds.max(0);
    if seconds < 60 {
        return "just now".to_owned();
    }
    let (value, unit) = match seconds {
        v if v < 3_600 => (v / 60, "minute"),
        v if v < 86_400 => (v / 3_600, "hour"),
        v if v < 2_592_000 => (v / 86_400, "day"),
        v => (v / 2_592_000, "month"),
    };
    format!("{value} {unit}{} ago", if value == 1 { "" } else { "s" })
}

/// Refuse an explicitly empty or whitespace-only scope or target flag.
///
/// A shell wrapper or harness that fills an unset variable with `""` (or
/// whitespace) must fail closed rather than silently falling back to the
/// scope the current directory resolves to or forwarding a blank project/
/// workspace name to the server.
///
/// # Errors
/// Returns an error naming `flag` when it was passed as an empty or
/// whitespace-only value.
pub(crate) fn refuse_empty_explicit(value: Option<&str>, flag: &str) -> Result<()> {
    if value.is_some_and(|v| v.trim().is_empty()) {
        bail!(
            "{flag} was passed empty; provide a non-empty value, or omit an optional scope \
             flag to use the project this directory resolves to"
        );
    }
    Ok(())
}

/// `AI_MEMORY_IGNORE_MARKER=1` skips rung 2 entirely.
pub(crate) fn resolve_scope(
    config: &Config,
    explicit_ws: Option<&str>,
    explicit_proj: Option<&str>,
) -> Result<(String, String)> {
    resolve_scope_noting_marker_project(config, explicit_ws, explicit_proj)
        .map(|(workspace, project, _)| (workspace, project))
}

/// [`resolve_scope`], also reporting whether a marker's `project` key named
/// the project. Hook capture routes such a project by name and never reads the
/// remote, so a caller mirroring capture needs that fact.
pub(crate) fn resolve_scope_noting_marker_project(
    config: &Config,
    explicit_ws: Option<&str>,
    explicit_proj: Option<&str>,
) -> Result<(String, String, bool)> {
    refuse_empty_explicit(explicit_ws, "--workspace")?;
    refuse_empty_explicit(explicit_proj, "--project")?;
    if let (Some(workspace), Some(project)) = (explicit_ws, explicit_proj) {
        return Ok((workspace.to_string(), project.to_string(), false));
    }
    let marker = marker_scope(config)?;
    let marker_project = explicit_proj.is_none()
        && marker
            .as_ref()
            .is_some_and(|(scope, _, _)| scope.project.is_some());
    let (workspace, project) =
        resolve_scope_with_marker(config, explicit_ws, explicit_proj, marker, true)?;
    Ok((workspace, project, marker_project))
}

pub(crate) fn resolve_scope_with_marker(
    config: &Config,
    explicit_ws: Option<&str>,
    explicit_proj: Option<&str>,
    marker: Option<(crate::marker::MarkerScope, String, String)>,
    announce: bool,
) -> Result<(String, String)> {
    refuse_empty_explicit(explicit_ws, "--workspace")?;
    refuse_empty_explicit(explicit_proj, "--project")?;

    let mut decided: Vec<&str> = Vec::with_capacity(2);
    let workspace = match explicit_ws {
        Some(explicit) => explicit.to_string(),
        None => match marker
            .as_ref()
            .and_then(|(scope, _, _)| scope.workspace.clone())
        {
            Some(declared) => {
                decided.push("workspace");
                declared
            }
            None => crate::config::DEFAULT_WORKSPACE.to_string(),
        },
    };

    let project = match explicit_proj {
        Some(explicit) => explicit.to_string(),
        None => {
            // A marker's explicit `project` pins the name for its whole tree.
            // Otherwise a valid remote supplies the canonical path name; only
            // the no-valid-remote fallback consults basename/repo-root.
            let declared = marker
                .as_ref()
                .and_then(|(scope, identity_cwd, lookup_cwd)| {
                    scope
                        .project
                        .clone()
                        .or_else(|| scope.canonical_remote_project())
                        .or_else(|| {
                            if scope.is_repo_root() {
                                crate::marker::repo_root_project(lookup_cwd)
                            } else {
                                ai_memory_consolidate::derive_project_name(
                                    std::path::Path::new(identity_cwd),
                                    ai_memory_consolidate::ProjectNameStrategy::Basename,
                                )
                                .map(|(name, _)| name)
                            }
                        })
                });
            match declared {
                Some(name) => {
                    decided.push("project");
                    name
                }
                None => resolve_project_name(config, None)?,
            }
        }
    };

    if announce && let Some((scope, _, _)) = marker.as_ref().filter(|_| !decided.is_empty()) {
        // Name only the halves the marker actually decided: an explicit flag
        // that was honoured must not read as if the file overrode it.
        eprintln!(
            "ai-memory: scope {workspace}/{project} ({} from {})",
            decided.join(" + "),
            scope.path.display()
        );
    }
    Ok((workspace, project))
}

/// Resolve `(workspace, project)` for an explicit local directory without
/// changing the process working directory, resolving symlinks, or consulting
/// wrapper cwd overrides.
///
/// The policy matches [`resolve_scope`]: a marker may pin either half, a valid
/// remote's canonical path wins an unpinned marker strategy, an explicit
/// `repo-root` strategy handles only the no-valid-remote case, and a tree
/// without a scope marker otherwise uses the cwd basename.
pub(crate) fn resolve_scope_for_path(
    config: &Config,
    cwd: &std::path::Path,
) -> Result<(String, String)> {
    resolve_scope_for_path_with_explicit(config, cwd, None, None)
}

pub(crate) fn resolve_scope_for_path_with_explicit(
    config: &Config,
    cwd: &std::path::Path,
    explicit_ws: Option<&str>,
    explicit_proj: Option<&str>,
) -> Result<(String, String)> {
    if !cwd.exists() {
        return Err(anyhow!(
            "project candidate does not exist: {}",
            cwd.display()
        ));
    }
    let cwd = crate::marker::absolute_normalized(cwd);
    let identity = cwd.to_string_lossy().into_owned();
    let marker = crate::marker::read_scope(&identity, &config.runtime_env)?;
    let workspace = explicit_ws
        .filter(|value| !value.is_empty())
        .map(str::to_owned)
        .or_else(|| marker.as_ref().and_then(|scope| scope.workspace.clone()))
        .unwrap_or_else(|| crate::config::DEFAULT_WORKSPACE.to_string());
    let project = if let Some(project) = explicit_proj.filter(|value| !value.is_empty()) {
        project.to_owned()
    } else {
        match marker.as_ref() {
            Some(scope) => scope
                .project
                .clone()
                .or_else(|| scope.canonical_remote_project())
                .or_else(|| {
                    if scope.is_repo_root() {
                        crate::marker::repo_root_project(&identity)
                    } else {
                        ai_memory_consolidate::derive_project_name(
                            &cwd,
                            ai_memory_consolidate::ProjectNameStrategy::Basename,
                        )
                        .map(|(name, _)| name)
                    }
                })
                .ok_or_else(|| anyhow!("could not derive project name from {}", cwd.display()))?,
            None => crate::marker::discover_remote_identity(&identity)
                .and_then(|repository| {
                    ai_memory_core::repository_identity::path_style_name(&repository)
                })
                .or_else(|| {
                    ai_memory_consolidate::derive_project_name(
                        &cwd,
                        ai_memory_consolidate::ProjectNameStrategy::Basename,
                    )
                    .map(|(name, _)| name)
                })
                .ok_or_else(|| anyhow!("could not derive project name from {}", cwd.display()))?,
        }
    };
    Ok((workspace, project))
}

/// Resolve only the workspace half, for the one command whose project half is
/// deliberately absent (`embed --force` fans out across every project in the
/// workspace). Resolving the pair there would make the command fail on the
/// cwd-derived project name it is about to throw away.
pub(crate) fn resolve_workspace(config: &Config, explicit_ws: Option<&str>) -> Result<String> {
    refuse_empty_explicit(explicit_ws, "--workspace")?;
    if let Some(explicit) = explicit_ws {
        return Ok(explicit.to_string());
    }
    Ok(match marker_scope(config)? {
        Some((scope, _, _)) => match scope.workspace {
            Some(declared) => {
                eprintln!(
                    "ai-memory: workspace {declared} (workspace from {})",
                    scope.path.display()
                );
                declared
            }
            None => crate::config::DEFAULT_WORKSPACE.to_string(),
        },
        None => crate::config::DEFAULT_WORKSPACE.to_string(),
    })
}

/// The nearest scope-declaring marker plus the cwd the walk started from.
fn marker_scope(config: &Config) -> Result<Option<(crate::marker::MarkerScope, String, String)>> {
    let Some((identity_cwd, lookup_cwd)) = scope_directories(config) else {
        return Ok(None);
    };
    let Some(scope) =
        crate::marker::read_scope_for(&lookup_cwd, &identity_cwd, &config.runtime_env)?
    else {
        return Ok(None);
    };
    Ok(Some((scope, identity_cwd, lookup_cwd)))
}

pub(crate) fn scope_directories(config: &Config) -> Option<(String, String)> {
    let identity_cwd = scope_cwd(config)?;
    // The Docker wrapper preserves the host cwd for identity but binds the
    // checkout at /work. Check the host path when its bounded root is mounted;
    // otherwise use the physical cwd so a marker in the /work bind is still
    // visible. Project derivation keeps using the host identity either way.
    let lookup_cwd = if let Some(scope_cwd) = config.runtime_env.scope_cwd() {
        scope_cwd.to_string()
    } else if std::path::Path::new(&identity_cwd).exists() {
        identity_cwd.clone()
    } else {
        std::env::current_dir()
            .ok()
            .map(|cwd| cwd.to_string_lossy().into_owned())?
    };
    Some((identity_cwd, lookup_cwd))
}

/// The directory marker discovery walks up from.
///
/// Prefers `AI_MEMORY_HOST_CWD` for the same reason [`resolve_project_name`]
/// does: inside the docker wrapper the container's own `current_dir()` is the
/// `/work` bind mount, which would find the wrong marker (or none).
fn scope_cwd(config: &Config) -> Option<String> {
    if let Some(host_cwd) = config.runtime_env.host_cwd() {
        return Some(host_cwd.to_string());
    }
    std::env::current_dir()
        .ok()
        .map(|cwd| cwd.to_string_lossy().into_owned())
}

/// Resolve the effective project name for a client command.
///
/// Prefer [`resolve_scope`] for new call sites: this resolves only half the
/// scope and never consults the marker, so a command that uses it alone still
/// pairs its project with whatever workspace the caller passed.
///
/// Precedence:
/// 1. `explicit` (the user's `--project` flag) when non-empty.
/// 2. Canonical path-style name from the valid `upstream` remote, then
///    `origin`, when the checkout has no marker identity/name override.
///    `AI_MEMORY_HOST_CWD` selects the host checkout before the remote is
///    inspected; if that path is unavailable in a container it remains the
///    basename fallback rather than borrowing `/work`'s identity.
/// 3. Basename of the current directory, including a git-repository
///    subdirectory or a non-git directory. `repo-root` is used only when a
///    marker/install strategy explicitly selects it.
///
/// Mirrors the heuristic the hook router uses in
/// `ai-memory-hooks::router::resolve_project_ids`, so commands
/// auto-target the same project the user's interactive sessions
/// have been writing into. Dot-prefixed dirs are preserved
/// verbatim (`~/.config` → project `.config`).
pub(crate) fn resolve_project_name(config: &Config, explicit: Option<&str>) -> Result<String> {
    if let Some(p) = explicit.filter(|s| !s.is_empty()) {
        return Ok(p.to_string());
    }
    if let Some(host_cwd) = config.runtime_env.host_cwd() {
        if let Some(repository) = crate::marker::discover_remote_identity(host_cwd)
            && let Some(name) = ai_memory_core::repository_identity::path_style_name(&repository)
        {
            return Ok(name);
        }
        if let Some(name) = std::path::Path::new(host_cwd)
            .file_name()
            .and_then(|s| s.to_str())
            .filter(|s| !s.is_empty())
        {
            return Ok(name.to_string());
        }
    }

    // Safety net: when running inside the docker wrapper, the
    // container's workdir is bind-mounted at `/work` (a fresh path
    // chosen specifically because the host's `$PWD` would conflict
    // with the $HOME bind mount). If we fall through to here while
    // `current_dir()` is `/work`, the wrapper is STALE: it didn't
    // pass `-e AI_MEMORY_HOST_CWD=$PWD` and the binary has no idea
    // which host dir invoked it. Bail with a clear remedy instead
    // of silently writing every project to `default/work`.
    let cwd = std::env::current_dir().context("getting CWD for project auto-detect")?;
    if cwd.as_os_str() == "/work" {
        bail!(
            "the `ai-memory` wrapper at ~/.local/bin/ai-memory looks stale \
             (it didn't pass AI_MEMORY_HOST_CWD into the container). Without \
             this, every project would land in `default/work` regardless of \
             which host dir you ran from. Reinstall the checksum-verified \
             wrapper from the latest GitHub Release as documented in README.md,\n  \
             (or run `ai-memory upgrade` if your existing wrapper is recent enough \
             to know that command)"
        );
    }

    // Shared with the hook router via `derive_project_name`: with no valid
    // remote and no explicit repo-root strategy, both use the current cwd's
    // basename, including repository subdirectories.
    if let Some(repository) = crate::marker::discover_remote_identity(&cwd.to_string_lossy())
        && let Some(name) = ai_memory_core::repository_identity::path_style_name(&repository)
    {
        return Ok(name);
    }
    if let Some((name, _)) = ai_memory_consolidate::derive_project_name(
        &cwd,
        ai_memory_consolidate::ProjectNameStrategy::Basename,
    ) {
        return Ok(name);
    }
    Err(anyhow!(
        "could not derive project name from CWD ({}); \
         pass --project explicitly",
        cwd.display()
    ))
}

/// Human-readable lines for the proposals the server refused to stage.
///
/// Empty when nothing was skipped, so a clean run prints nothing extra. Every
/// staging command shares this: a skipped proposal is otherwise
/// indistinguishable from one the reviewer never produced — the run reports
/// success either way, only with one proposal fewer — and the operator has no
/// way to learn that a paid review result was dropped.
pub(crate) fn skipped_proposal_lines(skipped: &[ai_memory_store::SkippedProposal]) -> Vec<String> {
    if skipped.is_empty() {
        return Vec::new();
    }
    let mut lines = Vec::with_capacity(skipped.len() + 1);
    lines.push(format!("Skipped {} proposal(s):", skipped.len()));
    lines.extend(
        skipped
            .iter()
            .map(|s| format!("  - {}: {}", s.target_path, s.reason)),
    );
    lines
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::RuntimeEnv;

    #[test]
    fn resolve_project_name_prefers_explicit_value() {
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests("/host/ignored"),
            ..Config::default()
        };

        assert_eq!(
            resolve_project_name(&config, Some("explicit-project")).unwrap(),
            "explicit-project"
        );
    }

    fn git(command: &[&str], cwd: &std::path::Path) -> bool {
        std::process::Command::new("git")
            .args(command)
            .current_dir(cwd)
            .status()
            .is_ok_and(|status| status.success())
    }

    #[test]
    fn resolve_project_name_uses_canonical_remote_path_and_upstream_priority() {
        let tmp = tempfile::TempDir::new().unwrap();
        if !git(&["init", "-q"], tmp.path()) {
            return;
        }
        assert!(git(
            &[
                "remote",
                "add",
                "origin",
                "https://[email protected]/wrong/origin.git"
            ],
            tmp.path()
        ));
        assert!(git(
            &[
                "remote",
                "add",
                "upstream",
                "[email protected]:Acme/Group/API.git"
            ],
            tmp.path()
        ));
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(tmp.path().to_str().unwrap()),
            ..Config::default()
        };

        assert_eq!(
            resolve_project_name(&config, None).unwrap(),
            "acme-group-api"
        );
    }

    #[test]
    fn static_scope_uses_path_default_and_respects_marker_opt_out_and_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        let repo = tmp.path().join("checkout");
        std::fs::create_dir(&repo).unwrap();
        if !git(&["init", "-q"], &repo) {
            return;
        }
        assert!(git(
            &[
                "remote",
                "add",
                "origin",
                "[email protected]:Acme/Group/API.git"
            ],
            &repo
        ));
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(repo.to_str().unwrap()),
            ..Config::default()
        };
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("default".into(), "acme-group-api".into())
        );

        std::fs::write(
            repo.join(".ai-memory.toml"),
            "workspace = \"oss\"\nidentity_style = \"host_path\"\n",
        )
        .unwrap();
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("oss".into(), "checkout".into())
        );

        std::fs::write(
            repo.join(".ai-memory.toml"),
            "workspace = \"oss\"\nproject = \"pinned\"\n",
        )
        .unwrap();
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("oss".into(), "pinned".into())
        );
    }

    #[test]
    fn remote_path_wins_explicit_repo_root_strategy_without_project_or_identity_override() {
        let tmp = tempfile::TempDir::new().unwrap();
        let repo = tmp.path().join("checkout");
        let subdir = repo.join("crates/cli");
        std::fs::create_dir_all(&subdir).unwrap();
        if !git(&["init", "-q"], &repo) {
            return;
        }
        assert!(git(
            &[
                "remote",
                "add",
                "origin",
                "[email protected]:Acme/Group/API.git"
            ],
            &repo
        ));
        std::fs::write(
            repo.join(".ai-memory.toml"),
            "workspace = \"oss\"\nproject_strategy = \"repo-root\"\n",
        )
        .unwrap();
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(subdir.to_str().unwrap()),
            ..Config::default()
        };

        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("oss".into(), "acme-group-api".into())
        );
        assert_eq!(
            resolve_scope_for_path(&Config::default(), &subdir).unwrap(),
            ("oss".into(), "acme-group-api".into())
        );
    }

    #[test]
    fn remote_less_git_subdirectory_uses_basename_unless_repo_root_is_explicit() {
        let tmp = tempfile::TempDir::new().unwrap();
        let repo = tmp.path().join("checkout");
        let subdir = repo.join("crates/cli");
        std::fs::create_dir_all(&subdir).unwrap();
        if !git(&["init", "-q"], &repo) {
            return;
        }
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(subdir.to_str().unwrap()),
            ..Config::default()
        };

        assert_eq!(resolve_project_name(&config, None).unwrap(), "cli");
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("default".into(), "cli".into())
        );
        assert_eq!(
            resolve_scope_for_path(&Config::default(), &subdir).unwrap(),
            ("default".into(), "cli".into())
        );

        std::fs::write(
            repo.join(".ai-memory.toml"),
            "project_strategy = \"repo-root\"\n",
        )
        .unwrap();
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("default".into(), "checkout".into())
        );
        assert_eq!(
            resolve_scope_for_path(&Config::default(), &subdir).unwrap(),
            ("default".into(), "checkout".into())
        );
    }

    #[test]
    fn resolve_project_name_uses_host_cwd_basename() {
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests("/host/my-project"),
            ..Config::default()
        };

        assert_eq!(resolve_project_name(&config, None).unwrap(), "my-project");
    }

    #[test]
    fn skipped_proposal_lines_are_empty_on_a_clean_run() {
        assert!(skipped_proposal_lines(&[]).is_empty());
    }

    #[test]
    fn skipped_proposal_lines_name_the_path_and_the_reason() {
        let lines = skipped_proposal_lines(&[ai_memory_store::SkippedProposal {
            target_path: "procedures/release.md".into(),
            reason: "a proposal is already pending review for this path".into(),
        }]);
        assert_eq!(lines.len(), 2, "{lines:?}");
        assert!(lines[0].contains('1'), "{lines:?}");
        assert!(lines[1].contains("procedures/release.md"), "{lines:?}");
        assert!(
            lines[1].contains("already pending review"),
            "the reason has to travel with the path, or the operator only \
             learns that something vanished: {lines:?}"
        );
    }

    /// Build a config whose scope resolution walks up from `cwd`, and drop a
    /// marker there when `marker` is given.
    fn config_at(dir: &std::path::Path, marker: Option<&str>) -> Config {
        if let Some(body) = marker {
            std::fs::write(dir.join(".ai-memory.toml"), body).unwrap();
        }
        Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(dir.to_str().unwrap()),
            ..Config::default()
        }
    }

    /// The bug this whole path exists for: a checkout whose marker declares a
    /// workspace used to resolve into `default` for every CLI command, while
    /// the lifecycle hooks — the only marker reader at the time — sent that
    /// same checkout's captures to the declared workspace.
    #[test]
    fn explicit_scope_wins_over_home_route_and_home_route_beats_fallback() {
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = tmp.path().join("outside/repo");
        std::fs::create_dir_all(&home).unwrap();
        std::fs::create_dir_all(&repo).unwrap();
        std::fs::write(
            home.join(".ai-memory.toml"),
            format!(
                "[routes.path.\"{}\"]\nroute_workspace=\"oss\"\nroute_project=\"acme-api\"\n",
                repo.to_string_lossy().replace('\\', "/")
            ),
        )
        .unwrap();
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_and_home_for_tests(
                repo.to_string_lossy(),
                home.to_string_lossy(),
            ),
            ..Config::default()
        };
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("oss".into(), "acme-api".into())
        );
        assert_eq!(
            resolve_scope(&config, Some("cli"), Some("explicit")).unwrap(),
            ("cli".into(), "explicit".into())
        );
    }

    #[test]
    fn invalid_home_routes_refuse_unscoped_and_partial_cli_but_explicit_pair_bypasses() {
        let tmp = tempfile::TempDir::new().unwrap();
        let home = tmp.path().join("home");
        let repo = tmp.path().join("outside/repo");
        std::fs::create_dir_all(&home).unwrap();
        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 config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_and_home_for_tests(
                repo.to_string_lossy(),
                home.to_string_lossy(),
            ),
            ..Config::default()
        };
        assert!(resolve_scope(&config, None, None).is_err());
        assert!(resolve_scope(&config, Some("explicit"), None).is_err());
        assert!(resolve_scope(&config, None, Some("explicit")).is_err());
        assert_eq!(
            resolve_scope(&config, Some("cli"), Some("explicit")).unwrap(),
            ("cli".into(), "explicit".into())
        );
        std::fs::write(home.join(".ai-memory.toml"), "x".repeat(65_537)).unwrap();
        assert!(resolve_scope(&config, None, None).is_err());
        assert_eq!(
            resolve_scope(&config, Some("cli"), Some("explicit")).unwrap(),
            ("cli".into(), "explicit".into())
        );
    }

    #[test]
    fn resolve_scope_takes_the_workspace_from_the_marker() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config = config_at(tmp.path(), Some("workspace = \"acme\"\n"));

        let (workspace, project) = resolve_scope(&config, None, None).unwrap();

        assert_eq!(workspace, "acme");
        assert_eq!(
            project,
            tmp.path().file_name().unwrap().to_str().unwrap(),
            "an unpinned project still comes from the cwd chain"
        );
    }

    #[test]
    fn workspace_only_marker_without_remote_uses_hook_basename_from_a_subdirectory() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(tmp.path().join(".ai-memory.toml"), "workspace = \"acme\"\n").unwrap();
        let subdir = tmp.path().join("crates").join("cli");
        std::fs::create_dir_all(&subdir).unwrap();
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(subdir.to_str().unwrap()),
            ..Config::default()
        };

        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("acme".to_string(), "cli".to_string())
        );
        assert_eq!(
            resolve_scope(&config, Some("flagged"), None).unwrap(),
            ("flagged".to_string(), "cli".to_string()),
            "an explicit workspace must not restore the main-repo fallback"
        );
    }

    #[test]
    fn explicit_path_scope_matches_marker_and_non_repo_fallback_policy() {
        let tmp = tempfile::TempDir::new().unwrap();
        let workspace_tree = tmp.path().join("workspace-tree");
        let workspace_child = workspace_tree.join("child");
        std::fs::create_dir_all(&workspace_child).unwrap();
        std::fs::write(
            workspace_tree.join(".ai-memory.toml"),
            "workspace = \"acme\"\n",
        )
        .unwrap();

        let pinned = tmp.path().join("pinned-checkout");
        std::fs::create_dir(&pinned).unwrap();
        std::fs::write(
            pinned.join(".ai-memory.toml"),
            "project = \"shared-project\"\n",
        )
        .unwrap();

        let plain = tmp.path().join("plain-checkout");
        std::fs::create_dir(&plain).unwrap();
        let config = Config::default();

        assert_eq!(
            resolve_scope_for_path(&config, &workspace_child).unwrap(),
            ("acme".to_owned(), "child".to_owned())
        );
        assert_eq!(
            resolve_scope_for_path(&config, &pinned).unwrap(),
            (
                crate::config::DEFAULT_WORKSPACE.to_owned(),
                "shared-project".to_owned()
            )
        );
        assert_eq!(
            resolve_scope_for_path(&config, &plain).unwrap(),
            (
                crate::config::DEFAULT_WORKSPACE.to_owned(),
                "plain-checkout".to_owned()
            )
        );
    }

    #[test]
    fn remote_less_workspace_marker_uses_linked_worktree_directory_name() {
        let tmp = tempfile::TempDir::new().unwrap();
        let worktree = tmp.path().join("feature-worktree");
        std::fs::create_dir_all(&worktree).unwrap();
        std::fs::write(
            worktree.join(".git"),
            "gitdir: /repo/.git/worktrees/feature\n",
        )
        .unwrap();
        std::fs::write(worktree.join(".ai-memory.toml"), "workspace = \"acme\"\n").unwrap();
        let config = Config {
            runtime_env: RuntimeEnv::with_host_cwd_for_tests(worktree.to_str().unwrap()),
            ..Config::default()
        };

        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("acme".to_string(), "feature-worktree".to_string()),
            "workspace-only markers preserve the hook's basename worktree identity"
        );
    }

    /// A marker that pins `project` overrides the cwd-derived name for its
    /// whole tree.
    #[test]
    fn resolve_scope_takes_a_pinned_project_from_the_marker() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config = config_at(
            tmp.path(),
            Some("workspace = \"acme\"\nproject = \"pinned\"\n"),
        );

        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("acme".to_string(), "pinned".to_string())
        );
    }

    /// Explicit flags are rung 1: they beat the marker on both halves, and
    /// each half is resolved independently.
    #[test]
    fn resolve_scope_prefers_explicit_flags_over_the_marker() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config = config_at(
            tmp.path(),
            Some("workspace = \"acme\"\nproject = \"pinned\"\n"),
        );

        assert_eq!(
            resolve_scope(&config, Some("flagged"), Some("flagged-proj")).unwrap(),
            ("flagged".to_string(), "flagged-proj".to_string())
        );
        assert_eq!(
            resolve_scope(&config, Some("flagged"), None).unwrap(),
            ("flagged".to_string(), "pinned".to_string()),
            "an explicit workspace must not drag the project along with it"
        );
        assert_eq!(
            resolve_scope(&config, None, Some("flagged-proj")).unwrap(),
            ("acme".to_string(), "flagged-proj".to_string()),
            "and vice versa"
        );
    }

    /// No marker means the previous behaviour, byte for byte.
    #[test]
    fn resolve_scope_without_a_marker_keeps_the_old_fallbacks() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config = config_at(tmp.path(), None);

        let (workspace, project) = resolve_scope(&config, None, None).unwrap();

        assert_eq!(workspace, crate::config::DEFAULT_WORKSPACE);
        assert_eq!(project, tmp.path().file_name().unwrap().to_str().unwrap());
    }

    /// A marker carrying only `[capture]` rules declares no scope, so it must
    /// not pull the command out of the default workspace.
    #[test]
    fn resolve_scope_ignores_a_marker_without_scope_keys() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config = config_at(
            tmp.path(),
            Some("[capture]\nignore_paths = [\"secret/**\"]\n"),
        );

        let (workspace, _) = resolve_scope(&config, None, None).unwrap();

        assert_eq!(workspace, crate::config::DEFAULT_WORKSPACE);
    }

    #[test]
    fn resolve_scope_and_workspace_refuse_empty_and_whitespace_flags() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config = config_at(
            tmp.path(),
            Some("workspace = \"acme\"\nproject = \"pinned\"\n"),
        );

        for empty in ["", " ", " \t\n "] {
            let err = resolve_scope(&config, Some(empty), None).unwrap_err();
            assert!(
                err.to_string().contains("--workspace was passed empty"),
                "{err}"
            );
            let err = resolve_scope(&config, Some(empty), Some("explicit")).unwrap_err();
            assert!(
                err.to_string().contains("--workspace was passed empty"),
                "{err}"
            );
            let err = resolve_scope(&config, None, Some(empty)).unwrap_err();
            assert!(
                err.to_string().contains("--project was passed empty"),
                "{err}"
            );
            let err = resolve_scope(&config, Some("explicit"), Some(empty)).unwrap_err();
            assert!(
                err.to_string().contains("--project was passed empty"),
                "{err}"
            );
            let err =
                resolve_scope_with_marker(&config, Some(empty), None, None, false).unwrap_err();
            assert!(
                err.to_string().contains("--workspace was passed empty"),
                "{err}"
            );
            let err =
                resolve_scope_with_marker(&config, None, Some(empty), None, false).unwrap_err();
            assert!(
                err.to_string().contains("--project was passed empty"),
                "{err}"
            );
            let err = resolve_workspace(&config, Some(empty)).unwrap_err();
            assert!(
                err.to_string().contains("--workspace was passed empty"),
                "{err}"
            );
        }

        // Legitimate controls: omitted flags use the marker; non-empty flags override it.
        assert_eq!(
            resolve_scope(&config, None, None).unwrap(),
            ("acme".to_string(), "pinned".to_string())
        );
        assert_eq!(
            resolve_scope(&config, Some("ws"), Some("proj")).unwrap(),
            ("ws".to_string(), "proj".to_string())
        );
        assert_eq!(resolve_workspace(&config, None).unwrap(), "acme");
        assert_eq!(resolve_workspace(&config, Some("ws")).unwrap(), "ws");
    }
}