trusty-mpm 1.8.2

//! In-project spawn path: shared base clone + per-session worktrees (#1706, #1803, #2032).
//!
//! Why: operators who run `tm` from inside a git repository should get a managed
//! session against a git-worktree slice of that repo rather than a full clone.
//! This module implements the "in-project" path: (a) a durable PROTECTED base
//! clone under `~/trusty-mpm-projects/<owner>/<repo>/` that is always on the
//! default branch and owned by the daemon, and (b) a per-session git worktree
//! at `<base>/.worktrees/<worktree_name>` branched off that clone so each
//! session works in isolation. Since #2032 `worktree_name` is the SEMANTIC
//! tmux session name (e.g. `tm-trusty-tools-01`), not the raw session UUID —
//! resolving that name requires the async `SessionManager`, which this module
//! deliberately does not depend on, so worktree CREATION is split from
//! DETECTION (see [`try_inproject_spawn`] vs [`create_session_worktree`]).
//! Existing UUID-named worktrees are left as-is; only NEW sessions get the
//! semantic name.
//! What: [`repos_root`] resolves the configurable root; [`base_clone_path`]
//! computes the per-project clone directory; [`ensure_base_clone`] clones if
//! absent; [`try_inproject_spawn`] is the main entry point called from the
//! lifecycle layer — it detects the GitHub identity and ensures the base
//! clone, returning `(base_path, owner, repo)`; [`create_session_worktree`]
//! adds a per-session worktree at `<base>/.worktrees/<worktree_name>` given a
//! CALLER-RESOLVED name; [`worktree_name_collides`] lets the caller steer name
//! resolution away from an existing worktree dir/branch;
//! [`ensure_worktrees_gitignored`] keeps the worktree directory out of
//! `git status`; [`get_origin_url`] reads the remote.origin.url from a git
//! directory, keeping "no remote" and "git failed" apart so a failure cannot
//! be mistaken for an absent remote (#4734). The sibling [`untracked_sync`]
//! module (#2196) syncs an
//! allowlist of untracked/secret files (e.g. `.env*`) from the operator's
//! live checkout into a freshly-created session worktree; it is called from
//! `lifecycle::reserve_inproject_worktree`, not from this module directly,
//! since only that call site holds both the live-checkout source path and
//! the resolved worktree destination.
//! Test: `try_inproject_spawn_returns_none_for_non_git_path` unit test covers the
//! non-git early exit; integration coverage via `tests/local_spawn.rs`.

use std::path::{Path, PathBuf};

use tracing::{info, warn};

pub mod untracked_sync;

// #7166 review follow-up: split out to keep this file under the 500-SLOC cap.
mod account_clone;
// #9091: the base clone and its account seam, split out for the 500-SLOC cap.
mod base_clone;
pub use base_clone::ensure_base_clone;
// #7166 owner ruling ("do B"): per-account gh config dir bootstrap, used by
// `account_clone` — a sibling module (not nested under it) so both this file
// and `account_clone` can reach it via `super`/direct path without an extra
// re-export hop.
mod account_config_dir;
// #8914: the `--account` session gate builds and checks the same dir.
pub(crate) use account_config_dir::ensure_account_config_dir;

/// Resolve (building if necessary) the per-account `gh` config directory for
/// `login`, for callers outside this module that need to persist it (#7166
/// review follow-up CRITICAL).
///
/// Why: [`ensure_base_clone`] only builds this directory on a genuine first
/// clone — an already-`.git`-containing `base_path` returns early without
/// ever calling [`account_clone::account_clone_env`]/the bootstrap. The CLI
/// (`bin/tm/commands/run_target.rs`'s `run_managed`, `main.rs`'s `Register`
/// handler) needs the SAME directory on every `--account` invocation,
/// including a reused-checkout run, so it can persist
/// `Project.github.config_dir` and keep every LATER session spawn (fetches,
/// pushes, `gh` calls) on the discriminating `GH_CONFIG_DIR` path instead of
/// the demoted `gh auth token -u` fallback.
/// What: delegates to
/// [`account_config_dir::ensure_account_config_dir_default`] — idempotent:
/// builds once from the operator's own logged-in `hosts.yml`, reused
/// untouched on every later call.
/// Test: covered indirectly via `account_config_dir::tests`, which exercise
/// the bootstrap this thin wrapper delegates to; this function adds no logic
/// of its own to test hermetically.
pub fn account_config_dir_for(login: &str) -> Result<PathBuf, String> {
    account_config_dir::ensure_account_config_dir_default(login)
}

/// Environment variable that overrides the managed repos root.
///
/// Why: operators need an escape hatch (tests, non-standard layouts) that wins
/// over config without touching the config file.
/// What: `"TRUSTY_MPM_REPOS_ROOT"`.
/// Test: indirectly by integration tests that set this env var.
pub const REPOS_ROOT_ENV: &str = "TRUSTY_MPM_REPOS_ROOT";

/// Default repos root directory name under `$HOME`.
///
/// Why: mirrors the canonical trusty-mpm-projects directory that `workspace_root()`
/// also resolves to, so both the guided-default path and `tm launch` converge on
/// the same base clone location (#1803).
/// What: `"trusty-mpm-projects"`.
/// Test: `repos_root_default_ends_with_canonical_segment`.
pub const DEFAULT_REPOS_DIR: &str = "trusty-mpm-projects";

