fix(stella-cli): unbreak main — resolve the boot.rs doc link #1920 left dangling by macanderson · Pull Request #1927 · macanderson/stella

macanderson · 2026-08-06T22:00:27Z

What & why

RUSTDOCFLAGS="-D warnings" cargo doc -p stella-cli fails on main: the parked field's intra-doc link in crates/stella-cli/src/daemon/boot.rs names supervised::APPROVAL_REQUEST with no supervised in scope. The doc-warnings gate is therefore red for every open PR. #1920 merged with it because ci.yml does not run on a push to main.

One line: qualify the link as stella_store::supervised::APPROVAL_REQUEST, the path the code itself uses. Refs #1920.

The witness

No witness needed (doc-link fix) — verified with RUSTDOCFLAGS="-D warnings" cargo doc -p stella-cli --no-deps, which fails on main and exits 0 with this change.

The gate

Verified as above; no behavior change, no flags, no docs pages affected.

Nothing left behind

The same fix rides on the #1921 feature branch (identical line, no conflict either way).

Summary by Sourcery

Bug Fixes:

Correct the BootCandidate documentation link to reference stella_store::supervised::APPROVAL_REQUEST so rustdoc no longer fails on main when treating warnings as errors.

…ft dangling The parked field's intra-doc link named supervised::APPROVAL_REQUEST with no supervised in scope in boot.rs, so RUSTDOCFLAGS="-D warnings" cargo doc fails and the doc-warnings gate is red for every open PR. ci.yml does not run on a push to main, which is how #1920's merge never saw it. Refs #1920

vercel · 2026-08-06T22:00:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stella-cli-docs	Building	Preview	Aug 6, 2026 10:00pm

sourcery-ai

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

sourcery-ai · 2026-08-06T22:00:40Z

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Fixes a failing intra-doc link in stella-cli’s daemon boot documentation by fully qualifying the referenced constant so cargo doc passes with -D warnings.

File-Level Changes

Change	Details	Files
Fully qualify the intra-doc link to the approval request constant so rustdoc succeeds under `-D warnings`.	Update the `parked` field’s documentation comment to reference `stella_store::supervised::APPROVAL_REQUEST` instead of the unqualified `supervised::APPROVAL_REQUEST`. Ensure `RUSTDOCFLAGS="-D warnings" cargo doc -p stella-cli --no-deps` no longer fails due to the missing `supervised` path in scope.	`crates/stella-cli/src/daemon/boot.rs`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

macanderson · 2026-08-06T22:27:58Z

