Skip to content

fix: refuse a windows junction wherever a directory symlink is refused - #34331

Merged
bolichen97 merged 1 commit into
mainfrom
fix/33289-junction-guards
Nov 10, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/33289-junction-guards

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On Windows, a directory junction in the member-records move or in an installed theme pack is refused exactly the way a directory symlink already is.

Five directory-link guards cannot see a Windows junction (mklink /J, no elevation needed): four ask only Path.is_symlink() or stat.S_ISLNK, one only S_ISDIR on an lstat, and a junction passes all three as a real directory:

  • A junction at the old trust\<kind> (or trust) layout is moved through and sealed: each original is deleted inside the junction's target and the emptied folder is removed (the junction itself, when it sits at trust\<kind>), with one INFO line. A symlink there holds the move unsealed with a WARNING telling the operator to replace the link, which is what the module and security.md promise for any link.
  • A junctioned installed theme pack is listed and served by GET /api/themes/<slug>, while a symlinked one is left out of the list and answers 500 invalid_installed_theme.

Why it matters

A Windows user who relocated their pre-upgrade member records with a junction has that folder emptied by the one-time move instead of getting the documented safe state. The bytes survive only as the promoted copies, with no warning that anything unusual happened. For themes nothing is gained or lost, but the same layout gets opposite answers on Windows and POSIX.

Not a goal

What changed (motivation → approach → change)

A Windows junction now gets the same answer a symlink gets at every directory-link guard in the member-records move and the installed-theme path.

The cause is one predicate: is_symlink() / S_ISLNK miss a junction, which platform-compat.md names as the mistake to avoid. Each guard now asks platform_compat.is_link_or_junction, the helper themes.py already uses for the install root and copy walk.

Guard A junction there before Now (same as a symlink)
member_records._legacy_state (trust, trust\<kind>) moved through, move sealed move held: "reached through a link"
member_records._plain_dir (member-records, member-records\<kind>) passed as a plain directory: a later write into it was refused by atomic_write, but a member-records\<kind> with nothing to copy let the move seal move held: "is not a plain directory"
_validate_theme_dir, pack root validated, detail answers 200 "theme path is not a directory", 500
_validate_theme_dir, an entry in the pack accepted when it pointed inside the pack (one pointing outside was already refused by containment) "symlinks are not allowed"
themes._list_themes_sync listed not listed

test/link_screen_sites.py is regenerated: _validate_theme_dir and _list_themes_sync now screen with the helper, and both refuse every link they find, so neither needs a hold.

Backwards compatibility

Breaking: on Windows, a junction at trust, trust\<kind> or member-records\<kind> now holds the member-records move unsealed until the operator replaces it, a junctioned theme pack is no longer listed or served, and a pack holding a junction is no longer served. POSIX is unchanged. Writer sweep on origin/main @ 9c5e565: no product code creates a junction at any of these names. The move creates its own directories with os.mkdir (_plain_dir(create=True)), the theme install stages with _copy_installed_theme, which already refuses junctions, and the product's symlink_or_junction callers (apps/bridges_skills.py for app skills, frontend.py for the built dashboard) link other names. Only a layout an operator built by hand changes.

Reader: src/kiro_crew/dashboard/handlers/themes.py:api_themes -- crew page -- leaves a junctioned pack out like a symlinked one; test_junctioned_directory_is_never_listed
Reader: src/kiro_crew/dashboard/handlers/themes.py:api_theme_detail -- crew page -- answers 500 invalid_installed_theme as for a symlinked pack; test_a_junction_is_refused_like_a_symlink
Reader: src/kiro_crew/dashboard/handlers/themes.py:_do_install -- crew page -- validates the staging copy, which holds no link; the existing install tests in test/test_theme_install.py pass
Reader: src/kiro_crew/member_records.py:records_dir -- chat -- raises RecordsNotMoved when ensure_migrated() is False and the kind's old layout still holds a record, which test_a_junction_holds_the_move_like_a_link sets up for a junction; test_records_behind_a_link_are_neither_promoted_nor_read_as_absent pins the reader on that False
Reader: src/kiro_crew/sandbox_staging.py:_member_records_move -- subagent -- refuses a launch whenever ensure_migrated() is False (Linux and macOS spawn prep), as for a symlink; test_records_behind_a_link_are_neither_promoted_nor_read_as_absent pins it on that False

