Repository navigation
docs(rfc): recover a refused main-agent start inside the start gate - #28664
Conversation
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS This is a docs-only draft RFC with nothing irreversible in it, and it asks for maintainer sign-off before any code is written. Notes
[DESIGN-REVIEWED] 4c278fb Description read[DESCRIPTION-READ] e88a49d83c00ef4a7b56db33a389028dfda068ee4f46e7af38e406277e3ad53a 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
HOLD (conflict) at f8b50e0. The branch conflicts with main in On the rebase, please also fix the Opus note: the test plan at namestest/test_agent.py for TestInstallAgent, but on main that class is in test/test_agent_install.py. The two Design notes (state the expected refused-start latency, and list which surfaces show "not landed" longer) would sharpen open questions 1 and 3. The rest of this docs-only draft RFC needs nothing more from me. A new head needs a fresh review.
— crew-pr-reviewer (r143) |
f8b50e0 to
cf8c7d2
Compare
|
Rebased onto main as one commit (cf8c7d2); the index row sits alongside main's rows. Test plan now names |
cf8c7d2 to
84782ee
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Design brief for rfc-main-spec-start-recovery (read in full at 7ba6c33).
What it does. Once #27535 keeps an unreadable kirocrew.json and refuses starts while it is unreadable, this RFC moves recovery onto the refused start itself. A start that finds the file readable again joins one shared rebuild. The episode closes only when that rebuild wrote the spec and the governance generation it projected still equals a fresh poll after the write. The early-retry timer and its two gateway hooks are then deleted. Admitting a start while the file is still unreadable (option C) is rejected.
Pros.
- Recovery happens as soon as someone needs it, with no up-to-a-minute wait.
- It deletes a stopgap timer, its thread and two gateway hooks instead of keeping a second mechanism.
- The round-4 finding from #15546 (admitting on
wrotealone) is fixed at the place the episode closes, so peers arriving after the write cannot skip the check. - It refuses nothing that #27535 admits, and admits nothing that #27535 refuses for a stale reading or on the event loop.
Cons.
- It is blocked on #27535 merging, and it must be re-read against that merged head.
- Holds with no start waiting (boot baseline, ceiling memo, held conductor and fork specs) clear later than with the timer. The RFC names this in 3.6 and asks about it in open question 3.
- A shared rebuild, a re-entry marker and a backoff are more moving parts in a security-sensitive path. The test plan covers each of them.
Tech debt. None added; it removes the timer stopgap.
Maintainer signs the direction. This is a comment, not an approval, so the document still needs its own acceptance before code starts.
|
Maintainer follow-up to my brief above, after the decision on #27535. #27535 was asked to drop its new start refusals (the start gate, the launch bound, the Still signed: the in-place recovery. When a rebuild finds the kept spec readable again, overlapping callers share one rebuild ( No longer signed, please drop: everything that exists to admit or refuse a start:
With no refusal on main, a start while the file is unreadable behaves as main does today. Recovery only decides when the kept spec gets rewritten. Please revise the document to that scope, against #27535 once its revision lands. |
7ba6c33 to
714055b
Compare
|
@bolichen97 Revised to the narrowed scope in 714055b, rebased onto main as one commit and written against #27535's revision with no start refusals. Still signed, kept:
Dropped:
Stated plainly (Summary and §3.1): a start while the file is unreadable behaves as main does today, and recovery only decides when the kept spec gets rewritten. The background now also describes #27535's in-place refilter of the kept worker and heartbeat mirrors through the current ceiling. |
|
Maintainer follow-up at 714055b: the revision matches the narrowed scope, thank you. I checked the start-refusal parts against the #27535 decision, and they are gone:
The signed direction (the in-place recovery, with the generation read before the layers) stands for this document as revised. This is a comment, not an approval. |
|
HOLD (conflict) at 714055b. The branch conflicts with main again in On the same rebase, please fix two things the Design and Opus notes point out:
The rest matches the narrowed scope @bolichen97 confirmed. Checks are green. A new head needs a fresh review. — crew-pr-reviewer (r146) |
714055b to
4c278fb
Compare
|
@iamwhatever thanks for the r146 HOLD. Rebased onto main as 4c278fb, still one commit.
|
iamwhatever
left a comment
There was a problem hiding this comment.
Approve at 4c278fb4b1323850d4fe7f1825f790211cca7bc8.
This is a docs-only draft RFC, revised to the scope @bolichen97 signed. Both r146 points are fixed. What changed now describes the narrowed design. §3.1 now names the one bounded wait that §3.3 adds (rfc#L87-L89). All checks are green, and the README index keeps main's rows.
AI findings judged non-blocking
- Design: the PR title and Problem section still say a start is "refused". Does not block: this is wording in the PR metadata, and the RFC itself says no start is refused. A retitle before merge would keep the commit subject accurate (rfc#L89).
- Design: the 5 s backoff has no stated reason. Does not block: it is a tuning value in a draft, and the wait bound is already open question 1 (rfc#L101).
Note: #28633 and #28632 edit the same README sentence, so the PRs that merge after this one will need another rebase.
— crew-pr-reviewer (r148)
Part of #18860
Problem / Motivation
Goal: Get a maintainer design decision on how a refused main-agent start recovers once its kept
kirocrew.jsonreads again, before any code for #18860.With #27535, a main-agent start stays refused after a user restores read access to
kirocrew.jsonuntil a rebuild writes the spec, and the only fast path is a stopgap early-retry timer. #18860 needs a maintainer design sign-off before code, so this is the request-for-change.Why it matters
Without in-gate recovery, the main agent can stay refused for about a minute (timer) or up to an hour (hourly retry) after access is restored, and the timer runs rebuilds on a schedule with nobody waiting.
Not a goal
What changed
Docs only. Adds
docs/request-for-change/rfc-main-spec-start-recovery.md(statusdraft) and its index row. Revised to the narrowed scope: it proposes that a main-agent start which finds an open unreadable-spec episode and a readable file joins one shared rebuild that rewrites the kept spec in place, then goes ahead on the same path it takes on main. It refuses no start and admits none differently from main. The rebuild reads the governance generation before the layers and runs once more if the generation moved mid-rebuild; nothing waits on or admits on that comparison. The only added delay is a start waiting for the shared rebuild, at most a 30-second waiter timeout. A scheduled or early-retry rebuild timer is a non-goal.Tests
scripts/docs_lint.pypasses andtest/test_docs_lint_fact_checks.pypasses (118). Two local security review rounds on the design; every finding is answered in the text. No code, so no code tests.