Skip to content

fix(context): skip linked steering in member snapshots instead of refusing - #17632

Merged
bolichen97 merged 1 commit into
mainfrom
fix/steering-symlink-skip-16672
Oct 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/steering-symlink-skip-16672

Conversation

@buluoray

@buluoray buluoray commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crew member starts normally when a file or folder under ~/.kiro/steering (or a project's .kiro/steering) is a symlink.

Every session start of a member with a member_id builds the V2 essentials snapshot. The implicit .kiro/steering/**/*.md walk in member_essential_context._matches raises linked document or directory on the first link it meets, so a user who keeps steering in a git repo and links it into ~/.kiro/steering cannot use the member at all. kiro-cli itself follows these links.

Why it matters

Linking steering from one versioned repo is an ordinary setup. Today it makes every member chat fail at session start with no workaround short of copying the files.

Not a goal

What changed (motivation → approach → change)

  • Symptom: member session start fails with Essential source …/.kiro/steering/…: linked document or directory.
  • Root cause: the implicit steering scan uses the same fail-closed walk as declared resources. Steering is read because it exists, not because a template names it, so it should sit on the same footing as the project-root AGENTS.md that fix(members): read member sources on a home reached through a symlink #16263 already handles.
  • Change: _matches takes an optional linked list. When given, a link the walk meets (a literal path component or a wildcard entry) is appended there and skipped: not read, not descended into. Only the implicit global and project steering scans in documents_for_member and kiro_launch_documents pass it. documents_for_member then adds one core essential-context#linked-skipped note naming the skipped links (up to 10, then a count), the same way the managed-prefix note works. The note says only that the snapshot does not carry the link and that the host may still load it natively; it does not tell the model to disregard the file. Only a link the glob could have used is named: a name matching the final component (*.md) or a directory. The directory probe follows the link, so the link is screened through validate_file_path first; a refused target (an untrusted UNC share on Windows) is named without being probed.

Signatures the walk refuses and what this change does to each:

  • Linked leaf file under .kiro/steering (implicit scan): skipped and named. This is the reported case.
  • Linked subdirectory under .kiro/steering (implicit scan): skipped and named, contents never listed.
  • Linked .kiro or .kiro/steering literal prefix (implicit scan): skipped and named.
  • Any link reached by a template's declared file:// glob: unchanged, still refuses.
  • Directory revisit check (first_linked_ancestor on a queued directory): unchanged. A skipped link is never queued, so it cannot reach this check.
  • A linked root ($HOME itself a symlink): unchanged, already admitted by _admitted_root.

Backwards compatibility

Compatible: the only behaviour change is that a session which used to refuse now starts with one extra in-band note. Nothing that works today changes.

Removes nothing: no reader, key, or document that loads today is dropped. The skipped links were never loaded before either, because the whole snapshot refused.

Tests

In test/test_member_essential_context.py:

  • test_linked_global_steering_file_is_named_instead_of_refusing_the_turn: a linked ~/.kiro/steering/context/style.md is left out unread, named in the linked-skipped note whose wording does not tell the model to disregard it, and a regular steering file beside it still loads.
  • test_linked_global_steering_directory_is_named_not_enumerated: a linked steering directory is named and its contents are not read.
  • test_linked_non_steering_entry_is_not_named: a linked README.txt under steering is not reported.
  • test_linked_steering_entry_is_screened_before_its_target_is_probed: a link whose target validate_file_path refuses (a Windows UNC target) is named without the link-following is_dir() probe.
  • test_kiro_launch_documents_leaves_a_linked_global_steering_file_out: the spawn-time native list (acp/harness/kiro.py resolve_spawn) no longer refuses.
  • test_declared_glob_still_refuses_a_linked_steering_file: the walk without linked still raises.

The first three fail on origin/main (0d885e6) with the reported error. Mutation check: removing the note, dropping linked=[] from kiro_launch_documents, or removing the name filter or the validate_file_path screen reddens the matching tests. Whole file: 219 passed, 2 skipped, run with PYTHONPATH set to this worktree's src. black and flake8 are clean on both files.

Manual verification

N/A: unit coverage drives the real ContextBuilder.build_message and kiro_launch_documents paths with real symlinks on Linux. Windows junctions and macOS go through the same is_link_or_junction call but were not run on those platforms (unverified).

Related Issues

Closes #16672

Related: #14007 (admit approved links by policy), #16263 (refused project AGENTS.md becomes an #omitted note).

Pattern harvest

Not generalizable: the implicit-versus-declared split is already the rule for AGENTS.md/SOUL.md. This applies that rule to the one implicit source that was still missing it.

Decision for the owner

The decision is whether a member whose implicit steering contains a symlink should start with that link skipped and named, or keep refusing until a steering.sources policy approves the target as #14007 proposes. This draft chooses skip-and-notice as the default, because steering is implicit like AGENTS.md and refusing every session is worse than a named omission, and it leaves #14007's opt-in admission free to land on top.

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 5652c89e6f1262ab8ac58b879cfe4eb7b3631c78 — 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: CONCERNS

The name filter (fnmatch / validate_file_path / entry.is_dir()) adds a link-following probe and a screen against it, only to keep non-.md links out of a note.

Not justified as shipped

  • Item 3 — oversized: the walk skips every link either way. The only thing the filter decides is whether the note names it. Of the clause fnmatch.fnmatchcase(entry.name, pieces[-1]) or validate_file_path(str(path)) is None or entry.is_dir(), the last two terms exist only because is_dir() follows the link, which creates the UNC-probe risk the screen then guards against.
    Subtraction: delete the filter, the validate_file_path screen and the is_dir() probe, and append every link the wildcard walk meets. This also deletes test_linked_non_steering_entry_is_not_named, test_linked_steering_entry_is_screened_before_its_target_is_probed and _wrap_scandir.
    Clears when: the filter is removed, or a reported case shows a non-steering link in the note confusing an agent.

What this change ships

Inventory (5 items) — 4 justified

Intent: a crew member whose .kiro/steering contains symlinks still starts a session. This is a FIX (#16672, and tests that fail on base).

  1. A member with linked global or project steering starts instead of refusing at session start — justified
  2. A new in-band note, essential-context#linked-skipped, names the skipped links — justified
  3. A linked *.md file or a linked directory is named, but other links are not; the target is screened and probed — oversized
  4. The spawn-time native list (kiro_launch_documents) no longer refuses a linked steering file — justified
  5. A template's declared file:// glob that reaches a link still refuses — justified

[FIRST-PRINCIPLES-REVIEWED] 5652c89

Description read

[DESCRIPTION-READ] c3d4870c4ab771b1d249fcd99fda7af5dd8113b6caed19e106841129462c4713

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 commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

A maintainer still has to settle the "Decision for the owner": should a symlink in implicit steering be skipped with a note by default, or keep refusing until #14007's steering.sources approves it?

[DESIGN-REVIEWED] 5652c89

Description read

[DESCRIPTION-READ] 27e3ccda5cdaeaee6e775035f742971d806cb25909502f1908d9447aeef09c1a

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

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 5652c89e6f1262ab8ac58b879cfe4eb7b3631c78 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5652c89

Verdict parsed from the review's SHA-scoped output markers for commit 5652c89e6f1262ab8ac58b879cfe4eb7b3631c78.

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

@buluoray
buluoray force-pushed the fix/steering-symlink-skip-16672 branch from 1223d69 to 8fe986a Compare October 7, 2026 08:00
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Dispositions for the review round on 1223d69662 (fixed in 8fe986afad):

  • Comment History Gate (red): fixed. The two (#16672) docstring references were removed.
  • Design Review CONCERNS, note contradicts what kiro-cli loads: fixed. The note now reads "LINKED STEERING NOT IN THIS SNAPSHOT … The host may still load linked steering natively, so its text can appear elsewhere in your context; this note only says the snapshot does not carry it." It no longer says "Do not assume" or asks the user to restructure. test_linked_global_steering_file_is_named_instead_of_refusing_the_turn pins the wording.
  • Opus advisory, non-steering links reported: fixed. A link is named only when its name matches the glob's final component or it is a directory. test_linked_non_steering_entry_is_not_named covers it and reddens when the filter is removed. The literal-prefix case (a linked .kiro or .kiro/steering) is still named, and the note now says "on the steering scan path" rather than "under .kiro/steering", so the wording is accurate there too.

@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 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 5652c89e6f1262ab8ac58b879cfe4eb7b3631c78 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5652c89

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

@buluoray
buluoray force-pushed the fix/steering-symlink-skip-16672 branch from 8fe986a to c9913b1 Compare October 7, 2026 08:20
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

GPT 6.1 BLOCKING (security-class, 8fe986afad, member_essential_context.py:429): fixed in c9913b185c, not overridden. The link-following entry.is_dir() probe now runs only after validate_file_path(str(path)) admits the link. That function screens Windows link targets and refuses untrusted UNC shapes before any resolution. A refused target is named in the note without being probed. test_linked_steering_entry_is_screened_before_its_target_is_probed spies on following is_dir() calls and fails when the screen is removed. The real UNC path is unverified on this Linux host.

@buluoray
buluoray force-pushed the fix/steering-symlink-skip-16672 branch from c9913b1 to 2fcd133 Compare October 7, 2026 08:37
@buluoray

buluoray commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor Author

First Principles CONCERNS on 2fcd13314d (advisory): kept as is, rebuttal below.

The note is item 3. The issue's own "Expected" asks for it: "a linked steering file that the snapshot reader refuses is left out of the snapshot and named in an in-band notice". It also satisfies the clearing condition the review names. On a harness that kiro-cli does not serve (member_inherits_default_resources / non-Kiro providers that receive the essentials envelope), linked steering reaches no context, and without the note the model has no signal that a user's always-steering exists. That is the case the Design Review on 1223d69662 already pointed out ("Non-Kiro harnesses don't have this problem, because the file really is absent there"). A logger.warning goes only to the gateway log, which the model never sees. Dropping the note in favour of a plain continue is the weaker alternative, and the owner can pick it.

@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 7, 2026
@buluoray
buluoray force-pushed the fix/steering-symlink-skip-16672 branch from 2fcd133 to 5652c89 Compare October 7, 2026 09:25
@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 7, 2026
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

First Principles CONCERNS on 5652c89e6f (the name filter): acknowledged, not pushed. The simplification it proposes is sound: name every link the wildcard walk meets and delete the fnmatch/validate_file_path/is_dir() clause and its two tests. That removes the link-following probe instead of guarding it. The filter exists only because the Opus advisory on 1223d69662 asked that a linked README.txt not be named. The fleet is under a GitHub API rate-limit hold that bars advisory-only pushes, so this head stays as is. The owner can take the subtraction before marking ready. It is a contained change: one clause and two tests.

@buluoray
buluoray marked this pull request as ready for review October 7, 2026 18:19
@buluoray
buluoray requested a review from a team as a code owner October 7, 2026 18:20
@buluoray
buluoray requested a review from dodgeblaster October 7, 2026 18:20
@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 7, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

This solves the real problem: one symlink under .kiro/steering used to make every member session fail at start. Now the implicit scan skips the link and names it in a note, and declared file:// globs still refuse. I checked that validate_file_path returns None on refusal, so a refused UNC target is named without the link-following is_dir() probe, and the tests pin that. I'm holding it because it relaxes a fail-closed link-traversal guard and carries an open "Decision for the owner" (skip-and-note now, or keep refusing until #14007). Its own fix round included a security-class GPT block about that probe. Before merging, consider the First Principles subtraction at member_essential_context.py:429: drop the fnmatch/validate_file_path/is_dir() filter so the probe disappears instead of being guarded. The author has already agreed to it.

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

Approving. Passing linked into _matches only from the implicit .kiro/steering/**/*.md scans leaves declared resources failing closed, and a skipped link is never read, so it cannot escape the root. validate_file_path runs before entry.is_dir(), so a refused target is named without probing, and _skipped_linked_note tells the agent the steering is missing instead of letting it assume. This matches the implicit AGENTS.md handling from #16263.

@bolichen97
bolichen97 merged commit 9a09e38 into main Oct 7, 2026
104 checks passed
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's session fails to start when a file under ~/.kiro/steering is a symlink

3 participants