fix: skip the legacy mount-source pass when no root it walks exists

[bolichen97]

Problem / Motivation

Every macOS and Windows install logs this at the default log level, once per
sweep tick (~10 minutes), forever:

WARNING kiro_crew.sandbox: sandbox mount-source sweep: legacy pass retained everything — bind coverage of /proc could not be established (pin scan incomplete, holder coverage unproven); the pass retries on the next tick

Nothing is wrong on those hosts, and there is nothing for the pass to reclaim.

Why it matters

The message is a real diagnostic — on a Linux host it means the legacy reclaim
pass is inert and the inode pile is not shrinking — so a warning that fires
unconditionally off Linux is worse than noise: it trains the reader to ignore
the line that matters. It also costs a full /proc walk per tick on hosts where
the walk can never succeed.

What changed (motivation → approach → change)

_cleanup_legacy_mount_source_residue proved bind coverage from /proc BEFORE
looking at whether the one root it may walk is present.
_launcher_tmpfs_roots() returns /run/user/$UID, a logind construct: off
Linux that path never exists, and /proc cannot be read either, so
complete and coverage.covered are both false on every tick and the pass
reports a held-back walk for a root it was never going to touch.

The fix is ordering. Filter the roots to those actually present and return
before the pin scan when none is — there is nowhere for an entry of this class
to be, so no coverage claim is needed to justify removing nothing.

The one-shot marker is deliberately not stamped on that path. The branch
found nowhere to look, which is not the same as finding nothing left, so the
pass stays armed; a repeat now costs one stat instead of a /proc walk. A
root appearing later is therefore still swept.

Linux behaviour with a present root is unchanged: same roots, same pin scan,
same fences, same stamping rules.

Tests

test_an_absent_root_skips_the_pin_scan_without_a_warning (in
TestLegacyResidueSweep) points the roots at a non-existent path and asserts
three things: the pin scan is never called, no held-back WARNING is emitted, and
the pass is not retired — a subsequent call with a real root still reclaims.

Verified non-vacuous: reverting the guard to the old ordering
(roots = _launcher_tmpfs_roots() / if False:) turns this test red, and only
this test.

Manual verification

N/A — the observed symptom is a log line on a code path unit coverage reaches
directly, and the branch is selected by the presence of a directory, which the
test controls.

Related Issues

Follow-up to #8559, which introduced this pass. No open issue tracks the
off-Linux noise.

Pattern harvest

Rule candidate: review-prompt
Pattern: an expensive precondition proof runs before the cheap check that
decides whether the work is possible at all — so on a platform where the proof
can never succeed, the failure is reported instead of the work being skipped.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable) — the function's own docstring fence list records the new short-circuit
• No secrets, credentials, or internal references in the diff

[github-actions]

Design Review (Fable 5) — ✅ PASS

Design-level review of a643379bf607c731f7b6f5a4804dceca6576a06d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

The change is a small, well-scoped reordering in _cleanup_legacy_mount_source_residue. I verified the design claims against the code: off Linux _launcher_tmpfs_roots() returns paths that never exist and /proc can't be scanned, so the old ordering warned unconditionally every tick; the new early return fires before the pin scan, preserves behavior on Linux with a present root (an absent root previously just hit OSError → continue in os.scandir, so the isdir filter changes nothing there), and deliberately leaves the one-shot marker unstamped so a root that later appears is still swept. The description matches the diff in both directions, the docstring fence list was updated in the same commit, and the test pins all three properties including non-retirement.

Design-Verdict: PASS

A cheap existence check now correctly precedes the expensive coverage proof; Linux behavior, fences, and the not-stamped marker semantics are all preserved.

[DESIGN-REVIEWED] a643379

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of a643379bf607c731f7b6f5a4804dceca6576a06d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a643379

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a643379bf607c731f7b6f5a4804dceca6576a06d: <one-sentence reason>

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed a643379bf607c731f7b6f5a4804dceca6576a06d — this comment is updated in place on each push.

Review details

The candidate list is empty ("No candidates"), so there is nothing to falsify in Step 1. The diff is a small, self-consistent defensive change: it filters _launcher_tmpfs_roots() to directories that actually exist and returns early before the /proc-reading pin scan when none are present, deliberately not stamping the retirement marker. Reading the hunk and its test, the early return is grounded and correct — no reachable crash, no removed guard, no security boundary crossed. Nothing meets the Step 2 bar.

No findings.

[OPUS-REVIEWED] a643379

Verdict parsed from the review's SHA-scoped output markers for commit a643379bf607c731f7b6f5a4804dceca6576a06d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a643379bf607c731f7b6f5a4804dceca6576a06d: <one-sentence reason>

[github-actions]

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of a643379bf607c731f7b6f5a4804dceca6576a06d — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All claims verified against the repository: the caller cleanup_stale_sandbox_profiles (sandbox.py:4709) runs on every platform's periodic sweep, _launcher_tmpfs_roots() returns only /run/user/$UID (a logind path), and the old ordering ran the /proc pin scan and its WARNING before ever consulting the root. The keyed sibling sweep (_cleanup_stale_sandbox_mount_sources) already builds its pin scan lazily on the first directory candidate, so this fix brings the legacy pass to the ordering its sibling already has — no unfixed siblings of the pattern remain.

First-Principles-Verdict: PASS

A per-tick false WARNING on every non-Linux install is removed by checking root presence before the /proc proof; nothing rides along.

What this change ships

Intent: stop a spurious once-per-sweep WARNING (and a wasted /proc walk) on hosts where the legacy sweep's only root can never exist. This is a FIX.

1. Off-Linux hosts no longer log the held-back-sweep WARNING every ~10 minutes — justified (the reported defect).
2. The /proc pin scan is skipped when the sweep's root is absent, one stat instead — justified, same fix.
3. The pass stays armed (marker not stamped) when the root is absent — declared; correct, since a Linux host whose session dir appears later must still be swept.
4. Docstring fence list records the short-circuit — justified (AGENTS.md same-commit doc rule).
5. New regression test asserting no scan, no WARNING, no retirement — justified, proven non-vacuous per description.

Counts: _cleanup_legacy_mount_source_residue has exactly 1 caller (sandbox.py:4709, all-platform sweep); _launcher_tmpfs_roots has 1 real consumer. Grepped the eager-proof-before-cheap-check pattern's siblings: the keyed sweep (sandbox.py:5093) already builds its pin scan lazily on the first directory candidate, so 0 unfixed siblings. No new public surface, config key, or flag; the fix sits at cause level (wrong ordering), not symptom level.

[FIRST-PRINCIPLES-REVIEWED] a643379

[chenmingwei23]

Approved: readiness: passed, all eligible checks green, no merge conflict.