Skip to content

fix: backport #27535 and #32804 to 0.12.1 (keep an unreadable agent spec) - #32758

Merged
buluoray merged 2 commits into
release/0.12.0from
crew/slack/0.12.1-batch-50
Nov 8, 2026
Merged

buluoray merged 2 commits into
release/0.12.0from
crew/slack/0.12.1-batch-50

Conversation

@buluoray

@buluoray buluoray commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bring #27535 (a rebuild that cannot read an existing kirocrew.json keeps the user's spec instead of writing defaults over it) from main onto release/0.12.0, with its main follow-up #32804, one commit each, in a PR of their own.

Size and risk: +2364/-376 across 25 files. Production code is 10 files: src/kiro_crew/agent_parts/spec_rebuild.py is split into a new spec_siblings.py (+467, moved code) and a new spec_unreadable.py (+179); spec_upgrades.py, agent.py, agent_parts/__init__.py, agent_materialization/mcp_aliases.py, cli_setup.py, dashboard/handlers/_shared_config_followups.py and dashboard/server_runtime/config_watch.py change by 10-43 lines each. 1,458 of the added lines are tests (1,115 in the new test_agent_unreadable_main_spec.py). Behavior change: when a present agent spec cannot be read (EACCES, EIO, a Windows sharing violation after retry), the rebuild keeps the file, skips that cycle and logs it, instead of treating it as missing and writing defaults. A missing file or invalid JSON is handled as today. Rollback: revert this one PR.

Why it matters

