TypeError on startup with Starlette >=1.0: Starlette.__init__() got an unexpected keyword argument 'on_startup'

[francip]

Symptom

Running ./run-dashboard.sh (or uvicorn app:app) against a venv that has Starlette 1.0+ installed crashes immediately:

File "/.../hermesdashboard/app.py", line 3987, in <module>
    app = Starlette(routes=routes, on_startup=[_run_startup_session_metadata_backfill])
TypeError: Starlette.__init__() got an unexpected keyword argument 'on_startup'

Cause

Starlette removed the deprecated on_startup / on_shutdown constructor kwargs in 1.0.0 (they had been deprecated for years in favor of the lifespan context manager). app.py:3987 still uses the legacy kwarg.

requirements.txt declares starlette>=0.37 with no upper bound, so a fresh install via pip install -r requirements.txt resolves to Starlette 1.0.0 and immediately breaks.

Repro

python3.11 -m venv /tmp/hd-venv
/tmp/hd-venv/bin/pip install -r requirements.txt
/tmp/hd-venv/bin/python -m uvicorn app:app --host 127.0.0.1 --port 8081

Confirmed:

• Starlette 0.52.1 → starts cleanly
• Starlette 1.0.0 → TypeError above

Suggested fixes

Either is fine, the second is the proper fix:

1. Quick: pin starlette>=0.37,<1.0 in requirements.txt.
2. Proper: migrate app.py to the lifespan API:

   from contextlib import asynccontextmanager
   
   @asynccontextmanager
   async def lifespan(app):
       await _run_startup_session_metadata_backfill()
       yield
   
   app = Starlette(routes=routes, lifespan=lifespan)

   (Wrap the existing startup callable in an async wrapper if it isn't already a coroutine.)

Environment

• macOS 15 (Darwin 25.4.0), Python 3.11.13
• hermesdashboard main @ a1bdba6
• Hermes agent venv had Starlette 1.0.0, which is what surfaced this