Skip to content

fix(agent): keep an unreadable agent spec instead of resetting it - #27535

Merged
bolichen97 merged 2 commits into
mainfrom
fix/15515-agent-spec-unreadable-skip
Nov 6, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/15515-agent-spec-unreadable-skip

Conversation

@jeeshofone

@jeeshofone jeeshofone commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Moved from #15546 (fork) to a branch on this repo so CI runs on the CodeBuild fleet, per CONTRIBUTING.md. Earlier review threads and dispositions are on #15546.

Scope narrowed per the security sign-off. @bolichen97's review decided that security strictness is not being increased, so the start refusals this PR used to add cannot land and the data-loss fix can. This head keeps only the data-loss fix. Every new refusal is dropped (listed under Backwards compatibility), and while the file is unreadable a start behaves as it does on main. Refusing starts during an unreadable-spec episode would need its own decision, separate from this fix.

Problem / Motivation

Goal: a rebuild that cannot read an existing kirocrew.json keeps the user's spec and skips that cycle instead of writing defaults over it.

_load_existing_config caught (OSError, ValueError) together, so a valid spec whose read failed (EACCES, EIO, a Windows sharing violation) was treated as missing and rewritten with defaults, erasing its MCP servers, approvals, model pin and prompt.

Why it matters

Silent, permanent loss of the user's agent config: 1 in 39 rebuilds in #15515's harness.

Not a goal

What changed (motivation → approach → change)

Part What it does
Keep the file Every rebuild read of the spec uses read_bytes_with_retry. Only FileNotFoundError means absent, and invalid UTF-8 or JSON still rebuilds from defaults. Any other OSError raises _AgentSpecUnreadable, from the load (_read_existing_spec) or from the alias reconcile inside the write lock (mcp_aliases._durable_tool_aliases reports such a file as present, never as missing). _skip_unreadable_main_spec then keeps kirocrew.json and the heartbeat and worker specs mirrored from it, and still runs the steps that write other files (_install_sibling_specs: service and conductor specs, fork refresh, hook repair).
Retry The skip is a held rebuild (_conductor_spec_held, plus an open episode read through _spec_hold_open), so the ceiling memo stays pending, the boot baseline stays unseeded and the hourly maintenance wake rebuilds once the file reads again. The retry's warning names the kept file and never suggests --clean.
Say so The skip reports wrote=False. kirocrew setup prints "Agent config left unchanged" instead of "Agent installed", and _shared_config_followups.py and config_watch.py name the unreadable spec as a cause of a rebuild that did not write.
Reset kirocrew setup --clean stays the explicit reset that writes over an unreadable file.

New owner agent_parts/spec_unreadable.py holds the skip and the episode's bookkeeping, composed onto the agent.py facade. rebuild_agent_config's sibling installs move into _install_sibling_specs so the skip can run them without the mirrors.

Backwards compatibility

No new refusal. require_fork_governance and the whole acp/ package are identical to main; while the file is unreadable a start is decided exactly as on main. Dropped from the earlier head, with their tests:

  • require_main_spec_projected inside require_fork_governance
  • require_main_spec_launch_bound and every caller: direct-client spawn and the _send_request checks for session/new, session/load, session/resume and set_mode, shared-runtime spawn, _require_launch_bound_for_session_open (create, load, the entitlement probe), the KAS by-name read and the pre-send payload check
  • the set_mode checks in runtime_mode_activation.py and check_mode_frame, including the "kept changing" refusal
  • the projection's main_spec_refused path and its ValueError
  • the ValueError for session/new and session/load on the generic runtime_wire send paths
  • the early-retry timer and its gateway start and shutdown hooks

Behaviour change: a present kirocrew.json whose read fails is no longer overwritten with defaults, and that rebuild reports no write. A missing or invalid spec still rebuilds from defaults. No error code or SEL event changes.