/// Resolve the absolute root for base clones, with an optional direct override.
///
/// Why: tests that control the repos root must not mutate process-wide env vars
/// (which races other threads). Exposing the override as a parameter lets callers
/// supply the value directly without `set_var` / `remove_var`.
/// What: `env_override` wins over the `TRUSTY_MPM_REPOS_ROOT` env var, which
/// wins over `workspace_root()`. Falls back to `/tmp/trusty-mpm-projects` only
/// when the home directory is unresolvable AND nothing absolute was supplied.
/// Test: `repos_root_default_ends_with_canonical_segment`; `base_clone_path_respects_repos_root_override` (integration).
pub fn repos_root_from(env_override: Option<&str>) -> PathBuf {
    let home = dirs::home_dir();

    // Direct in-process override (highest priority — used by tests to avoid env mutation).
    if let Some(raw) = env_override {
        let raw = raw.trim();
        if !raw.is_empty() {
            return match &home {
                Some(h) => expand_tilde_repos(raw, h),
                None => PathBuf::from(raw),
            };
        }
    }

    // TRUSTY_MPM_REPOS_ROOT env override (backward compat, wins over workspace_root).
    if let Ok(raw) = std::env::var(REPOS_ROOT_ENV) {
        let raw = raw.trim();
        if !raw.is_empty() {
            return match &home {
                Some(h) => expand_tilde_repos(raw, h),
                None => PathBuf::from(raw),
            };
        }
    }

    // Delegate to the canonical workspace root resolver (TRUSTY_MPM_WORKSPACE_ROOT
    // > config template > ~/trusty-mpm-projects).
    let config = crate::core::trusty_tools_config::TrustyToolsConfig::load();
    crate::core::trusty_tools_config::workspace_root(&config)
}

/// Resolve the absolute root for base clones.
///
/// Why: the base-clone path needs ONE answer for "where do managed base clones
/// live?", with precedence TRUSTY_MPM_REPOS_ROOT env > TRUSTY_MPM_WORKSPACE_ROOT
/// env > config template > built-in `~/trusty-mpm-projects` (#1803).
/// What: delegates to [`repos_root_from`] with no in-process override, reading
/// `TRUSTY_MPM_REPOS_ROOT` from the environment as usual.
/// Falls back to `/tmp/trusty-mpm-projects` only when the home directory is
/// unresolvable AND nothing absolute was supplied.
/// Test: `repos_root_default_ends_with_canonical_segment`.
pub fn repos_root() -> PathBuf {
    repos_root_from(None)
}

/// Expand a leading `~` in a path string to `home`.
///
/// Why: env values are often home-relative; normalizing them once here keeps
/// caller code free of `~` handling.
/// What: replaces a leading `~/` or bare `~` with `home`; other paths pass through.
/// Test: covered indirectly by `repos_root` env-override tests.
fn expand_tilde_repos(template: &str, home: &Path) -> PathBuf {
    if let Some(rest) = template.strip_prefix("~/") {
        home.join(rest)
    } else if template == "~" {
        home.to_path_buf()
    } else {
        PathBuf::from(template)
    }
}

/// Compute the base clone path for a GitHub `owner/repo`.
///
/// Why: the base clone directory must be stable and deterministic so multiple
/// sessions against the same repo all share one protected clone.
/// What: returns `<repos_root>/<owner>/<repo>`.
/// Test: `base_clone_path_resolves_to_canonical_root` (unit); wiring via integration tests.
pub fn base_clone_path(owner: &str, repo: &str) -> PathBuf {
    repos_root().join(owner).join(repo)
}

/// Filename-suffix stem used when migrating a pre-#1803 old-layout dir aside.
///
/// Why: naming the backup suffix once keeps [`migrate_old_layout_aside`] and any
/// operator-facing docs/tests in agreement, and makes the moved directory
/// self-describing (`<repo>.old-layout-backup-<unix_ts>`).
/// What: `".old-layout-backup-"` — the timestamp is appended by the migrator.
/// Test: `ensure_base_clone_migrates_old_layout_dir_aside` asserts a sibling
/// directory whose name contains this stem is created.
pub const OLD_LAYOUT_BACKUP_SUFFIX: &str = ".old-layout-backup-";

/// Detect and migrate a pre-#1803 OLD-LAYOUT base directory out of the way (#1805).
///
/// Why: before #1803 the managed base directory `<repos_root>/<owner>/<repo>/` was
/// a plain container of per-session UUID full-clone subdirectories with NO
/// top-level `.git`. The new shared-base design wants to `git clone` INTO that same
/// path, but git refuses to clone into a non-empty directory — so the clone failed
/// and the daemon silently fell back to the legacy full-clone-per-session behaviour,
/// meaning migrated repos never got the `.worktrees/` layout. Moving the stale dir
/// aside (rather than erroring) upholds the project's "operator does nothing"
/// north-star: the fresh clone proceeds automatically and the old data is preserved
/// under a clearly-named backup the operator can inspect or delete at leisure.
///
/// #4270 carves a whole class out of that automatic rename: a directory holding
/// git or trusty-mpm state. A project directory with `.base` or `.worktrees`
/// matches the old-layout signature exactly (non-empty, no top-level `.git`)
/// but is nothing like it — those hold real repositories and checked-out
/// worktrees, and renaming the parent orphans every one of them at once,
/// possibly while a session is live. That is the #3605 failure mode with a
/// bigger blast radius, so this returns `Err` there instead. The `.git`
/// early-return below does not make `.git` redundant in that check:
/// `Path::exists` answers `false` for an entry it lacks permission to stat, so
/// an EACCES blip on `.git` would otherwise fall through to the rename.
/// What: acts ONLY when `base_path` exists, is a directory, is non-empty, has
/// NO top-level `.git` (the precise old-layout signature), and holds none of the
/// protected entries [`crate::core::harness_root::protected_state_in`] names. In
/// that case it renames `base_path` to a sibling
/// `<repo><OLD_LAYOUT_BACKUP_SUFFIX><unix_nanos>` and returns `Ok(Some(backup))`.
/// Empty dirs, already-`.git` dirs, and absent paths are left untouched
/// (`Ok(None)`) — git clone handles an empty/absent dir fine and the caller
/// handles the `.git` case before ever calling this. Loudly `warn!`s so the
/// migration is never silent.
/// Test: `ensure_base_clone_migrates_old_layout_dir_aside`,
/// `migrate_old_layout_aside_ignores_empty_and_git_dirs`,
/// `migrate_old_layout_aside_refuses_a_dir_holding_a_dot_base_store`,
/// `migrate_old_layout_aside_refuses_a_dir_holding_live_worktrees`.
fn migrate_old_layout_aside(base_path: &Path) -> Result<Option<PathBuf>, String> {
    // Absent path or an existing `.git` dir are both non-old-layout: nothing to do.
    if !base_path.exists() || base_path.join(".git").exists() {
        return Ok(None);
    }

    // A non-directory sitting at the base path is not an old-layout container;
    // leave it for `git clone` to fail loudly rather than silently deleting a file.
    if !base_path.is_dir() {
        return Ok(None);
    }

    // Empty directory → `git clone` succeeds into it; no migration needed.
    let is_empty = std::fs::read_dir(base_path)
        .map_err(|e| {
            format!(
                "inproject: could not inspect base dir {} for old-layout migration: {e}",
                base_path.display()
            )
        })?
        .next()
        .is_none();
    if is_empty {
        return Ok(None);
    }

    // #4270: never rename a directory holding git or trusty-mpm state. The
    // `.git` early-return above cannot cover this on its own — `Path::exists`
    // answers `false` for an entry it cannot stat, so an EACCES blip reads as
    // "no git dir" and the rename proceeds over live work.
    if let Some(found) = crate::core::harness_root::protected_state_in(base_path) {
        return Err(format!(
            "inproject: refusing to migrate {base} aside because it holds {found}, so it \
             already carries git or trusty-mpm state. A `{worktrees}/<id>` worktree or a \
             `{legacy}` store under it may belong to a live session, and renaming the \
             parent orphans every one of them. trusty-mpm will not move, rename, or \
             delete it; retiring a `{legacy}` store is a manual step for once no session \
             needs it.",
            base = base_path.display(),
            legacy = crate::core::harness_root::BASE_CLONE_DIRNAME,
            // #5204: name the configured base in the operator-facing message.
            worktrees = crate::session_manager::decommission::worktrees_dirname(),
        ));
    }

    // Non-empty, no top-level `.git` → this is the pre-#1803 old layout. Move it
    // aside so the fresh shared-base clone can be established at `base_path`.
    let ts = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    let leaf = base_path
        .file_name()
        .map(|n| n.to_string_lossy().into_owned())
        .unwrap_or_else(|| "repo".to_string());
    let backup = base_path.with_file_name(format!("{leaf}{OLD_LAYOUT_BACKUP_SUFFIX}{ts}"));

    warn!(
        base = %base_path.display(),
        backup = %backup.display(),
        "inproject: detected pre-#1803 old-layout base dir (non-empty, no top-level \
         .git); migrating it aside so the new shared-base clone + .worktrees/ layout \
         can engage. The old per-session clones are preserved at the backup path — \
         inspect and delete them once you have confirmed nothing is needed."
    );

    std::fs::rename(base_path, &backup).map_err(|e| {
        format!(
            "inproject: failed to migrate old-layout dir {} aside to {}: {e}",
            base_path.display(),
            backup.display()
        )
    })?;

    warn!(
        backup = %backup.display(),
        "inproject: old-layout base dir migrated aside successfully"
    );
    Ok(Some(backup))
}

