@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

package/src/api-account.ts

@@ -55,12 +55,15 @@ import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import { changePasswordRateLimiter } from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { findActiveSession } from "./sessions.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
 import {
   PASSWORD_MAX_LEN,
   UserNotFoundError,
+  type VaultVerb,
   getUserById,
   isFirstAdmin,
   validatePassword,
+  vaultVerbsForUserVault,
   verifyPassword,
 } from "./users.ts";
 
@@ -489,6 +492,15 @@ export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Respo
   const adminFlag = isFirstAdmin(deps.db, user.id);
   const csrf = ensureCsrfToken(req);
   const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  // Per-vault mintable verbs for the "mint an access token" affordance on each
+  // tile. Reads the assignment role (today always write → ["read", "write"])
+  // so the UI only ever offers a verb the POST handler would accept. Empty for
+  // the admin / no-vault branches (no assigned vaults to iterate).
+  const mintableVerbs: Record<string, VaultVerb[]> = {};
+  for (const v of user.assignedVaults) {
+    const verbs = vaultVerbsForUserVault(deps.db, user.id, v);
+    if (verbs && verbs.length > 0) mintableVerbs[v] = verbs;
+  }
   return htmlResponse(
     renderAccountHome({
       username: user.username,
@@ -497,6 +509,8 @@ export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Respo
       hubOrigin: deps.hubOrigin,
       isFirstAdmin: adminFlag,
       csrfToken: csrf.token,
+      twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
+      mintableVerbs,
     }),
     200,
     extra,

package/src/api-mint-token.ts

@@ -8,10 +8,31 @@
  *   - the future admin SPA when the operator wants to mint a one-shot
  *     scope-narrow token without dropping to a terminal.
  *
- * Auth: `Authorization: Bearer <token>` where `token`'s `scope` claim
- * contains `parachute:host:auth`. The operator's local operator.token
- * (admin scope-set) covers this; a narrow `--scope-set=auth` operator
- * token also covers this.
+ * Auth — capability attenuation: any bearer may mint a token whose authority
+ * is a SUBSET of its own. A requested scope `s` is grantable (`canGrant`) iff:
+ *
+ *   1. `s` is requestable AND the bearer holds `parachute:host:auth`
+ *      — host:auth mints any requestable scope (vault/scribe verbs, etc.).
+ *   2. `s` is `vault:<N>:admin` AND the bearer holds `parachute:host:admin`
+ *      — box-wide admin attenuates to one named vault's admin.
+ *   3. `s` is `vault:<N>:<verb>` (verb ∈ read/write/admin) AND the bearer
+ *      holds `vault:<N>:admin` for the SAME `<N>` — a vault-admin attenuates
+ *      to any same-vault subset, including an equal-level admin.
+ *
+ * Otherwise `s` is refused (400 `invalid_scope`). This single rule subsumes
+ * the former two-part guard: the old hard `parachute:host:auth` gate is now
+ * rule 1, and PR-A's `host:admin → vault:<name>:admin` carve-out (hub#449) is
+ * now rule 2. Rule 3 is new — it lets a `vault:<name>:admin` bearer mint
+ * same-vault sub-tokens (the canonical headless path to per-vault admin,
+ * replacing deprecated `pvt_*` — vault#282 — and the path the SPA tokens
+ * page uses via session → /admin/host-admin-token → here). Cross-vault and
+ * host-authority escalation are always blocked: a `vault:work:admin` bearer
+ * can never mint `vault:other:*` or any `parachute:host:*`.
+ *
+ * Entry gate: the bearer must hold at least one minting authority —
+ * `parachute:host:auth`, `parachute:host:admin`, or some `vault:<*>:admin`.
+ * A bearer with none (e.g. a read-only token) gets 403 `insufficient_scope`
+ * before any per-scope check; it cannot mint anything.
  *
  * Why a separate endpoint instead of extending /admin/host-admin-token:
  * that endpoint is session-cookie-gated for the SPA's needs and only
@@ -26,14 +47,38 @@
 import type { Database } from "bun:sqlite";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
-import { isNonRequestableScope } from "./scope-explanations.ts";
+import {
+  MINT_HOST_ADMIN_SCOPE,
+  MINT_HOST_AUTH_SCOPE,
+  canGrant,
+  hasMintingAuthority,
+} from "./scope-attenuation.ts";
+import {
+  isVaultAdminScope,
+  isWellFormedOrNonVaultScope,
+  vaultScopeName,
+} from "./scope-explanations.ts";
+
+// Re-export `canGrant` so existing importers (and the symmetric revoke path)
+// have a single name to reach for; the implementation lives in the shared
+// `scope-attenuation.ts` module alongside `hasMintingAuthority`.
+export { canGrant } from "./scope-attenuation.ts";
 
 /** Default lifetime when --expires-in / `expires_in` is omitted. Matches the CLI. */
 export const API_MINT_TOKEN_DEFAULT_TTL_SECONDS = 90 * 24 * 60 * 60;
 /** Hard cap. Matches the CLI's --expires-in upper bound. */
 export const API_MINT_TOKEN_MAX_TTL_SECONDS = 365 * 24 * 60 * 60;
-/** Scope required on the bearer token to call this endpoint. */
-export const API_MINT_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+/**
+ * Bearer scope that authorises minting any *requestable* scope (rule 1 of the
+ * attenuation model). Re-exported alias of the shared `MINT_HOST_AUTH_SCOPE`
+ * for back-compat with existing importers.
+ */
+export const API_MINT_TOKEN_HOST_AUTH_SCOPE = MINT_HOST_AUTH_SCOPE;
+/**
+ * Bearer scope that authorises minting `vault:<name>:admin` (rule 2).
+ * Re-exported alias of the shared `MINT_HOST_ADMIN_SCOPE`.
+ */
+export const API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE = MINT_HOST_ADMIN_SCOPE;
 /** client_id stamped on minted tokens. Matches the CLI flow's value. */
 export const API_MINT_TOKEN_CLIENT_ID = "parachute-hub";
 
@@ -87,12 +132,17 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
   }
 
