Skip to content

fix(seed): apply the $KIROCREW_HOME link guardrails to a Windows junction - #9067

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/seed-home-junction-guardrail
Sep 7, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/seed-home-junction-guardrail

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

seed._resolve_dst refuses to seed into a linked $KIROCREW_HOME, and its own
comment gives the reason:

The downstream rmtree would follow the link and delete the link target; even
the --replace-less path leads the user into a dead end.

Both checks ask dst.is_symlink(), which is False for a Windows junction. That
is the shape that matters here: a directory symlink on Windows needs
SeCreateSymbolicLinkPrivilege, while mklink /J needs none — so putting
$KIROCREW_HOME on 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/main with a real
_winapi.CreateJunction junction:

1. Non-empty, without --seed-replace — fires GUARDRAIL_NON_EMPTY:

AssertionError: assert 'non_empty' == 'symlink_replace'

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_replace calls it out
by name as a review-bot regression guard. It is restored in full for junctions.

2. Non-empty, with --seed-replace — reaches shutil.rmtree:

OSError: Cannot call rmtree on a symbolic link

rmtree refuses a junction exactly as it refuses a symlink, so the harm the comment
names (deleting the link target) does not occur — but the user gets
EXIT_IO_ERROR with that text instead of the actionable "point it at a real
directory"
.

3. Empty — and this one is the opposite outcome, not a worse message.

Failed: DID NOT RAISE <class 'kiro_crew.seed.SeedError'>

Both link checks are False, so control falls to elif dst.exists(): dst.rmdir() —
and os.rmdir on a junction detaches the junction (that is exactly how
platform_compat.unlink_link_or_junction removes one). Nothing raises. The user's
redirection 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_EMPTY and 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_HOME no longer points where
they 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. rmtree
refuses 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 which
the 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 a
junction.
Change: both checks use pinned_fs.is_reparse_point(dst).

if pinned_fs.is_reparse_point(dst):        # non-empty branch
...
elif dst.exists() and pinned_fs.is_reparse_point(dst):   # empty branch

Why pinned_fs.is_reparse_point and not platform_compat.is_link_or_junction.
Both would fix the three cases. is_reparse_point is already imported by this
module (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 the
better semantic fit: is_link_or_junction narrows to symlink-or-mount-point,
while is_reparse_point is true for any reparse tag — and this is a
refuse-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:

  • the guardrail constants GUARDRAIL_SYMLINK_REPLACE / GUARDRAIL_SYMLINK_EMPTY
    are unchanged — they are the audit-record and exit-code contract, and
    renaming them for accuracy would be a breaking change for a cosmetic gain;
  • the message becomes "symlinked or junctioned $KIROCREW_HOME", which names both
    shapes while keeping the "symlinked" substring the existing tests assert on.

Nothing else in seed.py is touched.

Tests

test/test_seed.py, 3 tests — one per measured consequence:

Test Locks in
test_seed_refuses_a_junctioned_nonempty_home GUARDRAIL_SYMLINK_REPLACE on the first attempt, not the NON_EMPTY dead end
test_seed_replace_refuses_a_junctioned_home --seed-replace refuses instead of reaching rmtree; the link target survives
test_seed_refuses_an_EMPTY_junctioned_home_instead_of_detaching_it the empty branch refuses; the link is still a link afterwards and nothing was seeded through it

They deliberately do not carry @requires_symlinks: conftest.make_dir_link
makes 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 branch
precondition 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 the
wrong 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.py reports the same 1 failed on
pristine origin/main as with the patch (test_seed_cli_flag_registered,
unrelated), and 32 → 35 passed — exactly the 3 tests added.

Gates on this head: flake8 clean, isort --check-only clean, mypy --platform linux reports nothing in seed.py, black and subprocess-encoding gates pass scoped
origin/main...HEAD. Both files are in .github/black-baseline.txt and were
deliberately 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 Windows
junction blind spot, the same family as #7881.

Pattern harvest

Rule candidate: agents-md
Pattern: a link guardrail whose only tests are @requires_symlinks. That marker
skips 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 (junction
on Windows, symlink elsewhere) keeps the coverage instead of skipping it;
@requires_symlinks should be reserved for cases that genuinely need symlink
semantics rather than link semantics.

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)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