/// Compute the per-session worktree directory for `worktree_name` under `base_path`.
///
/// Why: both [`create_session_worktree`] and the caller-side collision check
/// ([`worktree_name_collides`], used by the in-project spawn routing layer to
/// steer `SessionManager::resolve_session_name` away from a name whose
/// worktree already exists on disk, #2032) must agree on exactly where a
/// worktree for a given name would live.
/// What: `<base_path>/<worktrees-dirname>/<worktree_name>`, where the base name
/// is the configured one (#5204) and defaults to `.worktrees` — dot-prefixed so
/// `ensure_worktrees_gitignored` hides it from `git status`.
/// Test: `session_worktree_path_uses_dot_prefix`,
/// `worktree_path_for_honours_configured_base`.
pub fn worktree_path_for(base_path: &Path, worktree_name: &str) -> PathBuf {
    // #5204: CREATION site — resolve the single configured base, not a literal.
    base_path
        .join(crate::session_manager::decommission::worktrees_dirname())
        .join(worktree_name)
}

/// Compute the per-session branch name for `worktree_name`.
///
/// Why: re-exported here (rather than defined here) so existing callers in
/// this module keep the short `worktree_branch_for(...)` spelling. The single
/// source of truth lives in [`crate::core::worktree_naming`] — an
/// unconditionally-compiled module — specifically so
/// `session_manager::decommission` (which is NOT gated behind the `daemon`
/// feature) can depend on the SAME convention without pulling in this
/// feature-gated `daemon` module (#2032; see that module's doc for why the
/// dependency direction matters).
/// What: `format!("session/{worktree_name}")`.
/// Test: `crate::core::worktree_naming::tests::worktree_branch_for_adds_session_prefix`.
pub use crate::core::worktree_naming::worktree_branch_for;

/// Check whether a worktree directory or branch already exists for `worktree_name`.
///
/// Why (#2032): `tmux_name` collisions were already guarded by
/// `SessionManager::resolve_session_name`'s live-tmux-session check, but that
/// check knows nothing about git worktrees or branches — a DIFFERENT
/// collision surface. Without this, two names could theoretically differ in
/// tmux-liveness (one dead, one live) yet share the same worktree directory
/// once #2032 makes the worktree leaf equal to the tmux name, silently
/// clobbering (or failing to clobber, but confusingly erroring on) a stale
/// worktree left behind by a hand-deleted-but-not-decommissioned session.
/// This predicate is threaded into `resolve_session_name` as its
/// `extra_collision` callback so a colliding candidate is retried with the
/// next free serial BEFORE `create_session_worktree` ever runs, rather than
/// discovered as a raw `git worktree add`/`git branch` failure.
/// What: `true` if `<base_path>/.worktrees/<worktree_name>` exists on disk OR
/// `refs/heads/session/<worktree_name>` already exists in `base_path`'s repo.
/// Test: `worktree_name_collides_detects_existing_dir_and_branch`.
pub fn worktree_name_collides(base_path: &Path, worktree_name: &str) -> bool {
    if worktree_path_for(base_path, worktree_name).exists() {
        return true;
    }
    let branch_ref = format!("refs/heads/{}", worktree_branch_for(worktree_name));
    trusty_common::git::command()
        .arg("-C")
        .arg(base_path)
        .args(["rev-parse", "--verify", "--quiet"])
        .arg(&branch_ref)
        .output()
        .map(|out| out.status.success())
        .unwrap_or(false)
}

