PAB-58: move startup orchestration out of middleware

[pablopunk]

What changed?
Moved the server startup orchestration from the middleware into a dedicated bootstrap module. This improves responsiveness by ensuring the application is available for setup/login as soon as the database is ready—background services like Docker, OpenCode, and Tailscale now start asynchronously without blocking HTTP requests.

Why?

• Production entrypoint: The Astro/Node standalone adapter has no application runtime‑start hook. Previously, the entire startup (including Docker, OpenCode, Tailscale, etc.) ran inside middleware, delaying the first request until everything was ready. Now a lightweight fallback in the middleware triggers a fire‑and‑forget bootstrap, while the request path only waits for database migrations.
• Development: Bootstrap is now triggered via a new Astro integration (astro:server:setup hook), decoupling startup from the middleware even in dev mode.

Key changes

• New bootstrap system (src/server/bootstrap/)
  • astro-integration.ts – triggers bootstrap during development via astro:server:setup.
  • coordinator.ts – orchestrates startup operations with retry/cooldown logic; treats Docker, Tailscale, prewarm, and defaults as detached/non‑fatal, while database and OpenCode failures are fatal.
  • housekeeping.ts – manages periodic session cleanup independently of requests.
  • process-state.ts – global singleton that survives Vite HMR and owns all timers/shutdown registrations.
• Middleware simplified (src/middleware.ts)
  • Removed the monolithic ensureInitialized() function.
  • Calls startServerBootstrap() at module evaluation (one‑time, fire‑and‑forget).
  • getSetupNeeded() now only awaits ensureDatabaseReady(); the heavy background startup no longer blocks authentication or setup routing.
• Configuration (astro.config.ts)
  • Registers the serverBootstrapIntegration to hook into the dev server lifecycle.
• Documentation (README.md)
  • Added a “Server startup” section explaining the dual boot paths and request blocking guarantees.

Impact

• Requests reach setup/login faster – they only wait for database readiness, not for Docker/OpenCode/other services.
• Background startup failures are contained: non‑critical failures are logged but never break the request path; critical failures (OpenCode) are retried with a cooldown.
• The system is more resilient under production deployments that lack startup hooks.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
doce-dev-www	Ready	Preview, Comment	Jul 17, 2026 3:56pm

[kody-ai]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	❌
Security	✅
Business Logic	❌

Access your configuration settings here.

​