Skip to content

docs(rfc): recover a refused main-agent start inside the start gate - #28664

Merged
iamwhatever merged 1 commit into
mainfrom
docs/rfc-18860-main-spec-recovery
Nov 6, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
docs/rfc-18860-main-spec-recovery

Conversation

@jeeshofone

@jeeshofone jeeshofone commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Part of #18860

Problem / Motivation

Goal: Get a maintainer design decision on how a refused main-agent start recovers once its kept kirocrew.json reads again, before any code for #18860.

With #27535, a main-agent start stays refused after a user restores read access to kirocrew.json until 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 (status draft) 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.py passes and test/test_docs_lint_fact_checks.py passes (118). Two local security review rounds on the design; every finding is answered in the text. No code, so no code tests.

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

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 4c278fb4b1323850d4fe7f1825f790211cca7bc8 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 4c278fb4b1323850d4fe7f1825f790211cca7bc8 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 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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

  • The title ("recover a refused main-agent start") and the Problem section ("a main-agent start stays refused") contradict the RFC's own invariant, "No start is refused… fix(agent): keep an unreadable agent spec instead of resetting it #27535 refuses no start." The RFC text is the reliable version.
  • The RFC says "a backoff stops repeated rebuilds" (§3.3) but gives no reason for the 5-second value. Tie it to measured rebuild cost alongside the 30-second waiter in open question 1, so that starts during an episode never add up to repeated 30-second waits.

[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 .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 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 4c278fb

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

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

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4c278fb

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

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 3, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (conflict) at f8b50e0.

The branch conflicts with main in docs/request-for-change/README.md, which is the index row. Please rebase onto main and resolve that row.

On the rebase, please also fix the Opus note: the test plan at

In `test/test_agent.py` (`TestInstallAgent`) and the #27535 spec-unreadable tests:
names test/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)

@jeeshofone
jeeshofone force-pushed the docs/rfc-18860-main-spec-recovery branch from f8b50e0 to cf8c7d2 Compare November 3, 2026 10:02
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Rebased onto main as one commit (cf8c7d2); the index row sits alongside main's rows. Test plan now names test/test_agent_install.py. Open question 1 states the expected refused-start latency, and open question 3 lists the surfaces that show "not landed" longer.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 3, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-18860-main-spec-recovery branch from cf8c7d2 to 84782ee Compare November 3, 2026 20:32
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge 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 readiness: checking Automated validation is still running labels Nov 3, 2026
@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: checking Automated validation is still running labels Nov 4, 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.

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 wrote alone) 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.

@bolichen97

Copy link
Copy Markdown
Contributor

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 set_mode gates and the early-retry timer that lifts them). The rule is that we do not increase security strictness. It may keep only the part that stops an unreadable kirocrew.json from being overwritten with defaults. This RFC builds on those refusals, so the signed direction is narrowed to match:

Still signed: the in-place recovery. When a rebuild finds the kept spec readable again, overlapping callers share one rebuild (_MainSpecRebuild, no new thread, the in-rebuild marker, the backoff). The kept spec is rewritten as soon as it reads, with the generation read before the layers. Removing the early-retry timer also stays signed, because without the refusals there is nothing for it to lift.

No longer signed, please drop: everything that exists to admit or refuse a start:

  • the invariant in 3.1 framed as "a start is admitted only when the episode is closed"
  • recover_main_spec_episode() as a step that refusal paths call before they refuse (the 3.4 table)
  • the waiter timeout and backoff ending in a refusal
  • the refuse_unprojected_main_spec_start text and its SEL rows
  • the tests that assert a start is refused

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.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-18860-main-spec-recovery branch from 7ba6c33 to 714055b Compare November 5, 2026 12:06
@jeeshofone

Copy link
Copy Markdown
Contributor Author

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

  • In-place recovery: a main-agent start that finds an open episode and a readable file joins one shared rebuild (_MainSpecRebuild, no new thread, the in-rebuild marker, the 5 s backoff) before it loads the spec (§3.3, §3.4).
  • The kept spec is rewritten as soon as it reads, and the rebuild reads the generation before either layer (§3.2).
  • The early-retry timer: fix(agent): keep an unreadable agent spec instead of resetting it #27535's revision already removes it, so the RFC now lists a scheduled retry as a non-goal and rejected option C instead of a deletion list.

Dropped:

  • The §3.1 invariant "a start is admitted only when the episode is closed". §3.1 now states that no start is refused, admitted or delayed differently from main.
  • recover_main_spec_episode() as a pre-refusal step and the §3.4 table. It now returns None, raises nothing a start sees, and the start continues whatever the rebuild did.
  • The waiter timeout and backoff ending in a refusal. A waiter that times out, or a start inside the backoff, goes ahead as on main.
  • The refuse_unprojected_main_spec_start text and its SEL rows, and the open question on SEL refusal causes.
  • Every test asserting a refusal. A new test pins that a start takes the same path and result as on main across readable, unreadable, rebuild error and waiter timeout.

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.

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

Copy link
Copy Markdown
Contributor

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 invariant now says no start is refused, and none is admitted or delayed differently from main.
  • recover_main_spec_episode() returns None and only lets a rebuild write the spec, after which the start goes ahead on main's path.
  • The non-goals rule out refusing or admitting on the episode, and rule out any early-retry timer.
  • The "still unreadable" test asserts the start proceeds as on main, with no SEL row added.

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.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 5, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (conflict) at 714055b.

The branch conflicts with main again in docs/request-for-change/README.md (the index row). Please rebase and keep both rows.

On the same rebase, please fix two things the Design and Opus notes point out:

  • The description's What changed still describes the old design: it recovers "a refused start", closes the episode on a generation match, and deletes the early-retry timer. The revised RFC refuses no start and lists the timer as a non-goal. Update What changed (not the frozen Goal).
  • §3.1 says no start is delayed differently from main, but §3.3 runs the rebuild on the first start's thread and makes later starts wait. Either reword the invariant to admit that delay and state its expected size, or let a start that finds a rebuild running go ahead without waiting.

The rest matches the narrowed scope @bolichen97 confirmed. Checks are green. A new head needs a fresh review.

— crew-pr-reviewer (r146)

@jeeshofone
jeeshofone force-pushed the docs/rfc-18860-main-spec-recovery branch from 714055b to 4c278fb Compare November 6, 2026 07:14
@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 labels Nov 6, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for the r146 HOLD. Rebased onto main as 4c278fb, still one commit.

  • Conflict: docs/request-for-change/README.md keeps both main's rows and this PR's row and its added-on sentence.
  • What changed: rewritten to the current design. It refuses no start, admits none differently from main, and lists the scheduled or early-retry timer as a non-goal. The frozen Goal is untouched.
  • §3.1 vs §3.3: I reworded the §3.1 invariant to admit the delay rather than change §3.3. Only a start that finds an open episode and a readable file waits, for one rebuild's duration and at most the 30-second waiter timeout (open question 1). A start with no open episode waits for nothing.
    Docs checks pass locally.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 6, 2026

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

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)

@iamwhatever
iamwhatever merged commit 0a82a47 into main Nov 6, 2026
101 of 108 checks passed
@iamwhatever
iamwhatever deleted the docs/rfc-18860-main-spec-recovery branch November 6, 2026 18:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 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.

3 participants