/// Create a per-session git worktree, refusing when the disk is too full.
///
/// Why (#7497): this is the name every tm-owned provisioning path calls, so the
/// `disk.max_usage_pct` gate belongs on it rather than beside it — a creation
/// path that forgets to check is then a call to a differently-spelled function,
/// not an omission. The ungated mechanics stay reachable as
/// [`create_session_worktree_unchecked`], which is what a test fixture building
/// a worktree to exercise something else calls.
/// What: measures the mount the worktree would land on and delegates to
/// [`create_session_worktree_measured`].
/// Test: `create_session_worktree_measures_a_real_mount` in
/// `tests/worktree_disk_usage_gate.rs` — the live half; the decision itself is
/// pinned through [`create_session_worktree_measured`].
pub fn create_session_worktree(
    base_path: &Path,
    worktree_name: &str,
    owner_session_id: &crate::session_manager::ManagedSessionId,
) -> Result<PathBuf, String> {
    create_session_worktree_gated(
        base_path,
        worktree_name,
        owner_session_id,
        &crate::core::disk_usage_guard::DiskGate::MeasureTarget,
    )
}

/// [`create_session_worktree`] with the measurement source named explicitly.
///
/// Why (#7603): the gate's target path is built HERE, from `base_path` and
/// `worktree_name`, so a caller that wants to pin the measurement cannot take it
/// itself — it has to hand down a [`DiskGate`] and let this function apply it.
/// That is what keeps the tm-bin provisioning tests off the developer's real
/// volume and real `~/.trusty-tools/trusty-mpm/config.yaml`.
/// What: resolves the measurement through `gate` and delegates to
/// [`create_session_worktree_measured`] — same threshold, same decision, only
/// the measurement's source differs.
/// Test: `provision_for_launch_explicit_request_creates_worktree`,
/// `a_pinned_over_threshold_gate_refuses_a_launch_worktree`.
///
/// [`DiskGate`]: crate::core::disk_usage_guard::DiskGate
pub fn create_session_worktree_gated(
    base_path: &Path,
    worktree_name: &str,
    owner_session_id: &crate::session_manager::ManagedSessionId,
    gate: &crate::core::disk_usage_guard::DiskGate,
) -> Result<PathBuf, String> {
    let measured = gate.measurement_for(&worktree_path_for(base_path, worktree_name));
    create_session_worktree_measured(
        base_path,
        worktree_name,
        owner_session_id,
        measured.as_ref(),
    )
}

/// [`create_session_worktree_gated`], recorded in the worktree ledger (#8994).
///
/// Why: every tm provisioning route must enter the tree it creates into
/// `~/.trusty-mpm/worktrees.jsonl`, and a ledger it cannot write must refuse
/// the creation instead of producing an unrecorded tree. One helper serves the
/// daemon and the CLI so the two routes record identically.
/// What: [`crate::core::worktree_ledger::record::create_recorded`] around
/// [`create_session_worktree_gated`], with the session branch and `origin`.
/// Test: `reserve_inproject_worktree_refuses_when_the_ledger_cannot_record`,
/// `reserve_inproject_worktree_records_the_created_tree`,
/// `a_launch_worktree_is_refused_when_the_ledger_cannot_record`.
pub fn create_session_worktree_recorded(
    base_path: &Path,
    worktree_name: &str,
    owner_session_id: &crate::session_manager::ManagedSessionId,
    gate: &crate::core::disk_usage_guard::DiskGate,
    ledger: &crate::core::worktree_ledger::WorktreeLedger,
    origin: crate::core::worktree_ledger::Origin,
) -> Result<PathBuf, String> {
    use crate::core::worktree_ledger::record::{CreationIntent, create_recorded};
    let intent = CreationIntent {
        repo: base_path,
        branch: Some(worktree_branch_for(worktree_name)),
        origin,
        session: Some(owner_session_id.to_string()),
    };
    create_recorded(ledger, intent, || {
        create_session_worktree_gated(base_path, worktree_name, owner_session_id, gate)
    })
    .map_err(|e| e.to_string())
}

/// The daemon's [`create_session_worktree`], recorded in the operator's ledger
/// (#8994).
///
/// What: [`create_session_worktree_recorded`] with the real disk measurement,
/// the `$HOME` ledger and [`crate::core::worktree_ledger::Origin::TmDaemon`];
/// no resolvable home is a refusal.
/// Test: `reserve_inproject_worktree_refuses_when_the_ledger_cannot_record`.
pub fn create_daemon_session_worktree(
    base_path: &Path,
    worktree_name: &str,
    owner_session_id: &crate::session_manager::ManagedSessionId,
) -> Result<PathBuf, String> {
    use crate::core::worktree_ledger::{Origin, WorktreeLedger};
    let ledger = WorktreeLedger::host().map_err(|e| e.to_string())?;
    create_session_worktree_recorded(
        base_path,
        worktree_name,
        owner_session_id,
        &crate::core::disk_usage_guard::DiskGate::MeasureTarget,
        &ledger,
        Origin::TmDaemon,
    )
}

/// [`create_session_worktree`] against an ALREADY-TAKEN measurement.
///
/// Why: the seam the end-to-end tests pin a synthetic percentage through, so
/// the gate's behaviour at, over and below the threshold — and on an
/// unmeasurable mount — is asserted deterministically rather than depending on
/// how full the runner's volume happens to be (#7497 review).
/// What: applies [`crate::core::disk_usage_guard::check_measured`] — fail-closed
/// on `None` per ADR-0037 — and creates nothing when it refuses.
/// Test: `create_session_worktree_refuses_a_pinned_over_threshold_measurement`,
/// `create_session_worktree_refuses_an_unmeasurable_mount`,
/// `create_session_worktree_creates_on_a_pinned_under_threshold_measurement`.
pub fn create_session_worktree_measured(
    base_path: &Path,
    worktree_name: &str,
    owner_session_id: &crate::session_manager::ManagedSessionId,
    measured: Option<&crate::core::disk_usage_guard::MeasuredMount>,
) -> Result<PathBuf, String> {
    // #7497: refuse before creating anything when the mount is at or above
    // `disk.max_usage_pct`.
    crate::core::disk_usage_guard::check_measured(
        &worktree_path_for(base_path, worktree_name),
        measured,
    )
    .map_err(|e| e.to_string())?;
    create_session_worktree_unchecked(base_path, worktree_name, owner_session_id)
}