Full local gate audit of main — this is the only break. (Moved here from my duplicate #1929, which I am closing in favour of this one.)

Since no ci.yml run has started since 19:03 (#1899), I ran the whole gate locally against origin/main to find out what else has slipped through. Exactly one failing step, and it is this one.

Gate tier	Result
20 toolchain-free guards (`make guards-fast`)	OK
`cargo fmt --check`	OK
`wire-schema`	OK — `docs/wire/` matches the types
`cargo clippy --workspace --all-targets -- -D warnings`	OK
`cargo test --workspace`	OK — 123 test binaries, 0 failures
`RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps`	FAILS — this PR

So merging this returns main to a fully green gate, and nothing else accumulated behind the outage — which is the more reassuring half of the answer.

One correction to the description, since it changes where to look: ci.yml does run on pushes to main — the runs exist. They never start. Every one since 19:03 sits in queued and none has reached in_progress, so #1920 merged on absent required contexts rather than on a workflow that was never triggered. That is a different failure from #1645's (a red check overridden): branch protection cannot distinguish "the required check passed" from "the required check never ran" while the run is stuck queued.

For the record, #1920 is mine, and I reported tests, clippy, fmt and four guard scripts clean on it — all true, and none of them is the rustdoc step. Thanks for catching it.

macanderson · 2026-08-06T23:01:08Z

CI is running again, and it confirms this PR is the single thing blocking every open branch. Hard evidence rather than my local gate run.

ci.yml run 31128773050 on fix/1595-pipeline-calibration (a docs-only, one-string change to stella-parity) completed failure:

fmt + clippy + test  ::  failure
  cargo doc -D warnings
    error: unresolved link to `supervised::APPROVAL_REQUEST`
           no item named `supervised` in scope
    error: could not document `stella-cli`
    ##[error]Process completed with exit code 101.

That branch touches one string literal in crates/stella-parity/src/lib.rs and nothing else. The failure is entirely main's, reproduced on a PR that cannot have caused it — the "a red main makes every PR red" shape, arriving through the doc-warnings step.

A push to main at 22:05 also completed failure for the same reason, while the 22:03 push completed success — so the break is bisected to the merge between them, which is #1920.

Merging this returns main to green and unblocks every open PR at once. My earlier full local gate audit still stands: this is the only failing step — 20 toolchain-free guards, fmt --check, wire-schema, workspace clippy and 123 test binaries all pass on main as it is.

…n cannot stall the sweep (#1921) (#1928) ## What & why `resume_all` streamed each resumed run to completion with no upper bound, so any turn that never ends — a wedged tool, a provider that never returns, a model call retrying forever — stalled every id behind it, exactly as an unanswered approval used to, and just as silently. #1920 fixed the one such state visible on disk before spawning (a parked approval); this is option 2 of the pair #1698 said compose: a **per-run wall-clock ceiling** on the boot sweep — `stella daemon resume-all --ceiling MINUTES`, default 30. The design calls the issue asked to be stated: - **The stop path is the existing graceful one, not a second one.** Expiry never kills the child outright — a `SIGKILL` at the ceiling would land mid-edit, worse than the stall it fixes. The ceiling goes through `Supervised::interrupt_and_drain`, the same discipline as Ctrl-C and `stella daemon stop`: `SIGTERM`, the measured 8-second `STOP_GRACE` for the engine to abort at a safe boundary (invariant 6) and write its own terminal status, escalation only then. `STOP_GRACE` is untouched. - **A timed-out run IS charged its boot attempt.** The attempt is recorded before the spawn (as every attempt already was) and deliberately not refunded. The two endings compose with the existing brakes rather than needing new ones: a child that honours the stop ends deliberately (checkpoint discarded, `Cancelled` recorded — same as any operator stop), so the next sweep skips it as ended and returns its attempts; a child so wedged it had to be killed wrote nothing, keeps its resume point, and is swept again next boot — where the charge counts against `MAX_BOOT_ATTEMPTS`. So the charge only ever persists for the genuinely wedged run, which is exactly the recurring failure the three-attempt bound exists to stop. A run that was merely slower than the ceiling is `stella daemon resume <id>`'s to continue by hand — that verb has no ceiling. - **Nothing is quiet** (#1627's "a run silently resumed at boot is as bad as one silently lost"): the watch names the ceiling the moment it fires, and the sweep prints one operator-actionable line per stopped run (`ceiling_report`, pure and witnessed like `SkipReason::explain`). Mechanically: `watch` gains an `Option<Duration>` ceiling and answers `Watched::{Finished, CeilingReached}`; the bounded race is `tokio::time::timeout` over the existing `follow()` future (all streaming state lives on `Supervised`, so the abandoned future drops losslessly). `resume_supervised` threads it; hand resumes pass `None`. Also in this PR: `Tail` moved verbatim from `daemon.rs` into `daemon/console.rs`, where its readers already live. `daemon.rs` stood at 1493 lines with the ceiling in place — file-size policy says a file approaching the 1500 gate gets split, not grown. It now sits at ~1400, and no baseline entry changed. Closes #1921 ## The witness - [x] This PR includes a witness test (fails on `main`, passes here) `daemon::tests::a_run_that_outlives_the_ceiling_is_stopped_gracefully_and_the_watch_returns` — a real supervised child that traps `TERM` outlives a 250ms ceiling; the test asserts the watch *returns* (the property the sequential sweep rests on), that the child saw `SIGTERM` before anything harder (the trap's marker file), and that the stop is recorded `Cancelled` rather than aging into a crash. `a_run_that_finishes_under_the_ceiling_is_left_to_finish` pins the no-misfire half, and `boot::tests::a_ceiling_stop_names_the_ceiling_the_safe_stop_and_the_next_step` pins the console contract. On `main` these fail as the feature is genuinely absent (`watch` has no ceiling parameter and `Watched`/`ceiling_report` do not exist). ## The gate - [x] `cargo fmt --check` - [x] `cargo clippy --workspace --all-targets -- -D warnings` - [x] `cargo test` (`make gate CARGO_SCOPE="-p stella-cli"`) - [x] Docs updated: `website/content/docs/commands/daemon.mdx` § `resume-all` (new "What bounds each resume" block + synopsis), `--help` text on `ResumeAll`, module docs in `daemon/boot.rs` (new "What stops a stalled sweep" section stating the attempt-charging decision) - [x] CLA signed - [x] `Closes #1921` appears both above and as a commit trailer ## Nothing left behind While gating this, main turned out doc-red: #1920 merged a dangling intra-doc link in `boot.rs` (`ci.yml` does not run on pushes to main). The second commit here fixes it — and the same one-line fix is also open as a dedicated unbreak, #1927, so every other PR heals without waiting on this one; the two apply cleanly in either order. That commit also swaps the bounded race to the canonical `tokio::time::timeout` and teaches `describe_ceiling` to speak milliseconds rather than round a sub-second test ceiling to "0-second". Refs #1585, #1627, #1698, #1920, #1927.

…a dangling boot.rs doc link (#1985) ## What & why `main`'s required `fmt + clippy + test` job has been **red since #1951** (five consecutive merges), so every open PR inherits a red gate. Four distinct errors are involved. This PR fixes the two that **no open PR covers**. ### 1. `cargo clippy -D warnings` — `plan_stage` has 8 arguments (limit 7) `crates/stella-pipeline/src/pipeline.rs`. #1953 added a `research` parameter, pushing `plan_stage` over `clippy::too_many_arguments`. `Spend<'_>` (`crates/stella-pipeline/src/pipeline/stage_budget.rs`) already groups the `budget`/`total` pair, and **seven** sibling stage methods take it; `plan_stage` was the last one carrying the two loose. Adopting it takes the count to 7. This is the right fix rather than `#[allow(clippy::too_many_arguments)]` because there is no argument that the lint is wrong *here* — the grouping type the lint is asking for already exists — and because `pipeline.rs` is a grandfathered god file closed to growth, which this change **shrinks**. ### 2. `cargo doc -D warnings` — unresolved link in `boot.rs` `crates/stella-cli/src/daemon/boot.rs`. #1939 left ``[`SkipReason::NoResumePoint`]`` in the module doc unresolvable (`no item named `SkipReason` in scope`), which fails `rustdoc::broken_intra_doc_links`. Qualified to the full path — the same remedy #1927 applied to *this same file* for *this same reason* after #1920. That recurrence is filed as #1986. ## What this PR deliberately does NOT fix The other two errors belong to the open PR **#1964**: - `flip_halt_arming.rs` references `PassingShell` / `shell_call_result`, test helpers #1945 landed the test file without. - `crates/stella-pipeline/src/management_prompt/tests.rs`'s exhaustive match omits `ModelCallRole::Research`, which #1953 added. Duplicating them here is how two parallel unbreak PRs collide, so they are left to #1964. **`main` needs both PRs.** This one alone leaves `cargo test` red; #1964 alone leaves clippy and rustdoc red (verified: #1964's own CI still fails both, and its clippy failure is the identical `plan_stage` error). Neither is sufficient on its own, and the merge order does not matter. Because of that, **this PR's own `cargo clippy` and `cargo test` steps will stay red until #1964 merges** — clippy `--all-targets` reaches the missing test helpers once the lib error is gone. That is expected, not a regression. ## The witness - [x] No witness test needed — a lint fix and a doc-link fix, neither a behavior change. Verified the artisanal way: - `RUSTDOCFLAGS="-D warnings" cargo doc -p stella-cli --no-deps` fails on `main` and **exits 0** with this change. - `cargo check -p stella-pipeline --all-targets` reports **only** the three #1964-owned errors; the `plan_stage` arg-count error is gone and both call sites (`pipeline/scope_stage.rs`, `pipeline/tests/management_accounting.rs`) compile. - `cargo fmt --check -p stella-pipeline -p stella-cli` exits 0. ## The gate - [x] `check-file-size.sh` and `check-god-files.sh` pass; `pipeline.rs` shrinks, so no baseline change is needed. - [x] No behavior change, no new flags, no docs pages affected. - [x] No new dependencies. ## Nothing left behind - **#1986** — `boot.rs`'s module doc has now broken `main`'s rustdoc twice in two days by the same mechanism (#1920 → #1927, then #1939 → this PR), because `ci.yml` does not run on a push to `main`. Filed as a handoff. - **#1974** — `CandidateState` is hand-built at two sites, which is how #1951's field addition silently broke PR #1962 at merge time. Noticed in the same investigation. Refs #1953, #1939, #1964

sourcery-ai Bot reviewed Aug 6, 2026

View reviewed changes

macanderson mentioned this pull request Aug 6, 2026

feat(stella-cli): bound each boot resume by wall clock so a wedged run cannot stall the sweep (#1921) #1928

Merged

7 tasks

This was referenced Aug 6, 2026

fix(stella-cli): unbreak main — broken intra-doc link in #1698's boot guard #1929

Closed

fix(stella-cli): make the resume frame impossible to forget (#1672) #1930

Merged

macanderson merged commit 20c0e53 into main Aug 7, 2026
4 checks passed

macanderson deleted the fix/unbreak-boot-doc-link-1920 branch August 7, 2026 00:10

This was referenced Aug 7, 2026

fix(stella-pipeline,stella-cli): unbreak main — clippy arg count and a dangling boot.rs doc link #1985

Merged

CI: ci.yml does not run on a push to main, so main goes red and stays red (twice by the same boot.rs doc link) #1986

Open

Navigation Menu

Uh oh!

fix(stella-cli): unbreak main — resolve the boot.rs doc link #1920 left dangling - #1927

fix(stella-cli): unbreak main — resolve the boot.rs doc link #1920 left dangling#1927
macanderson merged 1 commit into
mainfrom
fix/unbreak-boot-doc-link-1920

macanderson commented Aug 6, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

vercel Bot commented Aug 6, 2026 •

edited

Loading

Uh oh!

sourcery-ai Bot left a comment

Uh oh!

sourcery-ai Bot commented Aug 6, 2026

Reviewer's Guide

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

macanderson commented Aug 6, 2026

Uh oh!

macanderson commented Aug 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

macanderson commented Aug 6, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

The witness

The gate

Nothing left behind

Summary by Sourcery

Uh oh!

vercel Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

sourcery-ai Bot commented Aug 6, 2026

Reviewer's Guide

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

macanderson commented Aug 6, 2026

Uh oh!

macanderson commented Aug 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

macanderson commented Aug 6, 2026 •

edited by sourcery-ai Bot

Loading

vercel Bot commented Aug 6, 2026 •

edited

Loading