-  // 3. Scope gate.
-  if (!bearerScopes.includes(API_MINT_TOKEN_REQUIRED_SCOPE)) {
+  // 3. Entry gate — the bearer must hold at least one minting authority
+  //    (`parachute:host:auth`, `parachute:host:admin`, or some
+  //    `vault:<*>:admin`). A bearer with none can mint nothing under the
+  //    attenuation model, so we 403 before per-scope checks. Per-scope
+  //    grantability (which authority covers which scope) is enforced below
+  //    via `canGrant`.
+  if (!hasMintingAuthority(bearerScopes)) {
     return jsonError(
       403,
       "insufficient_scope",
-      `bearer token lacks ${API_MINT_TOKEN_REQUIRED_SCOPE}`,
+      `bearer token holds no minting authority (need ${API_MINT_TOKEN_HOST_AUTH_SCOPE}, ${API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE}, or vault:<name>:admin)`,
     );
   }
 
@@ -117,19 +167,40 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     return jsonError(400, "invalid_request", "scope must contain at least one scope");
   }
 
-  // Privilege-diffusion guard: mint paths cannot themselves mint tokens
-  // carrying non-requestable scopes (parachute:host:admin, the host:*
-  // narrow scopes, vault:<name>:admin). Holder of `parachute:host:auth`
-  // can mint vault/scribe/agent verb scopes for downstream services, but
-  // cannot mint another `:auth` (or any other non-requestable) without
-  // forced re-auth via the operator.token rotation path. Same set the
-  // public OAuth flow already rejects.
-  const blocked = scopes.filter((s) => isNonRequestableScope(s));
+  // Shape guard (defensive hygiene — adversarial audit 2026-05-28): reject any
+  // scope that is shaped like a *named* per-vault scope but malformed —
+  // `vault:work:ADMIN` (uppercase verb), `vault::admin` (empty name),
+  // `vault:work:read:admin` (extra segment), `VAULT:work:admin` (uppercase
+  // resource). These slip past `isNonRequestableScope`'s strict regexes, so
+  // `canGrant` rule 1 would admit them as "requestable" and mint a junk
+  // registry row. They grant zero access today (the vault consumer's
+  // `decomposeVaultScope` rejects all four), so this is NOT exploitable now —
+  // the check is a backstop against a future consumer-normalization regression
+  // plus registry hygiene. It's an input-shape check, orthogonal to authority,
+  // so it runs for ALL callers before any `canGrant` attenuation. Non-vault
+  // scopes and the unnamed `vault:<verb>` forms are unaffected.
+  const malformed = scopes.filter((s) => !isWellFormedOrNonVaultScope(s));
+  if (malformed.length > 0) {
+    return jsonError(
+      400,
+      "invalid_scope",
+      `malformed vault scope ${malformed.join(", ")}; expected vault:<name>:<read|write|admin>`,
+    );
+  }
+
+  // Capability-attenuation guard: every requested scope must be a subset of
+  // the bearer's own authority under `canGrant` (rules in the file docstring).
+  // A `parachute:host:auth` bearer mints any requestable scope; a
+  // `parachute:host:admin` bearer additionally mints `vault:<name>:admin`; a
+  // `vault:<name>:admin` bearer mints same-vault subsets only. Anything else
+  // — host:* escalation, cross-vault, a non-requestable with no covering
+  // authority — is blocked. One blocked scope rejects the whole request.
+  const blocked = scopes.filter((s) => !canGrant(bearerScopes, s));
   if (blocked.length > 0) {
     return jsonError(
       400,
       "invalid_scope",
-      `scope ${blocked.join(", ")} is not requestable via mint-token; use OAuth flow or operator rotation`,
+      `scope ${blocked.join(", ")} is not grantable by this bearer; use OAuth flow or operator rotation`,
     );
   }
 