/// Create a per-session git worktree branched off the base clone, with NO disk
/// gate.
///
/// Why: each managed session must work in an isolated branch; git worktrees
/// achieve this without duplicating the object store of the base clone. Since
/// #2032 the caller supplies the ALREADY-RESOLVED semantic tmux name (e.g.
/// `tm-trusty-tools-01`) rather than the raw session UUID, so the worktree
/// directory and branch are human-readable and match the tmux session the
/// operator actually sees in `tm session ls`.
///
/// NOTE for #2033 (trusty-search index-id derivation): the worktree LEAF NAME
/// computed here (`worktree_name`) is significant beyond this function — the
/// trusty-search index id for a managed session is derived from the worktree
/// path, so #2033 must read the ACTUAL path this function returns (or the
/// record's `workspace_path`, which `spawn_managed_inproject` sets to this
/// same path) rather than re-deriving a path from the session id.
/// What: runs `git -C <base_path> worktree add -b session/<worktree_name>
/// <base_path>/.worktrees/<worktree_name> <start-point>`, where `<start-point>`
/// is `origin/<default-branch>` freshly fetched by
/// [`super::inproject_start_point::resolve`] (#4957 — omitting it inherits the
/// base checkout's local `HEAD`, which starts every session as stale as the
/// operator's last `git pull`). A fetch that fails degrades to the last-known
/// remote-tracking ref (or `HEAD`) and is `warn!`-logged, never silent.
/// Returns the worktree path on
/// success. Fails loudly (rather than silently clobbering) if the target
/// worktree directory already exists — callers are expected to have already
/// steered `SessionManager::resolve_session_name` away from a colliding name
/// via [`worktree_name_collides`], so hitting this guard indicates a TOCTOU
/// race or a caller that skipped the collision check.
/// `owner_session_id` (#3649, Option B): the managed session this worktree is
/// being created FOR — written into the ownership sentinel (as a JSON
/// payload, replacing the pre-#3649 zero-byte convention) so the orphan-GC
/// sweep and the `decommission` owner gate can later resolve who is entitled
/// to reclaim this worktree.
/// Test: covered by integration tests against a real temp repo;
/// `create_session_worktree_rejects_existing_worktree_dir`,
/// `create_session_worktree_writes_owner_sentinel` (#3649),
/// `session_worktree_branches_from_fetched_origin_not_stale_local_main` (#4957).
pub fn create_session_worktree_unchecked(
    base_path: &Path,
    worktree_name: &str,
    owner_session_id: &crate::session_manager::ManagedSessionId,
) -> Result<PathBuf, String> {
    let worktree_path = worktree_path_for(base_path, worktree_name);
    let branch = worktree_branch_for(worktree_name);

    if worktree_path.exists() {
        return Err(format!(
            "inproject: worktree path already exists: {} — refusing to clobber \
             (this should have been caught by the pre-reservation collision check)",
            worktree_path.display()
        ));
    }

    // #4957: cut the session branch from the freshly-fetched remote default
    // branch. Omitting the start-point inherits the base checkout's local
    // HEAD, which is stale on any machine that has not pulled recently.
    // #8934: a local-only repo with no default branch refuses here.
    let start_point =
        super::inproject_start_point::resolve(base_path).map_err(|e| format!("inproject: {e}"))?;
    if let Some(reason) = start_point.warning() {
        warn!(
            base = %base_path.display(),
            branch = %branch,
            "inproject: session worktree is NOT branched from a freshly-fetched origin — {reason}"
        );
    }

    info!(
        base = %base_path.display(),
        worktree = %worktree_path.display(),
        branch = %branch,
        start_point = start_point.git_ref().unwrap_or("HEAD"),
        "inproject: creating per-session worktree"
    );

    let mut add_cmd = trusty_common::git::command();
    add_cmd
        .arg("-C")
        .arg(base_path)
        .args(["worktree", "add", "-b"])
        .arg(&branch)
        .arg(&worktree_path);
    if let Some(git_ref) = start_point.git_ref() {
        add_cmd.arg(git_ref);
    }
    let out = add_cmd
        .output()
        .map_err(|e| format!("inproject: git worktree add failed to spawn: {e}"))?;

    if !out.status.success() {
        let stderr = String::from_utf8_lossy(&out.stderr);
        return Err(format!(
            "inproject: git worktree add failed ({}): {stderr}",
            out.status
        ));
    }

    // #2189: give the new worktree a working `git pull` (upstream tracking the
    // default branch) WITHOUT letting `git push` target that branch. Best-effort
    // and non-fatal — see `configure_session_branch_tracking`.
    configure_session_branch_tracking(base_path, &worktree_path);

    // Item 5 (#1845; JSON payload added #3649): write the SM ownership sentinel
    // so remove_session_worktree can confirm this directory was TM-created and
    // not a user-owned path that happens to sit under a `.worktrees/` parent,
    // AND so the orphan-GC / `decommission` owner gate can resolve WHO owns it
    // (#3649, Option B) — the sentinel now carries a JSON payload naming
    // `owner_session_id`, rather than the pre-#3649 zero-byte convention. The
    // sentinel write is best-effort: a failure here is a non-fatal warning; the
    // worktree was created successfully and the naming-convention fallback in
    // decommission.rs provides backward-compat, while the tolerant sentinel
    // parser treats an unwritten sentinel identically to a legacy one
    // (owner-unknown), never as an error.
    // #8511: written to the git admin dir, so the new tree stays clean.
    if let Err(e) = crate::session_manager::worktree_ownership_location::write_sentinel_bytes(
        &worktree_path,
        &crate::session_manager::worktree_ownership::sentinel_payload_bytes(*owner_session_id),
    ) {
        warn!(
            worktree = %worktree_path.display(),
            sentinel = crate::session_manager::decommission::WORKTREE_SENTINEL_FILE,
            "inproject: failed to write SM ownership sentinel (non-fatal): {e}"
        );
    }

    info!(worktree = %worktree_path.display(), "inproject: per-session worktree created");

    // #5060: register this worktree with trusty-search NOW rather than waiting
    // for a session to launch in it. Fire-and-forget on a detached thread — a
    // cold BM25+KG walk of a large repo takes ~35s, and worktree creation must
    // never wait on it. The index is BM25+KG only (no embeddings); see
    // `core::worktree_index`. Its teardown is already owned by
    // `session_manager::search_gc`, which derives the same id (#2033).
    crate::core::worktree_index::index_new_worktree_in_background(worktree_path.clone());

    Ok(worktree_path)
}

