Skip to content

fix(agent): stop a held sibling pass rewriting specs every tick - #32804

Merged
buluoray merged 1 commit into
mainfrom
crew/slack/spec-unreadable-generation
Nov 8, 2026
Merged

buluoray merged 1 commit into
mainfrom
crew/slack/spec-unreadable-generation

Conversation

@buluoray

@buluoray buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: While kirocrew.json cannot be read and a sibling spec cannot be written either, a pending default-model change no longer rewrites every sibling spec on each 2-second config-watch tick.

With kirocrew.json unreadable, _skip_unreadable_main_spec keeps the file and runs the sibling pass (service, conductor and fork specs) once per governance generation. A pass that held a sibling write never recorded its generation. That happens when a second spec (kirocrew-heartbeat, the worker, a conductor) is also unreadable, which is the usual case because ownership, mode or an antivirus lock hit the whole agents directory. Then ConfigWatch._cycle retries the pending model change every DEFAULT_POLL_INTERVAL_SECS (2 s), each retry lands in the skip, and generation != _main_spec_skip_generation stays true, so the whole pass runs every tick: it rewrites the knowledge, research, mate, team-lead and conductor specs, runs a fork refresh and hook repair, and logs a WARNING each time. Found by Opus on the 0.12.1 port of #27535 (#32758); the same code is on main.

Why it matters

For as long as the directory stays unreadable, the gateway rewrites half a dozen spec files and logs a warning every 2 seconds, and kiro-cli reloads the watched specs each time.

Not a goal

  • Changing what the sibling pass does, or the hourly maintenance retry.
  • The deferred boot refresh, which still records no generation.

What changed (motivation → approach → change)

agent_parts/spec_unreadable.py: a pass that completed (raised nothing, refresh not deferred) now records its generation whether or not it held. If it held, it also records the time it ran (_main_spec_held_pass_at, on an injectable _held_pass_clock), and the same generation runs the pass again only once HELD_SIBLING_PASS_RETRY_SECS (30 min) have passed. That is shorter than the hourly maintenance wake (retry_held_conductor_specs), so the wake always finds the retry due and a tightened ceiling still reaches a held conductor spec. A pass that holds nothing clears the time; closing the episode clears both. A raising pass still records nothing and re-runs on the next skip.

agent.py re-exports the two new names; test/conftest.py resets the new state with the others. docs/system-specs/modules/governance.md says when a held pass runs again.

Backwards compatibility

Compatible. A held sibling pass now runs again after 30 minutes under the same generation, or when the generation moves, instead of on every skip. The hourly maintenance retry still re-runs it, so a held conductor spec is retried exactly as often as before through that path.

Reader: src/kiro_crew/agent_parts/spec_rebuild.py:retry_held_conductor_specs -- release -- its hourly rebuild lands in the skip after HELD_SIBLING_PASS_RETRY_SECS, so the held pass still re-runs; test_a_held_sibling_pass_is_retried_under_the_same_generation

Tests

Proof: PROVEN test/test_agent_unreadable_main_spec.py::TestUnreadableMainSpec::test_a_held_sibling_pass_waits_out_the_retry_interval (head 67a3c88)

  • New test_a_held_sibling_pass_waits_out_the_retry_interval: main spec unreadable, conductor held, ten 2-second ticks run the pass once (assert 10 == 1 on the old code), and the first skip after the interval runs it again.
  • test_a_held_sibling_pass_is_retried_under_the_same_generation, test_a_mirror_re_filter_that_fails_keeps_the_sibling_pass_owed and test_a_deferred_fork_refresh_leaves_the_generation_unrecorded now step the clock past the interval and assert the held time instead of an unrecorded generation.
  • Mutation check, one at a time: leaving a held pass unrecorded (the old line) turns 3 tests red; dropping the interval check turns 4 red.
  • Related: every test file naming spec_unreadable, the skip, the _main_spec_ state, retry_held_conductor_specs, _spec_hold_open or agent_parts (52 files) plus the flake ratchet: 2222 passed.
  • flake8, isort, black, mypy, comment-history, brand, file line cap and docs-lint pass.

Manual verification

N/A - the tick loop is driven deterministically in the new test with an injected clock.

Screenshots / video

Related Issues

Found on #32758 (the 0.12.1 port of #27535).