@@ -183,6 +254,40 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     permissionsCanonical = JSON.stringify(permissionsClaim);
   }
 
+  // Derive the `vault_scope` pin. Collect the set of vault names `<N>` from
+  // every requested `vault:<N>:<verb>` scope that was authorized via a
+  // vault-scoped authority — rule 2 (host:admin → vault:<N>:admin) or rule 3
+  // (vault:<N>:admin → same-vault subset). These are the vault-scoped mints,
+  // so we pin the token to those vault(s): it can ONLY ever be used against
+  // them (defense-in-depth + least privilege), matching the canonical
+  // session-path mint in `admin-vault-admin-token.ts`.
+  //
+  // Pure `parachute:host:auth` requestable mints (a `vault:<N>:read/write`
+  // granted by rule 1 with no covering vault-admin authority) stay UNpinned
+  // (`[]`) — the "no per-user restriction" sentinel; the scope string +
+  // audience are the authorization-bearing gate there, as before. We
+  // distinguish by checking the bearer's own vault-scoped authority: a vault
+  // name is pinned only when the bearer held `vault:<N>:admin` (rule 3) or
+  // host:admin and the scope is admin (rule 2).
+  //
+  // Note: `audience` is single-valued and `inferAudience` is first-wins, so a
+  // multi-vault request gets `aud=vault.<first>` and only authenticates
+  // against that vault. Mint one token per vault for the multi-vault case.
+  // The canonical consumers (mcp-install, SPA tokens page) request a single
+  // vault.
+  const bearerHasHostAdmin = bearerScopes.includes(API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE);
+  const vaultScopePinSet = new Set<string>();
+  for (const s of scopes) {
+    const name = vaultScopeName(s);
+    if (name === null) continue;
+    const grantedByVaultAdminBearer = bearerScopes.includes(`vault:${name}:admin`); // rule 3
+    const grantedByHostAdminForAdmin = isVaultAdminScope(s) && bearerHasHostAdmin; // rule 2
+    if (grantedByVaultAdminBearer || grantedByHostAdminForAdmin) {
+      vaultScopePinSet.add(name);
+    }
+  }
+  const vaultScopePin = [...vaultScopePinSet];
+
   // 6. Mint + register.
   const minted = await signAccessToken(deps.db, {
     sub: subject,
@@ -192,11 +297,14 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     issuer: deps.issuer,
     ttlSeconds,
     // Operator-driven CLI/API mint — the bearer already cleared the
-    // `parachute:host:auth` privilege gate, so there's no per-user vault
-    // pin to enforce. Empty `vault_scope` is the "no restriction"
-    // sentinel; the `scopes` themselves remain authorization-bearing as
-    // before.
-    vaultScope: [],
+    // attenuation guard. `vault_scope` is `[]` (no restriction) for any
+    // verb scope granted by rule 1, or the named vault(s) for vault-scoped
+    // mints authorized via rule 2 / rule 3 (see above). The pin tracks the
+    // grant rule, not the bearer: a host:admin bearer minting
+    // `vault:work:write` goes through rule 1 (write is requestable), so it
+    // ALSO gets `vault_scope:[]` — only its `vault:work:admin` mints (rule 2)
+    // are pinned.
+    vaultScope: vaultScopePin,
     ...(permissionsClaim !== undefined ? { extraClaims: { permissions: permissionsClaim } } : {}),
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });

package/src/api-modules-ops.ts

@@ -35,6 +35,7 @@
 import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
+import { MissingDependencyError, type MissingDependencyWire } from "@openparachute/depcheck";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
@@ -49,11 +50,7 @@ import {
   getSpec,
   synthesizeManifestForKnownModule,
 } from "./service-spec.ts";
-import {
-  findService,
-  readManifestLenient,
-  removeService,
-} from "./services-manifest.ts";
+import { findService, readManifestLenient, removeService } from "./services-manifest.ts";
 import type { ModuleState, SpawnRequest, Supervisor } from "./supervisor.ts";
 import { WELL_KNOWN_PATH, type regenerateWellKnown } from "./well-known.ts";
 
@@ -81,6 +78,15 @@ export interface Operation {
   log: string[];
   /** Error message when status is `failed`. Mirrored from the underlying throw. */
   error?: string;
+  /**
+   * Structured error detail when the failure is a known typed error — today
+   * only `MissingDependencyError.toWire()` (a missing external binary like
+   * `bun` / `git` during install). The operations-polling SPA switches on
+   * `error_detail.error_type === "missing_dependency"` to render a dedicated
+   * install card; the plain `error` string is the fallback for everything
+   * else. Wire shape matches `@openparachute/depcheck`'s `MissingDependencyWire`.
+   */
+  error_detail?: MissingDependencyWire;
   startedAt: string;
   finishedAt?: string;
 }
