[KevinHuSh]

Summary

The installers stop telling you what to run and run it. install.sh ends with
raven web --stop && raven web --foreground, so a finished install is the page
open in a browser rather than a hint to go and type something; first-run setup
is walked through by the page's own onboarding. The capability summary, the
upgrade-versus-first-run wording and the config.json probe that fed it go with
it. install.ps1 mirrors all of this, with one deliberate divergence: a
non-zero page exit only warns there, because under irm | iex that is the
reader's own interactive PowerShell and Ctrl-C, the ordinary way to end a
foreground page, returns non-zero.

Two gaps that only bite a source install are closed on the way:

• build_web_assets compares each artifact against its sources instead of only
  testing that it exists. An editable install relinks Python and nothing else,
  so ui-tui/dist/entry.js and ui-web/dist/index.html kept serving whatever
  the tree held at first install while every .py beside them moved on. The
  page watches i18n/ too, since ui-web/build.py inlines the catalogue.
  node_modules, dist and .modern are pruned: npm ci rewrites the first
  on every build, and the other two hold the artifact being judged.
• A node packaged without npm now fetches a private runtime that carries one.
  Debian and Ubuntu split the two packages, so a system node >= 22 satisfied
  ensure_node and the build then found no npm with no private runtime ever
  provisioned. The download body is split out as provision_private_node and
  called from the build probe as well, subshelled so a failure there is a
  skipped build rather than a failed install. It stays lazy rather than moving
  into ensure_node, so a wheel install that never runs npm does not pay for a
  50 MB download it has no use for.

Both READMEs are reordered and the clone install is documented under Quick
Start, where it was missing: ./install.sh and a piped run do different things
from inside a checkout, because local mode requires $0 to be a real file, and
RAVEN_LOCAL_SRC is the opt-out. The Chinese README also picks up the EverMind
ecosystem table the English one had already moved to.

One test changed rather than being deleted. test_readme_quickstart_matches_the_installer_hint
required an Onboard and run heading in both READMEs; the installers no longer
close with a first-run hint and neither README carries that section, so the pin
had no subject left. It is repointed at what the two must still agree on, which
is the clone install.

install.ps1 has not been parsed or executed. There is no pwsh on the machine
this was written on and no PowerShell step in CI, so every Windows change here
is reviewed by eye and pinned by text tripwires only. A real Windows run before
release would be worth it.

Type

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

Verification

uv run python -m pytest tests/ --ignore=tests/integration on the merged tree:
23161 passed, 109 skipped.

uv run pytest tests/test_install_script.py: 27 passed, including a functional
test that extracts the real is_stale and resolve_node_dir from install.sh
and runs them under sh. is_stale is checked across missing artifact, fresh
artifact, touched page source, touched catalogue, and build output touched;
resolve_node_dir across system node with npm, node without npm, node without
npm and a failed fetch, and no node at all. Both were mutation-checked: removing
the fallback line from install.sh turns the new tests red.

sh -n install.sh, make check-source-language, make check-large-files,
ruff check, ruff format --check: all clean.

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

Risk

User-visible: a finished install now holds the terminal on a running page
instead of returning to the prompt. That also means the installer's exit code is
the gateway's, so on a clone where the page build only warned, install.sh now
exits 1 with "No page is built" where it used to exit 0 with a working TUI. A
re-run over a checkout that has moved on will rebuild the frontend, which costs
an npm ci it used to skip.

Rollback is per commit: the launch, the rebuild-on-change and the npm fallback
are independent edits to install.sh and install.ps1 and can be reverted
separately. No runtime code outside the installers changed.

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

Related Issues

N/A

[gloryfromca]

Blocking: the stop/relaunch sequence can start a page-only process while the old gateway is still shutting down.

I reviewed the current github/main...HEAD diff, the installer callers and raven web lifecycle, relevant history, backward compatibility, test changes, and the repository rules/context. The inline finding is the only blocker I found.

Verification: uv run pytest tests/test_install_script.py -x passed (27 tests); uv run --with-editable ./plugins-dist/everos-memory python -m pytest tests/test_cli_onboard_commands.py -x passed (332 tests); sh -n install.sh, the source-language check, and the large-file check passed. The initial combined pytest invocation did not collect because the fresh environment lacked raven_everos; supplying that local plugin produced the passing result above. PowerShell is unavailable in this environment, so install.ps1 was reviewed by inspection.

[gloryfromca]

Blocking: the previously reported stop/relaunch lock race remains unchanged.

This head only merges the latest main; the PR's six-file diff, including the installer sequence covered by the open thread, is unchanged from the prior revision. I reviewed the merge delta, the current PR diff and history, the relevant architecture/context constraints and callers, backward compatibility, repository rules, and whether the tests were weakened. I found no new issues, but the existing blocker still applies and its thread remains open.

Verification on this merged tree: uv run --frozen --python 3.12 --all-extras pytest tests/test_install_script.py tests/test_cli_onboard_commands.py -x passed (359 tests); sh -n install.sh, the source-language check, and the large-file check passed.

[gloryfromca]

Blocking: the previously reported stop/relaunch lock race is still present.

The only delta from the prior reviewed head removes trailing whitespace in README.md; neither installer nor its tests changed, so the existing open finding remains applicable. I reviewed the revision delta, the current PR diff and history, callers and architecture/context constraints, backward compatibility, repository rules, and test integrity. I found no new issues and am leaving the existing thread open.

Verification on this head: uv run --frozen --python 3.12 --all-extras pytest tests/test_install_script.py tests/test_cli_onboard_commands.py -x passed (359 tests); sh -n install.sh, the source-language check, and the large-file check passed.

