Repository navigation
fix(security): key the resolver stall cooldown on the home directory, not on its container - #12647
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS A home container not spelled [DESIGN-REVIEWED] aead815 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Confirm issue #12386 matches the description's account (measured collapse, withdrawn third consequence) — this run could not fetch it; the base-failing test is verified by reading. What this change shipsInventory (4 items) — 4 justifiedIntent: FIX — stop one path-resolution stall under
[FIRST-PRINCIPLES-REVIEWED] aead815 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- docs/system-specs/modules/security.md:468 -- False positive or not applicable? A repository writer can comment: |
1a1b3a1 to
b4c9049
Compare
Security Scope Review -- 🟡 CONCERNSWhich legitimate operations does Verdict basis: the reviewer's own judgement; no confirmed regression. Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. Scope-Verdict: CONCERNS TIGHTENING: ADJUDICATED: 16 candidates submitted, 0 confirmed newly-refused. No confirmed rows were handed to this review; the adjudication legs run after capture and the deterministic fold reports their verdicts per leg. PLATFORM COVERAGE: posix — rows for all four deep-home layouts the diff's comment enumerates ( UNADJUDICATED: The tightening lives in a path resolver's stall-cooldown machinery, not in a pattern the shell classifier can flip. Call path: shell command → path fence →
[SCOPE-REVIEWED] aead815 |
… not on its container A host whose homes sit one level deeper than the usual layout keyed every path on the machine to the container of homes, so one resolver stall refused every tool call on the host for the cooldown. The key now never ends on a component named home: when the second component is a container of homes it takes the user too, so the boundary is the home directory itself, the key the usual layout already gets. Every other key is unchanged. Fixes #12386
b4c9049 to
aead815
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed the full diff. Pure fix, two lines in _stall_prefix (security/paths.py:1456-1457) plus docstring, one spec sentence and two tests. Verified the new key can never collapse two trees (the old key is always a prefix of the new one) and cannot be unbounded by an attacker: entries are only created by an observed stall in _mark_stalled and both dicts stay capped at 64. The single-wedged-NFS-container trade-off is disclosed in the body and in the docstring. Both tests go red on revert.
… not on its container (kirodotdev#12647) A host whose homes sit one level deeper than the usual layout keyed every path on the machine to the container of homes, so one resolver stall refused every tool call on the host for the cooldown. The key now never ends on a component named home: when the second component is a container of homes it takes the user too, so the boundary is the home directory itself, the key the usual layout already gets. Every other key is unchanged. Fixes kirodotdev#12386
… not on its container (kirodotdev#12647) A host whose homes sit one level deeper than the usual layout keyed every path on the machine to the container of homes, so one resolver stall refused every tool call on the host for the cooldown. The key now never ends on a component named home: when the second component is a container of homes it takes the user too, so the boundary is the home directory itself, the key the usual layout already gets. Every other key is unchanged. Fixes kirodotdev#12386
Problem / Motivation
On a host whose home directories sit one level deeper than usual --
/local/home/<user>, with/home/<user>a symlink into it (the standard cloud-desktop layout, already named in #8022) -- the resolver-stall cooldown collapses to one key for the whole machine._stall_prefixcharges a stall to the first two path components. On this layout that is/local/home, which contains every user, every workspace and checkout, the data home and the credential stores. Measured onorigin/main(#12386): five distinct paths under different users, directories and stores all key to/local/home; the same function keys/home/alice/...and/home/bob/...to two per-user keys, as designed.The function's own docstring already describes this exact failure mode -- for Windows: counting components without splitting the drive collapsed every user path to
C:\Users, "so one stall anywhere in the profile refused path resolution for essentially the whole host". That case was fixed by the drive split. A POSIX home at depth three reproduces the same collapse and was not covered.Why it matters
The sensitive-path gate runs before every other check on every tool call (
hooks.on_tool_call), so while the one key's cooldown is open every file read, write, grep, shell command and MCP call on the host is refused without touching the filesystem, in every session at once, with a refusal that names an ordinary project file. The user sees an agent that has apparently lost its tools. On a/home/<user>host the same stall costs one user's tree for 30 s; here it costs the whole machine, and repeat stalls under the shared key double that window toward the 1800 s ceiling with a counter that every session on the host feeds.Two of the issue's three consequences follow from the single key and are what this PR removes:
history is not None and wedged >= W - 1) sees a stall history for every path once any stall has been charged anywhere, so on the shipped two-worker pool a single pinned worker refuses everything.The third consequence as originally filed ("never decays") was withdrawn by the reporter and is confirmed wrong in code:
_run_resolution_boundedpops the prefix's entry on any completed resolution under it.What changed (motivation -> approach -> change)
Symptom: whole-host refusal for the cooldown after one stall. Root cause: the cooldown key is a fixed component count, and on this layout the second component is the container of homes, not a home.
/local/homeis to this host whatC:\Userswas to Windows.Approach. The key must stay lexical:
_stall_prefixis consulted before deciding whether to probe at all, and it names the prefix charged when the$HOMEanchor itself stalls, so it cannot touch the filesystem. That rules out the obvious mechanical fix -- a mount-derived key.os.path.ismountwalked upward wouldlstatthe very mount that may be wedged, and on this host (one local xfs at/, no network, CIFS or FUSE mount under the home) it reaches/: a process-wide key, worse than the collapse. Anchoring on$HOME's parent does not work either: on the affected host$HOMEis the/home/<user>spelling, so its parent is/homeand every/local/home/...path would still collapse; it would also make the key depend on the environment.Change. The key never ends on a container of home directories. A component spelled
homeis such a container --/home/<user>is the common layout, and the layouts that put homes one level deeper all keep the word:/local/home/<user>(cloud desktop),/usr/home(FreeBSD, where/homeis itself a symlink to it),/var/home(Fedora Silverblue, same),/export/home(Solaris, NFS servers). When the second component is that container and the path continues, the key takes one more component, so the boundary is the home directory itself:/local/home/<user>/oss/x -> /local/home/<user>, exactly the key a/home/<user>layout already gets.Usersneeds no entry: it only ever sits at depth one (/Users/<user>,C:\Users\<user>), where the two-component key already ends on the user.Every other key is unchanged:
/home/<user>,/tmp/<dir>,/Volumes/<share>,/net/<host>,C:\Users\<user>, UNC roots, relative paths, and the container alone (/local/homestays its own key when the path stops there). Two lines in_stall_prefixwith the rationale beside them, the function's docstring, and the one sentence indocs/system-specs/modules/security.mdthat describes the key; nothing in_mark_stalled, the load arm, the TTL cache or the degraded threshold is touched.What this does not buy, stated plainly. Two spellings of one tree (
/home/<user>and its/local/home/<user>target) remain two keys, each paying its own timeout -- inherent to a lexical key, and the resolution that would unify them is the operation the key exists to avoid. When the container is itself one wedged mount (an NFS/export/home), each user's tree pays its own timeout and pins its own worker: that is the cost a/home/<user>autofs layout already carries per user, bounded the same way by the pool size (KIROCREW_PATH_RESOLVE_WORKERS, #12460), and it is the isolation this key exists for; narrowing the rule to the literal/local/homewould leave/usr/homeand/var/homehosts -- single local filesystems with the identical collapse -- unfixed. A single-user host still has one key for that user's whole tree; that is the designed per-user granularity, the same one/home/<user>hosts get today. The issue's item 1 (floor the early-degrade threshold at two workers) is a separate, independent change already claimed by another operator on the issue; item 2 (pool size) landed as #12460; why the budget expires at all on a healthy local disk is #10255 / #10256.Backwards compatibility
Compatible: the only inputs whose key changes are absolute or relative paths whose second component is literally
homeand that continue past it; those now key one component deeper. The container by itself, every other layout and every Windows spelling key exactly as before, pinned by the three pre-existing_stall_prefixtests, which pass unchanged. The key is an in-memory index into the cooldown dictionary and is never persisted or exposed beyond thePathResolutionStalledmessage.Tests
test/test_security_path_resolve_bounded.py:test_the_stall_prefix_never_ends_on_a_container_of_homes-- the issue's reproduction inverted: two users' paths under/local/home/<user>/...are two keys, each the user's own home; the deeper layouts (/usr/home,/var/home,/export/home) key on the user; the container alone (/local/home,/home) is its own key;/home/x,/Volumes/share,/tmp/xare untouched. Driven throughposixpathso the layout is asserted on every platform.test_a_stall_under_one_home_leaves_a_sibling_home_resolving-- through the real cooldown machinery: a stall charged under one user's home refuses that user's other paths for free (no re-probe), while a second user's path under the same/local/homecontainer is submitted and resolved during the first user's cooldown, and the second user's key carries no history.Mutation-verified: with the two-line change disabled (
keep += 0), both new tests fail -- the key test on its first assertion, the key being/local/homeinstead of the user's home; the behavioural test withPathResolutionStalledraised for the second user's path, i.e. the reported collapse -- while the three existing prefix tests still pass. With the fix restored the whole file passes: 73 passed under-n0with an isolatedKIROCREW_HOMEand the pool at its shipped size (KIROCREW_PATH_RESOLVE_WORKERSunset).black,isort,flake8clean on both files;mypyclean onsecurity/paths.py.Manual verification
On the affected host, with this branch's
_stall_prefix, the five paths from the issue's measurement table key to/local/home/<user>(the one user's home) instead of/local/home; the/home/<user>/...spelling still keys to/home/<user>;/var/tmp/...still keys to/var/tmp. Everything else is a pure function of the path string and is covered by the tests above.Any other suggestions on the work
max(2, W - 1)for the early-degrade arm) is independent of this change and worth landing regardless; it is claimed separately on the issue.Related Issues
Fixes #12386
Related: #8022 (introduced
_stall_prefix), #12460 (pool size knob, item 2), #10255, #10256 (why the budget expires).Pattern harvest
Rule candidate: review-prompt
Pattern: a key or prefix derived by counting path components stands in for a filesystem boundary (mount, home) and must be checked against the layouts where that boundary sits one level deeper --
C:\Users\<user>and/local/home/<user>were the same defect in the same function, three weeks apart.Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)_stall_prefixdocstring and the key's description indocs/system-specs/modules/security.md