Tests

  • test_member_records.py::test_a_junction_holds_the_move_like_a_link (junction at trust, trust/member-rules, member-records/member-rules): the move does not seal, the failure names the link, and the member-rules original stays in place with no promoted copy.
  • test_theme_install.py::TestValidateThemeDir::test_a_junction_is_refused_like_a_symlink (pack root, and a styles entry): the validator refuses it.
  • test_dashboard_themes_coverage.py::TestListThemesSync::test_junctioned_directory_is_never_listed: the list leaves it out.

Each simulates a junction by patching platform_compat._ISJUNCTION (the os.path.isjunction probe), as test_pod_orphans.py does, so the case runs on every OS: the path is a directory, not a symlink, and the probe says junction. The existing symlink and plain-directory tests are unchanged.

Determinism: the six new cases passed 20 runs at -n0 and 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 with test_member_records.py and test_theme_install_identity.py as co-tenants; the three changed test files (335 ids) passed in a shuffled order, seed 33289, at -n0 (332 passed, 3 skipped).

Proof: PROVEN test/test_dashboard_themes_coverage.py::TestListThemesSync::test_junctioned_directory_is_never_listed, test/test_member_records.py::test_a_junction_holds_the_move_like_a_link[trust-reached through a link], test/test_member_records.py::test_a_junction_holds_the_move_like_a_link[trust/member-rules-reached through a link], test/test_member_records.py::test_a_junction_holds_the_move_like_a_link[member-records/member-rules-is not a plain directory], test/test_theme_install.py::TestValidateThemeDir::test_a_junction_is_refused_like_a_symlink[-theme path is not a directory] (head 36c2b70)

Manual verification

N/A — unit coverage sufficient: the guards' only input is the link probe, which the tests drive directly; no Windows host was available for a real mklink /J run.

Screenshots / video

N/A — no frontend change.

Related Issues

Closes #33289

Sibling sweep

Swept: git grep -nE "is_symlink()|S_ISLNK|islink(|S_ISDIR(" 69d3a9a -- src/kiro_crew/member_records.py src/kiro_crew/dashboard/theme_validate.py src/kiro_crew/dashboard/handlers/themes.py src/kiro_crew/sandbox_seals.py
Sibling: src/kiro_crew/member_records.py:194 -- changed here
Sibling: src/kiro_crew/dashboard/handlers/themes.py:145 -- changed here
Sibling: src/kiro_crew/dashboard/theme_validate.py:1795 -- not affected -- runs after resolve(), so it answers the same for a symlink and a junction; containment against the resolved root is the guard
Sibling: src/kiro_crew/sandbox_seals.py:241 -- not affected -- the namespace and Seatbelt sandboxes it guards run only on Linux and macOS, which have no junctions

Pattern harvest

Rule candidate: review-prompt
Pattern: a directory-link guard spelled Path.is_symlink() or stat.S_ISLNK instead of platform_compat.is_link_or_junction

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|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

Path.is_symlink() and stat.S_ISLNK are False for a Windows directory
junction, so five directory-link guards read one as a real directory:
the member-records move's source (trust, trust/<kind>) and destination
(member-records/<kind>) checks, the installed-theme validator's pack
root and per-entry checks, and the theme list. A junction at the old
trust layout was moved through and sealed, deleting the originals in
the junction's target, where a symlink holds the move unsealed. Each
guard now asks platform_compat.is_link_or_junction, the documented
helper, so a junction gets the answer a symlink already gets. POSIX is
unchanged.

_validate_theme_dir and _list_themes_sync join the link-screen
baseline: both refuse every link they find and never traverse one, so
neither needs a hold.