[gloryfromca]

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

The stop path now waits for the processes it signalled, fails closed on timeout, and therefore covers both installers through their shared raven web --stop call. I verified the resident supervisor topology with real processes: stop returned 0 after teardown, the gateway lock was gone, and the next launch selected the full gateway child. I replied to and resolved my prior thread.

I reviewed the revision delta and current PR diff, relevant history and callers, repository rules and context/architecture constraints, backward compatibility, and test integrity. No new findings remain.

Verification: uv run --frozen --python 3.12 --all-extras pytest tests/test_install_script.py tests/test_cli_onboard_commands.py tests/test_cli_serve_commands.py -x passed (437 tests); shell syntax, source-language, large-file, commit-message, PR-title, and diff-whitespace checks passed.

[0xKT]

**Not a blocker -- the staleness check is right, and I tried hard to break it. One line throws away the only channel the step it guards uses to report failure.

install.sh:590 redirects away the message its own sibling says must not be swallowed

"$bin" web --stop >/dev/null && "$bin" web --foreground

raven web --stop reports on stdout (typer.echo), so >/dev/null discards exactly the two messages this new step cannot afford to lose. The contract is not something I am importing from outside -- it is written in this PR's own changed set, in raven/cli/serve_commands.py:

# Reported, not swallowed: a relaunch from here lands on serve and the page comes up without channels, which is worse than refusing to start. (:909-911)

and eight hundred lines earlier the same file names the caller it was written for:

A caller that stops and relaunches back to back -- raven web --stop && raven web --foreground, which is what install.sh runs (:867-869)

Two branches, and the second is the one that matters:

• fatal (:912-913): prints error: still running after 20s: ..., exits 1. && short-circuits and set -eu (install.sh:26) ends the installer having printed nothing after Starting Raven -- your browser will open in a moment. The user gets a non-zero exit and no reason.
• warning (:895, :907): prints warning: could not stop the supervisor/gateway (pid N): ... and still exits 0. && proceeds into --foreground, which finds the gateway that was not stopped, prints attaching to the gateway already running: ... and returns 0. The install ends on the previous build's page and claims success -- which is the exact outcome "rebuild what moved on" exists to prevent.

Measured, not argued. A harness running launch_web extracted verbatim from install.sh (sha of the copy matched git show HEAD:install.sh), with only $HOME, uv and a raven shim faked:

shim behaviour	installer exit	what the user saw
stop rc=0	0	the start line, then the page
stop rc=1, message on stdout (what typer.echo does)	1	the start line, and nothing else
stop rc=1, same message on stderr	1	error: still running after 20s: ... survives

The stdout/stderr pair is the control: the loss is caused by the redirect, not by set -e. And a probe of the real _stop_resident() (with _pid_alive forced true, os.kill a no-op, no process signalled) put the message on STDOUT with exit 1, so the stream is not an assumption either.

install.ps1:650-654 turns the same non-zero into Write-Warn "could not clear the gateway a previous install left running; start the page with 'raven web'". So today the two installers disagree about whether the reader is told anything at all.

Dropping the redirect, or sending it to stderr, restores the channel. Nothing else in the step needs to change.

Related, same line: nothing pins the &&. A test that asserts --foreground does not run when --stop fails would catch both this and a future edit that turns it into ;.

What I could not break

The staleness rule. install.sh:200-210 claims mtime is the right question because git stamps every file it rewrites. I built the input designed to refute that -- a checkout that moves a source file backwards in history, where the content is older than the artifact by every measure except mtime -- in a throwaway git repo, driving is_stale extracted verbatim:

after building on the tip:            FRESH
after checking out the OLD content:   STALE   <- mtime caught the backwards move
artifact rebuilt:                     FRESH
checkout of an unchanged file:        FRESH   <- git rewrote nothing, no needless rebuild
checkout restoring CHANGED content:   STALE

Both halves hold. The input set is right too: ui-web/build.py:37 reads i18n/messages.json, which is why install.sh:250 and install.ps1:352 add $src/i18n to the page's sources; the TUI does not need it because ui-tui/src/i18n/messages.generated.ts is committed and arrives with any catalogue change.

On commitlint.config.cjs

I came to this one expecting to find a repo-wide rule relaxed so this PR's own commits would pass, and it is not that. The addition is

const ROOT_SURFACES = ["installer"];

with a comment giving the reason, and it follows a pattern the file already established: TOP_LEVEL_TREES has carried ui-web for a long time, and PRODUCTS and the wheel distributions are not raven/ subpackages either. One entry in an existing shape, with its rationale written down, is not moving the goalposts.

Worth saying while we are here, and not this PR's debt: AGENTS.md:172 still reads "scope -- a top-level subpackage of raven/", which stopped describing this config several scope groups ago. The file, not the doc, is what CI enforces.

Two things I am not filing, recorded so they are not lost

• install.ps1's staleness walk does not prune below depth 1, so ui-tui/packages/hermes-ink/node_modules (28 entries in package-lock.json) gets walked where install.sh:187-196 prunes those names at any depth. I have no PowerShell on this machine and will not guess Windows behaviour; the consequence points at an unnecessary rebuild, never a stale page.
• install.sh drops the ~/.local/bin PATH warning with no replacement, while install.ps1:671 kept an actual fix (Add-ProcessPath) that works there because irm | iex runs in the reader's own session. A POSIX script cannot edit its parent shell's PATH, and the installer now ends by running the page, so the immediate need is gone -- but the next raven in a fresh terminal is on the reader to find.