@@ -89,7 +95,11 @@ export interface OperationsRegistry {
   create(kind: OperationKind, short: string): Operation;
   get(id: string): Operation | undefined;
   /** Append a log line + (optionally) advance status. */
-  update(id: string, patch: Partial<Pick<Operation, "status" | "error">>, logLine?: string): void;
+  update(
+    id: string,
+    patch: Partial<Pick<Operation, "status" | "error" | "error_detail">>,
+    logLine?: string,
+  ): void;
 }
 
 /**
@@ -122,11 +132,16 @@ class InMemoryOperationsRegistry implements OperationsRegistry {
     return this.ops.get(id);
   }
 
-  update(id: string, patch: Partial<Pick<Operation, "status" | "error">>, logLine?: string): void {
+  update(
+    id: string,
+    patch: Partial<Pick<Operation, "status" | "error" | "error_detail">>,
+    logLine?: string,
+  ): void {
     const op = this.ops.get(id);
     if (!op) return;
     if (patch.status) op.status = patch.status;
     if (patch.error !== undefined) op.error = patch.error;
+    if (patch.error_detail !== undefined) op.error_detail = patch.error_detail;
     if (logLine) op.log.push(logLine);
     if (patch.status === "succeeded" || patch.status === "failed") {
       op.finishedAt = this.clock().toISOString();
@@ -520,13 +535,37 @@ export async function handleInstall(
   // immediately + the work runs in the background. Errors get logged
   // to the operation; nothing throws back to the request handler.
   void runInstall(op.id, short, spec, deps, bodyChannel).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    registry.update(op.id, { status: "failed", error: msg }, `install failed: ${msg}`);
+    failOperation(registry, op.id, "install", err);
   });
 
   return acceptedOp(op.id);
 }
 
+/**
+ * Mark an async op failed, attaching the structured `error_detail` wire when
+ * the underlying throw is a `MissingDependencyError` (a missing external
+ * binary like `bun` / `git` during install). The operations-polling SPA reads
+ * `error_detail` to render the dedicated install card; the plain `error`
+ * string is the fallback for every other failure.
+ */
+function failOperation(
+  registry: OperationsRegistry,
+  opId: string,
+  verb: string,
+  err: unknown,
+): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (err instanceof MissingDependencyError) {
+    registry.update(
+      opId,
+      { status: "failed", error: msg, error_detail: err.toWire() },
+      `${verb} failed: ${err.binary} not installed`,
+    );
+    return;
+  }
+  registry.update(opId, { status: "failed", error: msg }, `${verb} failed: ${msg}`);
+}
+
 /**
  * Internal install runner. Exported so non-API callers (the first-boot
  * wizard at `/admin/setup`, hub#259) can drive the same install →
@@ -722,8 +761,7 @@ export async function handleUpgrade(
   const spec = specFor(short);
 
   void runUpgrade(op.id, short, spec, deps).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    registry.update(op.id, { status: "failed", error: msg }, `upgrade failed: ${msg}`);
+    failOperation(registry, op.id, "upgrade", err);
   });
   return acceptedOp(op.id);
 }

package/src/api-modules.ts

@@ -3,10 +3,12 @@
  *
  * Combines three sources into a single per-module row:
  *
- *   - **Curated availability** — vault, notes, scribe, runner (the v0.6
- *     release bar). The Phase-2 marketplace will broaden this; for now
- *     it's hardcoded so the admin UI has a stable "what can I install?"
- *     list even on a fresh container where services.json is empty.
+ *   - **Curated availability** — vault, scribe (the launch focus per
+ *     Aaron 2026-05-27). The list was previously broader; trimmed for
+ *     the launch arc. The Phase-2 marketplace will broaden this; for
+ *     now it's hardcoded so the admin UI has a stable "what can I
+ *     install?" list even on a fresh container where services.json is
+ *     empty.
  *   - **Installed state** — services.json reads (version, installDir).
  *   - **Supervisor state** — per-module run status (`running` / `stopped`
  *     / `crashed` / `starting` / `restarting`) + pid. Absent when the
@@ -80,15 +82,30 @@ function lookupModule(
 export const API_MODULES_REQUIRED_SCOPE = "parachute:host:auth";
 
 /**
- * Curated module short-names for v0.6 Render self-host. Marketplace is
- * Phase 2 — until then, the admin UI offers exactly these. Order is the
- * recommended install order (vault → app → notes → scribe → runner;
- * app auto-bootstraps notes-ui on first boot — `notes` here is the
- * notes-daemon back-compat install path retained for operators still on
- * the pre-app architecture; scribe + runner come last because they
- * depend on a working vault + app to be useful).
+ * Curated module short-names. The admin UI offers exactly these for install
+ * + management. Order is the recommended install order (vault first, scribe
+ * second).
+ *
+ * Trimmed 2026-05-27 (Aaron-directed launch focus) from the prior set of
+ * `["vault", "surface", "notes", "scribe", "runner"]`. The dropped modules
+ * are still published on npm and still work — they're just not the focus:
+ *
+ *   - `notes` (notes-daemon): retired. Notes-UI now lives at
+ *     `notes.parachute.computer` as a hosted SPA — operators don't install
+ *     a notes daemon anymore. The npm package `@openparachute/notes-ui`
+ *     is a library imported by `parachute-surface` and by custom-surface
+ *     builders.
+ *   - `surface` (host module): de-emphasized. `@openparachute/surface-client`
+ *     remains the canonical library for folks building their own UIs
+ *     against a Parachute hub; running the surface-host module on your
+ *     own box is no longer the headline path (use notes.parachute.computer
+ *     or build your own).
+ *   - `runner`: experimental, not in the focus set for launch.
+ *
+ * Re-adding any of these is one line — keep the list small until use
+ * cases demand otherwise.
  */
