@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/commands/install.ts

@@ -4,6 +4,14 @@ import { dirname, join } from "node:path";
 import { autoWireScribeAuth } from "../auto-wire.ts";
 import { bunGlobalPrefixes, isLinked as defaultIsLinkedShared } from "../bun-link.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { type ExposeState, readExposeState } from "../expose-state.ts";
+import {
+  HUB_DEFAULT_PORT,
+  type PidOnPortFn,
+  defaultPidOnPort,
+  readHubPort,
+} from "../hub-control.ts";
+import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
   ModuleManifestError,
@@ -26,8 +34,14 @@ import {
   synthesizeManifestForKnownModule,
 } from "../service-spec.ts";
 import { findService, readManifest, upsertService } from "../services-manifest.ts";
+import {
+  type DisableStaleModuleUnitsOpts,
+  type DisableStaleModuleUnitsResult,
+  disableStaleModuleUnits as defaultDisableStaleModuleUnits,
+} from "../stale-module-units.ts";
+import { type OwnerProbeFn, defaultOwnerOfPid } from "../supervisor.ts";
 import { WELL_KNOWN_PATH } from "../well-known.ts";
-import { start as lifecycleStart } from "./lifecycle.ts";
+import { type LifecycleOpts, start as lifecycleStart } from "./lifecycle.ts";
 import { migrateNotice } from "./migrate.ts";
 import {
   type InteractiveAvailability,
@@ -215,6 +229,60 @@ export interface InstallOpts {
    * leave it false so today's behavior is unchanged.
    */
   noCreate?: boolean;
+  /**
+   * `parachute install vault --interactive` (#579 / #580 item 1): opt back into
+   * the FULL interactive module setup — the service's own `spec.init` (vault's
+   * vault-name prompt, "install as MCP in Claude Code?", "mint an API token?")
+   * and, for vault, its self-registered standalone daemon.
+   *
+   * Default: false. The manual `parachute install <svc>` path is now LIGHT
+   * (matching `parachute init`'s Step 2.5): install the package, seed/register
+   * services.json, start under the supervisor, and print a short guidance block
+   * pointing at the admin UI + the optional extras (`parachute-vault
+   * mcp-install`, token minting in the UI). No interactive interview, no
+   * vault-side daemon registration that would race the supervisor for :1940.
+   *
+   * The old "drag me through the full init" behavior is opt-in via this flag.
+   * When `true` AND the spec ships an `init` command, install runs `spec.init`
+   * as it did pre-#579. When `false` (the default) for a module whose `init`
+   * would otherwise run an interview, install SKIPS `spec.init` (the
+   * `noCreate`-equivalent quiet path) and emits the guidance block instead.
+   *
+   * Orthogonal to `noCreate` (which `parachute init` uses to ALSO skip the
+   * post-install start). The light manual path still starts the module under
+   * the supervisor; only the interactive interview is suppressed.
+   */
+  interactive?: boolean;
+  /**
+   * Test seam for the supervised-hub probe + admin-URL resolution that drive
+   * the light-install guidance block. Production reads the real expose-state /
+   * hub-port / hub-unit deps; tests inject deterministic values so the guidance
+   * assertions don't depend on the operator's live box.
+   */
+  guidanceCtx?: {
+    /** Is a hub unit installed (→ supervised box)? Defaults to the real probe. */
+    hubUnitInstalled?: boolean;
+    /** Hub-unit deps for the real `isHubUnitInstalled` probe. */
+    hubUnitDeps?: HubUnitDeps;
+    /** Live expose state (→ public admin URL). Defaults to `readExposeState()`. */
+    exposeState?: ExposeState | undefined;
+    /** Hub loopback port for the admin URL fallback. Defaults to `readHubPort()`. */
+    hubPort?: number | undefined;
+  };
+  /**
+   * Test seam for the install-time stale-unit sweep (#580 item 3). Production
+   * wires `disableStaleModuleUnits` (the #522 migrate/teardown sweep, reused
+   * verbatim — known-module shorts only, hub + cloudflared skipped, idempotent,
+   * non-fatal). Tests inject a fake so no real launchctl/systemctl runs and the
+   * sweep's invocation (and logged actions) can be asserted.
+   *
+   * The sweep fires only when a supervised hub is present (the same
+   * `guidanceCtx.hubUnitInstalled` discriminant) and the module is being
+   * started — a leftover standalone `parachute-<short>` unit (KeepAlive /
+   * RunAtLoad) would otherwise keep an unsupervised module bound to the port,
+   * crash-looping the supervisor's own child (the #580 field signature).
+   */
+  disableStaleModuleUnits?: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
   /**
    * `parachute install scribe` only: pre-pick the transcription provider so
    * the prompt doesn't fire. Validated against scribe's known providers — an
@@ -239,6 +307,22 @@ export interface InstallOpts {
    * unless the test populates services.json directly.
    */
   portProbe?: (port: number) => Promise<boolean>;
+  /**
+   * Test seam for the install-time port-squatter naming (#590 item 2). When the
+   * canonical port walk has to assign a fallback port because the canonical one
+   * is held, this looks up the pid LISTENing on the canonical port so the
+   * warning can name the holder (`pid 1234 (bun .../vault/src/server.ts)`) — the
+   * same #581 `pidOnPort` / `ownerOfPid` seams the supervisor start-path uses,
+   * reused (not duplicated). Detection-only — never kills. Production wires
+   * `defaultPidOnPort` (`lsof -ti :<port>`); tests inject a deterministic stub.
+   */
+  pidOnPort?: PidOnPortFn;
+  /**
+   * Test seam for the install-time port-squatter naming (#590 item 2): the
+   * best-effort command line of the squatting pid. Production wires
+   * `defaultOwnerOfPid` (`ps -o command= -p <pid>`); tests inject a stub.
+   */
+  ownerOfPid?: OwnerProbeFn;
   /**
    * Test seam for reading `<packageDir>/.parachute/module.json`. Production
    * uses the real file reader; tests inject a map from package-dir → manifest
@@ -553,6 +637,111 @@ function resolveInstallTarget(
   return { kind: "npm", packageName: input };
 }
 
+/**
+ * Build the LifecycleOpts the install auto-start uses (hub#573).
+ *
+ * The auto-start MUST thread the SAME supervisor + migrate-offer opts the
+ * production CLI dispatch passes for `parachute start <svc>` (cli.ts:
+ * `supervisor: {}` + `migrateOffer: { enabled: true }`). Without them, `start`
+ * resolved `unitInstalled` to its omitted-supervisor default of `false` and
+ * `migrateOffer.enabled` to `false` — so the auto-start ALWAYS took the no-unit
+ * path, printed "No supervised hub unit is installed. Run `parachute migrate
+ * --to-supervised`…", and returned non-zero → the "⚠ didn't start cleanly"
+ * warning. Meanwhile `parachute migrate` (which DOES run the real
+ * `isHubUnitInstalled` probe + /health) reported the unit already installed +
+ * healthy: the two paths disagreed because only `migrate` opted into real
+ * detection. `supervisor: {}` makes the auto-start run the same probe;
+ * `migrateOffer: { enabled: true }` makes it offer the cutover on a genuinely-
+ * unmigrated box instead of dumping a bare error mid-install.
+ *
+ * Exported so the convergence is unit-testable without driving a real start.
+ */
+export function defaultStartLifecycleOpts(ctx: {
+  manifestPath: string;
+  configDir: string;
+  log: (line: string) => void;
+}): LifecycleOpts {
+  return {
+    manifestPath: ctx.manifestPath,
+    configDir: ctx.configDir,
+    log: ctx.log,
+    supervisor: {},
+    migrateOffer: { enabled: true },
+  };
+}
+
+/**
+ * Read the expose-state, swallowing a malformed-file error to undefined so the
+ * guidance block degrades to the loopback admin URL instead of throwing mid-
+ * install. Mirrors init's tolerant read of the same file.
+ */
+function safeReadExposeState(): ExposeState | undefined {
+  try {
+    return readExposeState();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the canonical admin URL the light-install guidance points at — the
+ * SAME resolution `parachute init` uses (`init.ts:resolveAdminUrl`): the live
+ * expose-state public FQDN when the hub is exposed, otherwise the loopback
+ * `http://127.0.0.1:<port>/admin/`. Kept as a thin local copy (rather than
+ * importing init.ts) so the install command doesn't pull in the wizard module
+ * graph; the shape is asserted against init's in tests.
+ */
+function resolveGuidanceAdminUrl(
+  exposeState: ExposeState | undefined,
+  hubPort: number | undefined,
+): string {
+  if (exposeState?.canonicalFqdn) {
+    return `https://${exposeState.canonicalFqdn}/admin/`;
+  }
+  return `http://127.0.0.1:${hubPort ?? HUB_DEFAULT_PORT}/admin/`;
+}
+
+/**
+ * The post-install guidance block for the LIGHT manual install path (#579).
+ *
+ * Replaces the old interactive interview ("name your vault / install MCP / mint
+ * a token") with a short pointer to where the operator manages + creates vaults
+ * (the admin UI) plus one-liners for the optional extras they used to be dragged
+ * through up front. Aaron's framing: "I just wanna install vault and then I'm
+ * managing it through the UI" — the install confirms the module is up and tells
+ * them where to go next, no token minted, no MCP wired, until they ask.
+ *
+ * Returns an empty array for modules that don't carry the interactive-init
+ * footprint (so the generic `postInstallFooter` stays the surface for those).
+ *
+ * VAULT-ONLY for now, intentionally (N4). Vault is the only SERVICE_SPECS module
+ * that ships an interactive `spec.init` today, so it's the only one whose light
+ * path drops an interview that needs replacing with guidance. When a FUTURE
+ * module ships its own `spec.init` (and thus takes the light-path skip), add its
+ * guidance arm HERE — or, if the per-module copy starts to diverge meaningfully,
+ * lift the guidance text onto the ServiceSpec shape (e.g. a
+ * `lightInstallGuidance?: (adminUrl) => string[]` extra) so each module owns its
+ * own next-steps block instead of this central switch. The empty-array fallback
+ * keeps every other module silent here regardless.
+ */
+export function buildLightInstallGuidance(short: string, adminUrl: string): string[] {
+  if (short === "vault") {
+    return [
+      "",
+      "Vault is installed and running under the hub supervisor.",
+      "Manage + create vaults in the admin UI:",
+      `  ${adminUrl}`,
+      "",
+      "Optional, when you want them (not needed to start):",
+      "  • Connect a vault to Claude Code:  parachute-vault mcp-install",
+      "  • Mint an API token for other MCP clients: do it from the admin UI (Tokens).",
+      "",
+      "Run the full interactive setup instead with: parachute install vault --interactive",
+    ];
+  }
+  return [];
+}
+
 export async function install(input: string, opts: InstallOpts = {}): Promise<number> {
   const runner = opts.runner ?? defaultRunner;
   const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
@@ -733,7 +922,35 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
       ? spec.manifestName
       : manifest.name;
 
-  if (spec.init && !opts.noCreate) {
+  // Whether to run the module's interactive `spec.init` (#579 / #580 item 1).
+  //
+  // The manual `parachute install <svc>` path is now LIGHT by default: we do
+  // NOT drag the operator through `spec.init`'s interview (for vault: vault-name
+  // prompt, "install as MCP?", "mint a token?", and a self-registered standalone
+  // daemon that would race the supervisor for :1940). The operator installs the
+  // module and manages it from the admin UI. `spec.init` runs ONLY when the
+  // caller explicitly opts back in with `--interactive` (and isn't in the
+  // `noCreate` quiet path the wizard uses). Modules without a `spec.init` are
+  // unaffected — there's no interview to suppress.
+  const runInteractiveInit = spec.init !== undefined && opts.interactive === true && !opts.noCreate;
+  if (runInteractiveInit && spec.init) {
+    // Reviewer surprise 2 / #580: the interactive path runs the module's OWN
+    // init, which (for vault today) registers a standalone platform daemon
+    // (launchd KeepAlive / systemd Restart=always). On a SUPERVISED hub that
+    // daemon races the supervisor for the module's port — the exact #580
+    // EADDRINUSE-crash-loop condition the light path avoids by not running init.
+    // Warn so an operator who reaches for --interactive on a supervised box
+    // knows to pass the daemon-off flag (or prefer the light default).
+    const supervisedForWarn =
+      opts.guidanceCtx?.hubUnitInstalled ??
+      (opts.guidanceCtx !== undefined || manifestPath === SERVICES_MANIFEST_PATH
+        ? isHubUnitInstalled(opts.guidanceCtx?.hubUnitDeps ?? defaultHubUnitDeps)
+        : false);
+    if (supervisedForWarn) {
+      log(
+        `⚠ --interactive runs ${short}'s own setup, which may register a standalone daemon. On a supervised hub that daemon races the supervisor for ${short}'s port (#580). Prefer the light default, or pass --no-autostart through to ${short}'s init.`,
+      );
+    }
     // Forward --vault-name from the InstallOpts when set so `parachute setup`
     // (and any future programmatic caller) can pre-answer the name prompt.
     const initCmd =
@@ -748,6 +965,15 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   } else if (spec.init && opts.noCreate) {
     log(`(skipping ${spec.init.join(" ")} — --no-create: module installed, no instance created)`);
+  } else if (spec.init) {
+    // Light path: the module ships an interactive init but the operator didn't
+    // ask for it. Skip the interview; the guidance block at the end of install
+    // tells them where to manage + create instances. The supervisor (started
+    // below) owns the lifecycle, so vault's own daemon registration is
+    // deliberately NOT triggered here — that's the :1940 race #580 fixed.
+    log(
+      `(skipping ${spec.init.join(" ")} — manage ${short} from the admin UI; re-run with --interactive for the full setup)`,
+    );
   }
 
   // Hub-as-port-authority (#53): pick the service's port now and reflect it
@@ -770,6 +996,25 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   });
   if (portResult.warning) {
     log(`⚠ ${portResult.warning}`);
+    // #590 item 2: the canonical port was held, so we walked to a fallback. Name
+    // the squatter — the supervisor start-path does this post-#581; do it here at
+    // install-time too. Reuse the #581 pidOnPort / ownerOfPid seams (detection
+    // only; never kill). When the holder is a foreign pid (not one of OUR rows —
+    // which is the common case when a stale pre-supervisor daemon is squatting),
+    // surface its pid + command line + a hint.
+    if (canonicalPort !== undefined && portResult.source !== "canonical") {
+      const pidOnPort = opts.pidOnPort ?? defaultPidOnPort;
+      const ownerOfPid = opts.ownerOfPid ?? defaultOwnerOfPid;
+      const holder = pidOnPort(canonicalPort);
+      if (holder !== undefined) {
+        const cmdline = ownerOfPid(holder);
+        const who = cmdline ? `pid ${holder} (${cmdline})` : `pid ${holder}`;
+        log(`  canonical port ${canonicalPort} is held by ${who}.`);
+        log(
+          `  This may be a stale pre-supervisor daemon. If so, stop it (kill ${holder}) and re-run \`parachute install ${entryName}\` to reclaim the canonical port.`,
+        );
+      }
+    }
   }
 
   // Find-or-seed the manifest entry. Re-read after the seed write so a silent
@@ -870,6 +1115,40 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   const notice = migrateNotice(configDir, now());
   if (notice) log(notice);
 
+  // Install-time stale-unit sweep (#580 item 3 / #522 part 2). Before we start
+  // the module under the supervisor, disable any leftover STANDALONE per-module
+  // autostart unit (a pre-supervisor `parachute-<short>.service` with
+  // Restart=always, or a `computer.parachute.<short>` LaunchAgent with
+  // KeepAlive). Such a unit keeps RESPAWNING an unsupervised module that binds
+  // the module's port; the supervised child then EADDRINUSE-crash-loops and
+  // lands `crashed` — the recurring field signature in #580 / #522. Reuses the
+  // exact #522 migrate/teardown sweep (`disableStaleModuleUnits`): known-module
+  // shorts only, hub + cloudflared explicitly skipped, idempotent (already-
+  // disabled/absent = silent no-op), non-fatal (a failed disable warns +
+  // continues). Gated on a supervised hub being present — on a non-supervised
+  // box the per-module unit IS the legitimate lifecycle and we must not touch
+  // it. Only runs on the start path (skipped under --no-start / --no-create).
+  const willStart = !opts.noStart && !opts.noCreate;
+  if (willStart) {
+    const gctx = opts.guidanceCtx;
+    const sweepAllowed =
+      opts.disableStaleModuleUnits !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
+    const supervisedForSweep =
+      gctx?.hubUnitInstalled ?? isHubUnitInstalled(gctx?.hubUnitDeps ?? defaultHubUnitDeps);
+    if (sweepAllowed && supervisedForSweep) {
+      const sweep = opts.disableStaleModuleUnits ?? defaultDisableStaleModuleUnits;
+      const result = sweep({ log: (l) => log(l) });
+      const disabled = result.actions.filter((a) => a.result === "disabled");
+      if (disabled.length > 0) {
+        log(
+          `Swept ${disabled.length} stale per-module autostart unit(s) so the supervisor owns the port(s): ${disabled
+            .map((a) => a.unit)
+            .join(", ")}.`,
+        );
+      }
+    }
+  }
+
   // Auto-start: vault and notes' inits historically left a daemon running, but
   // scribe (and any service without a daemon-launching init) didn't — so
   // launch-day `install scribe` ended with a silent install and the user
@@ -883,7 +1162,8 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   if (!opts.noStart && !opts.noCreate) {
     const startService =
       opts.startService ??
-      ((short: string) => lifecycleStart(short, { manifestPath, configDir, log }));
+      ((short: string) =>
+        lifecycleStart(short, defaultStartLifecycleOpts({ manifestPath, configDir, log })));
     const startCode = await startService(short);
     if (startCode !== 0) {
       log(`⚠ ${short} didn't start cleanly. Run manually: parachute start ${short}`);
@@ -898,6 +1178,44 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     for (const line of footer) log(line);
   }
 
+  // Light-install guidance block (#579 / #580 item 1). When we suppressed the
+  // module's interactive init (light path: it ships an init, the operator
+  // didn't pass --interactive, and this isn't the wizard's noCreate path),
+  // replace the absent interview with a short pointer to the admin UI + the
+  // optional extras. Skipped for --interactive (the service's own footer
+  // covers it) and for noCreate (the wizard prints its own admin URL).
+  //
+  // INFORMATIONAL, independent of the start path (N3): this block is *guidance*,
+  // not an action, so it deliberately does NOT gate on `willStart` /
+  // `!opts.noStart` the way the stale-unit sweep above does. Even under
+  // `--no-start` (CI / piped installs) the operator still benefits from "here's
+  // where to manage it once it's up" — the admin URL + extras are equally true
+  // whether or not THIS invocation started the daemon.
+  //
+  // The supervised-hub probe + admin-URL resolution touch real on-disk state
+  // (the hub plist / expose-state / hub-port file). Gate the production probe
+  // on `manifestPath === SERVICES_MANIFEST_PATH` — the same isolation gate the
+  // well-known regen uses — so a test driving install against a tempdir
+  // manifestPath never reads the operator's real `~/.parachute`. Tests opt into
+  // the guidance assertions by passing `guidanceCtx` explicitly.
+  const guidanceProbeAllowed =
+    opts.guidanceCtx !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
+  if (spec.init && !opts.interactive && !opts.noCreate && guidanceProbeAllowed) {
+    const gctx = opts.guidanceCtx;
+    const supervised =
+      gctx?.hubUnitInstalled ?? isHubUnitInstalled(gctx?.hubUnitDeps ?? defaultHubUnitDeps);
+    // Only emit the "managed under the supervisor" guidance when there's a
+    // supervised hub to manage it through. On a non-supervised box (no hub
+    // unit) the admin UI may not be reachable, so we stay quiet and let the
+    // generic install output stand — the operator can run --interactive.
+    if (supervised) {
+      const exposeState = gctx && "exposeState" in gctx ? gctx.exposeState : safeReadExposeState();
+      const hubPort = gctx && "hubPort" in gctx ? gctx.hubPort : readHubPort(configDir);
+      const adminUrl = resolveGuidanceAdminUrl(exposeState, hubPort);
+      for (const line of buildLightInstallGuidance(short, adminUrl)) log(line);
+    }
+  }
+
   // Final registration check — the service may have written its own
   // authoritative entry during init or first boot, replacing the seed (or
   // filling a gap when the service had no seedEntry). Re-read at exit so the

package/src/commands/migrate-cutover.ts

@@ -86,6 +86,7 @@ import { type PortListeningFn, defaultPortListening } from "../port-probe.ts";
 import { type AliveFn, clearPid, readPid } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import { enrichedUnitPath } from "../spawn-path.ts";
 import {
   type DisableStaleModuleUnitsOpts,
   type DisableStaleModuleUnitsResult,
@@ -232,14 +233,14 @@ export interface WriteUnitResult {
  * and `installManagedUnit(start:false)` — daemon-reload / write-the-plist but
  * NEVER enable --now / bootstrap. The §7.1 step-2 race-avoider.
  */
-function defaultUnitPath(bunInstall: string): string {
-  return `${bunInstall}/bin:/usr/local/bin:/usr/bin:/bin`;
-}
-
 export function defaultWriteUnitWithoutStarting(opts: WriteUnitOpts): WriteUnitResult {
   const { deps } = opts;
   const bunInstall = `${deps.homeDir()}/.bun`;
-  const path = defaultUnitPath(bunInstall);
+  // Shared with the init-bringup path (hub-unit.ts) so the two unit-generation
+  // sites can't drift — enriches the unit PATH with operator-tool dirs
+  // (`$HOME/.local/bin`, brew bin) so a migrated launchd/systemd hub can find
+  // scribe's `parakeet-mlx` + `ffmpeg`. See `spawn-path.ts`.
+  const path = enrichedUnitPath(bunInstall, deps.homeDir(), deps.platform);
   const logPath = `${opts.parachuteHome}/hub/logs/hub.log`;
   let unit: ManagedUnit;
   try {
@@ -878,6 +879,12 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
     log("The supervised hub unit is gone. To run the hub now, either:");
     log("  - `parachute serve` (foreground), or");
     log("  - `parachute migrate --to-supervised` to reinstall the unit.");
+  } else if (res.messages.length > 0) {
+    // removed === false WITH detail: a real removal failure, not a clean
+    // no-op. Surface the reason rather than the misleading "nothing was
+    // installed" line (hub#534 — the CLI also maps this to a non-zero exit).
+    log("Hub-unit teardown did not complete:");
+    for (const m of res.messages) log(`  ${m}`);
   } else {
     log("No hub unit was installed — nothing to tear down.");
   }

package/src/commands/serve-boot.ts

@@ -27,6 +27,7 @@ import {
   shortNameForManifest,
 } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import { enrichedPath } from "../spawn-path.ts";
 import type { Supervisor } from "../supervisor.ts";
 
 export interface BootOpts {
@@ -75,9 +76,14 @@ export interface BuildSpawnRequestOpts {
  * Env layering (later wins):
  *   1. `PORT` from the services.json `entry.port` — overrides hub's own PORT
  *      so supervised children honor their canonical port assignment
- *      (hub#356/#357).
+ *      (hub#356/#357). This is authoritative and is NOT overridable by a
+ *      `.env` `PORT` (see below) — services.json is the single source of truth
+ *      for the port (scribe#41 4-tier ladder; hub#206).
  *   2. per-service `.env` at `<configDir>/<short>/.env` — operator-configured
- *      values (e.g. scribe provider keys) override the bare PORT.
+ *      values (e.g. scribe provider keys) merge on top. A `PORT` key here is
+ *      dropped: a stale pre-#206 `.env` `PORT` must not shadow `entry.port`
+ *      (hub#537 — a leftover scribe `PORT=1944` ≠ services.json `1943` leaked
+ *      into the injected PORT and broke the supervisor's readiness probe).
  *   3. `PARACHUTE_HUB_ORIGIN` = `opts.hubOrigin` — anchors the child's `iss`
  *      expectation to the value hub mints with (hub#365).
  *   4. `opts.extraEnv` — test seam / first-boot pass-through; wins last.
@@ -93,7 +99,31 @@ export function buildModuleSpawnRequest(
   opts: BuildSpawnRequestOpts,
 ): SpawnReqShape {
   const fileEnv = readEnvFileValues(join(opts.configDir, short, ".env"));
-  const env: Record<string, string> = { PORT: String(entry.port), ...fileEnv };
+  // Drop a `PORT` from the per-service .env: services.json `entry.port` is the
+  // canonical port and must win (scribe#41 ladder; hub#206). A stale pre-#206
+  // `.env` PORT (e.g. scribe's `1944` vs services.json `1943`) would otherwise
+  // leak into the injected PORT and the supervisor's readiness probe would
+  // check the wrong port → false `started_but_unbound` (hub#537). The module's
+  // own resolvePort ladder already prefers services.json, so this keeps the
+  // injected PORT + probe in agreement with what the child actually binds.
+  const { PORT: _staleEnvPort, ...fileEnvSansPort } = fileEnv;
+  // PATH enrichment (hub launchd-PATH regression): the hub unit bakes a minimal
+  // PATH and `Bun.spawn` defaults to empty env, so without this the child only
+  // ever sees the unit's PATH — which omits `$HOME/.local/bin` (scribe's
+  // `parakeet-mlx`) + the Homebrew bin (`ffmpeg`), killing transcription on
+  // canonical installs. `enrichedPath` appends those dirs (when they exist) to
+  // the inherited PATH; inherited entries keep their order. A per-service `.env`
+  // PATH (operator intent) still wins via the spread below. See `spawn-path.ts`.
+  // The API-start path builds its own env — see `api-modules-ops.ts`
+  // `spawnSupervised`, which calls `enrichedPath()` too (keep the two in sync).
+  // `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 env: Record<string, string> = {
+    PATH: enrichedPath(),
+    PORT: String(entry.port),
+    ...fileEnvSansPort,
+  };
   if (opts.hubOrigin) env[HUB_ORIGIN_ENV] = opts.hubOrigin;
   if (opts.extraEnv) Object.assign(env, opts.extraEnv);