Skip to content

fix(steering): list links outside the readable tree as linked, not shown - #25152

Merged
bolichen97 merged 1 commit into
mainfrom
fix/steering-linked-not-shown-14627
Oct 28, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/steering-linked-not-shown-14627

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The Steering tab lists every steering link a session can load, and marks a link whose target is outside the folders the dashboard may read as "linked, not shown" instead of hiding it.

A global steering file in ~/.kiro/steering/ that is a symlink into a checkout outside $HOME (for example /workplace/<user>/<repo>/...) is missing from Settings → Steering. kiro-cli still follows the link and loads the file into every session, so the tab says fewer files are in effect than really are.

Why it matters

Keeping a checkout outside $HOME is common (dev desktops use /workplace). On those hosts the tab under-reports the steering a session reads, and nothing says a file was dropped. That makes "why does the agent follow this rule?" hard to answer.

Not a goal

  • Reading, serving or naming the target of such a link. The dashboard still never opens a file outside its trust base.
  • An allowlist or opt-in policy for extra roots (the steering.sources direction in fix: admit approved global steering symlinks #14007).
  • Changing which links are readable today, or the write path (linked entries stay read-only).

What changed (motivation → approach → change)

Symptom → cause → change:

Before After
Link whose target is outside its trust base ($HOME for global, the steering root for workspace) dropped from the listing listed with readable: false, no target path, no size, no head metadata
Its detail pane — the link chip plus one sentence: "Linked, not shown. … Sessions can still load it." No body request is made, Edit and Delete are disabled
Its read (GET /api/steering/<key>) 404 404 (unchanged)
Sensitive, dangling or looping target, or a link to the base folder itself hidden hidden
Detail read refused for any file (e.g. 413 too large) "Loading…" forever the error is shown, with "Ask the agent" (view mode holds no draft)

The listing decides "outside" from the already-resolved path string (_target_outside in src/kiro_crew/dashboard/handlers/steering.py), so the target is never opened, read or named; the only thing the listing shows is that the target exists. Every other entry gains readable: true. The frontend (website/src/pages/overview/SteeringTab.tsx, website/src/types/index.capabilities.ts) skips the detail fetch and the mode chip for a not-shown entry. The new string is in all 13 locale catalogs under website/src/i18n/locales/. The steering spec (docs/system-specs/modules/steering-viewer.md) and the user doc (src/kiro_crew/docs/steering-and-hooks.md) describe the new state, and test/requires-real-symlinks.txt lists the renamed and new symlink tests.

Backwards compatibility

Compatible: the listing only gains entries and an optional readable field; an older tab ignores the field and an absent field reads as readable. No accepted request is refused and no key is renamed.

Removes nothing: the read and write paths refuse exactly what they refused on main, and every entry main listed is still listed with the same fields.

Tests

  • test/test_steering_api.py::TestLinkedEntries — an outside link (global and workspace) lists by name only with no target, size or body in the response; the listing never calls Path.stat or os.open on the target; the read endpoint still 404s; sensitive targets and a link to the base folder stay hidden; admissible links report readable: true.
  • website/src/test/SteeringTab.test.tsx — a not-shown entry renders the sentence, disables Edit/Delete, shows no body or mode chip and never calls the detail API; a refused detail read shows its error and the agent hand-off instead of "Loading…".

Proof: PROVEN test/test_steering_api.py::TestLinkedEntries::test_link_escaping_home_lists_by_name_only, test/test_steering_api.py::TestLinkedEntries::test_link_escaping_home_never_opens_or_stats_target, test/test_steering_api.py::TestLinkedEntries::test_workspace_link_to_project_file_outside_root_is_never_read, test/test_steering_api.py::TestLinkedEntries::test_workspace_link_escaping_project_lists_by_name_only (head 83c8d7954a0d)

The new frontend test fails on main (no readable handling) and passes here.

Manual verification

Ran this branch's dashboard on an isolated localhost gateway with a throwaway $HOME: a regular file, a link inside $HOME, and context/team-rules.md linking to a file outside $HOME whose body holds a marker string. Steering (3) listed all three; the outside link showed the "linked, not shown" sentence with Edit/Delete disabled, and the rendered page contained neither the marker string nor the target's folder name, on desktop and at 390 px. The first-run setup gate was answered "ready" in that browser only, because this host has no OS sandbox; the steering responses were real.

Screenshots / video

Desktop: the outside link is listed and selected, with the sentence in place of a body.

Steering tab, desktop, linked not shown

Phone width (390 px):

Steering tab, mobile, linked not shown

A refused detail read (a 324 KB file over the 256 KiB cap) now shows its error with the agent hand-off, instead of "Loading…":

Steering tab, refused read error

Related Issues

Closes #14627

Sibling sweep

Swept: git grep -n "steering_target_admissible|_link_trust_base" -- src/
Sibling: src/kiro_crew/context_assembly/agent_spec.py -- not affected -- the session loader keeps its own HOME gate; this PR changes only what the tab lists
Sibling: src/kiro_crew/dashboard/handlers/steering.py -- not affected -- its read path (resolve_steering_file) must keep refusing an outside target, which the tests pin

Pattern harvest

Not generalizable: a listing that silently dropped entries its own gate refused to read; the fix is specific to the steering tab's list-versus-read split.

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 28, 2026 05:35
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The listing now matches what kiro-cli actually loads. The read path still refuses links outside the readable tree, and the screenshots cover the new state.

Notes

  • _target_outside decides "outside" by comparing path strings. It does not run the full admission gate, so the listing and the read path could disagree again if steering_target_admissible ever changes. Pinning both behaviours in one test would catch that.

[DESIGN-REVIEWED] f439db4

Description read

[DESCRIPTION-READ] 28c22d4f12bad9c2e5f88200490c3bec5c9cd0d42d4abcc6b8044bb7660d979d

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 28, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f439db41f5fb1a05abef3c8385fa2b8c7dbf76c6 — 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, but the new "Sessions can still load it" sentence is only true for kiro-cli's own sessions. Kiro Crew's own steering loader still drops these links.

Notes

  • Item 1 — inherited: the premise is "kiro-cli still follows the link and loads the file into every session". Kiro Crew's own loader, _load_steering_resources, checks each file with steering_target_admissible(p.resolve()) at src/kiro_crew/context_assembly/agent_spec.py:118, and that check defaults to $HOME. So dashboard-chat sessions never inject an outside-$HOME target, while the tab now says they can. The root cause is that the listing and Kiro Crew's loader use different admission gates. This PR makes the listing follow a vendored tool's behaviour that nobody has verified, and leaves the loader's gate as it was. Subtraction: shrink the linked_not_shown sentence by deleting "Sessions can still load it."
  • Item 2 — inherited: the base spec says workspace has no loader of this repo's own ("kiro-cli reads that root itself"). Listing workspace links that point outside the steering root rests on the same unverified claim that kiro-cli follows them. Subtraction: limit the _unshown_link_entry branch to source == "user".

What this change ships

Inventory (6 items) — 3 justified

Intent: make Settings → Steering show every steering link a session loads, even when the link points outside the folders the dashboard may read — FIX.

  1. A global link that points outside $HOME now appears as "linked, not shown" — inherited, premise unverified against Kiro Crew's own loader
  2. A workspace link that points outside the steering root now appears by name only — inherited
  3. The detail pane shows one sentence instead of a body, Edit/Delete are disabled, and no body request is made — justified
  4. A not-shown entry has no inclusion-mode chip — justified
  5. Every other entry gains readable: true in the listing — justified
  6. A refused detail read (e.g. 413) now shows its error with "Ask the agent" instead of "Loading…" forever — rides along

[FIRST-PRINCIPLES-REVIEWED] f439db4

Description read

[DESCRIPTION-READ] c5be30948321940bf7d262229e1ba198840546c0d37b6f655c3aeb83d89d5746

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 28, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks. The blind reader understood the "Linked, not shown" sentence correctly, and the screenshots show every changed state: the not-shown link on desktop and at phone width, and the refused read.

Notes

  • The new error state shows the server's raw text, "file too large (324012 bytes; cap 262144)", and the blind reader asked for plain words. Map the 413 to something like "This file is over 256 KB, so it can't be shown here. Sessions still load it." That assumes the session loader does still load it.
  • The blind reader worried that "Ask the agent" in the error state "would change my file without asking me." Name the outcome, for example "Ask the agent to shorten this file", or state what the hand-off message will ask for.

[UX-REVIEWED] f439db4

Description read

[DESCRIPTION-READ] bcb5e167bf1dce02feb54a32a4991c15fc56fa50a89e76f9a6a61bfb5fc3d9ef

That sha256 names everything this verdict read: the PR description, plus the 6 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 28, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f439db4

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) October 28, 2026 05:39
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f439db4

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