Ray picked it for 0.12.1 (11-07). Reported by jeeshofone on the main PR. On 0.12.0 a valid spec whose read fails for a moment is rewritten with defaults, which silently and permanently erases its MCP servers, approvals, model pin and prompt (1 in 39 rebuilds in #15515's harness).

The faulty line is on release/0.12.0 @ 7ea28ed960: src/kiro_crew/agent_parts/spec_upgrades.py:83 except (OSError, ValueError): returns build_agent_config(...) as a fresh install for a read error as well as for corrupt JSON.

Not a goal

  • No fix that is not already merged on main; nothing is changed only here.
  • No version bump, no tag, no CHANGELOG.md change.

What changed (motivation → approach → change)

Main squash commit 4883d3b5bf was cherry-picked with -x onto release/0.12.0 @ 7ea28ed960 as 67f9a5639f, with no prerequisite. The docs/system-specs/modules/governance.md update ships with it.

One hunk is hand-resolved. Git applied the pick without a conflict, but release already carries #31620's mcp_dropped_servers.record_rebuild_drops(...) block right after write_default_spec(...) in agent_parts/spec_rebuild.py, and git left that block after the pick's new early return _skip_unreadable_main_spec(...), where it could never run. The block is moved into the try, right after write_default_spec(...), so the region from unreadable: _AgentSpecUnreadable | None = None to logger.info("Installed agent config: ...") is byte-identical to origin/main. test_mcp_dropped_servers.py fails 2 of 6 without the move and passes 6 of 6 with it. Every other file has added and removed lines identical to the main commit.

The hand-resolved commit is authored with the public identity and names its original author (Will Laws) in the message.

#32804 (217b3350c3, release commit d134ab390b) is the main fix for the finding Opus 5.5 raised on this PR's earlier head (agent_parts/spec_unreadable.py:152): when the main spec and a sibling spec are both unreadable, the skip never recorded its generation, so a pending default-model change re-ran the whole sibling pass on every 2 s config-watcher tick. It picked cleanly and is identical to main (+173/-23, 6 files, 126 of them in test_agent_unreadable_main_spec.py).

After the pick no touched code file is over the line cap (agent.py 1,674, spec_rebuild.py 1,282).

builder-security checked: dashboard/server_runtime/config_watch.py and _shared_config_followups.py only handle the new "unreadable, skipped" result of a rebuild; no bind, listener, route, auth mechanism or storage grant changes.

Backwards compatibility

Compatible: a missing or corrupt spec is rebuilt as before; only a present-but-unreadable spec now survives.

Removes nothing: no setting, key or caller is removed.

Tests

Proof: not provable -- other: a backport of a main commit whose proof ran on its own PR

  • CI does not run the backend suite on PRs into release/*, so the related set was run here: every touched test file (including test/integration/test_boot_smoke.py) plus every test file that imports a touched module, 123 files including test_mcp_dropped_servers.py, -n 4 --dist loadgroup. 5021 passed, 26 skipped, 1 failed: test_acp_harness_contract.py::test_a_missing_self_served_binary_names_its_install_command[copilot], which fails the same way on a clean release/0.12.0. The PR's own test_agent_unreadable_main_spec.py and test_agent_spec_hold_ratchet.py pass.
  • With fix(agent): stop a held sibling pass rewriting specs every tick #32804 on top: every file it touches, every test file that imports a touched module, plus test_agent_unreadable_main_spec.py and test_mcp_dropped_servers.py, 111 files, 4792 passed, 9 skipped, 1 failed (the same test_acp_harness_contract.py::...[copilot] release failure).
  • flake8 passes on the changed Python files.

Manual verification

N/A - verified on its own main PR. The 0.12.1 RC soak is the end-to-end check.

Screenshots / video

N/A - no frontend file changes.

Related Issues

Backport to the 0.12 line for 0.12.1 of #27535 and #32804.

Sibling sweep

Siblings: none -- the source PR carried its own sibling sweep; this PR only carries that fix.

Pattern harvest

Not generalizable: this PR only carries a fix already on main. The source PR has its own harvest.

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.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 7, 2026 23:13
@buluoray
buluoray requested review from tim-finnigan and removed request for a team November 7, 2026 23:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check: the change is backend-only. The only new text people see is one CLI line, and it says what happened and what to do next.

Notes

  • cli_setup.py: in "Agent config left unchanged: {agent_path} (see the log for why it was not rewritten)", replace "the log" with the actual log file path, so the user knows where to look.
  • The three attached screenshots show a "PPTX Maker" app page, which this diff does not touch. Remove them from this PR's description.

[UX-REVIEWED] d134ab3

Description read

[DESCRIPTION-READ] d02cf43f7b721db85169d4ee521c39b7926a10302627489f96fd6fcaec96d85f

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: this is a clean backport of two fixes already merged on main. A present spec that cannot be read is now kept and the rebuild cycle is skipped, which is the safer direction, and the only conflict was hand-resolved to match main byte for byte.

Notes

  • Once a spec stays unreadable (a permission change, for example), every rebuild skips it and it never self-heals. Make sure the 0.12.1 release notes or the soak checklist tell operators about the new "could not be read" RuntimeError text from config_watch, so a stuck model pin gets looked into rather than ignored.

[DESIGN-REVIEWED] d134ab3

Description read

[DESCRIPTION-READ] 0bd532610aacee70beaec5ab5092bd4445f4458305b29a9e3039ea961370af81

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d134ab390b323284307e491bf8572ce8193673bf — 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

This is a backport of two fixes already merged on main. Every item traces to the reported default-overwrite defect, and the Goal requires the code to be byte-identical to main.

What this change ships

Inventory (10 items) — 10 justified

Intent: stop a 0.12.x rebuild from writing defaults over a valid kirocrew.json that briefly fails to read (this is a FIX).

  1. A present but unreadable kirocrew.json is kept, the cycle is skipped and logged, and defaults are no longer written over it — justified
  2. During a skip, the heartbeat and worker specs drop only the grants the ceiling no longer allows, and nothing is re-derived — justified
  3. Sibling-spec passes during a skip run again only when the generation moves, or after 30 min or the hourly wake — justified
  4. kirocrew setup prints "Agent config left unchanged" instead of "installed" when nothing was written — justified
  5. The config watcher and dashboard report a model change as not landed while the spec is unreadable — justified
  6. The tool-alias reconcile treats an unreadable spec as present and refuses to write over it — justified
  7. One warning per path and errno, plus one INFO line when the spec is written again — justified
  8. spec_rebuild.py is split into spec_siblings.py (moved code, under the line cap) — justified
  9. The record_rebuild_drops block is moved back inside the try, so it runs again — justified
  10. The governance.md rebuild section describes the unreadable-spec case — justified

[FIRST-PRINCIPLES-REVIEWED] d134ab3

Description read

[DESCRIPTION-READ] 62ddb4a95b61b644b55d1125b56c42142a0a22f9b26e0651d51f0b29f5bd71e3

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d134ab3

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

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

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on d134ab390b323284307e491bf8572ce8193673bf; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/agent_parts/spec_unreadable.py:166 -- Invalidate the sibling cache when configuration changes

if first_skip or generation != _main_spec_skip_generation or held_retry_due:
Trigger: While kirocrew.json remains unreadable, a sibling pass completes without holds. The operator then changes agent.role_models.background; _apply_background_model calls rebuild_agent_config, which reaches this condition with unchanged governance generation and skips the sibling installers.
Outcome: kirocrew-lite.json retains its previous model although the applier reports “background agent specs rebuilt.” New optimizer sessions resolve that stale pin and use the previous model. Hourly maintenance also skips the sibling pass because _main_spec_held_pass_at is unset after a successful pass.
Anchor: defect
Fix: Invalidate the cached sibling pass when its configuration inputs change, including the background role model, while retaining suppression for identical retries.

[BLOCK-MERGE-DOWNGRADED] d134ab3
[GPT-REVIEWED] d134ab3

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 is downgraded: it no longer blocks the merge.

F1: Harm is LOW. The failure needs two things at once:

  • kirocrew.json exists but can't be read, which opens an episode (spec_unreadable.py:136-141).
  • The operator changes agent.role_models.background during that episode, and its applier calls rebuild_agent_config (config_watch.py:112-121). That rebuild skips the sibling pass because the governance generation hasn't moved (spec_unreadable.py:166), so kirocrew-lite (installed by _install_aim_capabilities, spec_siblings.py:98) keeps its old model.

Recovery: while the episode is open, _spec_hold_open stays true, so the hourly retry_held_conductor_specs keeps rebuilding (spec_rebuild.py:374-385). The first rebuild that can read the file runs every installer and closes the episode (spec_unreadable.py:206-221). Until then a WARNING is already logged (spec_unreadable.py:142). The heartbeat spec is deliberately left stale during the episode too, so the stale lite model matches the episode's existing contract.

Remedy cost: the real fix makes the skip key track every config input the sibling installers read, not only the generation. That is a new invariant that every future installer input would have to keep, added to an episode cache that is already complex. That cost exceeds a stale cheap-model pin on a rare fault path that recovers by itself.

[ADJUDICATION] d134ab390b323284307e491bf8572ce8193673bf total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/agent_parts/spec_unreadable.py:166 reason=disproportionate-remedy
[GPT-ADJUDICATED] d134ab390b323284307e491bf8572ce8193673bf

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d134ab390b323284307e491bf8572ce8193673bf 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 Nov 7, 2026
…7535)

* fix(agent): keep an unreadable agent spec instead of resetting it

rebuild_agent_config read kirocrew.json with a plain read_text and treated
every OSError like a corrupt file, so a transient read failure on a present,
valid spec (a Windows sharing violation while another writer replaces it, a
permission or I/O error) rewrote the user's spec with defaults.

Every read of the main spec on the rebuild path goes through
read_bytes_with_retry, and only FileNotFoundError means absent. Any other
OSError raises _AgentSpecUnreadable, from the load or from the alias
reconcile inside the write lock (mcp_aliases._durable_tool_aliases reports
such a file as present). _skip_unreadable_main_spec then leaves
kirocrew.json and the heartbeat and worker specs mirrored from it untouched,
and still runs the steps that write other files (_install_sibling_specs), so
the fork refresh and conductor specs follow a moved ceiling. That sibling
pass runs on the first skip of an episode and again only when the governance
generation moves since the last pass that held no write. The skip is
reported as an unwritten, held rebuild, which the existing retry paths act
on, and kirocrew setup, the dashboard and the config watcher say the spec
was left unchanged.

Until a rebuild writes the spec again, require_fork_governance refuses the
main agent and its two mirrors, keyed on the spec FILE a start resolves to,
with the remedy in the message, one SEL denial per refusal and an early
retry at 5, 15 and 60 s (then every 60 s). Neither can run its projected
spec during the episode: a fresh kiro-cli that cannot read the file starts
its own default agent, and a running one keeps the copy it loaded, because
kiro-cli reloads a spec only when its content changes (probed on Linux,
kiro-cli 2.31 to 2.33).

While the episode is open every start is refused, another agent's
included, one SEL denial each, with no exemption for a project spec or a
view's source: a start with no prepared view, or on KAS, hands kiro-cli (or
Crew's own read by name) a bare name that cannot be pinned to a file, a rename
of the main agent after the last rebuild write cannot be learned from an
unreadable file, a link or a retarget can put the kept file under any name,
and kiro-cli keeps serving a spec it loaded after the file turns unreadable,
so a doubt refuses.

The native skill projection refuses a view read across an episode, whatever
file it was read from, and a launch on a view records its source: a session
open or switch on a view is refused while an episode is open. An app agent's
launch copy is checked as a bare name is, at its spawn and at every open and
switch on it. Every session/new and session/load on the shared runtime goes
through _send_session_open, and every set_mode frame on kiro-cli through
check_mode_frame; each is checked right before its send, since the frame
activates an agent the process already holds. create_session and
load_session also check before their setup, so a refused create takes no
start permit. A mid-session switch reads the modeId its send will carry
with the projection's pure lookup, so a refused switch writes one SEL
denial.

Once a rebuild closes the episode every start is admitted again, a view
built before it included, and no process is ended. Only a spec read before
the episode ended stays refused: a KAS payload read by name across it, or an
agent the projection read during it. refuse_unprojected_main_spec_start says
so in the message and in the SEL row's cause and remedy: a new start reads
it again. While an episode is open, a name other than the main spec's own
that is refused by name is told it is resolved by name and the unreadable
spec may declare it; a refused view is not.

The episode lives in its own agent_parts owner, spec_unreadable; the
rebuild's part stays in spec_rebuild, and the two classes owners may not
define stay on the agent facade.

A missing file, a read that returns invalid UTF-8 or JSON, and a clean
rebuild still write defaults.

Closes #15515

* fix(agent): drop the unreadable-spec start refusals per security sign-off

Per the maintainer's security sign-off on #27535, this PR no longer raises
security strictness. It keeps only the data-loss fix: an unreadable
kirocrew.json, and the worker and heartbeat specs mirrored from it, are
kept instead of being overwritten with defaults.

Dropped, with their tests:
- require_main_spec_projected in require_fork_governance
- require_main_spec_launch_bound and every caller (direct-client spawn and
  _send_request, shared-runtime spawn, _require_launch_bound_for_session_open,
  the KAS by-name read and the pre-send payload check)
- the set_mode checks in runtime_mode_activation.py and check_mode_frame
- the projection's main_spec_refused path
- the runtime_wire session/new and session/load ValueErrors
- the early-retry timer and its gateway start and shutdown hooks

The acp/ package and the gateway hooks are back to main. While the file
is unreadable, starts are decided as on main; a test pins that the open
episode changes no start decision. The skip stays a held rebuild, so the
hourly maintenance wake still rewrites the kept spec once it reads.

Main's enforcement of a tightened ceiling on the worker and heartbeat
specs is kept: while the main spec cannot be read, their existing
allowedTools and autoApprove are re-filtered through the current ceiling
in place (_refilter_kept_mirrors), with no server copied in and no grant
added. A re-filter that fails holds the memo. _install_sibling_specs and
the re-filter live in the new agent_parts/spec_siblings.py, which brings
spec_rebuild.py back under 1,600 lines.

(cherry picked from commit 4883d3b)

Original author: Will Laws (#27535). Hand-resolved for release: release already carries #31620's record_rebuild_drops block after write_default_spec, which git placed after the new early return. It is moved into the try, after write_default_spec, as on main.
@buluoray
buluoray force-pushed the crew/slack/0.12.1-batch-50 branch from 9fc59ce to 67f9a56 Compare November 7, 2026 23:52
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026
With kirocrew.json unreadable, the rebuild skips and runs the sibling
pass (service, conductor and fork specs) once per governance
generation. A pass that held a sibling write (a second unreadable spec,
a held conductor) never recorded its generation, so while a default
model change was pending the config watcher's 2-second retry re-ran the
whole pass on every tick, rewriting every sibling spec each time.

A held pass now records its generation and the time it ran, and runs
again under the same generation only after HELD_SIBLING_PASS_RETRY_SECS
(30 min), which the hourly maintenance wake always reaches. A pass that
raised, or a deferred boot refresh, still records nothing.

(cherry picked from commit 217b335)
@buluoray buluoray changed the title fix: backport #27535 to 0.12.1 (keep an unreadable agent spec) fix: backport #27535 and #32804 to 0.12.1 (keep an unreadable agent spec) Nov 8, 2026
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

Goal edited at the maintainer's request: #32804 (main fix for Opus 5.5's spec_unreadable.py:152 finding, merged as 217b335) is added after the #27535 pick. Head 67f9a56 -> d134ab3.

@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 Nov 8, 2026
@buluoray
buluoray merged commit f70a42b into release/0.12.0 Nov 8, 2026
26 of 35 checks passed
@buluoray
buluoray deleted the crew/slack/0.12.1-batch-50 branch November 8, 2026 04:34
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Nov 8, 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.

1 participant