Skip to content

fix(auto-improvement): stop a junction widening the do-not-pollute snapshot - #8871

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/pollute-junction-snapshot-scope
Sep 8, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/pollute-junction-snapshot-scope

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

spine/pollute.py::_hash_path is the blocking do-not-pollute gate: it snapshots the host paths the measurement runtime may write under, boots that runtime once, re-snapshots, and refuses the whole experiment on any diff. Its contract for links is explicit in the docstring:

Symlinks are recorded by their target string (a flipped symlink is a change) without following them (avoids escaping the snapshot scope)

The predicate was Path.is_symlink(), which is False for a Windows directory junction. Both halves of that contract broke there, in opposite directions:

  • The snapshot escaped its own root. pathlib deliberately does not recurse into a symlink, but it does descend through a junction — measured:

    rglob under root: ['j', 'j\secret', 'j\secret\leak.txt']
    descended through the junction? True
    

    So the walk hashed the link target's whole tree. Any unrelated write under that target — by anything on the machine, not the measured runtime — then read as a leak and blocked the run.

  • A re-pointed junction became invisible. A junction was hashed as a plain directory (a D marker plus its relative name), so flipping one to another empty directory produced an identical hash. A real host write the gate exists to catch passed as hermetic.

Why it matters

This gate decides whether an autonomous run may start at all. The first failure makes it refuse clean runs for a reason the operator cannot see in any diff — the changed content is outside every watched path. The second is worse in kind: it is a leak the detector was built to catch, reported as hermetic.

The file's own test module opens by noting that a detector which always answers "hermetic" "passes every test a green-path suite can write, and is worthless". That is precisely the state of the re-pointing case on Windows.

What changed (motivation → approach → change)

Root cause is the link predicate, not the walk.

Both the top-level check and the per-child check now route through platform_compat.is_link_or_junction — the shim-table row for this exact question (AGENTS.md: "Detect/remove a dir link → is_link_or_junction(path) NOT path.is_symlink() (misses a Windows junction)"). That alone fixes the re-pointing case, because the existing record-by-target branch then runs; readlink() resolves a junction on Windows, so nothing else in that branch needed changing.

Fixing the escape needs one more step, because rglob has already yielded the descendants by the time the link is seen. A link_roots list suppresses any child that sits under a link already recorded by target. The walk is already sorted by path string for determinism, and that ordering is what puts a link ahead of everything beneath it — so a single pass is sufficient and no second traversal is introduced.

Exclusion ordering is deliberately unchanged: an excluded link is skipped before it is recorded, and its descendants are still excluded because _is_excluded resolves each child and prefix-matches against the resolved exclude set.

Tests

tests/test_pollute.py. The plant is staged with a local mirror of test/conftest.py::make_dir_link, which calls _winapi.CreateJunction unconditionally on Windows — a plain symlink on POSIX, a real directory junction on Windows — so these run on every platform and the junction arm is the one actually exercised there.

It is deliberately not platform_compat.symlink_or_junction: that tries os.symlink FIRST and falls back to a junction only where the privilege is missing, so a runner with Developer Mode gets a SYMLINK and the junction arm is never exercised — silently, while still reporting green. The first head of this PR shipped that mistake; a guard-the-guard test asserting the plant really was a junction is what caught it, on the Windows CI shard. It is mirrored rather than imported because only the test/ testpath gets that conftest.

Both behavioural tests fail on origin/main:

  • test_a_write_under_a_linked_child_is_not_a_leak — assert True is False: main blocks on a write that is outside the watched root and only reachable by following the link.
  • test_a_repointed_link_still_blocks — assert False is True: main does not notice the flip at all.

Green on both sides:

  • test_the_staged_plant_is_really_a_junction_on_windows — guards the guard: it asserts the plant really is a junction on Windows, so the two tests above cannot quietly stop exercising the junction arm. This is the test that caught the symlink_or_junction mistake on the first head.

Local (Windows, repo-pinned toolchain): test_pollute.py 21 passed / 4 skipped (the 4 are the pre-existing symlink tests). Full auto_improvement suite: 1042 passed / 64 skipped / 0 failed. flake8 clean; scripts/check_black_formatting.py passes in scope (the one file it flagged was formatted with black --target-version py310, a three-line change confined to a line this PR added).

Manual verification

N/A — unit coverage sufficient: the change is one predicate plus a descendant filter inside a single function, and the tests drive the real run_do_not_pollute against a tmp fake-HOME with the real plant on the affected platform, as the module's own test conventions require.

