@openparachute/hub 0.6.3 → 0.6.4-rc.2

package/src/api-modules-ops.ts

@@ -52,6 +52,7 @@ import {
   synthesizeManifestForKnownModule,
 } from "./service-spec.ts";
 import { findService, readManifestLenient, removeService } from "./services-manifest.ts";
+import { enrichedPath } from "./spawn-path.ts";
 import type { ModuleState, SpawnRequest, Supervisor } from "./supervisor.ts";
 import { WELL_KNOWN_PATH, type regenerateWellKnown } from "./well-known.ts";
 
@@ -383,11 +384,95 @@ async function resolveSpawnSpec(
   return composeKnownModuleSpec(km, manifest);
 }
 
+/**
+ * Outcome of `resolveSpawnRequest`: either a freshly-built `SpawnRequest`
+ * (carrying CURRENT env — live `deps.issuer` → `PARACHUTE_HUB_ORIGIN`,
+ * enriched PATH, re-resolved `cwd`) or a structured error the HTTP handler
+ * can return verbatim. A discriminated union so `handleStart` /
+ * `handleRestart` / `runUpgrade` share the resolve-and-rebuild path
+ * without duplicating the not-installed / no-start-cmd error shapes.
+ */
+type ResolveSpawnResult =
+  | { ok: true; req: SpawnRequest }
+  | { ok: false; status: number; code: string; message: string };
+
+/**
+ * Build a `SpawnRequest` for an already-installed module from CURRENT state,
+ * identically to the serve-boot path (PORT / per-service `.env` / live
+ * `PARACHUTE_HUB_ORIGIN` / enriched PATH via the shared
+ * `buildModuleSpawnRequest`). This is the single source of truth the start,
+ * restart, and post-upgrade-restart paths share so each re-injects the
+ * current hub origin + PATH rather than replaying a stale first-start
+ * snapshot (hub#532). `cwd` is re-resolved from the row's `installDir` too,
+ * so a post-upgrade relocation is picked up.
+ *
+ * Returns a structured `{ ok: false }` for the two operator-facing
+ * preconditions the start endpoint already surfaced: 400 `not_installed`
+ * (no services.json row) and 422 `no_start_cmd` (CLI-only / unreadable
+ * module.json). Callers map these to the response shape their surface wants.
+ */
+async function resolveSpawnRequest(
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<ResolveSpawnResult> {
+  const spec = specFor(short);
+
+  // The module must already be installed (present in services.json).
+  const entry = findService(spec.manifestName, deps.manifestPath);
+  if (!entry) {
+    return {
+      ok: false,
+      status: 400,
+      code: "not_installed",
+      message: `${short} is not installed (no services.json entry) — install it first via POST /api/modules/${short}/install`,
+    };
+  }
+
+  // KNOWN_MODULES shorts (vault / scribe / runner): module.json is the
+  // canonical source for startCmd. Re-resolve from
+  // `<installDir>/.parachute/module.json` when installDir is stamped so the
+  // module is authoritative for its own spawn cmd — mirroring runInstall's
+  // post-bun-add re-resolve. Falls back to the imperative `extras.startCmd`
+  // carried by `spec` when installDir is absent or module.json is unreadable.
+  let spawnSpec: ServiceSpec = spec;
+  if (entry.installDir && KNOWN_MODULES[short]) {
+    const resolved = await resolveSpawnSpec(short, entry.installDir);
+    if (resolved) spawnSpec = resolved;
+  }
+
+  const cmd = spawnSpec.startCmd?.(entry);
+  if (!cmd || cmd.length === 0) {
+    return {
+      ok: false,
+      status: 422,
+      code: "no_start_cmd",
+      message: `${short} has no resolvable startCmd (CLI-only module, or <installDir>/.parachute/module.json missing a startCmd)`,
+    };
+  }
+
+  // Build the SpawnRequest identically to the serve-boot path so start,
+  // restart, and post-upgrade-restart produce the same child env (PORT / .env
+  // / live HUB_ORIGIN / enriched PATH). The test-seam / first-boot `spawnEnv`
+  // rides the shared helper's `extraEnv` and wins last, matching
+  // `spawnSupervised`'s precedence.
+  const req = buildModuleSpawnRequest(short, entry, cmd, {
+    configDir: deps.configDir,
+    ...(deps.issuer ? { hubOrigin: deps.issuer } : {}),
+    ...(deps.spawnEnv ? { extraEnv: deps.spawnEnv } : {}),
+  });
+  return { ok: true, req };
+}
+
 function defaultRun(cmd: readonly string[]): Promise<number> {
   // Inherit env so child `bun add` sees TMPDIR, BUN_INSTALL, PARACHUTE_*,
   // etc. set by the Dockerfile / Render env. Bun.spawn defaults to empty
   // env — without this, bun-add fails with cross-mount rename errors on
   // Render (where TMPDIR points at the persistent disk). See hub#349.
+  // PATH: intentionally the raw `process.env` (no per-call `enrichedPath()`).
+  // This is `bun add`, not a module spawn — it doesn't need the operator-tool
+  // dirs (parakeet-mlx / ffmpeg). It still benefits from the serve-startup PATH
+  // enrichment: `serve.ts` applies `enrichedPath()` to `process.env.PATH` at
+  // boot, so the PATH inherited here is already enriched under a managed hub.
   const proc = Bun.spawn([...cmd], {
     stdio: ["ignore", "inherit", "inherit"],
     env: process.env,
@@ -488,7 +573,18 @@ async function spawnSupervised(
   // operator has had a chance to write `configDir/<short>/.env`, so install
   // spawns with install-env only. The per-service `.env` is layered in by
   // `buildModuleSpawnRequest` (serve-boot.ts) on the next `boot` or `start`.
+  // PATH enrichment (hub launchd-PATH regression): mirror the serve-boot path's
+  // `buildModuleSpawnRequest` so a module STARTED from the admin SPA gets the
+  // same operator-tool dirs (`$HOME/.local/bin`, brew bin) as one booted from
+  // services.json — otherwise scribe started via /admin/modules can't find
+  // `parakeet-mlx` / `ffmpeg`. This is the SECOND, independently-built spawn
+  // env; keep it in sync with serve-boot.ts:buildModuleSpawnRequest. `spawnEnv`
+  // (test seam) still wins via the spread below. See `spawn-path.ts`.
+  // `process.env.PATH` may ALREADY be enriched by serve startup (serve.ts);
+  // re-enriching here is a harmless no-op — `enrichedPath` is idempotent
+  // (dedupe + append-only), so double-enrichment can't duplicate or reorder.
   const childEnv: Record<string, string> = {
+    PATH: enrichedPath(),
     PORT: String(entry.port),
     ...(deps.issuer ? { PARACHUTE_HUB_ORIGIN: deps.issuer } : {}),
     ...(deps.spawnEnv ?? {}),
@@ -775,56 +871,40 @@ export async function handleStart(
   const authFail = await authorize(req, deps);
   if (authFail) return authFail;
 
-  const spec = specFor(short);
-
-  // Pure-spawn precondition: the module must already be installed
-  // (present in services.json). `start` never installs — that's the
-  // install endpoint's job, which is far heavier (bun add -g / seed /
-  // stamp). A missing row is an operator error worth a clear message.
-  const entry = findService(spec.manifestName, deps.manifestPath);
-  if (!entry) {
-    return jsonError(
-      400,
-      "not_installed",
-      `${short} is not installed (no services.json entry) — install it first via POST /api/modules/${short}/install`,
-    );
-  }
-
-  // KNOWN_MODULES shorts (vault / scribe / runner): module.json is the
-  // canonical source for startCmd. Re-resolve from
-  // `<installDir>/.parachute/module.json` when installDir is stamped so the
-  // module is authoritative for its own spawn cmd — mirroring runInstall's
-  // post-bun-add re-resolve. Falls back to the imperative `extras.startCmd`
-  // carried by `spec` when installDir is absent or module.json is unreadable.
-  let spawnSpec: ServiceSpec = spec;
-  if (entry.installDir && KNOWN_MODULES[short]) {
-    const resolved = await resolveSpawnSpec(short, entry.installDir);
-    if (resolved) spawnSpec = resolved;
-  }
-
-  const cmd = spawnSpec.startCmd?.(entry);
-  if (!cmd || cmd.length === 0) {
-    return jsonError(
-      422,
-      "no_start_cmd",
-      `${short} has no resolvable startCmd (CLI-only module, or <installDir>/.parachute/module.json missing a startCmd)`,
-    );
+  // Build the SpawnRequest from CURRENT state (live issuer / PATH / .env /
+  // re-resolved startCmd), shared with the restart + post-upgrade-restart
+  // paths so each spawn carries the same fresh env (hub#532). The two
+  // operator-facing preconditions — 400 `not_installed` (no services.json
+  // row; `start` never installs, that's the heavier install endpoint's job)
+  // and 422 `no_start_cmd` (CLI-only / unreadable module.json) — surface as
+  // structured errors here.
+  const resolved = await resolveSpawnRequest(short, deps);
+  if (!resolved.ok) return jsonError(resolved.status, resolved.code, resolved.message);
+  const spawnReq = resolved.req;
+
+  let state: Awaited<ReturnType<typeof deps.supervisor.start>>;
+  try {
+    state = await deps.supervisor.start(spawnReq);
+  } catch (err) {
+    // A spawn-level throw (e.g. Bun.spawn ENOENT because the module's
+    // installDir/cwd no longer exists — the hub#536 wedge) used to escape the
+    // handler as a naked 500 with no JSON body; the CLI then surfaced an
+    // opaque "✗ <short>: request failed" with no actionable next step.
+    // Return the real reason instead.
+    return moduleOpFailure(short, "start", err);
   }
-
-  // Build the SpawnRequest identically to the serve-boot path so `start`
-  // and boot produce the same child env (PORT / .env / HUB_ORIGIN). The
-  // test-seam / first-boot `spawnEnv` rides the shared helper's `extraEnv`
-  // and wins last, matching `spawnSupervised`'s precedence.
-  const spawnReq = buildModuleSpawnRequest(short, entry, cmd, {
-    configDir: deps.configDir,
-    ...(deps.issuer ? { hubOrigin: deps.issuer } : {}),
-    ...(deps.spawnEnv ? { extraEnv: deps.spawnEnv } : {}),
-  });
-
-  const state = await deps.supervisor.start(spawnReq);
   return jsonOk({ short, state });
 }
 
+/**
+ * Map a thrown supervisor-op failure to a structured 500 so the CLI/SPA can
+ * surface the real reason instead of an opaque "request failed" (hub#536).
+ */
+function moduleOpFailure(short: string, op: string, err: unknown): Response {
+  const msg = err instanceof Error ? err.message : String(err);
+  return jsonError(500, "module_op_failed", `${short} ${op} failed: ${msg}`);
+}
+
 /**
  * POST /api/modules/:short/stop — synchronous.
  *
@@ -847,7 +927,12 @@ export async function handleStop(
   const authFail = await authorize(req, deps);
   if (authFail) return authFail;
 
-  const state = await deps.supervisor.stop(short);
+  let state: Awaited<ReturnType<typeof deps.supervisor.stop>>;
+  try {
+    state = await deps.supervisor.stop(short);
+  } catch (err) {
+    return moduleOpFailure(short, "stop", err);
+  }
   if (!state) {
     return jsonOk({ short, stopped: false });
   }
@@ -857,10 +942,19 @@ export async function handleStop(
 /**
  * POST /api/modules/:short/restart — synchronous.
  *
- * Routes through `supervisor.restart(short)` which does stop → await
- * exit → start with the same SpawnRequest. Returns the new state in
- * the body — the UI's spinner can clear as soon as the response
- * arrives, no operation poll needed.
+ * Rebuilds the SpawnRequest from CURRENT state (live `deps.issuer` →
+ * `PARACHUTE_HUB_ORIGIN`, enriched PATH, re-resolved cwd) — identically to
+ * `handleStart` via the shared `resolveSpawnRequest` — and hands it to
+ * `supervisor.restart(short, req)` so the re-spawn re-injects the current
+ * hub origin (hub#532). Before this, restart replayed the env captured at
+ * FIRST start, so an admin-UI restart / `parachute restart <svc>` never
+ * picked up a corrected hub origin (or, since #546, the enriched PATH) —
+ * only `start` and the `expose up` self-heal rebuilt env. The refreshed req
+ * also becomes the supervisor entry's `req`, so subsequent crash-restarts
+ * carry the current env too.
+ *
+ * Returns the new state in the body — the UI's spinner can clear as soon as
+ * the response arrives, no operation poll needed.
  */
 export async function handleRestart(
   req: Request,
@@ -871,7 +965,19 @@ export async function handleRestart(
   const authFail = await authorize(req, deps);
   if (authFail) return authFail;
 
-  const state = await deps.supervisor.restart(short);
+  // Rebuild the spawn env from current state. A `not_installed` row is a 400
+  // (same as `start`); `no_start_cmd` a 422. A module that's installed but
+  // not currently supervised falls through to the 404 `not_supervised` below
+  // (the supervisor returns `undefined`).
+  const resolved = await resolveSpawnRequest(short, deps);
+  if (!resolved.ok) return jsonError(resolved.status, resolved.code, resolved.message);
+
+  let state: Awaited<ReturnType<typeof deps.supervisor.restart>>;
+  try {
+    state = await deps.supervisor.restart(short, resolved.req);
+  } catch (err) {
+    return moduleOpFailure(short, "restart", err);
+  }
   if (!state) {
     return jsonError(
       404,
@@ -1057,7 +1163,16 @@ async function runUpgrade(
     });
   }
 
-  const state = await deps.supervisor.restart(short);
+  // Rebuild the spawn req from post-upgrade state before restarting: a major
+  // bump may have relocated installDir (re-stamped above), so the re-spawn's
+  // cwd must track it, and the restart should carry the live hub origin /
+  // enriched PATH like start does (hub#532). Fall back to a plain replay
+  // restart if the row can't be resolved into a fresh req (shouldn't happen
+  // mid-upgrade, but a missing startCmd shouldn't wedge the upgrade op).
+  const resolved = await resolveSpawnRequest(short, deps);
+  const state = resolved.ok
+    ? await deps.supervisor.restart(short, resolved.req)
+    : await deps.supervisor.restart(short);
   if (!state) {
     registry.update(
       opId,

package/src/api-modules.ts

@@ -243,8 +243,32 @@ interface ModuleWireShape {
   management_url: string | null;
 }
 
+/**
+ * Per-module supervisor snapshot for the `supervised` array (hub#539). The
+ * supervisor-derived subset of `ModuleWireShape` — enough for `status` to
+ * render a run-state row for a module that isn't in the curated catalog.
+ */
+interface SupervisedSnapshotWire {
+  short: string;
+  installed: boolean;
+  installed_version: string | null;
+  supervisor_status: ModuleState["status"] | null;
+  pid: number | null;
+  supervisor_start_error: ModuleStartError | null;
+}
+
 interface ModulesResponse {
   modules: ModuleWireShape[];
+  /**
+   * Run-state for EVERY module the supervisor is currently tracking — not just
+   * the curated `modules` (vault/scribe). Non-curated supervised modules (e.g.
+   * the `surface` UI host) appear here so `parachute status` / the SPA can
+   * reflect their real run-state instead of mislabelling them `inactive`
+   * because they're absent from the curated catalog (hub#539). Curated modules
+   * also appear here (harmless — consumers dedupe by `short`, preferring the
+   * richer `modules` entry). Same supervisor-field shape as a `modules` entry.
+   */
+  supervised: SupervisedSnapshotWire[];
   /**
    * Whether the supervisor is wired into this hub. `false` under
    * `parachute expose` / on-box CLI; the UI greys out install/start
@@ -522,8 +546,20 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     });
   }
 
+  // Every supervised module's run-state — curated AND non-curated (hub#539).
+  // Built from the same supervisor.list() snapshot already in `stateByShort`.
+  const supervised: SupervisedSnapshotWire[] = Array.from(stateByShort.values()).map((s) => ({
+    short: s.short,
+    installed: installedByShort.has(s.short),
+    installed_version: installedByShort.get(s.short)?.version ?? null,
+    supervisor_status: s.status,
+    pid: s.pid ?? null,
+    supervisor_start_error: s.startError ?? null,
+  }));
+
   const body: ModulesResponse = {
     modules,
+    supervised,
     supervisor_available: supervisor !== undefined,
     module_install_channel: getModuleInstallChannel(deps.db),
   };

package/src/auto-wire.ts

@@ -99,6 +99,26 @@ function writeScribeConfig(path: string, token: string): void {
   renameSync(tmp, path);
 }
 
+/**
+ * Read scribe's current `auth.required_token` from `config.json`, or undefined
+ * when the file is absent / malformed / has no auth token. Used by the
+ * serve-boot self-heal to decide whether scribe's config is already in sync
+ * with vault's `.env`.
+ */
+function readScribeAuthToken(path: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    const auth = (parsed as Record<string, unknown>).auth;
+    if (!auth || typeof auth !== "object" || Array.isArray(auth)) return undefined;
+    const token = (auth as Record<string, unknown>).required_token;
+    return typeof token === "string" && token.length > 0 ? token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Mint (or preserve) a shared secret and persist it to vault and scribe, plus
  * pin SCRIBE_URL on vault's side. Caller has already confirmed both services
@@ -182,3 +202,70 @@ export async function autoWireScribeAuth(opts: AutoWireOpts): Promise<AutoWireRe
     restartedVault,
   };
 }
+
+export interface SelfHealScribeAuthResult {
+  /** True when scribe's config.json was written this call (was missing/out-of-sync). */
+  healed: boolean;
+  /**
+   * Why no heal happened (when `healed` is false): "no-token" (vault .env has
+   * no SCRIBE_AUTH_TOKEN — nothing to sync) or "already-synced" (scribe already
+   * carries the same token). Undefined when `healed` is true.
+   */
+  reason?: "no-token" | "already-synced";
+}
+
+/**
+ * Idempotent self-heal of scribe's `auth.required_token`, run on hub `serve`
+ * startup (item H — the loopback-open finding).
+ *
+ * The gap: `autoWireScribeAuth` only fires from `parachute install scribe` (and
+ * the vault↔scribe install pairing). An install that PREDATES auto-wire — or
+ * any path where scribe booted with no `auth.required_token` — leaves scribe
+ * accepting UNAUTHENTICATED transcription requests over loopback forever; the
+ * shared secret never lands in scribe's config even though vault's `.env`
+ * already carries `SCRIBE_AUTH_TOKEN`. Install-time wiring can't fix an
+ * already-installed box.
+ *
+ * The fix mirrors the issuer self-heal in `vault-hub-origin-env.ts`: run on
+ * every `serve` boot, fully idempotent. When vault's `.env` carries a
+ * `SCRIBE_AUTH_TOKEN` AND scribe's `config.json` either lacks
+ * `auth.required_token` or carries a DIFFERENT value, write/sync the vault
+ * value into scribe's config (via `writeScribeConfig`'s merge-don't-clobber
+ * logic — only the auth token is touched, every other config key is preserved).
+ * Vault's `.env` is treated as the source of truth (it's where the operator's
+ * worker reads the secret from). No-op when vault has no token (nothing to
+ * sync) or the two already match. Does NOT restart scribe — `serve` boots the
+ * supervised modules AFTER this runs, so the synced config is read on that
+ * first boot; an already-running scribe (manual start) is the operator's to
+ * restart, same posture as the issuer self-heal.
+ *
+ * Logs only when it actually heals.
+ */
+export function selfHealScribeAuth(opts: {
+  configDir: string;
+  log?: (line: string) => void;
+}): SelfHealScribeAuthResult {
+  const log = opts.log ?? (() => {});
+  const vaultEnvPath = join(opts.configDir, "vault", ".env");
+  const scribeConfigPath = join(opts.configDir, "scribe", "config.json");
+
+  const vaultToken = parseEnvFile(vaultEnvPath).values[SCRIBE_AUTH_ENV_KEY];
+  if (vaultToken === undefined || vaultToken.length === 0) {
+    // Nothing to sync — vault hasn't been wired with a scribe secret. (Either
+    // scribe isn't in use, or auto-wire never ran on either side.)
+    return { healed: false, reason: "no-token" };
+  }
+
+  const scribeToken = readScribeAuthToken(scribeConfigPath);
+  if (scribeToken === vaultToken) {
+    return { healed: false, reason: "already-synced" };
+  }
+
+  writeScribeConfig(scribeConfigPath, vaultToken);
+  log(
+    scribeToken === undefined
+      ? `Self-healed scribe auth: wrote required_token to ${scribeConfigPath} (scribe was running auth-OPEN; synced from vault ${SCRIBE_AUTH_ENV_KEY}).`
+      : `Self-healed scribe auth: re-synced required_token in ${scribeConfigPath} to match vault ${SCRIBE_AUTH_ENV_KEY}.`,
+  );
+  return { healed: true };
+}