Sibling sweep

Siblings: none -- _skip_unreadable_main_spec is the only place the sibling pass is gated on a recorded generation; retry_held_conductor_specs and the profile watch keep their own backoffs.

Pattern harvest

Not generalizable: the gate is specific to the unreadable-spec episode.

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 8, 2026 00:47
@buluoray
buluoray requested a review from tim-finnigan November 8, 2026 00:47
@buluoray
buluoray enabled auto-merge (squash) November 8, 2026 00:48
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 4ea8deb26b6e6dd3141204243db48c3938fd2cc3 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 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the fix records the generation and the time of the held pass, so the 2-second retries stop re-running it. The hourly wake can still make the pass due again explicitly.

Notes

  • The description's "What changed" never mentions _make_held_sibling_pass_due or the spec_rebuild.py hunk. It argues that the 30-minute interval is enough for the hourly wake, but the code does not rely on that because it forces the pass due. Name the seam in the description so it matches the code.

[DESIGN-REVIEWED] 4ea8deb

Description read

[DESCRIPTION-READ] 84a6679f7cb76eb3a0d38680004583fbfd3492eaa43fc5f386027cba1f3138f8

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 4ea8deb26b6e6dd3141204243db48c3938fd2cc3 — 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 belongs at the cause. It ships two retry triggers for the held pass where one, the existing hourly wake, already covers the job.

Notes

  • Item 2 — oversized: the description says the 30 min interval "is shorter than the hourly maintenance wake ... so the wake always finds the retry due". The diff contradicts that: the wake calls _make_held_sibling_pass_due() because "it may land inside HELD_SIBLING_PASS_RETRY_SECS". The wake already forces the re-run, and a moved generation re-runs the pass anyway, so the interval only adds a 30-minute re-run on config-watch ticks that nobody is shown to need.
    Subtraction: delete HELD_SIBLING_PASS_RETRY_SECS, _held_pass_clock, _main_spec_held_pass_at, the held_retry_due branch and the matching agent.py re-exports. Instead, retry_held_conductor_specs sets _main_spec_skip_generation = None under the lock, which it may do because it only runs while a hold is open.
    Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (5 items) — 2 justified

Intent: stop the gateway rewriting every sibling spec and logging a warning every 2 s while the agents directory is unreadable. This is a FIX.

  1. While the main spec and a sibling spec stay unreadable, a pending model change no longer re-runs the sibling pass on every tick — justified
  2. A held pass re-runs under the same generation on any skip after 30 minutes — oversized
  3. The hourly maintenance wake re-runs a held pass at once, ignoring the interval — undeclared
  4. A shared template held by the deferred boot pass is now retried after the interval or at the hourly wake, not on the next skip — undeclared
  5. The governance spec now says when a held pass runs again — justified

[FIRST-PRINCIPLES-REVIEWED] 4ea8deb

Description read

[DESCRIPTION-READ] 5e74de140d65bbeb89aca726f58b44d339b309c5f23c2379822ce06eca37ed9d

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 4ea8deb

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

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

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4ea8deb

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 4ea8deb26b6e6dd3141204243db48c3938fd2cc3 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 8, 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.
@buluoray
buluoray force-pushed the crew/slack/spec-unreadable-generation branch from 67a3c88 to 4ea8deb Compare November 8, 2026 01:13
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

span=52bfbc939a26
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

  • Fixed in 4ea8deb. The hourly wake (retry_held_conductor_specs) now calls _make_held_sibling_pass_due() before it rebuilds, which clears _main_spec_held_pass_at, so the wake always re-runs a held sibling pass even inside HELD_SIBLING_PASS_RETRY_SECS. The 2 s config-watcher retry still waits out the interval. New test test_the_hourly_wake_re_runs_a_held_pass_inside_the_interval goes red with the call removed (assert 1 == 2) and green with it; governance.md says the wake makes the pass due.

@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 8, 2026
@buluoray
buluoray merged commit 217b335 into main Nov 8, 2026
99 checks passed
@buluoray
buluoray deleted the crew/slack/spec-unreadable-generation branch November 8, 2026 02:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 8, 2026
buluoray added a commit that referenced this pull request Nov 8, 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 added a commit that referenced this pull request Nov 8, 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)
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.

2 participants