@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 28, 2026
@bolichen97
bolichen97 force-pushed the fix/steering-linked-not-shown-14627 branch from 70cce23 to f439db4 Compare October 28, 2026 06:33
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=0e4cb0ae93b6 Detail-read error lacks an explicit hand-off decision

fixed in f439db4: the view-mode detail-read ErrorNotice now passes askAgent; the branch renders only when not editing, so no draft is at risk.
SteeringTab.test.tsx 'shows a refused read instead of loading forever' asserts the Ask the agent control inside the notice.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=745bca232229 ErrorNotice on the detail read failure has no hand-off decision

fixed in f439db4: the view-mode detail-read ErrorNotice now passes askAgent, as the finding proposed; the branch renders only when not editing.
SteeringTab.test.tsx 'shows a refused read instead of loading forever' asserts the Ask the agent control inside the notice.

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

Copy link
Copy Markdown
Contributor

HOLD (open maintainer decision) at f439db41f5fb1a05abef3c8385fa2b8c7dbf76c6.

The code is sound as far as I can tell: an outside-trust-base leaf link is listed by name only with readable: false, no target, size or front matter (

if _target_outside(resolved, link_base) and not is_sensitive_path(
,
def _unshown_link_entry(source: str, root: Path, entry: Path) -> dict[str, Any]:
), sensitive/dangling targets stay hidden, the read path (resolve_steering_file) is unchanged, and the tab skips the detail fetch for such an entry. All checks are green and all five AI lanes PASS; the earlier GPT/Opus askAgent findings are fixed in this head.

Why HOLD: #14627 is labelled needs-human, and the triage on it (#14627) leaves the choice between option A (list-but-don't-serve, what this PR does) and option B (an opt-in allowlist via #14007's steering.sources) to a maintainer, saying the issue stays open for that decision. This PR picks A and Closes #14627, which would also close the record of option B. What would clear it: a maintainer confirms option A is the chosen direction (or the PR switches to Part of #14627).

AI findings judged non-blocking

— crew-pr-reviewer (r133)

@bolichen97
bolichen97 merged commit 328cedb into main Oct 28, 2026
110 checks passed
@bolichen97
bolichen97 deleted the fix/steering-linked-not-shown-14627 branch October 28, 2026 17:04
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 28, 2026
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.

Steering tab hides symlinked steering files whose target is outside $HOME, though kiro-cli loads them

2 participants