Repository navigation
fix(seed): apply the $KIROCREW_HOME link guardrails to a Windows junction - #9067
Conversation
…tion `seed` refuses to seed into a linked `$KIROCREW_HOME` for a stated reason: the downstream `rmtree` would follow the link and delete the link target. Both checks spell "is this a link?" as `dst.is_symlink()`, which is False for a Windows junction — and the junction is the shape that matters, because a directory symlink there needs SeCreateSymbolicLinkPrivilege while `mklink /J` needs none. Putting `$KIROCREW_HOME` on another drive is exactly what a Windows user does with one. All three consequences measured on unpatched main with a real junction: - non-empty, no `--seed-replace`: fires `GUARDRAIL_NON_EMPTY`, whose advice is "pass --seed-replace" — the two-step dead end the symlink check was hoisted above this branch specifically to prevent; - non-empty, with `--seed-replace`: reaches `shutil.rmtree`, which refuses a junction just as it refuses a symlink — `OSError: Cannot call rmtree on a symbolic link`, surfacing as EXIT_IO_ERROR instead of the actionable guardrail; - EMPTY: the worst one. Both link checks are False, so control reaches `elif dst.exists(): dst.rmdir()` — and `os.rmdir` on a junction DETACHES it. No error is raised at all: the user's redirection is silently removed and the fixture is seeded into a fresh real directory at that path. The symlink case refuses; the junction case does the opposite. Routed through `pinned_fs.is_reparse_point`, already imported here and already used in this role at `snapshot.py:3144`. It is the right predicate rather than the narrower junction-only one: this is a refuse-to-act guard, so any reparse point should trip it. The guardrail constants are unchanged — they are the audit/exit-code contract — and the message keeps the substring the existing tests assert on while naming both shapes. Every existing guardrail test here is `@requires_symlinks`, so none of them run on the one platform where a junction is reachable. The new tests use `conftest.make_dir_link` and need no privilege, so Windows CI exercises them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of All PR claims verify against the base tree: Design-Verdict: PASS Right predicate, right layer: swapping one junction-blind check for the already-imported, refuse-only Suggestions
[DESIGN-REVIEWED] c35a8cd |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of All verification complete. The author's claims check out against the base tree; I found one unfixed sibling of the stated root cause. Final review: First-Principles-Verdict: CONCERNS Sound predicate-level fix, but the root cause has a third instance in the same function — the dangling-link guard at seed.py:486 keeps the blind What this change shipsIntent: make the seed guardrails refuse a junctioned
Verified: WatchDescription says the root cause is "one predicate, used twice" — I count three [FIRST-PRINCIPLES-REVIEWED] c35a8cd |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
bolichen97
left a comment
There was a problem hiding this comment.
Tech Lead review — approved.
Distinct fix site, not a duplicate. Same defect class as #8873 (merged, apps/builtins/papyrus/backend/store.py) and #9059 (open, dashboard/handlers/discover.py), but zero file overlap: this one is seed.py's $KIROCREW_HOME guardrail chain. Three independent call sites of the same root cause, each needing its own fix and its own test.
Claims verified against origin/main:
pinned_fsalready imported atseed.py:32— no import path grows.is_reparse_point(pinned_fs.py:421) covers a junction viast_reparse_tagafteros.path.islinkreturns False; its docstring names this exact defect.conftest.make_dir_linkbuilds a real_winapi.CreateJunctionjunction on Windows and a directory symlink on POSIX, so the three new tests exercise the junction shape on the Windows shards and the symlink shape elsewhere — dropping@requires_symlinksis correct, not a coverage loosening.- Both replaced predicates are exactly the two
is_symlink()guards inside theexists() and any(iterdir())/ empty-branch pair. Guardrail constants and the"symlinked"substring the existing tests assert on are preserved. - Case 3 is the one that matters:
os.rmdiron a junction detaches it, so the pre-fix empty branch silently discarded the user's redirection and seeded a fresh real directory. Refusal is the right outcome, and it now matches the symlink case.
Scope is clean: 2 files, +97/-7, one commit, no behaviour change for a non-linked home, and the change is refuse-only — it can only turn a wrong success or a cryptic OSError into an actionable guardrail refusal.
Residual (non-blocking, matches the Design and First Principles advisories): the dangling-link guard at seed.py:486 still asks dst.is_symlink() and not dst.exists(), so a dangling junction bypasses it and lands as a raw FileExistsError from copytree. That is a message-quality gap with no data loss and no wrong-outcome divergence, unlike the three cases fixed here — fine as a follow-up rather than a reason to hold this. Worth folding into the same follow-up as any remaining siblings of this predicate elsewhere in the tree.
All 65 check-runs green; GPT 5.6 and Opus 4.8 no findings, Design PASS, First Principles CONCERNS on the residual above only.
…tion (kirodotdev#9067) `seed` refuses to seed into a linked `$KIROCREW_HOME` for a stated reason: the downstream `rmtree` would follow the link and delete the link target. Both checks spell "is this a link?" as `dst.is_symlink()`, which is False for a Windows junction — and the junction is the shape that matters, because a directory symlink there needs SeCreateSymbolicLinkPrivilege while `mklink /J` needs none. Putting `$KIROCREW_HOME` on another drive is exactly what a Windows user does with one. All three consequences measured on unpatched main with a real junction: - non-empty, no `--seed-replace`: fires `GUARDRAIL_NON_EMPTY`, whose advice is "pass --seed-replace" — the two-step dead end the symlink check was hoisted above this branch specifically to prevent; - non-empty, with `--seed-replace`: reaches `shutil.rmtree`, which refuses a junction just as it refuses a symlink — `OSError: Cannot call rmtree on a symbolic link`, surfacing as EXIT_IO_ERROR instead of the actionable guardrail; - EMPTY: the worst one. Both link checks are False, so control reaches `elif dst.exists(): dst.rmdir()` — and `os.rmdir` on a junction DETACHES it. No error is raised at all: the user's redirection is silently removed and the fixture is seeded into a fresh real directory at that path. The symlink case refuses; the junction case does the opposite. Routed through `pinned_fs.is_reparse_point`, already imported here and already used in this role at `snapshot.py:3144`. It is the right predicate rather than the narrower junction-only one: this is a refuse-to-act guard, so any reparse point should trip it. The guardrail constants are unchanged — they are the audit/exit-code contract — and the message keeps the substring the existing tests assert on while naming both shapes. Every existing guardrail test here is `@requires_symlinks`, so none of them run on the one platform where a junction is reachable. The new tests use `conftest.make_dir_link` and need no privilege, so Windows CI exercises them. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Problem / Motivation
seed._resolve_dstrefuses to seed into a linked$KIROCREW_HOME, and its owncomment gives the reason:
Both checks ask
dst.is_symlink(), which is False for a Windows junction. Thatis the shape that matters here: a directory symlink on Windows needs
SeCreateSymbolicLinkPrivilege, whilemklink /Jneeds none — so putting$KIROCREW_HOMEon another drive is something a Windows user does with a junction,not a symlink. This is an ordinary supported configuration, not a planted one.
Three consequences, all measured on unpatched
origin/mainwith a real_winapi.CreateJunctionjunction:1. Non-empty, without
--seed-replace— firesGUARDRAIL_NON_EMPTY:Its advice is "Pass --seed-replace to wipe it and re-seed". That is precisely the
two-step dead end the symlink check was hoisted above this branch to prevent — the
existing
test_seed_refuses_symlinked_nonempty_target_without_replacecalls it outby name as a review-bot regression guard. It is restored in full for junctions.
2. Non-empty, with
--seed-replace— reachesshutil.rmtree:rmtreerefuses a junction exactly as it refuses a symlink, so the harm the commentnames (deleting the link target) does not occur — but the user gets
EXIT_IO_ERRORwith that text instead of the actionable "point it at a realdirectory".
3. Empty — and this one is the opposite outcome, not a worse message.
Both link checks are False, so control falls to
elif dst.exists(): dst.rmdir()—and
os.rmdiron a junction detaches the junction (that is exactly howplatform_compat.unlink_link_or_junctionremoves one). Nothing raises. The user'sredirection to another drive is silently removed, and the fixture is seeded into a
fresh real directory at that path. For a symlink the same situation raises
GUARDRAIL_SYMLINK_EMPTYand refuses.Why it matters
Case 3 is a silent, destructive divergence: two link shapes that are
interchangeable from the user's point of view produce a refusal and a quiet
reconfiguration respectively. The user's
$KIROCREW_HOMEno longer points wherethey put it, and nothing told them.
Cases 1 and 2 are the guardrail failing to do its job on the platform where its
trigger is reachable at all. Graded honestly: no data loss in either.
rmtreerefuses rather than deleting through the junction, so the link target is never
destroyed — the guard's stated worst case does not happen. What is lost is the
refusal itself, the actionable message, and (case 3) the user's configuration.
This is invisible to CI today. All three existing guardrail tests here are
@requires_symlinks, so they are skipped on Windows — the only platform on whichthe junction shape exists. The guard has never been exercised where it can break.
What changed (motivation → approach → change)
Symptom: three different wrong behaviours for a junctioned
$KIROCREW_HOME.Root cause: one predicate, used twice —
dst.is_symlink()does not report ajunction.
Change: both checks use
pinned_fs.is_reparse_point(dst).Why
pinned_fs.is_reparse_pointand notplatform_compat.is_link_or_junction.Both would fix the three cases.
is_reparse_pointis already imported by thismodule (no import path grows), is already used in exactly this role at
snapshot.py:3144, and its docstring names this defect verbatim. It is also thebetter semantic fit:
is_link_or_junctionnarrows to symlink-or-mount-point,while
is_reparse_pointis true for any reparse tag — and this is arefuse-to-act guard, where the conservative direction is to trip on anything
that redirects. Widening a guard that only ever declines cannot cause the failure a
too-broad predicate causes at a guard that acts.
Contract deliberately preserved:
GUARDRAIL_SYMLINK_REPLACE/GUARDRAIL_SYMLINK_EMPTYare unchanged — they are the audit-record and exit-code contract, and
renaming them for accuracy would be a breaking change for a cosmetic gain;
shapes while keeping the
"symlinked"substring the existing tests assert on.Nothing else in
seed.pyis touched.Tests
test/test_seed.py, 3 tests — one per measured consequence:test_seed_refuses_a_junctioned_nonempty_homeGUARDRAIL_SYMLINK_REPLACEon the first attempt, not theNON_EMPTYdead endtest_seed_replace_refuses_a_junctioned_home--seed-replacerefuses instead of reachingrmtree; the link target survivestest_seed_refuses_an_EMPTY_junctioned_home_instead_of_detaching_itThey deliberately do not carry
@requires_symlinks:conftest.make_dir_linkmakes a junction on Windows, which needs no privilege, so these run on the Windows
shards where the three existing symlink tests skip.
Guard-the-guard. Each asserts the planted shape through an oracle outside the
module under test —
pinned_fs.is_reparse_point(link)— plus the branchprecondition the case depends on (
any(link.iterdir())for the non-empty cases,not any(...)for the empty one). Without those, a test could pass for reaching thewrong branch.
Red-before, measured on unpatched
origin/main:3 failed, one per row above,with the exact assertions quoted in Problem / Motivation.
Control for pre-existing noise:
test_seed.pyreports the same 1 failed onpristine
origin/mainas with the patch (test_seed_cli_flag_registered,unrelated), and
32 → 35 passed— exactly the 3 tests added.Gates on this head:
flake8clean,isort --check-onlyclean,mypy --platform linuxreports nothing inseed.py, black and subprocess-encoding gates pass scopedorigin/main...HEAD. Both files are in.github/black-baseline.txtand weredeliberately not reformatted.
Manual verification
N/A — unit coverage sufficient: all three behaviours are decided by which branch the
link matches, and the tests build a real junction on the affected platform and drive
seed()itself rather than mocking the predicate.Related Issues
None — found by inspection while auditing
is_symlink-based guards for the Windowsjunction blind spot, the same family as #7881.
Pattern harvest
Rule candidate:
agents-mdPattern: a link guardrail whose only tests are
@requires_symlinks. That markerskips on Windows, which is the one platform where the junction spelling exists —
so a guard written against links is verified exclusively on the platform where it
cannot fail. When a test needs a directory link,
conftest.make_dir_link(junctionon Windows, symlink elsewhere) keeps the coverage instead of skipping it;
@requires_symlinksshould be reserved for cases that genuinely need symlinksemantics rather than link semantics.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code