Skip to content

fix(context): leave oversized steering out instead of aborting member startup - #22622

Merged
bolichen97 merged 1 commit into
mainfrom
fix/steering-oversize-22575
Oct 21, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/steering-oversize-22575

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: One steering file over the read cap no longer stops every crew member from starting, and any over-cap error names the file, its size and the cap in bytes.

A global steering file of 265,585 bytes under ~/.kiro/steering/ blocks every member that inherits global steering. Startup aborts before any tool runs ("Turn interrupted") with File exceeds 0 MB safety cap. The cap is 256,000 bytes, so 256000 // 1024² prints as 0. The read happens before inclusion: is parsed, so an auto or manual file aborts startup too.

Why it matters

Every member chat on the host is dead until the user finds and trims a file the error never names. Nothing in the message says which file, how big, or what the limit is.

Not a goal

  • Truncating an inclusion: always file to the cap. A file over 256,000 bytes cannot fit the 64,000-character essentials envelope whole anyway, and a cut prefix would present partial rules as complete.
  • Changing the cap, the essentials envelope size, or how kiro-cli loads steering natively.
  • Letting a declared non-steering source, AGENTS.md or SOUL.md over the cap through. They keep refusing.
  • The other "MB safety cap" messages: they use the 50 MB MAX_FILE_BYTES cap and print correctly.

What changed (motivation → approach → change)

Source over the 256,000-byte cap Before After
Global or project steering (any inclusion) startup aborts, 0 MB left out, named in a note, member starts
Steering under a declared steering glob aborts left out, named
kiro_launch_documents, projected_resource_documents abort skip with a warning
Declared non-steering file, AGENTS.md, SOUL.md aborts, 0 MB, no path still refuses, with path, size and cap

The symptom came from two gaps. FileTooLargeError is not an OSError or ValueError, so _read in member_essential_context.py let it escape with no file path. And safe_read_file_bytes_nolink in hook_runtime/safe_reads.py printed its cap in whole MB, which rounds a sub-MiB cap to 0.

FileTooLargeError in hooks.py gains an optional size, which the no-link read fills with the size it measured on the open descriptor. _read turns the error into _OversizedEssentialSourceError, a kind of the existing unreadable-source error, carrying that size. Steering already leaves an unreadable file out and names it, so an over-cap steering file takes that same path, with its own essential-context#oversized-skipped:<template> note that gives each file's size and the cap. The project-root guide reader re-raises it, so an over-cap AGENTS.md keeps failing as documented. The read error now says File is 265,585 bytes, over the 256,000-byte safety cap. The module spec in docs/system-specs/modules/memory-skills-hooks.md states the new rule.

Backwards compatibility

Compatible: the only behavior change turns an abort into a skip for steering; every source that refused before still refuses, with a clearer message, and no code reads the old message text. FileTooLargeError(...) without size still works; size is then None.

Removes nothing: no path, key, record or function is removed; an over-cap steering file was never loaded before either.

Tests

test/test_member_essential_context_oversized_steering.py (new):

  • Global steering over the cap, for no frontmatter and each of always, auto, manual, fileMatch: the member starts, the body is absent, the note and the warning name the file, its size and the cap, and 0 MB never appears.
  • Project steering and a declared steering glob: left out and named.
  • kiro_launch_documents and projected_resource_documents: skip the file, keep the rest.
  • A declared non-steering file and AGENTS.md over the cap: still refuse, with name, size and cap.
  • safe_read_file_bytes_nolink message: exact bytes text, and the error carries the measured size.
  • The note lists each file once, with the size the read measured.

Red on origin/main (File exceeds 0 MB safety cap), green with the fix. prove.py --base origin/main: PROVEN. Determinism: 5 serial repeats, reversed node order and -n 2 all pass.

Manual verification

N/A - unit coverage sufficient: the tests drive the real member message build on a temp home with a real 265,585-byte file, the reported shape.

Related Issues

Closes #22575

Pattern harvest