Writer sweep on 90ae232: _load_existing_config ← rebuild_agent_config (skips); _durable_tool_aliases ← default_spec_commit.write_default_spec and _reconcile_tool_aliases_from_disk (both raise on an unreadable spec, unless --clean); rebuild_agent_config_reporting ← retry_held_conductor_specs, _reproject_holding_the_lock, rebuild_agent_spec, config_watch (say left unchanged), endpoint_migration and the template-server request handler (already report not rewritten; MCP apply: #18679).

Tests

  • test_agent_unreadable_main_spec.py: the spec and its mirrors kept byte for byte (eacces, eio) while the sibling steps still run; a sharing violation retried before it counts; no migration over other specs on a skipped cycle; the next readable rebuild writes the user's fields; the sibling pass once per governance generation; the alias reader and the write-lock path; --clean and invalid UTF-8 still reset; warnings once per episode; overlapping rebuilds never close a newer episode or drop its hold.
  • Regression pin for main's behaviour: reading the unreadable spec as missing, as main does (_read_existing_spec returning None and _durable_tool_aliases returning (False, None) on an OSError), writes defaults over it and test_unreadable_existing_spec_is_kept_and_the_cycle_skipped goes red. Checked by running that mutation.
  • test_an_open_episode_changes_no_start_decision: require_fork_governance gives the main agent, its mirrors, another agent and an unknown name the same answer with the episode open as closed, on the same unreadable file. Mutation pin: refusing the main agent during the episode goes red. Checked by running that mutation.
  • test_agent_spec_hold_ratchet.py: _conductor_spec_held is read only through _spec_hold_open and the template-only probe.
  • test_cli_setup.py, test_conductor_allowed_tools_survive.py, test_agent_refactor_fork_refresh.py, test_agent_parts.py, test_governance_profile_reprojection.py, test_worker_agent.py, integration test_boot_smoke.py: the setup wording, the retry warning, the hold on the profile watch and ceiling hook, the facade, and the moved sibling installs.

Local: the changed test files, every test_agent*, test_acp* and test_native_skill* file, the error-code contract and ws event-scoping suites, test_slack_gateway.py and the code-review pool tests: 13,394 passed, 1 failed (test_launch_record_resources_match_the_alias_file_kiro_cli_loads, which fails the same way on a clean main on this host). Integration test_boot_smoke.py with KIROCREW_INTEGRATION=1: 17 passed. black, flake8, mypy and Semgrep (semgrep/) clean on the changed files; Semgrep's two hits are existing main lines.

Manual verification

N/A beyond the harness.

Pattern harvest

Rule candidate: review-prompt (AUTOSDE a-failed-read-is-not-a-corrupt-file)
Pattern: a reader that falls back to defaults on every read error; it must keep the file on "could not read it" and rebuild only on "read it, damaged".

Related Issues

Closes #15515
Related: #18679, #17792, #17882

Checklist

  • Tests added; existing tests pass; self-review, docs, no secrets

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@jeeshofone
jeeshofone requested review from a team and KiroCrewCaptain as code owners November 1, 2026 23:29
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 1, 2026
@github-actions

github-actions Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 08f2539c6eaaf54d319bc0496e83e3dcad367caa touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

The fix is at the cause: it splits "could not read" from "read it, damaged" at the one reader that fell back to defaults. Two bits of extra bookkeeping are noted below.

Notes

  • Item 6 — oversized: the description says "the config watcher retries a failed model change every tick", but it never measures what an extra skip costs. On that basis it adds _main_spec_skip_generation, a once-per-generation gate on the sibling pass, and _main_spec_warned, which warns once per errno. Subtraction: delete _main_spec_skip_generation and its branch in _skip_unreadable_main_spec, and run the sibling pass on every skip. Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 8 — undeclared: kirocrew setup now also prints "Agent config left unchanged" for a shared-home refusal, which is an older case unrelated to agent: a Windows sharing violation while rebuild_agent_config reads kirocrew.json rebuilds it from defaults and writes that back, erasing user edits #15515. The description names only the unreadable case. This is a rider with no premise risk.

What this change ships

Inventory (9 items) — 7 justified

Intent: a rebuild that cannot read an existing kirocrew.json keeps the user's agent spec instead of resetting it to defaults (#15515). FIX.

  1. A present spec that cannot be read is no longer overwritten with defaults, and that cycle is skipped — justified
  2. The alias reconcile inside the write lock treats an unreadable spec as present, so nothing is written over it — justified
  3. A Windows sharing violation is retried before the read counts as failed, using the existing read_bytes_with_retry — justified
  4. While the main spec cannot be read, the heartbeat and worker specs are re-filtered in place against the current governance ceiling — justified
  5. A skipped cycle stays held: the hourly maintenance wake retries it and the ceiling baseline stays unseeded — justified
  6. The sibling pass runs once per governance generation, warnings once per episode, and a revision counter handles overlapping rebuilds — oversized: dedup rests on an unmeasured cost
  7. The config-watcher and dashboard log/error text names the unreadable spec as a cause — justified
  8. kirocrew setup prints "Agent config left unchanged" when nothing was written — undeclared: also covers the shared-home refusal
  9. The sibling installs move into agent_parts/spec_siblings.py — justified

[FIRST-PRINCIPLES-REVIEWED] 08f2539

Description read

[DESCRIPTION-READ] 93e8a39535f68057435c684bc757e86b5848f333f76edaf8963d1ffa698db9b6

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the fix targets the root cause, treating a failed read as a missing file, and only FileNotFoundError now means absent. No start decision changes.

Notes

  • The skip path carries a lot of episode bookkeeping: a revision counter, a generation memo and per-errno warning keys. A plain skip with no sibling pass would be smaller. That trade-off only holds if re-filtering forks and conductor specs while kirocrew.json is unreadable is actually needed.
  • In default_spec_commit.write_default_spec, the --clean path passes an _UnreadableSpec sentinel into spec_fingerprint. The reset works only because a non-map value reads as no prior alias generation. That makes it an implicit contract worth pinning with a test.

[DESIGN-REVIEWED] 08f2539

Description read

[DESCRIPTION-READ] ab042e3bb9a8f978a62a4fc8dadf5846337d14907b62dd8b5fc0a10f55d540b9

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 08f2539

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

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

@github-actions

github-actions Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

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

GPT 6.1 flagged blocking issues on 08f2539c6eaaf54d319bc0496e83e3dcad367caa; 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:152 -- Do not cache a sibling pass whose fork refresh failed

if not sibling_held and refresh_forks != "defer":
with _main_spec_episode_lock:
_main_spec_skip_generation = generation
Trigger: During an unreadable-main-spec rebuild, an inline refresh encounters a transient read/write error on a corroborated fork. _refresh_forked_templates_locked records _fork_refresh_failed, but successful sibling installs and shared-template processing leave sibling_held=False, so this branch caches the generation.
Outcome: Once the fork recovers, subsequent rebuilds—including maintenance retries—skip its refresh while the main spec remains unreadable and governance is unchanged. require_fork_governance continues rejecting that fork’s sessions despite its restored access.
Anchor: defect
Fix: Record the sibling generation only when the inline fork refresh also leaves no failures.
Sites: none

[BLOCK-MERGE-DOWNGRADED] 08f2539
[GPT-REVIEWED] 08f2539

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

F1 — harm is LOW, and it fails safe. The failure needs two things to happen in the same skip pass. First, the main spec is unreadable and its sibling pass runs (spec_unreadable.py:141). Second, a fork read or write fails on that pass, which is recorded at fork_refresh.py:491; fork failures never set sibling_held (spec_siblings.py:364-370 only holds shared templates), so the generation is cached at spec_unreadable.py:152-154. The cost is visible and blocks rather than leaks: require_fork_governance refuses that fork's sessions with an error pointing at the gateway log (spec_rebuild.py:1083-1088), and the main spec being unreadable is already logged as a warning (spec_unreadable.py:125). Several things recover it: the operator fixing the main spec closes the episode (spec_unreadable.py:175) and the next readable rebuild refreshes the forks again (spec_siblings.py:363); a restart starts at _main_spec_unreadable = False (spec_unreadable.py:36), so the pass runs again; and stop-following triggers a refresh on its own (agent_capabilities.py:1533-1543). The real fix costs more than it looks: gating the memo on _fork_refresh_failed means any fork that keeps failing (a markdown or ambiguous fork, fork_refresh.py:412-432) re-runs the whole sibling pass on every config-watcher tick. Avoiding that needs new transient-versus-permanent failure state, all to serve one rare path that already fails closed.

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

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 08f2539c6eaaf54d319bc0496e83e3dcad367caa 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 1, 2026
@jeeshofone
jeeshofone force-pushed the fix/15515-agent-spec-unreadable-skip branch from ea0fd68 to d0a920b Compare November 2, 2026 01:11
@jeeshofone

jeeshofone commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

This applied to d0a920bab1 and is superseded on the current head.
GPT 6.1 disposition for d0a920bab1.

span=test/test_acp_healthy_host_session_open.py:170 F1 (real skill projections outlive temporary-directory teardown): fixed in d0a920bab1. Both test/test_acp_healthy_host_session_open.py and test/test_native_skill_projection_view_provenance.py now bind the shared autouse _end_projections_before_tmp_path_goes fixture from native_skill_projection_helpers, as the other native-projection modules do. It requests tmp_path and monkeypatch, so it tears down before both. It ends every projection started during the test, including those held by _drive's traceback cycle, while the test's patched paths are still in place, so the cleanup lock and side-file directories never land in a removed tree. The same leftover caused the New-test stability (ubuntu-latest) setup error on ea0fd687ef (FileExistsError/FileNotFoundError on the reused .../kiro/agents directory).

First-pass check: R1-R8 OK.

@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 Nov 2, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD for a human reviewer at d0a920b.

What holds it:

  1. Reserved governance change. During an unreadable-spec episode, the new agent_parts/spec_unreadable.py and its call sites in acp/ decide which agent starts, session opens and mode switches are admitted, and they write SEL denials. The user's rules reserve that for a human.
  2. Unfinished change request. cruisercohen's last change request on fix(agent): keep an unreadable agent spec instead of resetting it #15546 (review) was never followed by the re-review their 26 Oct comment promised. This PR moved the same commits here, so it should get that re-review.

One question from our r133 hold is still open. _governed_by_main_spec still admits a user agent whose own readable file declares its name. On kiro-cli, require_main_spec_launch_bound refuses every start afterwards, so the exemption admits nothing there. On KAS, set_mode runs only require_main_spec_projected, so that exemption is the whole check for a KAS mode switch during an episode. Please confirm that is intended. The description's "every start refused" row does not cover it.

I found no definite defect in the parts I read. The keep-the-spec fix is right. The GPT F1 fix matches its disposition. The three Design notes (rename-aside alternative, ship the small fix first, name the model-probe reader in Backwards compatibility) are advice and do not block. Checks are all green on this head.

To clear: cruisercohen or another maintainer re-reviews this head, answers the KAS question and approves the start gate.

— crew-pr-reviewer (r140)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 3, 2026
@jeeshofone
jeeshofone force-pushed the fix/15515-agent-spec-unreadable-skip branch from d0a920b to dcb541f Compare November 3, 2026 10:24
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 3, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 5, 2026
jeeshofone added a commit that referenced this pull request Nov 5, 2026
…-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.
@jeeshofone

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks, applied as written in c10f233. Point by point:

Keep

  • _AgentSpecUnreadable and _skip_unreadable_main_spec: kept. The unreadable kirocrew.json and its worker and heartbeat mirrors are left as they are, and the sibling steps that write other files still run.
  • --clean: still the explicit reset that writes over an unreadable file (test_a_clean_rebuild_still_resets_an_unreadable_spec).
  • The kirocrew setup wording: kept ("Agent config left unchanged" when nothing was written).

Drop

  • require_main_spec_projected inside require_fork_governance: removed. require_fork_governance is now identical to main's.
  • require_main_spec_launch_bound and every caller (direct-client spawn and _send_request for session/new, load, resume and set_mode, shared-runtime spawn, _require_launch_bound_for_session_open, the KAS by-name read and the pre-send payload check): removed. The whole acp/ package is back to main.
  • The set_mode checks in runtime_mode_activation.py and check_mode_frame, including "kept changing": removed with acp/.
  • The projection's main_spec_refused path and its ValueError: removed with acp/.
  • The runtime_wire session/new and session/load ValueErrors: removed with acp/.
  • The early-retry timer: removed, with its gateway start and shutdown hooks. The skip stays a held rebuild, so the existing hourly maintenance wake rewrites the kept spec once it reads.

While the file is unreadable, starts behave as on main. test_an_open_episode_changes_no_start_decision pins that: require_fork_governance gives the same answer with the episode open as closed, and refusing the main agent during the episode turns it red. test_unreadable_existing_spec_is_kept_and_the_cycle_skipped pins the fix itself: restoring main's read-as-missing behaviour writes defaults over the file and turns it red. I ran both mutations.

Test notes

  • Tests that varied file or link state while the gate refused unconditionally (including test_no_read_error_on_the_main_spec_admits_a_bare_name) are gone with the refusals. The parametrized tests that remain vary the read error (EACCES, EIO) or where an overlapping skip lands, and each case is asserted on its own outcome.
  • The "admitted" docstrings were in test_agent_unreadable_main_spec_gate.py and test_native_skill_projection_view_provenance.py, which are deleted, so none remain.

The PR description is updated to the narrowed scope.

@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 5, 2026
jeeshofone added a commit that referenced this pull request Nov 5, 2026
…-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.
@jeeshofone
jeeshofone force-pushed the fix/15515-agent-spec-unreadable-skip branch from c10f233 to c37ccee Compare November 5, 2026 03:12
@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 5, 2026

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

Re-reviewed at c37ccee. Thank you: the start refusals, the launch bound, the set_mode gates and the early-retry timer are all gone, as asked, and keeping the unreadable kirocrew.json instead of overwriting it is exactly the part we wanted. No regex is added.

Requesting changes for one gap, which the Opus lane also found. When _read_existing_spec raises _AgentSpecUnreadable, _install_sibling_specs(..., mirror_main=False) now skips _install_heartbeat_agent and worker_agent._install_worker_agent entirely. On main, those two specs are rebuilt on every rebuild and their allowedTools / autoApprove are filtered through the governance ceiling. So if an administrator tightens the ceiling while the main spec is unreadable, kirocrew-worker.json and the heartbeat spec keep the grants of the old ceiling. kiro-cli auto-approves those tools before the PreToolUse gate sees them.

This is not a request for more strictness. It asks the PR to keep main's current enforcement. The PR's goal is to stop overwriting the user's spec, not to let a tightened ceiling be skipped.

Requested:

  • While the main spec is unreadable, still filter the existing worker and heartbeat grants through the current ceiling, in place: read each spec, drop what the ceiling no longer allows from allowedTools / autoApprove, and write it back.
  • Do not copy the main spec's servers into them, since that would need the unreadable file.
  • Do not add a start refusal for this.
  • Add a test: open an unreadable-spec episode, tighten the ceiling, run a rebuild, and assert the worker and heartbeat specs no longer carry the removed grants while kirocrew.json stays byte-identical.

Separately, and non-blocking: agent_parts/spec_rebuild.py is now 1,610 lines, past the 1,600-line target.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks, applied in 6e27db2. Point by point:

  • Filter the existing worker and heartbeat grants through the current ceiling, in place. Done. While kirocrew.json cannot be read, _install_sibling_specs(..., mirror_main=False) now calls _refilter_kept_mirrors() where the two installers would run. It reads kirocrew-worker.json and the heartbeat spec, filters allowedTools through the ceiling (_apply_allowed_tools_ceiling) and drops every server's ungoverned autoApprove (_strip_ungoverned_auto_approve). These are the same two passes the installers run. It writes the spec back only when something was removed, under the locks the installers take. A worker spec with a KAS permissions block gets it derived again from the filtered list.
  • Do not copy the main spec's servers in. Nothing is added. The server map and every grant the ceiling still allows stay as they are. A worker file another writer owns is skipped, as its installer skips it.
  • No start refusal. None added. acp/ is still identical to main.
  • The test. test_a_tightened_ceiling_reaches_the_kept_mirrors_in_place opens an unreadable-spec episode, tightens the ceiling, and runs a rebuild. It asserts the withheld grants are gone from both specs, an allowed grant stays, no server was added, and kirocrew.json is byte-identical. Removing the re-filter call makes it fail.
  • A failed re-filter. It counts as a hold, so the governance generation is not recorded and the next rebuild retries (test_a_mirror_re_filter_that_fails_keeps_the_sibling_pass_owed, which also fails without the fix).
  • spec_rebuild.py size. _install_sibling_specs and the re-filter moved to a new owner, agent_parts/spec_siblings.py, so spec_rebuild.py is now 1,263 lines.

The branch is also rebased onto current main.

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

Re-reviewed at be0d3d5. Thank you: _refilter_kept_mirrors() does what I asked. It filters the kept worker and heartbeat specs through the current ceiling in place, adds no server and no start refusal, and adds no regex. That part is ready.

One CI failure this PR causes blocks the approval: test/test_ledger_conductor_agent.py::test_the_boot_installer_writes_this_spec fails on Linux and Windows shard 6. The test reads agent_parts/spec_rebuild.py and asserts it contains _install_ledger_conductor_agent(clean=clean), but this PR moves that call into agent_parts/spec_siblings.py. Please point the test at the file that now holds the call (or at both), so it still proves the boot installer writes the spec. Coverage Gate and PR Readiness are red only because of that shard. Once it is green I will approve.

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

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks. Fixed in 8892423.

test_the_boot_installer_writes_this_spec now checks both files, so it still proves the boot rebuild writes the ledger-conductor spec:

  • agent_parts/spec_rebuild.py must call _install_sibling_specs(refresh_forks, gated_off, clean=clean), so the rebuild still runs the sibling installs.
  • agent_parts/spec_siblings.py must contain _install_ledger_conductor_agent(clean=clean), so the sibling installs still write the spec.

Both assertions are exact string checks, as strict as the original one. That test was the only failure in shard 6 on Linux and Windows. I ran the whole of shard 6 locally with the CI sharding plugin: the ledger test passes, and the 4 other failures also fail on a clean main on my machine. The branch is rebased onto current main.

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

Re-reviewed at 8892423. Thank you: the only change since be0d3d5 is the test fix. test_the_boot_installer_writes_this_spec now checks that the rebuild calls _install_sibling_specs(...) and that spec_siblings.py holds _install_ledger_conductor_agent(clean=clean), which still proves the boot installer writes the spec.

The First Principles lane now blocks this head, and I agree with it: _refilter_kept_mirrors calls _apply_allowed_tools_ceiling and _strip_ungoverned_auto_approve by hand, which is the same pass pair fork_refresh._apply_governance_passes already owns. If a pass is later added there, the kept mirrors would miss it. Please call fork_refresh._apply_governance_passes(...) in place of the two calls, keeping the derived permissions step and the write-only-on-change check as they are. This changes no behavior today; it keeps one copy of the filter.

The other CI jobs on this head are still running. Once the lane passes and CI is green I will approve.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks. Done in 49c4b7f.

_refilter_kept_mirrors now calls fork_refresh._apply_governance_passes(governed, source="_refilter_kept_mirrors") in place of the hand-written _apply_allowed_tools_ceiling and _strip_ungoverned_auto_approve calls, so there is one copy of the filter and a pass added there reaches the kept mirrors too. The derived permissions step and the write-only-on-change check are unchanged, and the audit stays on as before. No behaviour change: the related suites pass (809 tests, the two re-filter tests included).

@bolichen97

Copy link
Copy Markdown
Contributor

Thank you for the update at 49c4b7f. The code fix looks right: _refilter_kept_mirrors now calls fork_refresh._apply_governance_passes, and nothing else changed. I will approve once CI runs.

CI never started on this head, though: only the PR Readiness group shows up, and the test, lint and review jobs never appeared. The push event was likely lost in a GitHub outage. Could you push an empty commit to start it? For example: git commit --allow-empty -m "ci: retrigger".

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

Copy link
Copy Markdown
Contributor Author

@bolichen97 CI never started on 49c4b7f, so I pushed 08f2539 to retrigger it. It is the same tree with only the commit date changed (git diff 49c4b7fceb 08f2539c6e is empty). I re-dated the head instead of adding an empty commit because PR Hygiene allows at most two commits per PR. Checks are now running on 08f2539.

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

Reviewed at 08f2539. Thank you: CI ran on this head, and every PR-own line is the same as 49c4b7f, which I read before. The unreadable kirocrew.json is kept instead of overwritten, the kept worker and heartbeat specs go through the current ceiling via fork_refresh._apply_governance_passes, no start refusal is added, the shard 6 test points at spec_siblings.py, and there is no new regex.

Gates at this head: 98 checks pass with none red, First Principles and Opus pass, and no other change request is open. This approval replaces my earlier change requests.

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.

agent: a Windows sharing violation while rebuild_agent_config reads kirocrew.json rebuilds it from defaults and writes that back, erasing user edits

3 participants