/// Give a freshly-created session worktree a working `git pull` from the
/// default branch, WITHOUT making `git push` target that branch (#2189).
///
/// Why: [`create_session_worktree`] leaves the new `session/<name>` branch
/// with no upstream at all, so a bare `git pull` inside the worktree fails
/// with "There is no tracking information for the current branch." Setting
/// the upstream to `origin/<default>` fixes `pull`/`fetch`-with-merge, but
/// naively doing so ALSO makes a bare `git push` try to push the session
/// branch's commits onto the shared default branch — which is exactly what a
/// per-session isolated branch must never do. Scoping `push.default =
/// current` to this one worktree (via `extensions.worktreeConfig` +
/// `--worktree` config) keeps push targeting `origin/session/<name>` while
/// pull still tracks the default branch.
///
/// ORDERING IS A SAFETY PROPERTY (#2867). `branch.<session>.merge =
/// refs/heads/<default>` is a FOREIGN upstream: the session worktree does not
/// own the default branch. It is only safe while `push.default = current` is
/// actually in effect for this worktree — that is the single knob keeping a
/// bare `git push` off the default branch. The push pin is therefore
/// established and READ BACK FIRST, and the foreign upstream is written only
/// once the pin is confirmed. When the pin cannot be confirmed (an old git
/// without `extensions.worktreeConfig`, a read-only base config, a sandbox
/// blocking the config write) the worktree is left with NO upstream at all:
/// `git pull` then needs a one-off `git pull origin <default>`, which is a far
/// cheaper failure than an armed worktree whose bare push lands on a branch it
/// does not own — the exact shape that clobbered PR #2863's reviewed lineage.
///
/// What: (1) runs `git -C <base_path> config extensions.worktreeConfig true`
/// to enable per-worktree config on the shared base repo (idempotent — safe to
/// set on every call); (2) runs `git -C <worktree_path> config --worktree
/// push.default current` so `git push` always targets the current (session)
/// branch; (3) reads the EFFECTIVE `push.default` back from the worktree and
/// aborts without setting any upstream unless it resolves to `current`; (4)
/// resolves the default branch via
/// [`super::inproject_hygiene::get_default_branch`], falling back to `"main"`
/// when it cannot be determined, and runs `git -C <worktree_path> branch
/// --set-upstream-to=origin/<default>` so `git pull` works. Every step is
/// best-effort: a failure is logged via `warn!` and does NOT fail worktree
/// creation — the worktree itself was already created successfully by the time
/// this runs, and an operator can always set tracking manually as a fallback.
/// Test: `create_session_worktree_sets_pull_upstream_and_worktree_scoped_push`
/// and `push_pin_detection_matches_effective_config` (real temp git repos with
/// a bare `origin` remote).
/// Does the effective `push.default` say a bare `git push` targets the current
/// branch?
///
/// Note the deliberately narrow claim: this reports on `push.default` only. It
/// is NOT a proof that no push can leave the current branch. A configured
/// `remote.<name>.push` refspec bypasses `push.default` entirely, and the gate
/// is equally satisfied by a GLOBAL `push.default = current` that trusty-mpm
/// does not own and the user may change later, re-arming an upstream already
/// written under it. The `pre-push` guard (`crate::core::push_guard`) is the
/// backstop for both; this check only decides whether writing a foreign
/// upstream is defensible in the first place.
///
/// Why: this is the precondition for [`configure_session_branch_tracking`] to
/// be allowed to write a FOREIGN upstream (#2867). Checking the exit status of
/// the `git config --worktree push.default current` write is not enough — it
/// answers "did the write succeed", not "what will `git push` actually do".
/// What: reads the EFFECTIVE `push.default` with `git config --get`, which
/// resolves the whole config stack (system → global → local → `config.worktree`)
/// exactly as `git push` will, and reports whether it is `current`. Any failure
/// to read (git missing, not a repo, key unset) is reported as NOT pinned —
/// the fail-safe direction.
/// Test: `push_pin_detection_matches_effective_config`.
fn push_is_pinned_to_current(worktree_path: &Path) -> bool {
    trusty_common::git::command()
        .arg("-C")
        .arg(worktree_path)
        .args(["config", "--get", "push.default"])
        .output()
        .ok()
        .filter(|out| out.status.success())
        .is_some_and(|out| String::from_utf8_lossy(&out.stdout).trim() == "current")
}