Closes #33289
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 10, 2026 05:07
@bolichen97
bolichen97 enabled auto-merge (squash) November 10, 2026 05:18
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 36c2b70316dbf1fa2c36800dd1abe7e7301bb07e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 36c2b70316dbf1fa2c36800dd1abe7e7301bb07e — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. Every guard now calls the existing platform_compat.is_link_or_junction instead of a second spelling, and the defect comes from linked issue #33289.

What this change ships

Inventory (5 items) — 5 justified

Intent: on Windows, an operator's hand-built junction gets the same documented safe refusal a symlink gets, in the member-records move and in installed theme packs. FIX.

  1. A junction at trust or trust\<kind> holds the member-records move unsealed instead of being moved through and emptied — justified
  2. A junction at member-records\<kind> holds the move as "not a plain directory" — justified
  3. A junctioned theme pack is no longer served by the theme detail endpoint (500 invalid_installed_theme) — justified
  4. A junction inside a theme pack is refused as "symlinks are not allowed" — justified
  5. A junctioned theme pack is no longer listed — justified

[FIRST-PRINCIPLES-REVIEWED] 36c2b70

Description read

[DESCRIPTION-READ] eaf94427ccc51161c03d86e36af4b5ba5044e1ece4e1e1c7f4ae60cf46d97cc7

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 36c2b70316dbf1fa2c36800dd1abe7e7301bb07e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The PR swaps in the existing is_link_or_junction helper at five directory-link guards, and the Windows CI lane already runs the code that detects junctions.

Notes

  • No real mklink /J run was done. The new tests stand in for a junction by patching the _ISJUNCTION probe, so they never check what the real probe returns for an actual junction. That rests on the helper's existing callers in themes.py.

[DESIGN-REVIEWED] 36c2b70

Description read

[DESCRIPTION-READ] 45d11abef20bd91cb9ae06ce2e2a6a6d886e2a45aac358c4bf825f856c426146

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 36c2b70

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 36c2b70316dbf1fa2c36800dd1abe7e7301bb07e false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 36c2b70316dbf1fa2c36800dd1abe7e7301bb07e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 36c2b70

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 36c2b70316dbf1fa2c36800dd1abe7e7301bb07e false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 10, 2026

@buluoray buluoray 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.

Approve on 36c2b70. Five directory-link guards (member-records move x2, theme validator root + entry, installed-theme list) now use platform_compat.is_link_or_junction, so a Windows junction gets the symlink answer; on POSIX the predicate equals islink/S_ISLNK, so it only tightens. Decisive lines: src/kiro_crew/member_records.py:194, src/kiro_crew/member_records.py:242, src/kiro_crew/dashboard/theme_validate.py:1277, src/kiro_crew/dashboard/theme_validate.py:1377, src/kiro_crew/dashboard/handlers/themes.py:145

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 10, 2026
@bolichen97
bolichen97 merged commit 7c9d44a into main Nov 10, 2026
115 of 126 checks passed
@bolichen97
bolichen97 deleted the fix/33289-junction-guards branch November 10, 2026 08:46
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 10, 2026
bolichen97 added a commit that referenced this pull request Nov 10, 2026
#34331)

Path.is_symlink() and stat.S_ISLNK are False for a Windows directory
junction, so five directory-link guards read one as a real directory:
the member-records move's source (trust, trust/<kind>) and destination
(member-records/<kind>) checks, the installed-theme validator's pack
root and per-entry checks, and the theme list. A junction at the old
trust layout was moved through and sealed, deleting the originals in
the junction's target, where a symlink holds the move unsealed. Each
guard now asks platform_compat.is_link_or_junction, the documented
helper, so a junction gets the answer a symlink already gets. POSIX is
unchanged.

_validate_theme_dir and _list_themes_sync join the link-screen
baseline: both refuse every link they find and never traverse one, so
neither needs a hold.

Closes #33289

(cherry picked from commit 7c9d44a)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Windows junction guards: the member-records move and the installed-theme check read a directory junction as a real directory

2 participants