Related Issues

None — found by source review of the is_symlink()-versus-junction seam after #8766 and #8767.

Pattern harvest

Rule candidate: semgrep
Pattern: Path.is_symlink() used to decide whether a directory walk may descend. It is False for a Windows junction, and — unlike a symlink, which pathlib refuses to recurse into — a junction is traversed, so the walk silently leaves its intended root. Two distinct failures follow from the one predicate: content from outside the root enters the result, and the link's own identity (its target) is never recorded. The repo's shim table already names is_link_or_junction; the residual risk is any walk that predates it.

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

@leonlaiyc
leonlaiyc requested review from a team and buluoray September 6, 2026 03:28
@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

Design Review (Fable 5, fork) — ✅ PASS

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

Analysis complete. The fix routes the link predicate through the repo's own platform_compat.is_link_or_junction shim (exactly what the platform-compat table prescribes), the sorted-walk prefix ordering that the descendant suppression relies on is sound (a path string strictly prefixes its children, so a link always precedes its subtree), the hash format is never persisted across runs so no compat concern, POSIX behavior is unchanged (the junction probe is False off Windows), and the affected platform is exercised by the Windows CI shard plus a guard-the-guard test that pins the plant as a real junction.

Design-Verdict: PASS

Root-cause fix at the repo's own platform_compat seam, both failure directions pinned by tests that fail on main and run on the affected platform.

Suggestions

  • rglob still enumerates the junction target's whole tree before the suppression filter drops it, so a junction to a large tree makes this blocking gate arbitrarily slow; pruning at descend (an os.walk-based walk that skips a link's children) would cap the gate's cost at the watched root — fine as a follow-up.

[DESIGN-REVIEWED] e3a9e6a

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of e3a9e6a37bfad5ec2f3fbb1419216984f72c08b4 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 claims verified. The in-package tests are collected (setup.cfg:343 lists src/kiro_crew/apps/builtins as a testpath), and test/conftest.py applies only to the test tree, so the local mirror of make_dir_link is genuinely necessary rather than a second spelling. The fix is mandated by a documented invariant (docs/system-specs/common/platform-compat.md:43), the defect's provenance is tests that fail on base (confirmed by reading the base predicate), the platform claims are corroborated in-repo (portability.py:146, themes.py:243), and no new public surface ships. Sibling is_symlink-gated walks exist elsewhere (deploy, snapshot, artifacts), but the description declares that residual class explicitly and a cross-subsystem sweep is genuinely larger — accepted-and-deferred, not a demand.

First-Principles-Verdict: PASS

Fail-on-base evidence exists only on Windows — verify the Windows CI shard collected and ran the three new junction tests before merging.

What this change ships

Intent: FIX — make the do-not-pollute gate treat a Windows junction as a link, so clean runs stop being falsely blocked and a re-pointed junction is caught.

Inventory (5 items)
  1. A clean run is no longer refused when a watched tree holds a junction whose target changed elsewhere — justified
  2. Re-pointing a junction inside a watched tree now blocks the run — justified
  3. Nothing beneath a recorded link is hashed; the snapshot stays inside its root — justified
  4. The docstring contract now says "links", covering junctions — justified
  5. Three new tests, staged via a local junction-forcing mirror of test/conftest.py::make_dir_link (unimportable there: test/ is a separate testpath) — justified

[FIRST-PRINCIPLES-REVIEWED] e3a9e6a

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- src/kiro_crew/apps/builtins/auto_improvement/tests/test_pollute.py:45 -- Function-local "import _winapi" violates top-level-imports -> Fix: use a module-level optional import.
[GPT-REVIEWED] e3a9e6a

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e3a9e6a

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@leonlaiyc
leonlaiyc force-pushed the fix/pollute-junction-snapshot-scope branch from c2723a4 to d40a0e5 Compare September 6, 2026 05:33
…apshot

_hash_path snapshots the host paths the measurement runtime may write under, and
its contract is explicit: links are "recorded by their target string (a flipped
symlink is a change) without following them (avoids escaping the snapshot
scope)".

The predicate was Path.is_symlink(), which is False for a Windows directory
junction, and both halves of that contract broke there:

* pathlib deliberately does NOT recurse into a symlink, but it DOES descend
  through a junction. So the walk hashed the link target's whole tree and the
  snapshot escaped its own root. Any unrelated write under that target -- by
  anything on the machine -- then read as a leak by the measured runtime and
  blocked the run.