fn configure_session_branch_tracking(base_path: &Path, worktree_path: &Path) {
    // Step 1: enable per-worktree config on the shared base repo (idempotent).
    let enable_worktree_config = trusty_common::git::command()
        .arg("-C")
        .arg(base_path)
        .args(["config", "extensions.worktreeConfig", "true"])
        .output();
    match enable_worktree_config {
        Ok(out) if out.status.success() => {
            info!(base = %base_path.display(), "inproject: extensions.worktreeConfig enabled on base clone");
        }
        Ok(out) => {
            warn!(
                base = %base_path.display(),
                "inproject: git config extensions.worktreeConfig failed (non-fatal) ({}): {}",
                out.status,
                String::from_utf8_lossy(&out.stderr).trim()
            );
        }
        Err(e) => {
            warn!(
                base = %base_path.display(),
                "inproject: failed to spawn git config extensions.worktreeConfig (non-fatal): {e}"
            );
        }
    }

    // Step 2: scope push.default=current to THIS worktree only, so `git push`
    // always targets `origin/session/<name>` and never the default branch.
    let set_push_default = trusty_common::git::command()
        .arg("-C")
        .arg(worktree_path)
        .args(["config", "--worktree", "push.default", "current"])
        .output();
    match set_push_default {
        Ok(out) if out.status.success() => {
            info!(
                worktree = %worktree_path.display(),
                "inproject: worktree-scoped push.default=current set (git push cannot target the default branch)"
            );
        }
        Ok(out) => {
            warn!(
                worktree = %worktree_path.display(),
                "inproject: failed to set worktree-scoped push.default (non-fatal) ({}): {}",
                out.status,
                String::from_utf8_lossy(&out.stderr).trim()
            );
        }
        Err(e) => {
            warn!(
                worktree = %worktree_path.display(),
                "inproject: git config --worktree push.default failed to spawn (non-fatal): {e}"
            );
        }
    }

    // Step 3 (#2867 gate): confirm the pin is EFFECTIVE before arming a
    // foreign upstream.
    if !push_is_pinned_to_current(worktree_path) {
        warn!(
            worktree = %worktree_path.display(),
            "inproject: push.default is NOT pinned to `current`; refusing to set the \
             session branch's upstream to the default branch (#2867). `git pull` in this \
             worktree needs an explicit `git pull origin <default-branch>`."
        );
        return;
    }

    // #8934: a local-only repo has no `origin/<default>` to track.
    if crate::core::remote_mode::remote_mode(base_path).is_ok_and(|m| m.is_local_only()) {
        let skip = crate::core::remote_mode::LOCAL_ONLY_SKIP;
        info!(worktree = %worktree_path.display(), "inproject: {skip}; no upstream set");
        return;
    }

    // Step 4: now that a bare `git push` provably cannot leave this branch,
    // set upstream so `git pull` (and `git fetch` + merge) works.
    let default_branch = super::inproject_hygiene::get_default_branch(base_path)
        .unwrap_or_else(|| "main".to_string());
    let upstream = format!("origin/{default_branch}");
    let set_upstream = trusty_common::git::command()
        .arg("-C")
        .arg(worktree_path)
        .args(["branch", &format!("--set-upstream-to={upstream}")])
        .output();
    match set_upstream {
        Ok(out) if out.status.success() => {
            info!(
                worktree = %worktree_path.display(),
                upstream = %upstream,
                "inproject: session worktree branch upstream set (git pull now works)"
            );
        }
        Ok(out) => {
            warn!(
                worktree = %worktree_path.display(),
                upstream = %upstream,
                "inproject: failed to set branch upstream (non-fatal; `git pull` will \
                 require manual tracking setup) ({}): {}",
                out.status,
                String::from_utf8_lossy(&out.stderr).trim()
            );
        }
        Err(e) => {
            warn!(
                worktree = %worktree_path.display(),
                "inproject: git branch --set-upstream-to failed to spawn (non-fatal): {e}"
            );
        }
    }
}

/// Keep the base clone's `.worktrees/` out of `git status` AND out of reach of
/// `git clean -ffd`.
///
/// Why: re-exported here (rather than defined here) so this module's existing
/// callers keep the short spelling, exactly like [`worktree_branch_for`] above.
/// The single source of truth moved to [`crate::core::worktree_naming`] in
/// #4270 because `provisioner::workspace` — which is NOT gated behind the
/// `daemon` feature — now produces the identical topology and needs the same
/// entry. See that module for the `git clean` evidence.
/// What: appends `.worktrees/` to `<base>/.git/info/exclude`, idempotently.
/// Test: `ensure_worktrees_gitignored_idempotent`,
/// `worktrees_exclude_entry_protects_against_double_force_clean`.
pub use crate::core::worktree_naming::ensure_worktrees_gitignored;

/// Confirm git reads the repository rooted at `path`, when one is rooted there.
///
/// Why: `git config --get` answers from whatever repository DISCOVERY finds,
/// and discovery walks straight past a `.git` it cannot read — which hides two
/// faults the exit code cannot express (#4734). A `.git` directory at mode 000
/// with no repo above it exits **1 with empty stderr**, identical to "no origin
/// remote"; the same `.git` nested inside another repo exits **0 with the
/// PARENT repo's origin**, which would have the daemon provision a managed
/// clone of the wrong repository. Neither shows up in the exit code or in
/// stderr, so the exit-code split alone cannot catch them and no amount of
/// stderr matching would either.
/// What: `path/.git` existing means a repository is rooted at `path`, so git's
/// own `rev-parse --show-toplevel` must name `path` back. A failure to answer,
/// or an answer naming a different directory, is `Err`. When `path/.git` does
/// NOT exist the check is skipped, which keeps the two legitimate cases
/// working: `path` is not in a repo at all (the caller's read exits 1, a true
/// `Ok(None)`), or `path` is a subdirectory of a repo, where discovering the
/// enclosing repo is exactly what callers want. `--show-toplevel` rather than
/// the git dir because a linked worktree's git dir lives under the main
/// checkout while its toplevel is the worktree itself — and tm creates linked
/// worktrees, so that case is load-bearing.
/// Test: `get_origin_url_errors_when_the_git_dir_is_unreadable`,
/// `get_origin_url_errors_when_discovery_escapes_to_a_parent_repo`,
/// `get_origin_url_reads_a_linked_worktree`.
fn ensure_repo_rooted_at(path: &Path) -> Result<(), String> {
    if !path.join(".git").exists() {
        return Ok(());
    }

    let out = trusty_common::git::command()
        .arg("-C")
        .arg(path)
        .args(["rev-parse", "--show-toplevel"])
        .output()
        .map_err(|e| format!("could not run `git rev-parse` in '{}': {e}", path.display()))?;

    if !out.status.success() {
        return Err(format!(
            "'{}' has a .git entry but git cannot read a repository there: {}",
            path.display(),
            String::from_utf8_lossy(&out.stderr).trim()
        ));
    }

    let toplevel = PathBuf::from(String::from_utf8_lossy(&out.stdout).trim());
    let rooted_here = std::fs::canonicalize(&toplevel)
        .ok()
        .zip(std::fs::canonicalize(path).ok())
        .is_some_and(|(found, want)| found == want);
    if !rooted_here {
        return Err(format!(
            "'{}' has a .git entry but git resolved the repository to '{}'; refusing to \
             answer with another repository's remote",
            path.display(),
            toplevel.display()
        ));
    }
    Ok(())
}