…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>
@leonlaiyc
leonlaiyc requested review from a team and chenmingwei23 September 6, 2026 16:46
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed c35a8cd79f91ec212cd3dbb4a201c0094a4448d8 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c35a8cd

@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of c35a8cd79f91ec212cd3dbb4a201c0094a4448d8 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All PR claims verify against the base tree: pinned_fs is already imported in seed.py:32, is_reparse_point (pinned_fs.py:421) covers junctions via st_reparse_tag, and conftest.make_dir_link builds a real junction on Windows. The two replaced checks are exactly the two is_symlink() guards in the diff, constants and the "symlinked" test substring are preserved. One gap: the same function's dangling-link guard (dst.is_symlink() and not dst.exists(), seed.py:~486) keeps the junction-blind predicate, so a dangling junction still falls through to copytree → raw FileExistsError.

Design-Verdict: PASS

Right predicate, right layer: swapping one junction-blind check for the already-imported, refuse-only is_reparse_point fixes all three measured divergences with no contract change.

Suggestions

  • The dangling-link guard a few lines above (dst.is_symlink() and not dst.exists()) is the third is_symlink() in this same chain; a dangling junction still bypasses it and lands as a raw FileExistsError from copytree. Same one-predicate fix applies — worth folding into this PR since it's the identical root cause.

[DESIGN-REVIEWED] c35a8cd

@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of c35a8cd79f91ec212cd3dbb4a201c0094a4448d8 via the fork AI-review pipeline — 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 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 is_symlink().

What this change ships

Intent: make the seed guardrails refuse a junctioned $KIROCREW_HOME on Windows the same way they refuse a symlinked one — a FIX.

  1. Non-empty junctioned home now refused with the actionable message, not the --seed-replace dead end — justified
  2. --seed-replace on a junctioned home now refused, instead of a raw rmtree OSError — justified
  3. Empty junctioned home now refused, instead of silently detaching the user's junction and seeding a fresh dir — justified
  4. Refusal message relabeled "symlinked or junctioned" — declared, part of the fix
  5. Three new guardrail tests that actually run on Windows shards (no @requires_symlinks) — justified

Verified: pinned_fs.is_reparse_point (pinned_fs.py:421) exists, its docstring names this exact defect, seed.py already imports pinned_fs (line 32), and snapshot.py:3144 already uses it in the same guard role — the reuse claim is real, no second spelling added. conftest.make_dir_link (test/conftest.py:187) exists and builds a junction on Windows.

Watch

Description says the root cause is "one predicate, used twice" — I count three is_symlink( guard sites in seed() (grep is_symlink\( in seed.py: lines 486, 521, 534); the dangling-link guard at 486 is left unfixed. A dangling junction skips it (is_symlink() False, exists() False), skips every patched branch, and reaches shutil.copytree → raw FileExistsError as EXIT_IO_ERROR — exactly what GUARDRAIL_DANGLING_SYMLINK exists to prevent, and its only test (test_seed.py:1011) is @requires_symlinks, so it stays invisible on Windows. The general fix is the same one-line predicate swap, in scope.

[FIRST-PRINCIPLES-REVIEWED] c35a8cd

@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed c35a8cd79f91ec212cd3dbb4a201c0094a4448d8 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c35a8cd

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 6, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_fs already imported at seed.py:32 — no import path grows.
  • is_reparse_point (pinned_fs.py:421) covers a junction via st_reparse_tag after os.path.islink returns False; its docstring names this exact defect.
  • conftest.make_dir_link builds a real _winapi.CreateJunction junction 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_symlinks is correct, not a coverage loosening.
  • Both replaced predicates are exactly the two is_symlink() guards inside the exists() 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.rmdir on 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.

@bolichen97
bolichen97 merged commit b0f201d into kirodotdev:main Sep 7, 2026
67 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 7, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants