[arelchan]

Summary

The upgrade button on the page could never work for a normal install, and when an upgrade did run, neither the page nor (on a slow link) the terminal showed anything that moved. This PR makes the page upgrade work, shows its progress, and fixes what an end-to-end run of it turned up, plus two entry-point changes from the same pass.

The page upgrade works on raven web. raven web runs raven gateway, so nearly every page is gateway-hosted, and system.upgrade refused all of them (gateway_hosted): its relaunch brought back a bare raven serve, which builds no ChannelManager, so the IM channels would have vanished. Now:

• On every page mount the gateway hands the page its own graceful stop (the path gateway.shutdown takes), its busy check, and its supervisor pid. Every mount, because a config swap tears the page down and disarms it.
• On upgrade the gateway exits 0. The raven web supervisor already reads a zero exit as "stand down" (its docstring names system.upgrade), so it exits too.
• The helper waits for the supervisor, not the gateway, then installs and relaunches raven web --supervise on the same port with the same token and cookie. Waiting on the supervisor matters: its cleanup removes web.json after the gateway exits, and a supervisor started before that would lose its state file, inviting the next raven web to start a second one.
• Refused, each with its own reason, when nothing would bring the gateway back (started by hand, or raven web --foreground), when work the page cannot see is running (an IM turn, a sub-agent, a pending question), or when there is no executable to relaunch from. The config swap and the upgrade now share one busy check.

This takes effect for upgrades that start from a release containing it; a gateway on an older release still refuses with the old message.

The page shows the upgrade's progress. The card said "Upgrading Raven..." and nothing else until the new Raven answered, because the process that served the page is gone for the whole install.

• The helper downloads the release itself, where the bytes can be counted, and hands uv the local files so uv only resolves dependencies. All or nothing: if any asset cannot be fetched, uv gets the original URLs and downloads them as before. Files live under ~/.raven/cache/upgrade/<version>; earlier versions' are cleared.
• Once the old Raven has exited, the helper answers on the page's port (recorded in the upgrade marker): /upgrade/status with phase, bytes done and total, and rate; 503 to everything else, so the page's "is it back?" probe keeps waiting and a reload gets a self-refreshing wait page. It answers only the page's own Host, and lets the port go before the relaunch binds it.
• A failure is held until the page has read it (at most five seconds). Before, a failed install relaunched the old version and the page reloaded onto it silently.
• The page polls the status, measures the bar while bytes are counted and slides it otherwise, and says when the new Raven is starting. Its twenty-minute ceiling now counts silence, not the whole upgrade, so a slow download that is visibly moving is not given up on.

Two bugs the end-to-end run exposed, both fixed here:

• A red "the service is not running, start it with raven web" bar during the upgrade. The transport's health probe counted any answer but 401/403 as "the gateway is back and refused this session", so the helper's 503 made it give up. A 5xx now means "not back yet". Following that bar's advice mid-upgrade is exactly what would start a second supervisor.
• The old gateway took 46 seconds to exit, blocked on the page's own open WebSocket. aiohttp's cleanup waits for live handlers instead of closing websockets. The WS gateway now closes its sockets from on_shutdown; the same run dropped to 4 ms. This also speeds up raven web --stop with a page open.

raven gateway refuses a half-written install. raven serve has guarded this since the upgrade marker existed, but the gateway never did, and the gateway is what raven web supervises. A restart inside an upgrade window came up on the half-written tree and, because the page route is chosen once, served the placeholder page until restarted by hand. The guard runs before the instance lock. It is also a precondition for the restart above.

Refusals are localized. The page pasted the server's English detail into an otherwise Chinese card. Refusals it can name come from the catalogue; refusals whose detail carries facts from this run keep them. A server-side busy gets the same wait notice as the page's own busy turn, not the "run this in a terminal" card.

The terminal upgrade names its download size. uv draws one bar per package and no total, so a large release reads like a stalled install (a real report: a 72 MiB upgrade at about 50 KB/s looked frozen). The helper prints each asset's size and the total before downloading, from HEAD requests bounded at 5 seconds, headline first so a hanging probe adds no silence; the terminal then shows the helper's own live progress line. Output is flushed so it keeps its place in web.log.

Bare raven opens the page. The installer ends in raven web, but the command typed the next day landed in the TUI. Bare raven now does what raven web does; where no browser can be opened it runs the TUI instead, decided before anything starts. raven web and raven tui are unaffected.

Composer placeholders. Empty: "Describe your task, or have Raven build an agent for it" becomes "Describe your task". While a turn runs: "it is sent once this turn ends" was stale (mid-turn sends merge into the running turn; the queue is only a fallback), so it now says Raven receives the new instruction directly.

Type

• Fix
• Feature
• Docs
• CI / tooling
• Refactor
• Other

Verification

End to end, three times, in a sandboxed uv tool install (own UV_TOOL_DIR and RAVEN_HOME, no plugins, so nothing reached a real memory server), upgrading 0.2.90 to 0.2.91 from a local stand-in for the GitHub release API, clicking the real rail-foot upgrade row in a browser:

• First run (fast local download): page back after 17 seconds, reloaded by itself, still signed in; served by python -P -m raven gateway (not serve) on the same port; web.json names the new supervisor, which is the new gateway's parent; old supervisor and gateway gone.
• Second run, with the release trickled at ~200 KB/s: the progress showed, and the run found the two bugs above (the red bar, and the old gateway taking 46 seconds to exit).
• Third run, same trickle, after the fixes: the card read "Downloading the new version: 0.6 / 6.1 MiB, 191 KB/s" five seconds after the click, then 2.4 / 6.1 MiB with the bar measuring; no red bar; the old gateway's page socket closed 4 ms after the control plane stopped; uv prepared the package from the local file in 157 ms; the page reloaded itself onto 0.2.91.
• raven upgrade in a real pseudo-terminal against the same trickle: the live line redrew in place 98 times from 0.1 to 6.1 of 6.1 MiB, then uv installed from the local file.

Commands, all on this branch rebased onto current main:

• make coverage - 26,955 passed. 21 failed, and they are the same 21 that fail on unmodified main on this machine (research-tool and simulation tests, and one that assumes LibreOffice is absent); a 22nd was a load-sensitive test added here, fixed in this PR and then 25 of 25 under CPU load
• scripts/coverage_gate.py diff --base-ref github/main --threshold 90 - 100% (77 of 77 changed lines)
• npm test --prefix ui-web - 3096 tests pass
• make lint-python - pass; uv run lint-imports - 10 contracts kept, 0 broken
• make lint-ui - 0 errors (4 pre-existing exhaustive-deps warnings in files this PR does not touch); npm run lint:i18n --prefix ui-tui - up to date
• node ui-web/scripts/check-page.mjs, check-css.mjs, check-class-namespace.mjs after npm run build and build.py - OK
• mkdocs build --strict - pass
• npx commitlint --from github/main --to HEAD, scripts/check_commit_messages.py, make check-source-language and make check-large-files with COMMIT_RANGE=github/main..HEAD - pass

New tests were mutation-checked; each edit below turns the test written for it red. Server: relaunching serve instead of the supervisor, waiting on the gateway instead of the supervisor, dropping the unsupervised refusal, the busy refusal, the no-relaunch guard, or the page-mount hand-over; not closing sockets on shutdown. Helper: never downloading, not closing the status server before the relaunch, dropping the Host check, not holding a failure, dropping the manifest or its flush. Page: counting the ceiling from the start instead of from silence, ignoring a held failure, dropping the "starting" line, a bar that ignores or overshoots the fraction, the old 5xx probe rule, server sentence instead of catalogue, busy routed to the failure card. Entry point: never opening the page, opening it on the wrong port.

Note for reviewers running the gates locally: make check-commits hardcodes --from origin/main, and check-source-language / check-large-files default COMMIT_RANGE to origin/main..HEAD. Where origin is not GitHub those ranges fail on unrelated commits; pass the GitHub base explicitly.

• Relevant tests pass locally
• Relevant lint / type checks pass locally
• User-facing docs or screenshots are updated when needed

The quick-start's update section (English and Chinese) now covers updating from the page.

Risk

User-visible changes:

• Bare raven opens the browser page instead of the TUI, leaving the resident gateway raven web always leaves. Headless machines keep the TUI; raven tui still names it outright.
• The page upgrade restarts the gateway, briefly disconnecting IM channels. It is refused while any turn, sub-agent or pending question is running.
• During a page-started upgrade the page's port is answered by the upgrade helper (status and 503s) instead of nothing.
• The helper keeps the current version's wheels under ~/.raven/cache/upgrade/<version> (about 75 MB for a release with its engines), because the tool's receipt names them as the install source.
• A raven gateway that starts inside an upgrade window waits it out and exits instead of serving; the supervisor restarts it once the install is whole.

Known edge: running raven web by hand in the seconds between the old supervisor exiting and the new one starting can start a second supervisor beside the relaunched one. The install itself stays protected by the upgrade marker, and the page no longer tells the reader to do this.

• Security impact considered
• Backward compatibility considered
• Rollback path is clear for risky changes

Security: the status endpoint is unauthenticated but loopback-only, answers only the page's own Host (so a rebound host name gets 421), and exposes version numbers and byte counts; the relaunch carries the same token and cookie the raven serve path already did. Rollback: revert the squash commit. Upgrades started from a release without this change keep the old refusal, so there is no mixed-version state to unwind.

Related Issues

N/A

[gloryfromca]

Blocking: a stalled helper can leave the page trapped in the upgrade shade indefinitely.

I reviewed the PR-specific diff against GitHub's actual base (2f5027cdf), plus the requested local github/main...HEAD diff, the upgrade/supervisor callers and history, backward compatibility, test changes, and the repository rules in AGENTS.md, CONTEXT-MAP.md, CONTEXT.md, and ui-web/CONTEXT.md. I found one blocking defect inline; I refuted the other candidates around supervisor teardown, port ownership, socket shutdown, busy-work detection, and the bare-command fallback.

Verification: uv run pytest tests/test_cli_gateway_commands.py tests/test_cli_tui_commands.py tests/test_rpc_serve_control.py tests/test_rpc_system.py tests/test_rpc_transport.py tests/test_updates_upgrade.py -x passed 380 tests after uv sync --extra dev; focused web tests passed 49 tests; the full web suite passed 3,096 tests; TypeScript type-check and RPC generation check passed; ESLint completed with four pre-existing warnings and no errors; source-language and large-file gates passed. The initial Python attempt failed in fixture setup because the default environment lacked raven_everos; no test assertion ran in that attempt.

[gloryfromca]

Blocking: the unchanged progress watcher still treats status-server liveness as progress and can wait forever.

The new revision only compresses the upgrade-helper bootstrap so it fits the Windows command-line limit. I reviewed that delta, its caller and tests, backward compatibility, and the applicable repository rules; the zlib/base64 bootstrap preserves the helper source and leaves substantial room under the platform limit. I found no new issue in this commit. The existing inline blocker remains open because ui-web/src/app/updates.ts is unchanged.

Verification for this revision: uv run pytest tests/test_updates_upgrade.py -x passed 156 tests. The generated bootstrap is 12,953 characters, and a representative fully quoted Windows launch command is 13,323 characters.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

I reviewed the fix delta and re-checked the affected watcher, helper behavior, history, backward compatibility, test changes, architecture boundary, and applicable AGENTS.md/CONTEXT rules. The prior blocker is fixed and its thread is resolved; I found no new plain error.

Verification: npm test -- src/app/updates.test.ts passed 19 tests, and npm run type-check passed.