Rule candidate: review-prompt
Pattern: a size-cap message built with integer division into a larger unit (cap // (1024 * 1024)) prints 0 for a cap under one unit; print bytes.

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 21, 2026 00:34
@bolichen97
bolichen97 requested a review from CrysisDeu October 21, 2026 00:34
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/hook_runtime/safe_reads.py

  • src/kiro_crew/hooks.py

  • @KiroCrewCaptain: missing the ## Sensitive change review heading

How to clear this check:

  1. The PR author posts the template below as a PR comment, with
    every field filled (N/A needs a reason). Keep the
    Head commit line: it must name the current head SHA.
  2. The check turns green within a minute, with no push.
  3. A new push resets this check: post it again for the new head.

Only the author's comment counts this way. A reviewer can instead
paste the filled template into an "Approve" review on this head.
Merging still needs a reviewer's approval.

## Sensitive change review
- Head commit: 2efa70d3028c84d19f5d3fac62bcc9425091714c
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 2efa70d3028c84d19f5d3fac62bcc9425091714c 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 added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check one thing before merge: a skipped inclusion: always file still reaches the member through kiro-cli's own loading. The new note says so, but no test covers that path.

[DESIGN-REVIEWED] 2efa70d

Description read

[DESCRIPTION-READ] b94a1814238611ac154ca8d94b2596d69fb4afd38be110d10352bf1f9598da8a

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2efa70d3028c84d19f5d3fac62bcc9425091714c — 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 the spec sentence "an oversized or non-UTF-8 steering file still raises" is meant to be reversed; #22575 is the only evidence for reversing it.

What this change ships

Inventory (7 items) — 7 justified

Intent: one oversized steering file should stop blocking every crew member from starting, and the error should name the file, its size and the cap. FIX.

  1. Global or project steering over 256,000 bytes, in any inclusion mode, is now left out and the member starts instead of aborting — justified
  2. The snapshot carries a new essential-context#oversized-skipped note that names each such file with its size and the cap — justified
  3. The over-cap read error reads "File is N bytes, over the C-byte safety cap" instead of "0 MB" — justified
  4. FileTooLargeError gains an optional size, read by one consumer (member_essential_context._read) — justified
  5. kiro_launch_documents and projected_resource_documents skip an oversized steering file with a warning — justified
  6. An oversized AGENTS.md, SOUL.md or declared non-steering source still refuses, now naming its path, size and cap — justified
  7. The memory-skills-hooks.md spec now says oversized steering is skipped, reversing the old "still raises" sentence — justified

[FIRST-PRINCIPLES-REVIEWED] 2efa70d

Description read

[DESCRIPTION-READ] b34989fc72203eadae66ad2843ac635b2931cd25b2b467062b21616110de67ca

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 2efa70d

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

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

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2efa70d

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

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- 🟡 CONCERNS

Which legitimate operations does 2efa70d3028c84d19f5d3fac62bcc9425091714c newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: the reviewer's own judgement; no confirmed regression.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 7 classified, 0 newly refused, 7 still allowed.
  • ubuntu-latest (platform posix): 7 classified, 0 newly refused, 7 still allowed.
  • windows-latest (platform windows): 6 classified, 0 newly refused, 6 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: CONCERNS

TIGHTENING: The patch doesn't tighten anything in the shell deny composite. The only change to refusal behavior is in the essential-context reader's handling of oversized files, and that change mostly loosens it. _read now turns FileTooLargeError into _OversizedEssentialSourceError (except FileTooLargeError as exc: ... raise _OversizedEssentialSourceError(f"Essential source {path}: {exc}", size=exc.size)). A steering document over the 256,000-byte cap is now left out and named in an essential-context#oversized-skipped:<template> note. Before this patch it refused the whole turn. The one stricter path is _read_implicit_guide's new except _OversizedEssentialSourceError: raise. It keeps an over-cap AGENTS.md/SOUL.md refusing. Before the patch that refusal came as an uncaught FileTooLargeError, so the outcome is the same and only the exception type and message change (File is {size:,} bytes, over the {read_limit:,}-byte safety cap). The one threat it refuses is still loading an oversized source as a truncated prefix that looks complete. No new attack shape is named.

ADJUDICATED: 12 candidates, 0 confirmed newly-refused. This count comes from my submission, not from a verdict: the classifier runs after this review is captured. Since SHELL_DENY_TIERS, the sensitive-bash tier, the exfil shapes and the deny-rules catalog are untouched by the patch, I expect no shell row to flip.

PLATFORM COVERAGE: I wrote candidates for posix, windows and any. They are the shell operations a user runs after the new note or error: measuring, listing, reading and splitting steering files and AGENTS.md, plus running the new test module.

  • posix: ~/.kiro/steering, .kiro/steering/, wc/du/find/split/head.
  • windows: $env:USERPROFILE and %USERPROFILE%, drive-letter and \ paths, PowerShell Get-ChildItem/Get-Item/Get-Content, and py -m pytest with a backslash path.
  • any: python -m pytest on the new test file.

The Python change's only platform-specific code is the existing "steering" in path.parts check in projected_resource_documents. Path.parts splits correctly on both platforms, so no other spelling needs a row.

UNADJUDICATED: The changed guard is the essential-context source reader, which no shell command reaches. Its call paths:

  • documents_for_member → add(path, root, steering=...) → _read → safe_read_file_bytes_nolink(max_bytes=_MAX_SOURCE_BYTES, allow_truncate=False).
  • _read_implicit_guide for AGENTS.md/SOUL.md.
  • projected_resource_documents and kiro_launch_documents, which catch _UnreadableEssentialSourceError.

These are the inputs I would have submitted but cannot get a verdict for:

  1. A 255,999-byte global steering file with inclusion: always. It is just under the cap and must still load.
  2. A project AGENTS.md of exactly 256,000 bytes. It sits on the cap, and the inclusive/exclusive edge of read_limit decides it.
  3. A declared non-steering resource, such as file://docs/guide.md, over the cap. It is still meant to refuse. Because _OversizedEssentialSourceError subclasses _UnreadableEssentialSourceError, it is now caught at projected_resource_documents's except _UnreadableEssentialSourceError. It re-raises only because the path has no steering part. A declared file under some other directory named steering (for example docs/steering/big.md) would therefore be skipped rather than refused. That edge is in the loosening direction, not this lane's, and is recorded here only as an untested boundary.
  4. A Windows path C:\Users\dev\.kiro\steering\big.md reaching the same path.parts check.

Nothing could classify these, so this review can't report PASS for the reader guard.

[SCOPE-REVIEWED] 2efa70d

@bolichen97
bolichen97 enabled auto-merge (squash) October 21, 2026 01:05
@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 21, 2026
@bolichen97
bolichen97 force-pushed the fix/steering-oversize-22575 branch from 7c2fcd1 to 7f25ec8 Compare October 21, 2026 01:25
@bolichen97

bolichen97 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: size-controlled test fixture

  • span=2faa3406c95c Make the size-controlled fixture byte-exact on Windows

fixed in 7f25ec8: _write_oversized writes UTF-8 bytes with write_bytes, so Windows newline translation no longer adds bytes; the st_size == _SIZE assertion is unchanged.
Root cause matches the Windows shard 1 red (265586/265589 vs 265585).

@bolichen97

bolichen97 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Over-cap inclusion: always file that kiro-cli may still load natively vs "Do not assume their contents"

fixed in 7f25ec8: the oversized-skipped note now uses the same wording as the sibling unreadable-steering note: the host may still load the file natively, so its text can appear elsewhere in context; the note only says the snapshot does not carry it.
It still names each file with its size and the 256,000-byte cap and says the user can shorten or split it.

@bolichen97

bolichen97 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor Author
  • An over-cap inclusion: always steering file is now dropped with only a note, where before startup stopped

rebutted (intended, checked): dropping is the existing outcome for this file one step later. A file over 256,000 bytes is far over the 64,000-character essentials envelope, so _fit_member_guides_into_envelope would leave it out whole anyway; steering is a guide, never core.
Before, that file stopped every member on the host with "0 MB"; now the member starts and the in-band note plus a warning log name the file, its size and the cap.
Truncating instead was rejected: a cut prefix presents partial rules as complete. Declared sources, AGENTS.md and SOUL.md keep refusing.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: unmeasured-size branch in the oversized note

  • span=c49f3b29c5dc Item 6 - zero consumers: the note's unmeasured-size branch

fixed in e21a5cd: the None branch in _skipped_oversized_note and its test are deleted; the note always prints the size the read measured, and _OversizedEssentialSourceError.size is an int.
FileTooLargeError.size stays optional for its other raisers, so _read only builds the skip error when a size is present; a size-less error fails closed as a plain MemberEssentialContextError naming the path, never a skip and never an invented number.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A SOUL.md over the cap still aborts every member start

rebutted (deliberate): SOUL.md is the member's core, not a guide. Core is never left out: an over-budget core already refuses with its source named (test_an_over_budget_core_still_refuses_with_the_source_named on main), so leaving an over-cap SOUL.md out would load a member without its persona.
Steering is a guide the envelope already drops whole, which is why only steering degrades here. The refusal now names the file, its size and the cap in bytes, so the fix is clear to the user.

@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 21, 2026
@bolichen97
bolichen97 force-pushed the fix/steering-oversize-22575 branch from e21a5cd to 2efa70d Compare October 21, 2026 03:15
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The reversed spec pin "an oversized or non-UTF-8 steering file still raises"

checked: the sentence came in with e4eb1cb (#20628, leave a hard-linked steering file out), as the scope edge of that fix. Its body's Not a goal and review thread discuss only hard links and other descriptor refusals; no size rationale is recorded.
The fail-closed reason does not apply to size: nothing past the cap is read, and an over-cap steering file is already left out whole one step later by the 64,000-character envelope fit. Declared sources, AGENTS.md and SOUL.md keep the refusal; non-UTF-8 steering still raises.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Check by hand that a member starts under kiro-cli with the 265,585-byte steering file present

rebutted (out of goal, no change to kiro-cli's load): the abort in #22575 is Kiro Crew's own snapshot reader raising before kiro-cli is involved; this PR changes only that reader and touches nothing kiro-cli loads natively.
The tests drive the real member message build and kiro_launch_documents (the spawn-time path) on a temp home with a real 265,585-byte file. How kiro-cli itself treats a large native resource is its own limit, unchanged here; the note says the host may still load the file.

@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 21, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The reversed spec pin "an oversized or non-UTF-8 steering file still raises"

checked: the sentence came in with e4eb1cb (#20628, leave a hard-linked steering file out), as the scope edge of that fix. Its body's Not a goal and review thread discuss only hard links and other descriptor refusals; no size rationale is recorded.
The fail-closed reason does not apply to size: nothing past the cap is read, and an over-cap steering file is already left out whole one step later by the 64,000-character envelope fit. Declared sources, AGENTS.md and SOUL.md keep the refusal; non-UTF-8 steering still raises.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Check by hand that a member starts under kiro-cli with the 265,585-byte steering file present

rebutted (out of goal, no change to kiro-cli's load): the abort in #22575 is Kiro Crew's own snapshot reader raising before kiro-cli is involved; this PR changes only that reader and touches nothing kiro-cli loads natively.
The tests drive the real member message build and kiro_launch_documents (the spawn-time path) on a temp home with a real 265,585-byte file. How kiro-cli itself treats a large native resource is its own limit, unchanged here; the note says the host may still load the file.

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

Review lanes on the head are clean apart from the hold the triage cron named (a sensitive-path change without a reasoning template, or an author-overridden Design lane); the watch holder read the hold and approved it explicitly.

@bolichen97
bolichen97 merged commit 71a0a9f into main Oct 21, 2026
107 of 109 checks passed
@bolichen97
bolichen97 deleted the fix/steering-oversize-22575 branch October 21, 2026 04:41
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 21, 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.

Oversized global steering aborts crew-member startup with misleading 0 MB safety-cap error

2 participants