Skip to content

fix(context): leave a hard-linked steering file out instead of refusing - #20628

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/windows-essential-steering-read
Oct 15, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/windows-essential-steering-read

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crew member starts even when one of its steering files is a hard link, instead of failing every session start.

A member whose package-installed template declares file://.kiro/steering/**/*.md fails at every session and subagent start with Essential source ...\.kiro\steering\<file>.md: missing, unreadable, or outside the admitted document root. The package manager places its steering by hard link and re-syncs it, so a manual fix comes undone within an hour. Reproduced on Windows with an isolated KIROCREW_HOME: one steering file with st_nlink == 2 refuses the whole start; a regular file beside it reads fine.

Why it matters

A member with this template cannot be used at all: every chat, subagent and cron turn it serves is refused before the model is called, and the user has no setting that fixes it.

Not a goal

  • Reading a hard-linked file. The st_nlink > 1 refusal in safe_read_file_bytes_nolink stays as it is.
  • Changing how a non-steering declared source, a link, a managed-state path or an out-of-root path is handled.
  • Changing what the package manager installs.

What changed (motivation → approach → change)

Steering file the read refuses Before After
hard link, non-link reparse point whole member start refused left out unread, named in a note
any other declared source refused refused

The message comes from member_essential_context._read() after the path screen and containment both pass: the no-follow descriptor read returned nothing because the inode has a second name. Symbolic links in the same steering trees are already left out and named (#17632, #19393); a hard link had no such path, so one file stopped the member.

In src/kiro_crew/member_essential_context.py, _read() raises a dedicated _UnreadableEssentialSourceError for exactly that case. A steering document (the implicit global or project steering scan, or a declared match with a steering path component, the same test main already uses for its inclusion frontmatter) refused this way is left out: the essentials snapshot names it in one essential-context#unreadable-skipped:<template> note (one label per template, so an owner and an execution template merge cleanly), and the KAS document reader and kiro_launch_documents skip it with a warning. The file is never opened through its second name. The spec in docs/system-specs/modules/memory-skills-hooks.md states the rule.

Backwards compatibility

Compatible: a start that succeeds today is unchanged; a start that was refused for a hard-linked steering file now succeeds without that file.

Removes nothing: no refusal of a read is lifted, no key or path is removed; only the consequence of one refusal for steering documents changes.

Tests

Six tests in test/test_member_essential_context.py:

  • a hard-linked file under the declared steering glob is named and not read, and the regular steering beside it loads;
  • an owner and an execution template that each leave out a different hard-linked file build one snapshot with both notes;
  • the same for the implicit global steering scan, in the snapshot and in kiro_launch_documents;
  • the KAS projected reader leaves it out;
  • a hard-linked declared non-steering source still refuses;
  • the note names each file once.

Five fail on the parent commit (four with the reported message, the note test because the helper is new); the non-steering refusal test passes on both, as it must. All six pass on this head. Determinism: the six ran 10 times in a row (10/10 green) and once in a shuffled order, green. They use os.link only, no timing or ordering.

Manual verification

On Windows with an isolated KIROCREW_HOME, a named workspace and the reported template shape, documents_for_member refused on the parent commit and returns the snapshot with the note on this head. Not run against a live gateway member chat.

Related Issues

Closes #20624

Refs #18722

Pattern harvest

Not generalizable: the essentials reader already turns each per-file refusal class it can name (link, missing, managed prefix) into a named skip for steering; this adds the last class the descriptor read can return, rather than a new pattern.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 15, 2026 05:22
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the Windows reparse-point path in safe_read_file_bytes_nolink returns None, not an OSError. Otherwise those files still refuse the start, and CI's os.link tests can't show it.

[DESIGN-REVIEWED] 90d5dc2

Description read

[DESCRIPTION-READ] 60a30db357a2cd3e38d0d59801f2c28e948337e0e11ed2a2e3402409b5bf0f0c

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

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd — 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.

First-Principles-Verdict: PASS

Check that kiro-cli itself loads the hard-linked steering on Windows. If it doesn't, the member starts without that vendor steering, and only a note and a warning say so.

What this change ships

Inventory (6 items) — 6 justified

Intent: let a crew member whose installer hard-links its steering files start its sessions instead of being refused every time. FIX.

  1. A hard-linked steering file under a declared steering glob is left out and named, so the start no longer fails — justified
  2. The same for the implicit global or project steering scan, in the snapshot and in kiro_launch_documents — justified
  3. The KAS projected document reader skips a hard-linked steering file with a warning — justified
  4. A new per-template essential-context#unreadable-skipped:<template> note names the files left out — justified
  5. A hard-linked non-steering declared source still refuses the turn — justified
  6. The spec paragraph in memory-skills-hooks.md states the rule — justified

[FIRST-PRINCIPLES-REVIEWED] 90d5dc2

Description read

[DESCRIPTION-READ] 071ea71ba0627f06714b499caef9a9f09044af3f84e27cf0d10b5d698f9f3eea

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 github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 90d5dc2

Verdict parsed from the review's SHA-scoped output markers for commit 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 90d5dc2

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 90d5dc2a64591d82a0b7d2d545c9863e2a1ce7cd: <one-sentence reason>

@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from b02dba5 to 37689af Compare October 15, 2026 05:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 15, 2026 05:35
@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from 37689af to b0dbfa7 Compare October 15, 2026 06:08
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • KAS projected reader drops a hard-linked steering file with only a warning

rebutted: leaving the file out of projected_resource_documents cannot strip steering from any harness.
Its only consumer is acp/runtime.py, which copies the result into handle.native_context_documents: the list of bodies the host already loads, so the envelope can skip resending them.
A file missing from that list is never deduplicated away; at worst the envelope keeps it. The envelope itself leaves the file out and names it in the essential-context#unreadable-skipped:<template> note.
KAS reads the declared file:// glob natively, so the hard-linked file still reaches a KAS session; before this PR that session did not start at all.
This is the same note-less shape the reader already uses for an in-project link (#19393).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Test fixture names under oss-fork-boundaries

fixed in b0dbfa7: the hard-link fixtures are renamed to neutral names (vendor-style.md, steering/vendor/rules.md); no vendor or package name remains in the diff.
The names carried no behavior: each test only needs a .md file under a steering tree whose inode has a second name.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/context_assembly/member.py (imports this module) since this head went green (83e97cd -> d95c24b); CI re-running.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • kiro-cli loading hard-linked steering on Windows is unverified

verified on Windows with kiro-cli 2.29.1: a project agent declaring file://.kiro/steering/**/*.md, whose only steering file was a hard link (fsutil hardlink list showed two names) holding a random codeword.
kiro-cli chat --no-interactive --agent <probe> answered with that exact codeword, so the host reads the file through the hard link.
A hard link is an ordinary directory entry, not a reparse point; only this reader's st_nlink > 1 check refuses it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Live gateway member chat on Windows not run

rebutted as disproportional: the reported refusal is raised inside documents_for_member, before any provider is contacted.
test_two_templates_leaving_out_different_hard_links_still_build and test_implicit_global_steering_names_a_hard_linked_file_instead_of_refusing drive the real ContextBuilder (_build_v2_essentials / build_message), the same entry a gateway member turn calls; they fail on the parent with the reported message.
These tests run on the Windows Backend Tests shards, which pass on this head.
The host side is checked separately: kiro-cli 2.29.1 on Windows loads a hard-linked declared steering file (codeword probe, see the first-principles disposition).
A full gateway boot adds provider auth and transport, which this diff does not touch.

@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 Oct 15, 2026
@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from b0dbfa7 to 6c381ba Compare October 15, 2026 06:49
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules (same directory as memory-skills-hooks.md) since this head went green (d95c24b -> de79f82); CI re-running.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 15, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) shard 6 fails on test_workflow_matrix_max_parallel[codeql.yml-analyze-], which also fails on a clean origin/main (5be771f): #20577 added codeql.yml after #20482's max-parallel rule. Tracked in #20698, fixed by #20699. This PR waits for that fix, then rebases. The AI review lanes on this head failed on the shared installation token's rate limit and will be re-run after the hourly reset.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 6c381ba.

The fix itself is small and keeps the no-follow refusal: a hard-linked steering file is left out and named instead of stopping the member. The new tests cover the reported shape.

To clear the hold:

  • CI on this head is not settled. Backend Tests (Windows) (6) is red on test_workflow_matrix_max_parallel[codeql.yml-analyze] (job), which looks unrelated to this diff. Five backend shards and CodeQL are still running. The AI lanes, Dependency License Gate, Publish readiness signal and Sensitive Change Review failed for infra reasons (Opus job). Re-run them so this SHA gets review evidence.
  • Reply to the Opus finding from b0dbfa7 (comment). The steering test uses absolute path.parts (#L1112), so a hard-linked non-steering file under any directory named steering is skipped instead of refused. Either test the root-relative parts or explain why that is acceptable.

— crew-pr-reviewer (r103)

@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from 1c13362 to 0dca4a9 Compare October 15, 2026 08:40
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Skip test should require a steering component and a real declared glob

fixed in 0dca4a9: the skip decision (snapshot add() and projected_resource_documents) now goes through _is_steering_below_root, which counts a steering component only in the path relative to its project or home root; a path under neither spelling of the root refuses.
A project that itself sits under a directory named steering no longer turns a declared non-steering source into steering: test_declared_non_steering_hard_link_refuses_in_a_project_under_steering[snapshot|projected] fails on 1c13362 and passes here.
test_project_steering_hard_link_is_still_left_out_in_a_project_under_steering pins that real steering in that project is still left out.
self-added: yes
mechanism: the skip keyed on absolute path parts instead of root-relative parts

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Does kiro-cli itself load a hard-linked steering file

verified, not assumed: on Windows with kiro-cli 2.29.1, a project agent declaring file://.kiro/steering/**/*.md whose only steering file was a hard link (two names per fsutil hardlink list) holding a random codeword.
kiro-cli chat --no-interactive --agent <probe> answered with that exact codeword, so the host loads the file through the hard link and the member does not run without it.
The in-band note only says the essentials snapshot does not carry the text; it does not tell the agent to ignore it.

@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from 0dca4a9 to 97eadb7 Compare October 15, 2026 09:26
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • _is_steering_below_root is a fifth way of deciding "is this steering"

fixed in 97eadb7: the absolute-path test at the declared-resource call site is replaced, not worked around. documents_for_member now passes steering=_is_steering_below_root(match, root) and add() only reads that flag; projected_resource_documents computes it once per path and uses it for both the skip and the inclusion frontmatter branch.
One classification per reader remains; the implicit scans keep steering=True (their paths are always <root>/.kiro/steering/...) and the pattern test in _resource_paths was already root-relative.
test_declared_non_steering_frontmatter_is_body_in_a_project_under_steering[snapshot|projected] fails on 0dca4a9 and passes here.
kiro_launch_documents keeps its "steering" in path.parts filter unchanged; that line predates this PR on main and is out of its goal.
self-added: yes
mechanism: a second steering test added beside the call-site test instead of replacing it

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A KAS-harness member may never be told a hard-linked steering file was skipped

rebutted: the agent is told through the essentials snapshot, not through projected_resource_documents.
A member session on any harness receives the V2 essentials envelope built by documents_for_member, and that reader appends the core essential-context#unreadable-skipped:<template> note naming the file.
projected_resource_documents is not a delivery path: its only caller (acp/runtime.py) stores the result in native_context_documents, the list of bodies the host already loads so the envelope can skip resending them. It has no note channel by design, the same as for an in-project link (#19393).
The host itself loads the hard-linked file (kiro-cli codeword probe, earlier disposition).

@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from 97eadb7 to f036c57 Compare October 15, 2026 09:41
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • On a non-Kiro harness a skipped hard-linked steering file is loaded by nothing

rebutted: that is the intended trade, the same one #17632 and #19393 made for linked steering. Before this PR such a member did not start at all on any harness.
The agent is told: the essentials envelope every member session receives carries the core essential-context#unreadable-skipped:<template> note naming the file, so it does not assume the contents.
The round-3 concern (a project under a directory named steering skips a refused non-steering source) is answered as out of goal: main already classifies such a document as steering for its frontmatter and launch documents; the skip inherits that one definition and still never reads the file. Re-scoping it changes non-steering handling, which ## Not a goal excludes.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Steering-classification change alters non-steering frontmatter (outside Not a goal); kiro_launch_documents still absolute

fixed in f036c57 by subtraction after the round-5 retrospective: _is_steering_below_root, its frontmatter use and the three project-under-steering tests are removed; the three touched files are byte-identical to 1c13362.
Every site, including kiro_launch_documents, uses main's single "steering" in ...parts test again, so non-steering frontmatter handling is identical to main and there is one classification, not two.
Retrospective: both mechanisms (rounds 3 and 4) were beyond the goal; removing them keeps every hard-linked steering file skipped and never reads a refused file.
self-added: yes
mechanism: below-root steering helper from rounds 3-4, removed

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Live Windows gateway member chat with a hard-linked steering file

rebutted as disproportional, as on b0dbfa7 and 6c381ba: the reported refusal is raised in documents_for_member before any provider is contacted, and the regression tests drive the real ContextBuilder entry a gateway member turn calls, on all eight Backend Tests (Windows) shards.
The host half is measured, not assumed: kiro-cli 2.29.1 on Windows loaded a hard-linked declared steering file (random-codeword probe).
A gateway boot adds provider auth and transport, which this diff does not touch; a maintainer may still ask for it before merging.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The skip covers every None from safe_read_file_bytes_nolink for steering, including a file that vanished or changed between walk and open

confirmed and intended, as answered on 6c381ba: _UnreadableEssentialSourceError is raised for any None after the path screen, containment and managed-state checks passed; the spec paragraph and the in-band note name a hard link, a non-link reparse point and a file that changed shape.
In each case no bytes exist to return, so nothing unscreened reaches the snapshot. A steering file that vanished mid-walk is left out and named, the same outcome as a declared literal that is absent (#18278).
A non-steering declared source, an oversized file and a non-UTF-8 file still refuse.

@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 Oct 15, 2026
A steering document that passes the path screen and containment but that
the no-follow descriptor read refuses (a hard link an installer placed, a
non-link reparse point) is left out unread and named in one
essential-context#unreadable-skipped note, so the member starts. The read
is unchanged and any other declared source it refuses still refuses.

Closes #20624
@bolichen97
bolichen97 force-pushed the fix/windows-essential-steering-read branch from f036c57 to 90d5dc2 Compare October 15, 2026 10:32
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules and src/kiro_crew (same directories, none of this PR's files) since this head went green (4cae548 -> dfc37de); CI re-running.

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

Copy link
Copy Markdown
Contributor Author
  • Windows reparse-point path in safe_read_file_bytes_nolink must return None, not raise OSError

verified: the open is try: fd = platform_compat.open_file_no_reparse(path, nonblocking=True) except OSError: return None in hook_runtime/safe_reads.py, and open_file_no_reparse reports a refused reparse point as OSError(ELOOP), so the caller sees None and _read raises _UnreadableEssentialSourceError.
Measured on Windows, not only in CI: a steering file given a non-link reparse tag (0xBEEF via FSCTL_SET_REPARSE_POINT, attrs 0x420) was refused by the open, safe_read_file_bytes_nolink returned None, and documents_for_member started the member with that file named in the unreadable-skipped note (it refused the start on the parent commit).
CI's os.link tests cover the hard-link case; the reparse case shares the same None branch.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Does kiro-cli itself load the hard-linked steering on Windows

verified on Windows with kiro-cli 2.29.1, as answered on b0dbfa7 and 0dca4a9: a project agent declaring file://.kiro/steering/**/*.md whose only steering file was a hard link (two names per fsutil hardlink list) holding a random codeword.
kiro-cli chat --no-interactive --agent <probe> answered with that exact codeword, so the host loads the file and the member does not start without that steering on kiro-cli.

@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 Oct 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved by a maintainer after reading the review lanes: every lane is clean on this head, and the automated triage held it only on a size, path, category or doc rule.

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.

A crew member refuses to start when a steering file is a hard link

4 participants