-export const CURATED_MODULES = ["vault", "surface", "notes", "scribe", "runner"] as const;
+export const CURATED_MODULES = ["vault", "scribe"] as const;
 export type CuratedModuleShort = (typeof CURATED_MODULES)[number];
 
 export interface ApiModulesDeps {

package/src/api-ready.ts

@@ -0,0 +1,102 @@
+/**
+ * `GET /api/ready` — hub-side boot-readiness probe (hub#443).
+ *
+ * Public (no bearer required) — used by:
+ *
+ *   1. The transient-state HTML page rendered by the upstream-error
+ *      flow (see `proxy-error-ui.ts`). Its inline poll script hits this
+ *      endpoint every 2s up to 5 times so a wizard mid-boot can refresh
+ *      itself without an HTML reload.
+ *   2. Any third-party tool (smoke test, dashboard) that wants to know
+ *      whether the hub's modules are all up.
+ *
+ * Shape:
+ *
+ *     {
+ *       "ready": boolean,
+ *       "ready_modules": string[],         // shorts that are up
+ *       "transient_modules": string[],     // shorts currently booting
+ *       "persistent_modules": string[]     // shorts crashed / stopped
+ *     }
+ *
+ * `ready: true` iff every supervised module is in the "running" state
+ * past its boot window AND no module is in transient/persistent
+ * failure. The hub itself is implicit — if you reached this endpoint,
+ * hub is up.
+ *
+ * Why public: the page that polls this is itself served pre-auth (a
+ * 503 from a proxied request before the operator has even reached
+ * /login). Bearer-gating would make the poll fail and the page sit
+ * forever on "still loading."
+ */
+
+import { DEFAULT_BOOT_WINDOW_MS } from "./proxy-state.ts";
+import type { Supervisor } from "./supervisor.ts";
+
+export interface ApiReadyDeps {
+  /** Container-mode supervisor handle. When absent the hub is in CLI
+   *  mode and we report ready=true (we have no visibility into other
+   *  processes' boot state). */
+  supervisor?: Supervisor;
+  /** Test seam over Date.now. */
+  now?: () => number;
+  /** Test seam over the boot window. */
+  bootWindowMs?: number;
+}
+
+export function handleApiReady(req: Request, deps: ApiReadyDeps = {}): Response {
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    return new Response("method not allowed", { status: 405 });
+  }
+  const now = (deps.now ?? Date.now)();
+  const bootWindow = deps.bootWindowMs ?? DEFAULT_BOOT_WINDOW_MS;
+
+  const ready: string[] = [];
+  const transient: string[] = [];
+  const persistent: string[] = [];
+
+  if (deps.supervisor) {
+    for (const m of deps.supervisor.list()) {
+      switch (m.status) {
+        case "starting":
+        case "restarting":
+          transient.push(m.short);
+          break;
+        case "crashed":
+        case "stopped":
+          persistent.push(m.short);
+          break;
+        case "running": {
+          // Inside the boot window we report transient even though the
+          // process is "running" — the listener may not have bound yet.
+          // After the window we report ready (process is up + presumed
+          // listening; if it's not, the proxy classifier still catches
+          // it via the same window check and surfaces persistent state).
+          let startedMs = 0;
+          if (m.startedAt) {
+            const parsed = Date.parse(m.startedAt);
+            if (Number.isFinite(parsed)) startedMs = parsed;
+          }
+          if (startedMs > 0 && now - startedMs < bootWindow) {
+            transient.push(m.short);
+          } else {
+            ready.push(m.short);
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  const isReady = transient.length === 0 && persistent.length === 0;
+  const body = JSON.stringify({
+    ready: isReady,
+    ready_modules: ready,
+    transient_modules: transient,
+    persistent_modules: persistent,
+  });
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}