Skip to main content

magi/
cache.rs

1//! Durable ownership of the shared Cargo build cache (`CARGO_TARGET_DIR`).
2//!
3//! One cache, many borrowers: an implement wave's candidates, a review
4//! round's E2E, the final gate, a human's `magi review` invoked by hand — all
5//! of them may point `CARGO_TARGET_DIR` at the same directory, sometimes from
6//! *different* worktrees, sometimes from a different `magi run` entirely. Two
7//! failures came out of sharing it with no ownership record at all:
8//!
9//! - A read-only reviewer seat that inherited `CARGO_TARGET_DIR` tried to
10//!   write into it, was refused by its own sandbox, and reported the refusal
11//!   as a defect in the code under review rather than a property of its own
12//!   seat. See `graph::wave`, which now only hands the variable to a seat
13//!   that [`crate::agent::Invocation::allow_write`] actually permits to use.
14//! - Two source trees building the same package name/version into one
15//!   `CARGO_TARGET_DIR` in sequence can leave a stale artifact from the
16//!   *older* worktree looking fresh to Cargo, and a later `cargo test` runs
17//!   binaries compiled from source nobody is looking at. [`ensure_fresh`]
18//!   selectively `cargo clean -p`s the workspace's own packages — never the
19//!   downloaded dependency graph — the moment the recorded source identity
20//!   for a cache directory changes.
21//!
22//! Both are consequences of one missing fact: *who is using this cache right
23//! now, and against which source*. This module is that fact, made durable
24//! (a JSON file per cache directory, surviving a process restart) and cheap
25//! to ask (`classify`, `in_use`, `inventory`).
26//!
27//! ## Reclaiming a dead owner
28//!
29//! Liveness is [`crate::proc::pid_alive`] — the same conservative check
30//! [`crate::daemon::sweep_stale_claims`] uses for the queue's own claim
31//! locks: every uncertain outcome reads as alive, and a lease whose file
32//! cannot even be parsed is never reclaimed automatically ([`Status::Unknown`]).
33//! This is deliberately the same policy as the queue's `.lock` files, not a
34//! new one — a bare lock file was never trusted alone there either; it is
35//! always paired with a liveness check.
36//!
37//! Process cleanup additionally holds an OS output lease through termination of
38//! managed tool descendants. Admission and destructive maintenance check that
39//! lease too: reclaiming a dead JSON owner alone does not permit deleting or
40//! reusing outputs still owned by cleanup.
41
42use std::path::{Path, PathBuf};
43use std::time::Duration;
44
45use anyhow::{Context as _, Result, bail};
46use jiff::Timestamp;
47use serde::{Deserialize, Serialize};
48
49use crate::proc::{self, Quiet as _};
50
51/// Who is holding, or wants, a cache directory.
52#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
53pub struct Owner {
54    /// The run this borrow belongs to.
55    pub run: String,
56    /// The graph node, e.g. `implement`, `review`, `gate`.
57    pub node: String,
58    /// Seat key, or a fixed label for a borrow that is not seat-shaped
59    /// (`"e2e"`, `"gate"`, `"janitor"`).
60    pub seat: String,
61    /// Process id of the magi process holding the lease — never the spawned
62    /// agent CLI or `cargo` child, both of which end well before this
63    /// process's own async task returns and releases the guard.
64    pub pid: u32,
65    /// The worktree the borrower is building from, for the report and for
66    /// [`ensure_fresh`]'s identity comparison.
67    pub worktree: String,
68    /// The commit the borrower is building, same purpose as `worktree`.
69    pub head: String,
70}
71
72impl Owner {
73    /// An owner for the current process.
74    #[must_use]
75    pub fn here(run: &str, node: &str, seat: &str, worktree: &Path, head: &str) -> Owner {
76        Owner {
77            run: run.to_owned(),
78            node: node.to_owned(),
79            seat: seat.to_owned(),
80            pid: std::process::id(),
81            worktree: worktree.display().to_string(),
82            head: head.to_owned(),
83        }
84    }
85}
86
87/// One held lease, as written to disk.
88#[derive(Debug, Clone, Serialize, Deserialize)]
89struct LeaseFile {
90    /// The literal cache path, kept alongside the owner so [`inventory`] can
91    /// report it without reversing the filename — the filename is a lossy
92    /// slug, not the path itself.
93    cache_dir: String,
94    owner: Owner,
95    acquired_at: Timestamp,
96}
97
98/// Where a cache directory's classification lands.
99#[derive(Debug, Clone, PartialEq, Eq)]
100pub enum Status {
101    /// No lease file, or one whose owner is confirmed gone.
102    Free,
103    /// A live owner holds it.
104    Active(Owner),
105    /// A lease file names an owner whose pid is confirmed gone. Reclaimable.
106    Stale(Owner),
107    /// A lease file exists but could not be trusted — unreadable or
108    /// unparseable. Never reclaimed automatically; a human decides.
109    Unknown,
110}
111
112/// Why [`try_acquire`] did not hand back a [`Guard`].
113#[derive(Debug, Clone, PartialEq, Eq)]
114pub enum Busy {
115    /// Held by a confirmed-live owner.
116    Active(Owner),
117    /// A lease is present but could not be trusted.
118    Unknown,
119    /// Lost a race with another acquirer; the caller should just try again.
120    Contended,
121    /// A process cleanup owner still protects the cache outputs.
122    Outputs,
123}
124
125impl Busy {
126    /// One line for an event log or an error message.
127    #[must_use]
128    pub fn describe(&self) -> String {
129        match self {
130            Busy::Active(o) => format!(
131                "held by run {} node {} seat {} (pid {})",
132                o.run, o.node, o.seat, o.pid
133            ),
134            Busy::Unknown => {
135                "an unreadable lease is present; refusing to guess who holds it".to_owned()
136            }
137            Busy::Outputs => {
138                "cache outputs are still owned by running tools or process cleanup".to_owned()
139            }
140            Busy::Contended => "lost a race for the lease; retrying".to_owned(),
141        }
142    }
143}
144
145/// A held lease. Releases on drop, so a panicking or early-returning caller
146/// never leaves the cache permanently marked busy — the same guarantee
147/// [`crate::queue::Claim`] gives the task queue's own lock file.
148#[derive(Debug)]
149pub struct Guard {
150    path: PathBuf,
151    released: bool,
152    outputs: Option<crate::retention::OutputLease>,
153}
154
155impl Guard {
156    fn new(path: PathBuf) -> Guard {
157        Guard {
158            path,
159            released: false,
160            outputs: None,
161        }
162    }
163
164    /// Release explicitly. Equivalent to dropping the guard; spelled out for
165    /// call sites where "the build finished, release now" reads better than
166    /// waiting for scope exit.
167    pub fn release(mut self) {
168        self.do_release();
169    }
170
171    fn do_release(&mut self) {
172        if !self.released {
173            let _ = std::fs::remove_file(&self.path);
174            self.released = true;
175        }
176    }
177}
178
179impl Drop for Guard {
180    fn drop(&mut self) {
181        self.do_release();
182    }
183}
184
185/// The directory leases live under, inside the magi home — never inside the
186/// cache directory itself, so [`crate::disk::prune_dir`]'s oldest-first sweep
187/// of the cache can never delete a lease file it does not know exists.
188fn leases_dir(home: &Path) -> PathBuf {
189    home.join("cache-leases")
190}
191
192/// A stable, filesystem-safe name for one cache directory's lease file.
193/// Human-legible prefix (so a directory listing is self-explanatory) plus a
194/// hash suffix (so two paths that sanitize to the same prefix — unlikely,
195/// but not impossible on a long path — never collide).
196fn slug(cache_dir: &Path) -> String {
197    if let Some(id) = crate::build_target::generation(cache_dir) {
198        return format!("isolated-{id}");
199    }
200    let norm = normalize(cache_dir);
201    let mut readable: String = norm
202        .chars()
203        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
204        .collect();
205    readable.truncate(80);
206    use std::hash::{Hash, Hasher};
207    let mut hasher = std::collections::hash_map::DefaultHasher::new();
208    norm.hash(&mut hasher);
209    format!("{readable}-{:08x}", hasher.finish() as u32)
210}
211
212/// Best-effort canonical form of a cache path, for hashing only — never
213/// shown to a human, who gets the literal path out of the lease file's own
214/// `cache_dir` field instead. Falls back to the literal string when the
215/// directory does not exist yet, so a lease can be taken before the first
216/// build creates it.
217fn normalize(p: &Path) -> String {
218    std::fs::canonicalize(p)
219        .map(|p| p.display().to_string())
220        .unwrap_or_else(|_| p.display().to_string())
221        .replace('\\', "/")
222        .to_ascii_lowercase()
223}
224
225fn lease_path(home: &Path, cache_dir: &Path) -> PathBuf {
226    leases_dir(home).join(format!("{}.json", slug(cache_dir)))
227}
228
229fn identity_path(home: &Path, cache_dir: &Path) -> PathBuf {
230    leases_dir(home).join(format!("{}.identity.json", slug(cache_dir)))
231}
232
233fn catalog_path(home: &Path, cache_dir: &Path) -> PathBuf {
234    leases_dir(home).join(format!("{}.catalog.json", slug(cache_dir)))
235}
236
237/// A cache directory magi has leased before, remembered past the point its
238/// lease file is gone.
239///
240/// A lease file's whole reason to exist is contention, and [`Guard::release`]
241/// deletes it the moment nobody holds it — correctly, since a stale lock file
242/// left lying around is exactly the bug this module exists to avoid repeating
243/// (see the module docs on the queue's own `.lock` files). But that means a
244/// cache directory nobody is actively borrowing is, from a lease file alone,
245/// indistinguishable from one magi never touched: both read as
246/// [`Status::Free`]. `magi-land6`, `magi-land7` and `magi-landtimedout` — idle
247/// Cargo caches worth tens of gigabytes each, found only by a manual sweep of
248/// `Temp` during the 2026-09-12 recovery — are exactly this: real, orphaned,
249/// magi-managed caches that [`inventory`] could not see because nothing was
250/// still holding them. This record is what closes that gap: written on every
251/// successful acquire, never deleted by [`Guard`], so a cleanup surface can
252/// still find and size a cache days after the last borrower let go of it.
253#[derive(Debug, Clone, Serialize, Deserialize)]
254struct CatalogRecord {
255    cache_dir: String,
256    last_owner: Owner,
257    last_used_at: Timestamp,
258}
259
260/// Remember `cache_dir` as one magi has leased, for [`inventory`] to find
261/// after the lease itself is gone. Best-effort: a write that fails costs a
262/// future cleanup listing one entry, never the acquire this rides along
263/// with — an operator missing an inventory row is a much smaller problem than
264/// a build that failed to get its cache.
265fn record_catalog(home: &Path, cache_dir: &Path, owner: &Owner) {
266    let path = catalog_path(home, cache_dir);
267    let record = CatalogRecord {
268        cache_dir: cache_dir.display().to_string(),
269        last_owner: owner.clone(),
270        last_used_at: Timestamp::now(),
271    };
272    let Ok(body) = serde_json::to_string_pretty(&record) else {
273        return;
274    };
275    let tmp = path.with_extension("json.tmp");
276    if std::fs::write(&tmp, &body).is_ok() {
277        let _ = std::fs::rename(&tmp, &path);
278    }
279}
280
281/// Read whatever JSON is at `path` as a [`CatalogRecord`], or `None` when it
282/// is missing or does not parse — an unreadable catalog entry costs
283/// [`inventory`] one row, not a wrong answer about who owns anything, since
284/// ownership is always decided from the lease file, never the catalog.
285fn read_catalog(path: &Path) -> Option<CatalogRecord> {
286    let body = std::fs::read_to_string(path).ok()?;
287    serde_json::from_str(&body).ok()
288}
289
290/// Read whatever JSON is at `path` as a [`LeaseFile`], or `None` when it is
291/// missing or does not parse.
292fn read_lease(path: &Path) -> Option<LeaseFile> {
293    let body = std::fs::read_to_string(path).ok()?;
294    serde_json::from_str(&body).ok()
295}
296
297/// Best-effort read of just the `cache_dir` field, for [`inventory`] to
298/// report a path even when the rest of the record — the owner — does not
299/// parse. A corrupt lease is still evidence of *which* directory is in a
300/// state nobody can vouch for.
301fn peek_cache_dir(path: &Path) -> Option<String> {
302    let body = std::fs::read_to_string(path).ok()?;
303    let value: serde_json::Value = serde_json::from_str(&body).ok()?;
304    value
305        .get("cache_dir")
306        .and_then(|v| v.as_str())
307        .map(str::to_owned)
308}
309
310/// Classify the lease at `path`, using the real process-liveness query.
311fn classify(path: &Path) -> Status {
312    classify_with(path, proc::pid_alive)
313}
314
315/// [`classify`] with its process-liveness query supplied by the caller —
316/// mirrors [`crate::daemon::sweep_stale_claims_with`], which exists for the
317/// identical reason: a real "confirmed dead" pid cannot be produced portably
318/// from a test (an out-of-range value reads as *unavailable*, not dead, to
319/// `tasklist`/`kill -0`, and the conservative policy those already apply -
320/// correctly - treats an unavailable query as alive). Production code always
321/// goes through [`classify`]; this is what a test calls directly to assert
322/// the classification logic against an injected answer instead.
323fn classify_with<F: Fn(u32) -> bool>(path: &Path, alive: F) -> Status {
324    if !path.exists() {
325        return Status::Free;
326    }
327    let Some(lease) = read_lease(path) else {
328        return Status::Unknown;
329    };
330    let this_process = std::process::id();
331    if lease.owner.pid == this_process || alive(lease.owner.pid) {
332        Status::Active(lease.owner)
333    } else {
334        Status::Stale(lease.owner)
335    }
336}
337
338/// Write a brand-new lease file, atomically — `create_new` refuses to
339/// overwrite an existing one, exactly like [`crate::queue::Queue::claim`]'s
340/// task lock, which this mirrors on purpose rather than inventing a second
341/// exclusion primitive in the same codebase.
342fn write_new(
343    path: &Path,
344    cache_dir: &Path,
345    owner: &Owner,
346    retry: crate::lock_file::Retry,
347) -> std::io::Result<()> {
348    write_lease(retry.create(path)?, cache_dir, owner)
349}
350
351fn write_lease(mut f: std::fs::File, cache_dir: &Path, owner: &Owner) -> std::io::Result<()> {
352    use std::io::Write as _;
353    let lease = LeaseFile {
354        cache_dir: cache_dir.display().to_string(),
355        owner: owner.clone(),
356        acquired_at: Timestamp::now(),
357    };
358    let body = serde_json::to_string_pretty(&lease).unwrap_or_default();
359    f.write_all(body.as_bytes())?;
360    Ok(())
361}
362
363/// What [`try_acquire`] returned.
364pub enum AcquireOutcome {
365    /// The lease is now held by the caller.
366    Acquired(Guard),
367    /// Somebody else has it, or its state could not be trusted.
368    Busy(Busy),
369}
370
371/// Take the lease for `cache_dir` if nobody live holds it, reclaiming a
372/// stale one first. One attempt — a caller that wants to wait uses
373/// [`wait_for`], which is this in a loop bounded by a budget.
374pub fn try_acquire(home: &Path, cache_dir: &Path, owner: &Owner) -> Result<AcquireOutcome> {
375    let Ok(_outputs) = crate::retention::OutputLease::cache(home, cache_dir, true) else {
376        return Ok(AcquireOutcome::Busy(Busy::Outputs));
377    };
378    try_acquire_with(home, cache_dir, owner, proc::pid_alive)
379}
380
381/// Take both cache ownership and exclusive output ownership for a destructive
382/// maintenance operation. Refuses while process cleanup still owns descendants.
383pub fn try_acquire_maintenance(
384    home: &Path,
385    cache_dir: &Path,
386    owner: &Owner,
387) -> Result<AcquireOutcome> {
388    crate::build_target::check_prune(home, cache_dir)?;
389    let Ok(outputs) = crate::retention::OutputLease::cache(home, cache_dir, true) else {
390        return Ok(AcquireOutcome::Busy(Busy::Outputs));
391    };
392    match try_acquire_with(home, cache_dir, owner, proc::pid_alive)? {
393        AcquireOutcome::Acquired(mut guard) => {
394            guard.outputs = Some(outputs);
395            Ok(AcquireOutcome::Acquired(guard))
396        }
397        busy => Ok(busy),
398    }
399}
400
401/// [`try_acquire`] with its process-liveness query supplied by the caller —
402/// see [`classify_with`] for why this split exists.
403fn try_acquire_with<F: Fn(u32) -> bool + Copy>(
404    home: &Path,
405    cache_dir: &Path,
406    owner: &Owner,
407    alive: F,
408) -> Result<AcquireOutcome> {
409    try_acquire_before(
410        home,
411        cache_dir,
412        owner,
413        alive,
414        crate::lock_file::Retry::new(None),
415    )
416}
417
418fn try_acquire_before<F: Fn(u32) -> bool + Copy>(
419    home: &Path,
420    cache_dir: &Path,
421    owner: &Owner,
422    alive: F,
423    retry: crate::lock_file::Retry,
424) -> Result<AcquireOutcome> {
425    let dir = leases_dir(home);
426    std::fs::create_dir_all(&dir).with_context(|| format!("create {}", dir.display()))?;
427    let path = dir.join(format!("{}.json", slug(cache_dir)));
428
429    // Two attempts: the first is the common case (free, or held by someone
430    // live); the second only runs after reclaiming a confirmed-stale lease,
431    // so this can never loop more than once per call — a caller that keeps
432    // losing the race to genuinely live contenders is exactly what `Busy`
433    // reports back, not something this function spins on.
434    for _ in 0..2 {
435        let result = write_new(&path, cache_dir, owner, retry);
436        if let Some(outcome) = acquire_result(home, &path, cache_dir, owner, alive, result)? {
437            return Ok(outcome);
438        }
439    }
440    Ok(AcquireOutcome::Busy(Busy::Contended))
441}
442
443// Shared stale/conflict handling; only opening the file is retried.
444fn acquire_result(
445    home: &Path,
446    path: &Path,
447    cache_dir: &Path,
448    owner: &Owner,
449    alive: impl Fn(u32) -> bool + Copy,
450    result: std::io::Result<()>,
451) -> Result<Option<AcquireOutcome>> {
452    match result {
453        Ok(()) => {
454            record_catalog(home, cache_dir, owner);
455            return Ok(Some(AcquireOutcome::Acquired(Guard::new(path.to_owned()))));
456        }
457        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
458        Err(e) => return Err(e).with_context(|| format!("create {}", path.display())),
459    }
460    match classify_with(path, alive) {
461        Status::Free => {}
462        Status::Stale(_) => {
463            let _ = std::fs::remove_file(path);
464        }
465        Status::Active(o) => return Ok(Some(AcquireOutcome::Busy(Busy::Active(o)))),
466        Status::Unknown => return Ok(Some(AcquireOutcome::Busy(Busy::Unknown))),
467    }
468    Ok(None)
469}
470
471async fn try_acquire_async(
472    home: &Path,
473    cache_dir: &Path,
474    owner: &Owner,
475    retry: crate::lock_file::Retry,
476    cancel: &(dyn Fn() -> bool + Sync),
477) -> Result<Option<AcquireOutcome>> {
478    let Ok(_outputs) = crate::retention::OutputLease::cache(home, cache_dir, true) else {
479        return Ok(Some(AcquireOutcome::Busy(Busy::Outputs)));
480    };
481    let dir = leases_dir(home);
482    std::fs::create_dir_all(&dir).with_context(|| format!("create {}", dir.display()))?;
483    let path = dir.join(format!("{}.json", slug(cache_dir)));
484    for _ in 0..2 {
485        let opened = retry
486            .run_async_unless(
487                || {
488                    std::fs::OpenOptions::new()
489                        .write(true)
490                        .create_new(true)
491                        .open(&path)
492                },
493                cancel,
494            )
495            .await;
496        let result = match opened {
497            Ok(Some(file)) => write_lease(file, cache_dir, owner),
498            Ok(None) => return Ok(None),
499            Err(error) => Err(error),
500        };
501        if let Some(outcome) =
502            acquire_result(home, &path, cache_dir, owner, proc::pid_alive, result)?
503        {
504            return Ok(Some(outcome));
505        }
506    }
507    Ok(Some(AcquireOutcome::Busy(Busy::Contended)))
508}
509
510/// Is `cache_dir` in use right now — held by a live owner, or in a state
511/// nobody can vouch for? The conservative half of the janitor's prune guard:
512/// [`Status::Unknown`] refuses exactly like [`Status::Active`], because a
513/// lease this process cannot read is not evidence the directory is free.
514#[must_use]
515pub fn in_use(home: &Path, cache_dir: &Path) -> bool {
516    let path = lease_path(home, cache_dir);
517    matches!(classify(&path), Status::Active(_) | Status::Unknown)
518        || crate::retention::OutputLease::cache(home, cache_dir, true).is_err()
519}
520
521/// Prefix of a resource machine hold. `triage` uses it when rechecking
522/// availability; the prefix alone does not establish an elapsed timeout.
523pub const RESOURCE_HOLD: &str = "[resource] ";
524
525/// A proven elapsed cache wait, distinct from cancellation and I/O errors.
526#[derive(Debug)]
527pub struct WaitTimeout(pub String);
528
529impl std::fmt::Display for WaitTimeout {
530    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
531        f.write_str(&self.0)
532    }
533}
534
535impl std::error::Error for WaitTimeout {}
536
537/// Acquire the lease for `cache_dir`, waiting out contention rather than
538/// failing on the first busy owner — but never past `budget`, and the wait
539/// comes out of that same budget rather than a second, unbounded one. A
540/// caller already has a node timeout; this is that timeout, not a new clock
541/// next to it, which is what keeps a wait from becoming the "無期限待機"
542/// AGENTS.md's own build-cache section warns is never acceptable. The error
543/// on timeout names who is still holding it, for the event this gets logged
544/// into.
545pub async fn wait_for(
546    home: &Path,
547    cache_dir: &Path,
548    owner: &Owner,
549    budget: Duration,
550    poll: Duration,
551) -> Result<Guard> {
552    match wait_for_unless(home, cache_dir, owner, budget, poll, &|| false).await? {
553        Some(g) => Ok(g),
554        None => bail!("the wait for the build cache was cancelled"),
555    }
556}
557
558/// [`wait_for`] that also gives up, with `Ok(None)`, as soon as `cancel`
559/// returns true. `cancel` is checked at each contention poll and before and
560/// after delete-pending sleeps, so a park request does not wait out the budget. The
561/// lease is never held on that path: nothing was acquired.
562pub async fn wait_for_unless(
563    home: &Path,
564    cache_dir: &Path,
565    owner: &Owner,
566    budget: Duration,
567    poll: Duration,
568    cancel: &(dyn Fn() -> bool + Sync),
569) -> Result<Option<Guard>> {
570    let start = std::time::Instant::now();
571    // Delete-pending retries share the whole resource wait budget; the helper
572    // checks cancellation before and after each retry sleep.
573    let retry = crate::lock_file::Retry::new(Some(start + budget));
574    loop {
575        let Some(acquired) = try_acquire_async(home, cache_dir, owner, retry, cancel).await? else {
576            return Ok(None);
577        };
578        match acquired {
579            AcquireOutcome::Acquired(g) => return Ok(Some(g)),
580            AcquireOutcome::Busy(busy) => {
581                if cancel() {
582                    return Ok(None);
583                }
584                let elapsed = start.elapsed();
585                if elapsed >= budget {
586                    return Err(WaitTimeout(format!(
587                        "timed out after {}s waiting for the build cache at {} ({})",
588                        budget.as_secs(),
589                        cache_dir.display(),
590                        busy.describe()
591                    ))
592                    .into());
593                }
594                tokio::time::sleep(poll.min(budget - elapsed)).await;
595            }
596        }
597    }
598}
599
600/// One cache directory's state, for `a0fc`'s capacity/cleanup inventory (and
601/// `magi cache show`, eventually). Every lease file on disk is reported —
602/// including ones this process itself does not want to touch — because the
603/// question this answers is "what is registered right now", not "what can I
604/// safely act on".
605#[derive(Debug, Clone)]
606pub struct Entry {
607    /// The literal cache path this entry describes.
608    pub cache_dir: String,
609    /// What [`classify`] made of the lease registered against it.
610    pub status: EntryStatus,
611}
612
613/// [`Entry::status`]'s possible values.
614#[derive(Debug, Clone)]
615pub enum EntryStatus {
616    /// Held by a confirmed-live owner.
617    Active(Owner),
618    /// Present, but the owner is confirmed gone — safe to reclaim.
619    Stale(Owner),
620    /// Present, but unreadable — never assume safe to reclaim.
621    Unknown,
622    /// No live lease right now — the borrower released it cleanly — but the
623    /// catalog remembers this path was leased before, by the owner named
624    /// here. Safe to reclaim: nothing holds it, and nothing has to guess that
625    /// from the lease file's mere absence, which is indistinguishable from a
626    /// path magi never touched (see [`CatalogRecord`]'s doc).
627    Idle(Owner),
628    /// Tools or their independent cleanup owner retain an OS output lease.
629    /// The attached owner is the last recorded cache borrower.
630    Outputs(Owner),
631}
632
633/// Every cache directory magi knows about under `home`, whether or not
634/// anything holds it right now. A lease file reports the current borrower;
635/// once released it is gone (by design — see [`Guard::release`]), so a
636/// directory nobody is borrowing is reported from the catalog instead,
637/// carrying its last known owner rather than nothing at all. There is
638/// nothing here for a directory this process has never leased: `inventory`
639/// answers "what has magi registered", not "what looks like a build cache".
640#[must_use]
641pub fn inventory(home: &Path) -> Vec<Entry> {
642    let mut entries = inventory_with(home, proc::pid_alive);
643    for entry in &mut entries {
644        if let EntryStatus::Idle(owner) | EntryStatus::Stale(owner) = &entry.status
645            && crate::retention::OutputLease::cache(home, Path::new(&entry.cache_dir), true)
646                .is_err()
647        {
648            entry.status = EntryStatus::Outputs(owner.clone());
649        }
650    }
651    entries
652}
653
654/// [`inventory`] with its process-liveness query supplied by the caller —
655/// see [`classify_with`] for why this split exists.
656fn inventory_with<F: Fn(u32) -> bool + Copy>(home: &Path, alive: F) -> Vec<Entry> {
657    let dir = leases_dir(home);
658    let Ok(rd) = std::fs::read_dir(&dir) else {
659        return Vec::new();
660    };
661    let mut out = Vec::new();
662    for entry in rd.flatten() {
663        let path = entry.path();
664        let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
665            continue;
666        };
667        if !name.ends_with(".json")
668            || name.ends_with(".identity.json")
669            || name.ends_with(".catalog.json")
670        {
671            continue;
672        }
673        let status = match classify_with(&path, alive) {
674            Status::Free => continue,
675            Status::Active(o) => EntryStatus::Active(o),
676            Status::Stale(o) => EntryStatus::Stale(o),
677            Status::Unknown => EntryStatus::Unknown,
678        };
679        // A lease so corrupted that not even its `cache_dir` field can be
680        // read still has to be findable: the lease file's own name is a
681        // one-way slug of the path it was for, so the file itself - not the
682        // path it can no longer name - is what a human or `a0fc` gets
683        // pointed at.
684        let cache_dir = peek_cache_dir(&path)
685            .unwrap_or_else(|| format!("(unreadable lease file: {})", path.display()));
686        out.push(Entry { cache_dir, status });
687    }
688
689    // Second pass: a cache directory whose lease was cleanly released is
690    // still registered, in the catalog, as long as its lease file has not
691    // been reacquired since. Skip anything the first pass already reported —
692    // a live or stale lease always outranks a catalog record, which only
693    // ever describes the *last* borrower, not the current one.
694    if let Ok(rd) = std::fs::read_dir(&dir) {
695        for entry in rd.flatten() {
696            let path = entry.path();
697            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
698                continue;
699            };
700            let Some(stem) = name.strip_suffix(".catalog.json") else {
701                continue;
702            };
703            if dir.join(format!("{stem}.json")).exists() {
704                continue;
705            }
706            if let Some(record) = read_catalog(&path) {
707                out.push(Entry {
708                    cache_dir: record.cache_dir,
709                    status: EntryStatus::Idle(record.last_owner),
710                });
711            }
712        }
713    }
714
715    out.sort_by(|a, b| a.cache_dir.cmp(&b.cache_dir));
716    out
717}
718
719/// Prune `cache_dir` to `limit`, but only while holding the lease — a prune
720/// that raced a live build would delete files a compile in flight still
721/// needs, on top of confusing whatever built them about why its own output
722/// vanished. `Ok(None)` when the cache is in use right now; that is not an
723/// error, it is the janitor's next pass catching it once the borrower is
724/// done. Never touches a lease file itself — they live outside `cache_dir`
725/// (see [`leases_dir`]), so [`crate::disk::prune_dir`]'s own sweep can never
726/// reach one.
727pub fn maintenance_prune(
728    home: &Path,
729    cache_dir: &Path,
730    limit: u64,
731) -> Result<Option<crate::disk::Prune>> {
732    let owner = Owner {
733        run: "maintenance".to_owned(),
734        node: "prune".to_owned(),
735        seat: "janitor".to_owned(),
736        pid: std::process::id(),
737        worktree: String::new(),
738        head: String::new(),
739    };
740    match try_acquire_maintenance(home, cache_dir, &owner)? {
741        AcquireOutcome::Busy(_) => Ok(None),
742        AcquireOutcome::Acquired(guard) => {
743            let _cargo = crate::retention::cargo_locks(cache_dir)?;
744            let result = crate::disk::prune_dir(cache_dir, limit)?;
745            guard.release();
746            Ok(Some(result))
747        }
748    }
749}
750
751/// The source a build against a cache directory was last known to come from.
752/// Compared by [`needs_refresh`] on every acquire, so a cache directory that
753/// only ever sees one worktree/head pair never pays a clean it does not need.
754#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
755pub struct Identity {
756    /// The worktree the build ran from.
757    pub worktree: String,
758    /// The commit it built.
759    pub head: String,
760}
761
762impl Identity {
763    /// Build an identity from a worktree path and the commit it is at.
764    #[must_use]
765    pub fn new(worktree: &Path, head: &str) -> Identity {
766        Identity {
767            worktree: worktree.display().to_string(),
768            head: head.to_owned(),
769        }
770    }
771}
772
773/// Has the source building against `cache_dir` changed since the last record?
774/// True (needs a refresh) whenever nothing was ever recorded — the
775/// conservative default for a cache directory this process has not tracked
776/// before.
777#[must_use]
778pub fn needs_refresh(home: &Path, cache_dir: &Path, current: &Identity) -> bool {
779    let path = identity_path(home, cache_dir);
780    let Ok(body) = std::fs::read_to_string(path) else {
781        return true;
782    };
783    match serde_json::from_str::<Identity>(&body) {
784        Ok(recorded) => &recorded != current,
785        Err(_) => true,
786    }
787}
788
789/// Persist `identity` as the last known source for `cache_dir`.
790pub fn record_identity(home: &Path, cache_dir: &Path, identity: &Identity) -> Result<()> {
791    let path = identity_path(home, cache_dir);
792    if let Some(parent) = path.parent() {
793        std::fs::create_dir_all(parent).with_context(|| format!("create {}", parent.display()))?;
794    }
795    let body = serde_json::to_string_pretty(identity).context("serialize cache identity")?;
796    let tmp = path.with_extension("json.tmp");
797    std::fs::write(&tmp, &body).with_context(|| format!("write {}", tmp.display()))?;
798    std::fs::rename(&tmp, &path).with_context(|| format!("replace {}", path.display()))?;
799    Ok(())
800}
801
802/// Forget the recorded source identity for `cache_dir`, so the next
803/// [`ensure_fresh`] call cannot skip its clean on the strength of a stale
804/// match.
805///
806/// For a builder that does not itself have one coherent (worktree, head) to
807/// record - an implement or fix wave, where several different worktrees
808/// deliberately share the cache concurrently - there is nothing correct to
809/// write in place of the old identity. Removing the record is still correct:
810/// it costs the next tracked caller ([`ensure_fresh`] at `e2e`/`gate`) one
811/// clean it might not have strictly needed, in exchange for never trusting a
812/// match against a write this module never observed. Best-effort: a stale
813/// record surviving a failed removal is no worse than the record this
814/// replaces.
815pub fn invalidate_identity(home: &Path, cache_dir: &Path) {
816    let _ = std::fs::remove_file(identity_path(home, cache_dir));
817}
818
819/// Parse `cargo metadata --no-deps`'s JSON for the names of packages defined
820/// in the workspace itself — never a dependency, which is exactly the
821/// distinction that keeps a freshness fix from also discarding a downloaded
822/// crate's compiled artifacts on every worktree switch. Pure, so the parse
823/// is tested against fixture text without a `cargo` on the test machine.
824#[must_use]
825pub fn parse_workspace_package_names(metadata_json: &str) -> Vec<String> {
826    let Ok(value) = serde_json::from_str::<serde_json::Value>(metadata_json) else {
827        return Vec::new();
828    };
829    value
830        .get("packages")
831        .and_then(|p| p.as_array())
832        .map(|packages| {
833            packages
834                .iter()
835                .filter_map(|p| p.get("name").and_then(|n| n.as_str()))
836                .map(str::to_owned)
837                .collect()
838        })
839        .unwrap_or_default()
840}
841
842/// Every `--manifest-path` the given verify commands pass, in order of first
843/// appearance, without duplicates. Understands `--manifest-path X` and
844/// `--manifest-path=X`, with `'` / `"` quoting. Pure.
845#[must_use]
846pub fn extract_manifest_paths(commands: &[String]) -> Vec<PathBuf> {
847    const KEY: &str = "--manifest-path";
848    let mut out: Vec<PathBuf> = Vec::new();
849    for command in commands {
850        let mut rest = command.as_str();
851        while let Some(at) = rest.find(KEY) {
852            rest = &rest[at + KEY.len()..];
853            let value = if let Some(r) = rest.strip_prefix('=') {
854                r
855            } else if rest.starts_with(char::is_whitespace) {
856                rest.trim_start()
857            } else {
858                continue;
859            };
860            let value = if let Some(s) = value.strip_prefix('\'') {
861                s.split('\'').next().unwrap_or("")
862            } else if let Some(s) = value.strip_prefix('"') {
863                s.split('"').next().unwrap_or("")
864            } else {
865                let end = value.find(char::is_whitespace).unwrap_or(value.len());
866                &value[..end]
867            };
868            if !value.is_empty() {
869                let path = PathBuf::from(value);
870                if !out.contains(&path) {
871                    out.push(path);
872                }
873            }
874        }
875    }
876    out
877}
878
879/// Where cargo is asked about the workspace's own packages.
880#[derive(Debug, Clone, PartialEq, Eq)]
881pub enum Target {
882    /// The worktree root, as before (no `--manifest-path`).
883    Root,
884    /// A manifest named by a verify command, resolved against the worktree.
885    Manifest(PathBuf),
886}
887
888/// Decide which manifests `cargo metadata` / `cargo clean -p` run against: the
889/// root when it has a `Cargo.toml`, plus every verify-named manifest that
890/// exists. Nothing at all is a valid answer (no crate, or one the commands do
891/// not name). Pure apart from `exists`.
892fn plan_targets(
893    worktree: &Path,
894    manifests: &[PathBuf],
895    exists: impl Fn(&Path) -> Result<bool>,
896) -> Result<Vec<Target>> {
897    let mut targets = Vec::new();
898    if exists(&worktree.join("Cargo.toml"))? {
899        targets.push(Target::Root);
900    }
901    for m in manifests {
902        let full = if m.is_absolute() {
903            m.clone()
904        } else {
905            worktree.join(m)
906        };
907        if exists(&full)? {
908            targets.push(Target::Manifest(full));
909        } else {
910            tracing::warn!(
911                manifest = %m.display(),
912                "build cache: --manifest-path from a verify command does not exist; skipped"
913            );
914        }
915    }
916    Ok(targets)
917}
918
919/// Existence of a file: only NotFound counts as "no"; any other I/O error
920/// propagates so an unreadable tree is never mistaken for an empty one.
921fn file_exists(path: &Path) -> Result<bool> {
922    match std::fs::metadata(path) {
923        Ok(m) => Ok(m.is_file()),
924        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(false),
925        Err(e) => Err(e).with_context(|| format!("stat {}", path.display())),
926    }
927}
928
929/// Selectively invalidate the workspace's own compiled artifacts in
930/// `cache_dir` — `cargo clean -p <name> --target-dir <cache_dir>` for every
931/// package `cargo metadata` reports as local to `worktree`, never a bare
932/// `cargo clean` (which would throw away every dependency's compile too).
933/// Returns `None` when there is no manifest to ask (no cargo is spawned).
934/// Real subprocess execution: never called from a test, only from
935/// [`ensure_fresh`] in the running binary.
936fn refresh_stale_packages(
937    worktree: &Path,
938    cache_dir: &Path,
939    manifests: &[PathBuf],
940    isolated: bool,
941) -> Result<Option<Vec<String>>> {
942    let targets = plan_targets(worktree, manifests, file_exists)?;
943    if targets.is_empty() {
944        return Ok(None);
945    }
946    let mut all = Vec::new();
947    let mut failed = Vec::new();
948    for target in &targets {
949        let manifest_arg = match target {
950            Target::Root => None,
951            Target::Manifest(m) => Some(m),
952        };
953        let mut cmd = if isolated {
954            crate::build_target::command::cargo(cache_dir)?
955        } else {
956            std::process::Command::new("cargo")
957        };
958        if !isolated {
959            crate::build_target::command::clear_std(&mut cmd)?;
960        }
961        cmd.args(["metadata", "--no-deps", "--format-version", "1"]);
962        if let Some(m) = manifest_arg {
963            cmd.arg("--manifest-path").arg(m);
964        }
965        let meta = cmd
966            .current_dir(worktree)
967            .quiet()
968            .output()
969            .context("run `cargo metadata`")?;
970        if !meta.status.success() {
971            bail!(
972                "cargo metadata failed: {}",
973                String::from_utf8_lossy(&meta.stderr)
974            );
975        }
976        let names = parse_workspace_package_names(&String::from_utf8_lossy(&meta.stdout));
977        for name in &names {
978            let mut clean = if isolated {
979                crate::build_target::command::cargo(cache_dir)?
980            } else {
981                std::process::Command::new("cargo")
982            };
983            clean.arg("clean").arg("-p").arg(name);
984            if let Some(m) = manifest_arg {
985                clean.arg("--manifest-path").arg(m);
986            }
987            if !isolated {
988                crate::build_target::command::clear_std(&mut clean)?;
989                clean.arg("--target-dir").arg(cache_dir);
990            }
991            let out = clean
992                .current_dir(worktree)
993                .quiet()
994                .output()
995                .with_context(|| format!("cargo clean -p {name}"))?;
996            if !out.status.success() {
997                // A failure here — a Windows test executable still holding its
998                // own file open is the case the evidence log records — means the
999                // stale artifact this was meant to remove may still be sitting
1000                // in `cache_dir`. Collecting it rather than only warning is what
1001                // lets `ensure_fresh` refuse to record the new identity: the
1002                // next reuse must not be told this cache is confirmed to match
1003                // `identity` when a piece of the *previous* one could not be
1004                // proven gone.
1005                failed.push(format!(
1006                    "{name}: {}",
1007                    String::from_utf8_lossy(&out.stderr).trim()
1008                ));
1009            }
1010        }
1011        for n in names {
1012            if !all.contains(&n) {
1013                all.push(n);
1014            }
1015        }
1016    }
1017    if !failed.is_empty() {
1018        bail!(
1019            "cargo clean -p failed for {} package(s): {}",
1020            failed.len(),
1021            failed.join("; ")
1022        );
1023    }
1024    Ok(Some(all))
1025}
1026
1027/// What cargo itself writes into a target directory it creates.
1028const CACHEDIR_TAG: &str = "Signature: 8a477f597d28d172789f06886806bc55\n\
1029# This file is a cache directory tag created by cargo.\n\
1030# For information about cache directory tags see https://bford.info/cachedir/\n";
1031
1032/// Recreate `CACHEDIR.TAG` in a cargo target directory that lost it, so
1033/// `cargo clean -p` stops refusing. Returns whether a tag was written.
1034///
1035/// Heals caches an older prune already broke. Safe because the caller holds the
1036/// lease, `cache_dir` is the directory magi itself handed cargo as its target,
1037/// and it is only done when `.rustc_info.json` proves cargo has built there — a
1038/// misconfigured path is never dressed up as a cargo target. An existing tag is
1039/// never touched (`create_new`), and a missing directory is left for cargo.
1040fn restore_cachedir_tag(cache_dir: &Path) -> Result<bool> {
1041    use std::io::Write as _;
1042    if !cache_dir.is_dir() || !cache_dir.join(".rustc_info.json").is_file() {
1043        return Ok(false);
1044    }
1045    let tag = cache_dir.join("CACHEDIR.TAG");
1046    match std::fs::OpenOptions::new()
1047        .write(true)
1048        .create_new(true)
1049        .open(&tag)
1050    {
1051        Ok(mut f) => {
1052            f.write_all(CACHEDIR_TAG.as_bytes())
1053                .with_context(|| format!("write {}", tag.display()))?;
1054            Ok(true)
1055        }
1056        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(false),
1057        Err(e) => Err(e).with_context(|| format!("create {}", tag.display())),
1058    }
1059}
1060
1061/// Guarantee that a build against `cache_dir` from `(worktree, head)` never
1062/// silently reuses another source's compiled output: clean the workspace's
1063/// own packages out of the cache when the recorded identity disagrees, then
1064/// record the new one. A no-op — no subprocess spawned — when the identity
1065/// already matches, which is the common case once a cache directory settles
1066/// on one worktree for a while.
1067///
1068/// Called with the lease already held: this is a mutation of the cache
1069/// directory's contents, and it must never race a concurrent build the same
1070/// way a plain `cargo clean` run by hand would not.
1071pub fn ensure_fresh(
1072    home: &Path,
1073    cache_dir: &Path,
1074    identity: &Identity,
1075    manifests: &[PathBuf],
1076) -> Result<()> {
1077    ensure_fresh_with(home, cache_dir, identity, manifests, false)
1078}
1079
1080pub(crate) fn ensure_fresh_with(
1081    home: &Path,
1082    cache_dir: &Path,
1083    identity: &Identity,
1084    manifests: &[PathBuf],
1085    isolated: bool,
1086) -> Result<()> {
1087    match restore_cachedir_tag(cache_dir) {
1088        Ok(true) => tracing::info!(
1089            cache = %cache_dir.display(),
1090            "build cache: restored a missing CACHEDIR.TAG"
1091        ),
1092        Ok(false) => {}
1093        // Not fatal: `cargo clean -p` below reports the real consequence.
1094        Err(e) => tracing::warn!(error = %e, "build cache: could not restore CACHEDIR.TAG"),
1095    }
1096    if needs_refresh(home, cache_dir, identity) {
1097        let worktree = PathBuf::from(&identity.worktree);
1098        match refresh_stale_packages(&worktree, cache_dir, manifests, isolated)? {
1099            Some(cleaned) => tracing::info!(
1100                ?cleaned,
1101                cache = %cache_dir.display(),
1102                "build cache: source identity changed; cleaned the workspace's own packages before reuse"
1103            ),
1104            None => {
1105                // No Cargo.toml at the root and none named by a verify
1106                // command: there is nothing to clean by name, and a crate
1107                // we could not locate may have left stale output behind, so
1108                // the identity is not vouched for either.
1109                tracing::warn!(
1110                    cache = %cache_dir.display(),
1111                    "build cache: no Cargo manifest found for the freshness check; skipping the package clean"
1112                );
1113                invalidate_identity(home, cache_dir);
1114                return Ok(());
1115            }
1116        }
1117    }
1118    record_identity(home, cache_dir, identity)
1119}
1120
1121#[cfg(test)]
1122mod tests {
1123    use super::*;
1124
1125    fn owner(pid: u32) -> Owner {
1126        Owner {
1127            run: "r1".to_owned(),
1128            node: "gate".to_owned(),
1129            seat: "gate".to_owned(),
1130            pid,
1131            worktree: "/w".to_owned(),
1132            head: "deadbeef".to_owned(),
1133        }
1134    }
1135
1136    #[test]
1137    fn a_missing_cachedir_tag_is_restored_only_for_a_cargo_target() {
1138        let t = tempfile::TempDir::new().expect("temp");
1139        let cache = t.path().join("cache");
1140        assert!(!restore_cachedir_tag(&cache).expect("missing dir"));
1141        assert!(!cache.exists(), "a missing directory is left for cargo");
1142
1143        std::fs::create_dir_all(&cache).expect("mkdir");
1144        assert!(!restore_cachedir_tag(&cache).expect("no rustc info"));
1145        assert!(!cache.join("CACHEDIR.TAG").exists());
1146
1147        std::fs::write(cache.join(".rustc_info.json"), "{}").expect("info");
1148        assert!(restore_cachedir_tag(&cache).expect("restore"));
1149        let body = std::fs::read_to_string(cache.join("CACHEDIR.TAG")).expect("tag");
1150        assert_eq!(
1151            body.lines().next(),
1152            Some("Signature: 8a477f597d28d172789f06886806bc55")
1153        );
1154
1155        std::fs::write(cache.join("CACHEDIR.TAG"), "custom").expect("custom");
1156        assert!(!restore_cachedir_tag(&cache).expect("existing"));
1157        assert_eq!(
1158            std::fs::read_to_string(cache.join("CACHEDIR.TAG")).expect("tag"),
1159            "custom"
1160        );
1161    }
1162
1163    #[test]
1164    fn an_uncontended_lease_is_acquired_and_freed_on_release() {
1165        let home = tempfile::TempDir::new().expect("temp");
1166        let cache = home.path().join("cache");
1167        let this = std::process::id();
1168        match try_acquire(home.path(), &cache, &owner(this)).expect("acquire") {
1169            AcquireOutcome::Acquired(g) => {
1170                assert!(in_use(home.path(), &cache), "held while the guard lives");
1171                g.release();
1172            }
1173            AcquireOutcome::Busy(b) => panic!("unexpectedly busy: {b:?}"),
1174        }
1175        assert!(!in_use(home.path(), &cache), "freed after release");
1176    }
1177
1178    #[test]
1179    fn a_lease_held_by_a_live_pid_is_reported_active_and_refuses_a_second_acquire() {
1180        let home = tempfile::TempDir::new().expect("temp");
1181        let cache = home.path().join("cache");
1182        let this = std::process::id();
1183        // Acquire as one owner, then try again as a different one — same
1184        // live pid (this test process), different run/seat, which is exactly
1185        // "another owner, still alive" without needing to fork a process.
1186        let _first =
1187            try_acquire(home.path(), &cache, &owner(this)).expect("first acquire succeeds");
1188        let mut second_owner = owner(this);
1189        second_owner.run = "r2".to_owned();
1190        match try_acquire(home.path(), &cache, &second_owner).expect("no io error") {
1191            AcquireOutcome::Busy(Busy::Active(held_by)) => assert_eq!(held_by.run, "r1"),
1192            other => panic!("expected Busy::Active, got a different outcome: {other:?}"),
1193        }
1194        assert!(in_use(home.path(), &cache));
1195    }
1196
1197    impl std::fmt::Debug for AcquireOutcome {
1198        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1199            match self {
1200                AcquireOutcome::Acquired(_) => write!(f, "Acquired"),
1201                AcquireOutcome::Busy(b) => write!(f, "Busy({b:?})"),
1202            }
1203        }
1204    }
1205
1206    #[test]
1207    fn a_lease_whose_pid_is_gone_is_stale_and_reclaimed_by_the_next_acquirer() {
1208        let home = tempfile::TempDir::new().expect("temp");
1209        let cache = home.path().join("cache");
1210        // Liveness is injected rather than asked of the real OS - a "known
1211        // dead" pid cannot be produced portably (see `classify_with`'s doc):
1212        // an out-of-range value reads as *unavailable* to `tasklist`, not
1213        // dead, and the conservative policy then reports it alive, which is
1214        // exactly what made this test flaky before this fix.
1215        let dead_owner = owner(999_999);
1216        let path = lease_path(home.path(), &cache);
1217        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
1218        write_new(
1219            &path,
1220            &cache,
1221            &dead_owner,
1222            crate::lock_file::Retry::new(None),
1223        )
1224        .expect("seed a stale lease");
1225        assert_eq!(
1226            classify_with(&path, |_| false),
1227            Status::Stale(dead_owner.clone())
1228        );
1229
1230        match try_acquire_with(home.path(), &cache, &owner(std::process::id()), |_| false)
1231            .expect("acquire")
1232        {
1233            AcquireOutcome::Acquired(_) => {}
1234            other => panic!("stale lease should have been reclaimed: {other:?}"),
1235        }
1236    }
1237
1238    #[test]
1239    fn an_unreadable_lease_is_unknown_and_never_reclaimed() {
1240        let home = tempfile::TempDir::new().expect("temp");
1241        let cache = home.path().join("cache");
1242        let path = lease_path(home.path(), &cache);
1243        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
1244        std::fs::write(&path, b"not json").unwrap();
1245        assert_eq!(classify(&path), Status::Unknown);
1246        assert!(in_use(home.path(), &cache), "unknown counts as in use");
1247        match try_acquire(home.path(), &cache, &owner(std::process::id())).expect("no io error") {
1248            AcquireOutcome::Busy(Busy::Unknown) => {}
1249            other => panic!("expected Busy::Unknown, got {other:?}"),
1250        }
1251    }
1252
1253    #[tokio::test]
1254    async fn waiting_for_a_busy_lease_times_out_within_its_own_budget() {
1255        let home = tempfile::TempDir::new().expect("temp");
1256        let cache = home.path().join("cache");
1257        let _held = try_acquire(home.path(), &cache, &owner(std::process::id()))
1258            .expect("acquire")
1259            .pipe();
1260        let mut waiter = owner(std::process::id());
1261        waiter.run = "r2".to_owned();
1262        let started = std::time::Instant::now();
1263        let err = wait_for(
1264            home.path(),
1265            &cache,
1266            &waiter,
1267            Duration::from_millis(150),
1268            Duration::from_millis(20),
1269        )
1270        .await
1271        .expect_err("still held, must time out");
1272        assert!(started.elapsed() < Duration::from_secs(2), "bounded wait");
1273        assert!(
1274            err.to_string().contains("r1"),
1275            "names the current holder: {err}"
1276        );
1277    }
1278
1279    #[tokio::test]
1280    async fn a_wait_succeeds_as_soon_as_the_lease_is_released() {
1281        let home = tempfile::TempDir::new().expect("temp");
1282        let cache = home.path().join("cache");
1283        let guard =
1284            match try_acquire(home.path(), &cache, &owner(std::process::id())).expect("acquire") {
1285                AcquireOutcome::Acquired(g) => g,
1286                AcquireOutcome::Busy(b) => panic!("unexpectedly busy: {b:?}"),
1287            };
1288        let home_path = home.path().to_path_buf();
1289        let cache_path = cache.clone();
1290        let mut waiter = owner(std::process::id());
1291        waiter.run = "r2".to_owned();
1292        let wait = tokio::spawn(async move {
1293            wait_for(
1294                &home_path,
1295                &cache_path,
1296                &waiter,
1297                Duration::from_secs(5),
1298                Duration::from_millis(10),
1299            )
1300            .await
1301        });
1302        tokio::time::sleep(Duration::from_millis(50)).await;
1303        guard.release();
1304        let acquired = wait.await.expect("task").expect("acquire after release");
1305        acquired.release();
1306    }
1307
1308    #[test]
1309    fn inventory_reports_active_stale_and_unknown_but_not_free() {
1310        let home = tempfile::TempDir::new().expect("temp");
1311        let active_cache = home.path().join("active");
1312        let stale_cache = home.path().join("stale");
1313        let unknown_cache = home.path().join("unknown");
1314
1315        let _held =
1316            try_acquire(home.path(), &active_cache, &owner(std::process::id())).expect("acquire");
1317        let stale_path = lease_path(home.path(), &stale_cache);
1318        std::fs::create_dir_all(stale_path.parent().unwrap()).unwrap();
1319        write_new(
1320            &stale_path,
1321            &stale_cache,
1322            &owner(999_999),
1323            crate::lock_file::Retry::new(None),
1324        )
1325        .unwrap();
1326        let unknown_path = lease_path(home.path(), &unknown_cache);
1327        std::fs::write(&unknown_path, b"garbage").unwrap();
1328
1329        // Liveness injected as `false` for everyone but this test process -
1330        // see `a_lease_whose_pid_is_gone_is_stale_and_reclaimed_by_the_next_acquirer`
1331        // for why the real OS query cannot portably produce a "confirmed
1332        // dead" answer.
1333        let entries = inventory_with(home.path(), |pid| pid == std::process::id());
1334        assert_eq!(entries.len(), 3, "{entries:?}");
1335        let by_dir = |dir: &Path| {
1336            entries
1337                .iter()
1338                .find(|e| e.cache_dir == dir.display().to_string())
1339                .unwrap_or_else(|| panic!("no entry for {}", dir.display()))
1340        };
1341        assert!(matches!(
1342            by_dir(&active_cache).status,
1343            EntryStatus::Active(_)
1344        ));
1345        assert!(matches!(by_dir(&stale_cache).status, EntryStatus::Stale(_)));
1346        // A lease this corrupted cannot name its own `cache_dir` - the point
1347        // of this third case - so it is found by status instead of by path,
1348        // and its reported path must still point somewhere a human can act
1349        // on: the lease file itself.
1350        let unknown = entries
1351            .iter()
1352            .find(|e| matches!(e.status, EntryStatus::Unknown))
1353            .unwrap_or_else(|| panic!("no Unknown entry: {entries:?}"));
1354        assert!(
1355            unknown
1356                .cache_dir
1357                .contains(&unknown_path.display().to_string()),
1358            "{unknown:?}"
1359        );
1360    }
1361
1362    #[test]
1363    fn a_released_lease_is_reported_idle_from_the_catalog_not_dropped_entirely() {
1364        let home = tempfile::TempDir::new().expect("temp");
1365        let cache = home.path().join("cache");
1366        let this = std::process::id();
1367
1368        match try_acquire(home.path(), &cache, &owner(this)).expect("acquire") {
1369            AcquireOutcome::Acquired(g) => g.release(),
1370            AcquireOutcome::Busy(b) => panic!("unexpectedly busy: {b:?}"),
1371        }
1372
1373        // The lease file is gone - `in_use` reads this path as free - but the
1374        // catalog written on acquire must still name it as a cache magi once
1375        // leased, exactly the gap the 2026-09-12 recovery evidence found:
1376        // an orphaned cache indistinguishable from one that never existed.
1377        assert!(!in_use(home.path(), &cache));
1378        let entries = inventory_with(home.path(), |pid| pid == this);
1379        let entry = entries
1380            .iter()
1381            .find(|e| e.cache_dir == cache.display().to_string())
1382            .unwrap_or_else(|| panic!("no entry for a released cache: {entries:?}"));
1383        match &entry.status {
1384            EntryStatus::Idle(o) => assert_eq!(o.run, "r1"),
1385            other => panic!("expected Idle, got {other:?}"),
1386        }
1387    }
1388
1389    #[test]
1390    fn reacquiring_a_released_cache_reports_active_not_idle() {
1391        let home = tempfile::TempDir::new().expect("temp");
1392        let cache = home.path().join("cache");
1393        let this = std::process::id();
1394        match try_acquire(home.path(), &cache, &owner(this)).expect("acquire") {
1395            AcquireOutcome::Acquired(g) => g.release(),
1396            AcquireOutcome::Busy(b) => panic!("unexpectedly busy: {b:?}"),
1397        }
1398        let _held = try_acquire(home.path(), &cache, &owner(this)).expect("reacquire");
1399        let entries = inventory_with(home.path(), |pid| pid == this);
1400        assert_eq!(
1401            entries.len(),
1402            1,
1403            "the catalog row must not duplicate the live lease: {entries:?}"
1404        );
1405        assert!(matches!(entries[0].status, EntryStatus::Active(_)));
1406    }
1407
1408    #[test]
1409    fn maintenance_prune_refuses_a_cache_a_live_owner_holds() {
1410        let home = tempfile::TempDir::new().expect("temp");
1411        let cache = home.path().join("cache");
1412        std::fs::create_dir_all(&cache).unwrap();
1413        std::fs::write(cache.join("big"), vec![0u8; 100]).unwrap();
1414        let _held = try_acquire(home.path(), &cache, &owner(std::process::id())).expect("acquire");
1415
1416        let result = maintenance_prune(home.path(), &cache, 1).expect("no io error");
1417        assert!(
1418            result.is_none(),
1419            "must not prune while a live owner holds it"
1420        );
1421        assert!(cache.join("big").exists(), "nothing was deleted");
1422    }
1423
1424    #[test]
1425    fn maintenance_prune_acts_once_the_cache_is_free_and_releases_after() {
1426        let home = tempfile::TempDir::new().expect("temp");
1427        let cache = home.path().join("cache");
1428        std::fs::create_dir_all(&cache).unwrap();
1429        std::fs::write(cache.join("big"), vec![0u8; 100]).unwrap();
1430
1431        let pruned = maintenance_prune(home.path(), &cache, 1)
1432            .expect("no io error")
1433            .expect("cache was free");
1434        assert!(pruned.freed > 0);
1435        assert!(
1436            !in_use(home.path(), &cache),
1437            "the maintenance lease was released"
1438        );
1439    }
1440
1441    #[test]
1442    fn identity_drift_is_detected_once_and_then_settles() {
1443        let home = tempfile::TempDir::new().expect("temp");
1444        let cache = home.path().join("cache");
1445        let a = Identity {
1446            worktree: "/w/a".to_owned(),
1447            head: "aaaa".to_owned(),
1448        };
1449        let b = Identity {
1450            worktree: "/w/b".to_owned(),
1451            head: "bbbb".to_owned(),
1452        };
1453        assert!(
1454            needs_refresh(home.path(), &cache, &a),
1455            "nothing recorded yet"
1456        );
1457        record_identity(home.path(), &cache, &a).expect("record");
1458        assert!(
1459            !needs_refresh(home.path(), &cache, &a),
1460            "same identity, no refresh needed"
1461        );
1462        assert!(needs_refresh(home.path(), &cache, &b), "different source");
1463        record_identity(home.path(), &cache, &b).expect("record");
1464        assert!(!needs_refresh(home.path(), &cache, &b));
1465    }
1466
1467    #[test]
1468    fn invalidating_forgets_a_recorded_identity_so_the_next_check_refreshes() {
1469        let home = tempfile::TempDir::new().expect("temp");
1470        let cache = home.path().join("cache");
1471        let a = Identity {
1472            worktree: "/w/a".to_owned(),
1473            head: "aaaa".to_owned(),
1474        };
1475        record_identity(home.path(), &cache, &a).expect("record");
1476        assert!(!needs_refresh(home.path(), &cache, &a));
1477
1478        // An untracked writer (an implement/fix wave, which shares the cache
1479        // across several worktrees at once and so has no single identity of
1480        // its own to record) touched the cache in between; the next tracked
1481        // caller must not trust the old match anymore.
1482        invalidate_identity(home.path(), &cache);
1483        assert!(
1484            needs_refresh(home.path(), &cache, &a),
1485            "invalidation must not be skippable by asking about the same identity again"
1486        );
1487
1488        // Invalidating a cache directory nothing ever recorded is a no-op,
1489        // not an error.
1490        invalidate_identity(home.path(), &home.path().join("never-recorded"));
1491    }
1492
1493    #[test]
1494    fn workspace_package_names_are_read_from_cargo_metadata_json() {
1495        let fixture = r#"{
1496            "packages": [
1497                {"name": "magi", "version": "0.1.0"},
1498                {"name": "magi-cli", "version": "0.1.0"}
1499            ],
1500            "workspace_members": []
1501        }"#;
1502        let mut names = parse_workspace_package_names(fixture);
1503        names.sort();
1504        assert_eq!(names, vec!["magi".to_owned(), "magi-cli".to_owned()]);
1505        assert_eq!(
1506            parse_workspace_package_names("not json"),
1507            Vec::<String>::new()
1508        );
1509        assert_eq!(parse_workspace_package_names("{}"), Vec::<String>::new());
1510    }
1511
1512    #[test]
1513    fn slugs_are_stable_and_filesystem_safe() {
1514        let a = slug(Path::new(r"C:\Users\op\Temp\magi-target"));
1515        let b = slug(Path::new(r"C:\Users\op\Temp\magi-target"));
1516        assert_eq!(a, b, "same input, same slug");
1517        assert!(
1518            a.chars()
1519                .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'),
1520            "filesystem-safe: {a}"
1521        );
1522    }
1523
1524    #[test]
1525    fn busy_active_describes_the_holder() {
1526        let b = Busy::Active(owner(123));
1527        let s = b.describe();
1528        assert!(
1529            s.contains("r1") && s.contains("gate") && s.contains("123"),
1530            "{s}"
1531        );
1532    }
1533
1534    trait Pipe: Sized {
1535        fn pipe(self) -> Guard;
1536    }
1537    impl Pipe for AcquireOutcome {
1538        fn pipe(self) -> Guard {
1539            match self {
1540                AcquireOutcome::Acquired(g) => g,
1541                AcquireOutcome::Busy(b) => panic!("expected Acquired, got Busy({b:?})"),
1542            }
1543        }
1544    }
1545
1546    fn cmds(v: &[&str]) -> Vec<String> {
1547        v.iter().map(|s| (*s).to_owned()).collect()
1548    }
1549
1550    #[test]
1551    fn manifest_paths_are_read_in_every_spelling() {
1552        let got = extract_manifest_paths(&cmds(&[
1553            "cargo test --manifest-path tools/a/Cargo.toml",
1554            "cargo build --manifest-path=tools/b/Cargo.toml --release",
1555            "cargo fmt --manifest-path 'q q/Cargo.toml'",
1556            "cargo clippy --manifest-path \"d/Cargo.toml\" && cargo test --manifest-path tools/a/Cargo.toml",
1557        ]));
1558        let want: Vec<PathBuf> = [
1559            "tools/a/Cargo.toml",
1560            "tools/b/Cargo.toml",
1561            "q q/Cargo.toml",
1562            "d/Cargo.toml",
1563        ]
1564        .iter()
1565        .map(PathBuf::from)
1566        .collect();
1567        assert_eq!(got, want);
1568        assert!(extract_manifest_paths(&cmds(&["cargo test", "cd x && cargo test"])).is_empty());
1569    }
1570
1571    #[test]
1572    fn plan_targets_covers_blog_root_both_and_none() {
1573        let w = Path::new("/w");
1574        let only = |set: &'static [&'static str]| {
1575            move |p: &Path| Ok(set.iter().any(|s| p == Path::new(s)))
1576        };
1577        let m = vec![PathBuf::from("tools/postprocess/Cargo.toml")];
1578        let blog = plan_targets(w, &m, only(&["/w/tools/postprocess/Cargo.toml"])).unwrap();
1579        assert_eq!(
1580            blog,
1581            vec![Target::Manifest(PathBuf::from(
1582                "/w/tools/postprocess/Cargo.toml"
1583            ))]
1584        );
1585        let root = plan_targets(w, &[], only(&["/w/Cargo.toml"])).unwrap();
1586        assert_eq!(root, vec![Target::Root]);
1587        let both = plan_targets(
1588            w,
1589            &m,
1590            only(&["/w/Cargo.toml", "/w/tools/postprocess/Cargo.toml"]),
1591        )
1592        .unwrap();
1593        assert_eq!(both.len(), 2);
1594        assert_eq!(both[0], Target::Root);
1595        assert!(plan_targets(w, &m, only(&[])).unwrap().is_empty());
1596        assert!(plan_targets(w, &[], only(&[])).unwrap().is_empty());
1597    }
1598
1599    #[test]
1600    fn a_repo_without_a_reachable_manifest_passes_untouched() {
1601        let home = tempfile::TempDir::new().expect("temp");
1602        let wt = tempfile::TempDir::new().expect("temp");
1603        // Only a nested crate, which no verify command names.
1604        std::fs::create_dir_all(wt.path().join("sub")).unwrap();
1605        std::fs::write(wt.path().join("sub/Cargo.toml"), "").unwrap();
1606        let cache = home.path().join("cache");
1607        std::fs::create_dir_all(&cache).unwrap();
1608        std::fs::write(cache.join("artifact"), "x").unwrap();
1609        let old = Identity {
1610            worktree: "/w/old".to_owned(),
1611            head: "old".to_owned(),
1612        };
1613        record_identity(home.path(), &cache, &old).unwrap();
1614        let id = Identity::new(wt.path(), "head");
1615        ensure_fresh(home.path(), &cache, &id, &[]).expect("must not fail");
1616        assert_eq!(
1617            std::fs::read_to_string(cache.join("artifact")).unwrap(),
1618            "x"
1619        );
1620        assert!(
1621            needs_refresh(home.path(), &cache, &old),
1622            "identity was invalidated, not recorded"
1623        );
1624        assert!(needs_refresh(home.path(), &cache, &id));
1625    }
1626}