* A junction was hashed as a plain directory (a "D" marker plus its relative
  name), so re-pointing one to another empty directory produced an IDENTICAL
  hash. A real host write the gate exists to catch passed as hermetic.

Route both the top-level and the per-child check through
platform_compat.is_link_or_junction, the shim-table row for this question, and
suppress the descendants rglob still yields under a link it has already recorded
by target. Sorting the walk by path string -- which the module already does for
determinism -- is what puts a link ahead of anything beneath it, so one pass is
enough.

readlink() resolves a junction on Windows, so the existing record-by-target
branch needed no other change.

Tests stage the plant with a local mirror of test/conftest.py::make_dir_link,
which calls _winapi.CreateJunction unconditionally on Windows. It is mirrored
rather than imported because only the test/ testpath gets that conftest, and it
is NOT platform_compat.symlink_or_junction: that tries os.symlink first, so a
runner with Developer Mode gets a symlink and the junction arm is never
exercised -- silently, while still reporting green.

Both behavioural tests fail on origin/main: the outside write blocks
("assert True is False") and the re-pointed link does not block
("assert False is True").

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@bolichen97
bolichen97 force-pushed the fix/pollute-junction-snapshot-scope branch from d40a0e5 to e3a9e6a Compare September 8, 2026 12:13
@bolichen97

Copy link
Copy Markdown
Contributor

Rebased onto main 02d7a2d0 by a maintainer as part of the 2026-09-08 open-PR audit.

Clean rebase, no conflicts. Main had not touched spine/pollute.py or its test since the merge base, so the diff is unchanged from your original commit.

Gates run locally on the changed files only: black --check, isort --check-only, flake8, and pytest src/kiro_crew/apps/builtins/auto_improvement/tests/test_pollute.py (25 passed).

Please review that the rebased head still matches your intent. Note that a maintainer push makes the maintainer the last pusher, so under this repo's last-push rule a second approver is needed before merge. Reply here if anything looks wrong.

@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 Sep 8, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) September 8, 2026 13:05

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

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: swaps Path.is_symlink for platform_compat.is_link_or_junction in the pollute-snapshot hasher and skips children under an already-recorded link root, so a Windows directory junction is recorded by its target string instead of being descended through by rglob -- the root cause of the snapshot hash escaping its own root and reading unrelated writes under the link target as a leak. Second file is the matching test. CodeQL is not applicable on this fork PR (default-setup emits no check-run); SAST coverage is Semgrep only, latest run success with 0 annotations.

@iamwhatever
iamwhatever merged commit 41dcadf into kirodotdev:main Sep 8, 2026
69 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 8, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…apshot (kirodotdev#8871)

_hash_path snapshots the host paths the measurement runtime may write under, and
its contract is explicit: links are "recorded by their target string (a flipped
symlink is a change) without following them (avoids escaping the snapshot
scope)".

The predicate was Path.is_symlink(), which is False for a Windows directory
junction, and both halves of that contract broke there:

* pathlib deliberately does NOT recurse into a symlink, but it DOES descend
  through a junction. So the walk hashed the link target's whole tree and the
  snapshot escaped its own root. Any unrelated write under that target -- by
  anything on the machine -- then read as a leak by the measured runtime and
  blocked the run.
* A junction was hashed as a plain directory (a "D" marker plus its relative
  name), so re-pointing one to another empty directory produced an IDENTICAL
  hash. A real host write the gate exists to catch passed as hermetic.

Route both the top-level and the per-child check through
platform_compat.is_link_or_junction, the shim-table row for this question, and
suppress the descendants rglob still yields under a link it has already recorded
by target. Sorting the walk by path string -- which the module already does for
determinism -- is what puts a link ahead of anything beneath it, so one pass is
enough.

readlink() resolves a junction on Windows, so the existing record-by-target
branch needed no other change.

Tests stage the plant with a local mirror of test/conftest.py::make_dir_link,
which calls _winapi.CreateJunction unconditionally on Windows. It is mirrored
rather than imported because only the test/ testpath gets that conftest, and it
is NOT platform_compat.symlink_or_junction: that tries os.symlink first, so a
runner with Developer Mode gets a symlink and the junction arm is never
exercised -- silently, while still reporting green.

Both behavioural tests fail on origin/main: the outside write blocks
("assert True is False") and the re-pointed link does not block
("assert False is True").

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.

3 participants