/// Read the `remote.origin.url` from a git repository at `path`.
///
/// Why: the in-project spawn path needs the remote URL to determine the
/// `owner/repo` identity and locate the matching base clone. Before #4734 this
/// returned a bare `Option`, so "this repo has no `origin` remote" and "git
/// could not answer at all" were the same value, and every caller read it as
/// the former — `tm launch` and the guided default told the operator a repo
/// they could not read had no remote, or was not a GitHub project, and sent
/// them to `tm connect` for a checkout that is fine.
/// What: guards with [`ensure_repo_rooted_at`], then runs
/// `git -C <path> config --get remote.origin.url` and keeps apart the outcomes
/// git distinguishes by exit code. Exit 0 yields `Ok(Some(url))`, or `Ok(None)`
/// when the configured value is empty. Exit 1 is git-config's "the key is not
/// set" answer, so it yields `Ok(None)` — both a plain non-git directory and a
/// repo with no `origin` land there, which is why this split changes no
/// existing caller's behaviour on a healthy machine (a multi-valued `origin`,
/// the one working setup that could have regressed into `Err`, exits 0).
/// Anything else — a spawn failure, or a fatal exit such as 128 for an
/// unreadable `.git/config`, a dangling gitdir pointer, or a `safe.directory`
/// ownership refusal — is `Err`, for the caller to fail closed on.
/// Test: `get_origin_url_returns_none_for_non_git`,
/// `get_origin_url_returns_none_for_repo_without_origin`,
/// `get_origin_url_handles_a_multi_valued_origin`,
/// `get_origin_url_reads_a_linked_worktree`,
/// `get_origin_url_errors_when_git_config_is_unreadable`,
/// `get_origin_url_errors_when_the_git_dir_is_unreadable`,
/// `get_origin_url_errors_when_discovery_escapes_to_a_parent_repo` (unit);
/// `try_inproject_spawn_errors_when_git_cannot_read_the_remote`
/// (`tests/inproject_git_failure.rs`).
pub fn get_origin_url(path: &Path) -> Result<Option<String>, String> {
    // #4734: the exit code alone cannot separate "no origin remote" from "git
    // never read the repo rooted here" — see `ensure_repo_rooted_at`.
    ensure_repo_rooted_at(path)?;

    let out = trusty_common::git::command()
        .arg("-C")
        .arg(path)
        .args(["config", "--get", "remote.origin.url"])
        .output()
        .map_err(|e| {
            format!(
                "could not run `git config --get remote.origin.url` in '{}': {e}",
                path.display()
            )
        })?;

    match out.status.code() {
        Some(0) => {
            let url = String::from_utf8_lossy(&out.stdout).trim().to_string();
            Ok(if url.is_empty() { None } else { Some(url) })
        }
        Some(1) => Ok(None),
        Some(code) => Err(format!(
            "`git config --get remote.origin.url` failed in '{}' (exit {code}): {}",
            path.display(),
            String::from_utf8_lossy(&out.stderr).trim()
        )),
        None => Err(format!(
            "`git config --get remote.origin.url` was killed by a signal in '{}'",
            path.display()
        )),
    }
}

/// Main entry point for the in-project spawn path's DETECTION phase (#1706, #2032).
///
/// Why: the lifecycle layer needs a single call that encapsulates in-project
/// detection: is the given path inside a git repo with a GitHub remote? If so,
/// ensure the base clone exists. Since #2032 this function STOPS SHORT of
/// creating the per-session worktree: the worktree directory/branch must be
/// named after the semantic tmux name (resolved via
/// `SessionManager::resolve_session_name`), which requires the session
/// manager's async store/tmux state that this synchronous, decoupled module
/// deliberately has no access to. The caller
/// (`daemon::managed_routes::lifecycle::spawn_managed_routed`) resolves the
/// name and calls [`create_session_worktree`] itself.
/// What: (1) checks that `path` is an existing directory with a `.git` entry;
/// (2) reads the `remote.origin.url` — returns `Ok(None)` if absent, and `Err`
/// when git could not answer at all (#4734: this step used to collapse those
/// two into `Ok(None)`, so the caller went on to report a repo git could not
/// read as one with no GitHub remote);
/// (3) parses the URL via `trusty_common::github_path::parse_github_path` —
/// returns `Ok(None)` if unparseable; (4) calls [`ensure_base_clone`];
/// (5) returns `Ok(Some((base_clone_path, owner, repo)))` — NOT a worktree
/// path (that was the pre-#2032 contract). Step 4 errors propagate as `Err`.
/// Test: `try_inproject_spawn_returns_none_for_non_git_path` (unit),
/// `try_inproject_spawn_errors_when_git_cannot_read_the_remote`
/// (`tests/inproject_git_failure.rs`).
pub fn try_inproject_spawn(path: &Path) -> Result<Option<(PathBuf, String, String)>, String> {
    if !path.is_dir() || !path.join(".git").exists() {
        return Ok(None);
    }

    // #4734: `?` here is the fix — a git failure stops the spawn instead of
    // falling through as though this repo simply had no remote.
    let Some(origin_url) = get_origin_url(path)? else {
        warn!(
            path = %path.display(),
            "inproject: no remote.origin.url found; falling through to local-path spawn"
        );
        return Ok(None);
    };

    let Some(gh) = trusty_common::github_path::parse_github_path(&origin_url) else {
        warn!(
            // #9124: a remote URL may embed `user:token@`.
            url = %crate::core::remote_url_redact::redact_stored_url(&origin_url),
            "inproject: cannot parse GitHub owner/repo from remote URL; falling through"
        );
        return Ok(None);
    };

    let base = base_clone_path(&gh.owner, &gh.repo);
    // #7166: an already-on-disk operator checkout has no account SELECTOR to
    // apply. #9091: `None` still clones as the origin's registry pin, else its
    // `[accounts]` login — the account its sessions spawn as.
    ensure_base_clone(&origin_url, &base, None)?;

    info!(
        owner = %gh.owner,
        repo = %gh.repo,
        base = %base.display(),
        "inproject: base clone ready for per-session worktree"
    );

    Ok(Some((base, gh.owner, gh.repo)))
}

#[cfg(test)]
mod tests;