@openparachute/hub 0.5.2 → 0.5.7

package/src/commands/expose.ts

@@ -17,39 +17,47 @@ import {
   stopHub,
 } from "../hub-control.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { HUB_MOUNT, HUB_PATH, writeHubFile } from "../hub.ts";
+import { HUB_PATH, writeHubFile } from "../hub.ts";
 import { type AliveFn, processState } from "../process-state.ts";
-import { effectivePublicExposure, shortNameForManifest } from "../service-spec.ts";
+import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
 import { type ServeEntry, bringupCommand, teardownCommand } from "../tailscale/commands.ts";
 import { getFqdn, isTailscaleInstalled } from "../tailscale/detect.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
+import type { VaultAuthStatus } from "../vault/auth-status.ts";
 import {
   WELL_KNOWN_DIR,
   WELL_KNOWN_MOUNT,
   WELL_KNOWN_PATH,
   buildWellKnown,
-  isVaultEntry,
   shortName,
   writeWellKnownFile,
 } from "../well-known.ts";
+import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
 import { restart } from "./lifecycle.ts";
 
 /**
  * Two exposure layers share a single tailscale serve config on this node.
  * Public layer adds `--funnel` to each handler; everything else is identical.
  *
- * Funnel constraint: Tailscale allows at most three public HTTPS ports per
- * node (443, 8443, 10000). Path-routing packs every service onto a single
- * port — that's why we default to one `--https=443` and mount services under
- * `/vault`, `/notes`, etc. rather than giving each service its own port or
- * subdomain. Subdomain-per-service requires the Tailscale Services feature
- * (virtual-IP advertisement) and is deferred.
+ * Single-rule shape: tailnet bringup emits exactly one `tailscale serve`
+ * mount — `/ → http://127.0.0.1:<hubPort>/`. The hub does all internal
+ * routing per request: hub UI, OAuth, well-known, vault SPA + per-vault
+ * proxy, and generic services.json-driven `/<svc>/*` dispatch. Layer
+ * detection (loopback / tailnet / public) and `publicExposure` enforcement
+ * also live in the hub (`layerOf` + `effectivePublicExposure`), so this
+ * plan layer no longer partitions services up-front. Cloudflare ingress
+ * shipped the same shape on 0.5.2 in #178; this closes the symmetry.
  *
- * Hub + well-known entries are HTTP proxies to an internal Bun.serve (see
- * `hub-control.ts`). They used to be `--set-path=<mount> <file>` entries but
- * macOS `tailscaled` runs sandboxed and can't read arbitrary files; proxy
- * mode is the only reliable shape.
+ * Funnel constraint, mostly historical now: Tailscale allows at most three
+ * public HTTPS ports per node (443, 8443, 10000). With one rule there is
+ * one port — symbolic but the constraint is what motivated path-routing
+ * over subdomain-per-service in the first place.
+ *
+ * Hub mount is an HTTP proxy to the internal Bun.serve (see `hub-control.ts`).
+ * Used to be `--set-path=<mount> <file>` entries but macOS `tailscaled` runs
+ * sandboxed and can't read arbitrary files; proxy mode is the only reliable
+ * shape.
  */
 
 export interface ExposeOpts {
@@ -92,6 +100,18 @@ export interface ExposeOpts {
    * spawning real child processes.
    */
   restartService?: (short: string) => Promise<number>;
+  /**
+   * Override `~/.parachute/vault` for the 2FA-enrollment probe on the public
+   * (Funnel) layer. Tests point at a tmp dir; production omits and the probe
+   * defaults to the resolved vault home. (#186)
+   */
+  vaultHome?: string;
+  /**
+   * Pre-computed vault auth status, primarily for tests. When set,
+   * `printPublic2FAWarning` consults this instead of reading
+   * `<vaultHome>/config.yaml` from disk. (#186)
+   */
+  vaultAuthStatus?: VaultAuthStatus;
 }
 
 /**
@@ -104,166 +124,49 @@ export interface ExposeOpts {
 const HUB_DEPENDENT_SHORTS = ["vault"] as const;
 
 /**
- * OAuth paths the hub serves natively. The mount path is what clients see;
- * the target is the hub's loopback origin (where `hub-server.ts` is
- * listening). tailscale strips the mount before forwarding, so the target
- * must include the same path so the hub-server router sees the full URL.
- *
- * Pre-cli#58 (PR (c)) these were proxied to vault's `/vault/<name>/oauth/*`
- * handlers; after PR (c) the hub IS the OAuth IdP and vault validates
- * hub-issued JWTs (vault#169).
+ * Single tailscale serve mount: `/ → http://127.0.0.1:<hubPort>/`. The hub
+ * dispatches everything internally (hub page, /admin, /api, /hub SPA, /oauth,
+ * /.well-known, /vault SPA + proxy, /vaults POST, generic /<svc>/*), so the
+ * tailscale plan stays at this single rule regardless of how many services
+ * are installed. `publicExposure: "loopback"` enforcement happens inside the
+ * hub via `layerOf` — see `proxyToService` / `proxyToVault` in hub-server.ts.
  */
-const OAUTH_PATHS = [
-  "/.well-known/oauth-authorization-server",
-  "/oauth/authorize",
-  "/oauth/token",
-  "/oauth/register",
-] as const;
+const HUB_CATCHALL_MOUNT = "/";
 
 /**
- * Single tailscale serve mount that catches every `/vault/<name>/...` request
- * and routes it through the hub. The hub then reads services.json on each
- * request to pick the right vault backend (#144). Consolidating to one mount
- * means `parachute vault create techne` is reachable on the tailnet without
- * re-running `parachute expose` — only the hub-internal lookup needs to know
- * about the new path.
- *
- * Trailing slash distinguishes the mount from `/vaults` (the create-vault
- * POST endpoint, an exact-match on hub).
+ * Warn (but don't rewrite) for legacy `paths: ["/"]` entries. Pre-#144 these
+ * were remapped to `/<shortname>` so they didn't collide with the hub page
+ * at `/`. Now that the entire tailnet is one catchall to the hub, the hub
+ * dispatches by services.json `paths[]` per request — a `paths: ["/"]` entry
+ * still wouldn't route correctly, but the failure is hub-side rather than a
+ * tailscale plan collision. Emit the warning so operators know to re-install.
  */
-const VAULT_MOUNT = "/vault/";
-
-/**
- * Remap legacy `paths: ["/"]` entries to `/<shortname>` so they don't collide
- * with the hub page at `/`. Emits a warning per remapped service. This is the
- * transitional path for services installed before the vault PR that writes
- * `paths: ["/vault/<default>"]` — once `parachute install` is re-run those
- * entries update themselves and this branch goes dormant.
- */
-function remapLegacyRoot(
-  services: readonly ServiceEntry[],
-  log: (line: string) => void,
-): ServiceEntry[] {
-  return services.map((s) => {
-    const first = s.paths[0];
-    if (first !== "/") return s;
+function warnLegacyRoot(services: readonly ServiceEntry[], log: (line: string) => void): void {
+  for (const s of services) {
+    if (s.paths[0] !== "/") continue;
     const sn = shortName(s.name);
-    const remapped = `/${sn}`;
     log(
-      `note: ${s.name} claims "/"; hub page lives there — exposing at "${remapped}" instead. Re-run \`parachute install ${sn}\` to update services.json.`,
+      `note: ${s.name} claims "/"; hub page lives there — re-run \`parachute install ${sn}\` to update services.json.`,
     );
-    return { ...s, paths: [remapped, ...s.paths.slice(1)] };
-  });
-}
-
-/**
- * Partition services into ones that will be mounted on the layer versus ones
- * that stay loopback-only. "allowed" services go on the serve plan; every
- * other effective exposure state (explicit loopback, explicit auth-required,
- * spec-default auth-required) is withheld. Hidden services still appear in
- * services.json so on-box callers reach them at http://127.0.0.1:<port>.
- */
-interface ExposurePartition {
-  exposed: ServiceEntry[];
-  hidden: Array<{ entry: ServiceEntry; reason: string }>;
-}
-
-function partitionByExposure(services: readonly ServiceEntry[]): ExposurePartition {
-  const exposed: ServiceEntry[] = [];
-  const hidden: Array<{ entry: ServiceEntry; reason: string }> = [];
-  for (const s of services) {
-    const eff = effectivePublicExposure(s);
-    if (eff === "allowed") {
-      exposed.push(s);
-      continue;
-    }
-    // Explicit declaration tells the user exactly what the service asked for;
-    // a spec-derived default points at the usual cause (no auth configured).
-    let reason: string;
-    if (s.publicExposure === "loopback") {
-      reason = "loopback-only by service declaration";
-    } else if (s.publicExposure === "auth-required") {
-      reason = "auth-required: service reports auth is not yet configured";
-    } else {
-      reason = "auth-required: service has no auth gate — set the service's auth token to expose";
-    }
-    hidden.push({ entry: s, reason });
   }
-  return { exposed, hidden };
 }
 
 /**
- * Compose the tailscale serve target URL for a service rooted at `mount`.
- *
- * `tailscale serve --set-path=<mount> <target>` strips `<mount>` from the
- * incoming request path before forwarding. So if the backend expects
- * requests to keep arriving at `<mount>/...` (every SPA with a configured
- * base path, plus vault's `/vault/<name>/` API root) the target URL must
- * include the same mount path — otherwise the backend sees requests at `/`,
- * emits a redirect back to its real base, tailscale strips again, and the
- * client loops on `ERR_TOO_MANY_REDIRECTS`.
- *
- * The rule of thumb is: mount and target path must match byte-for-byte
- * (including trailing slash state), so tailscale's strip-then-forward is a
- * no-op and the backend sees the full path it expects.
+ * Build the tailscale plan: one rule, `/ → http://127.0.0.1:<hubPort>/`.
+ * Hub does internal dispatch (UI, OAuth, well-known, vault SPA + per-vault
+ * proxy, generic /<svc>/* services.json dispatch) and per-request layer
+ * gating for `publicExposure: "loopback"` services. See `layerOf` in
+ * `hub-server.ts` for the access-control matrix.
  */
-function serviceProxyTarget(port: number, mount: string): string {
-  return `http://127.0.0.1:${port}${mount}`;
-}
-
-function planEntries(services: readonly ServiceEntry[], hubPort: number): ServeEntry[] {
-  const entries: ServeEntry[] = [];
-  entries.push({
-    kind: "proxy",
-    mount: HUB_MOUNT,
-    target: serviceProxyTarget(hubPort, HUB_MOUNT),
-    service: "hub",
-  });
-  let anyVault = false;
-  for (const s of services) {
-    if (isVaultEntry(s)) {
-      // Vault paths route through the single `/vault/` → hub mount below so
-      // `parachute vault create <name>` is reachable on the tailnet without
-      // a re-expose. Hub does the per-request services.json lookup (#144).
-      anyVault = true;
-      continue;
-    }
-    const mount = s.paths[0] ?? `/${shortName(s.name)}`;
-    entries.push({
+function planEntries(hubPort: number): ServeEntry[] {
+  return [
+    {
       kind: "proxy",
-      mount,
-      target: serviceProxyTarget(s.port, mount),
-      service: s.name,
-    });
-  }
-  if (anyVault) {
-    entries.push({
-      kind: "proxy",
-      mount: VAULT_MOUNT,
-      target: serviceProxyTarget(hubPort, VAULT_MOUNT),
-      service: "vault",
-    });
-  }
-  entries.push({
-    kind: "proxy",
-    mount: WELL_KNOWN_MOUNT,
-    target: serviceProxyTarget(hubPort, WELL_KNOWN_MOUNT),
-    service: "well-known",
-  });
-
-  // The hub is the OAuth IdP — mount the four endpoints at the canonical
-  // origin and proxy them to the hub's loopback. tailscale strips the mount
-  // before forwarding, so the target keeps the same path (matches the
-  // `serviceProxyTarget` rule of thumb in the doc above).
-  for (const oauthPath of OAUTH_PATHS) {
-    entries.push({
-      kind: "proxy",
-      mount: oauthPath,
-      target: serviceProxyTarget(hubPort, oauthPath),
-      service: "hub:oauth",
-    });
-  }
-  return entries;
+      mount: HUB_CATCHALL_MOUNT,
+      target: `http://127.0.0.1:${hubPort}/`,
+      service: "hub",
+    },
+  ];
 }
 
 async function runEach(
@@ -366,12 +269,13 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
     }
   }
 
-  const allServices = remapLegacyRoot(manifest.services, log);
-  // Split out loopback/auth-required services before planning the serve routes.
-  // Hidden services keep their /127.0.0.1:<port> accessibility for on-box
-  // callers (e.g., vault's transcription-worker dialing scribe); they just
-  // don't land on tailnet/funnel.
-  const { exposed: services, hidden } = partitionByExposure(allServices);
+  // Plan no longer partitions services — every service goes through the
+  // single hub catchall, and hub gates per request (`publicExposure` +
+  // `layerOf` in hub-server.ts). Just surface the legacy `paths: ["/"]`
+  // warning so operators know to re-install. `warnLegacyRoot` is
+  // side-effect-only (warning to `log`); use `manifest.services` directly
+  // downstream.
+  warnLegacyRoot(manifest.services, log);
 
   /**
    * Probe each service port before wiring tailscale up. A service that's
@@ -381,7 +285,7 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
    */
   const portProbe = opts.servicePortProbe ?? (async (p: number) => !(await defaultPortProbe(p)));
   const probeResults = await Promise.all(
-    services.map(async (s) => ({ svc: s, up: await portProbe(s.port) })),
+    manifest.services.map(async (s) => ({ svc: s, up: await portProbe(s.port) })),
   );
   for (const { svc, up } of probeResults) {
     if (up) continue;
@@ -394,7 +298,7 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
   // Kept for manual debugging / inspection only — the hub server now builds
   // /.well-known/parachute.json dynamically from services.json at request time
   // (#135), so this on-disk copy is no longer load-bearing for any consumer.
-  const wellKnownDoc = buildWellKnown({ services, canonicalOrigin });
+  const wellKnownDoc = buildWellKnown({ services: manifest.services, canonicalOrigin });
   writeWellKnownFile(wellKnownDoc, wellKnownFilePath);
   log(`Wrote ${wellKnownFilePath}`);
   writeHubFile(hubFilePath);
@@ -416,7 +320,7 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
     hubPort = existing;
   } else {
     const hub = await ensureHubRunning({
-      reservedPorts: services.map((s) => s.port),
+      reservedPorts: manifest.services.map((s) => s.port),
       ...(opts.hubEnsureOpts ?? {}),
       configDir,
       wellKnownDir,
@@ -428,15 +332,12 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
     else log(`✓ hub already running (pid ${hub.pid}, port ${hub.port}).`);
   }
 
-  const entries = planEntries(services, hubPort);
+  const entries = planEntries(hubPort);
   log(`Exposing under ${canonicalOrigin} (${layerLabel(layer)}, path-routing, port ${port}):`);
   for (const e of entries) {
     const suffix = e.kind === "proxy" ? `→ ${e.target}  (${e.service})` : `→ ${e.target}`;
     log(`  ${e.mount.padEnd(30, " ")} ${suffix}`);
   }
-  for (const { entry: hiddenSvc, reason } of hidden) {
-    log(`  (${hiddenSvc.name} is loopback-only — ${reason})`);
-  }
 
   const cmds = entries.map((e) => bringupCommand(e, { port, funnel }));
   const code = await runEach(runner, cmds, log);
@@ -470,6 +371,20 @@ export async function exposeUp(layer: ExposeLayer, opts: ExposeOpts = {}): Promi
   log(`  Discovery: ${canonicalOrigin}${WELL_KNOWN_MOUNT}`);
   log(`  OAuth issuer: ${hubOrigin}`);
 
+  // 2FA-enrollment warning, public-layer only. /admin/login became reachable
+  // from every layer when 0.5.3-rc.1 collapsed the access-control matrix into
+  // the hub; on Funnel that means the open internet, where 2FA is the
+  // defense beyond #188's rate-limit floor. Tailnet exposure stays
+  // tailscale-authed at the ingress so the warning is moot there. See #186.
+  if (layer === "public") {
+    printPublic2FAWarning({
+      log,
+      publicUrl: canonicalOrigin,
+      ...(opts.vaultHome !== undefined ? { vaultHome: opts.vaultHome } : {}),
+      ...(opts.vaultAuthStatus !== undefined ? { status: opts.vaultAuthStatus } : {}),
+    });
+  }
+
   // Auto-restart services that cache the hub origin. Aaron hit this on launch
   // day: after `expose public` first-run, vault kept its stale (loopback)
   // PARACHUTE_HUB_ORIGIN, the OAuth issuer didn't match what clients saw, and

package/src/commands/install.ts

@@ -545,29 +545,27 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   }
 
-  // CLI-as-port-authority (#53): pick the service's port now and persist it
-  // via `~/.parachute/<svc>/.env`. lifecycle.start merges that .env into the
-  // spawn env (PR #50), so the next daemon boot binds the port we picked.
-  // Idempotent — an existing PORT in .env wins, so re-installs and
-  // user-edited ports survive across upgrades. Compiled-in service-side
-  // fallbacks (vault → 1940 etc.) stay; this just adds a CLI-managed
-  // override.
+  // Hub-as-port-authority (#53): pick the service's port now and reflect it
+  // in services.json. Pre-hub#206 the install path also wrote `PORT=<port>`
+  // into the service's `.env`; post-#206 (option A) services.json is the
+  // single source of truth — services follow the 4-tier resolvePort ladder
+  // (services.json → service config → bare PORT env → compiled-in default,
+  // per parachute-scribe#41 / parachute-agent#146 / parachute-agent#148 /
+  // parachute-patterns#45), so the duplicate `.env` PORT was at best dead
+  // weight and at worst a source of drift on re-install. Existing `.env`
+  // PORT lines on operator machines stay where they are — harmless — and
+  // future installs no longer touch them.
   const preInitEntry = findService(entryName, manifestPath);
   const probe = opts.portProbe ?? defaultPortProbe;
   const occupied = await collectOccupiedPorts(manifestPath, entryName, preInitEntry?.port, probe);
-  const envPath = join(configDir, short, ".env");
   const canonicalPort = spec.seedEntry?.().port ?? preInitEntry?.port;
   const portResult = assignServicePort({
-    envPath,
     canonical: canonicalPort,
     occupied,
   });
   if (portResult.warning) {
     log(`⚠ ${portResult.warning}`);
   }
-  if (portResult.written) {
-    log(`Wrote PORT=${portResult.port} to ${envPath}.`);
-  }
 
   // Find-or-seed the manifest entry. Re-read after the seed write so a silent
   // upsert failure (filesystem permission, races against an external writer)
@@ -600,7 +598,7 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   } else if (entry && entry.port !== portResult.port) {
     // init wrote an entry on the canonical port but the CLI assigned a
     // different one (collision). Reflect the CLI's choice so the hub and
-    // status views stay consistent with the .env we just wrote.
+    // status views stay consistent with the canonical-port assignment.
     upsertService({ ...entry, port: portResult.port }, manifestPath);
     entry = findService(entryName, manifestPath);
     log(

package/src/commands/lifecycle.ts

@@ -136,6 +136,24 @@ export interface LifecycleOpts {
   killWaitMs?: number;
   /** Poll interval while waiting for SIGTERM to land. */
   pollIntervalMs?: number;
+  /**
+   * How long `start` sleeps before re-checking `alive(pid)` to catch the
+   * spawn-then-immediately-die failure shape (hub#194: notes-serve crashed
+   * 50ms in on Bun.resolveSync, but `start` reported success because the
+   * spawn returned a pid). 250ms is the default in production — long
+   * enough to catch real silent-crashes (resolve failures, port
+   * collisions, missing args) without making `parachute start` feel
+   * laggy.
+   *
+   * Defaulting policy: if `alive` is not overridden, the settle defaults
+   * to 0 (skipped). Stub spawners hand back fake pids that the real
+   * `defaultAlive` would mark as dead, which would make every existing
+   * stub-spawner test fail spuriously. Tests that want to exercise the
+   * settle path inject both `alive` and `startSettleMs` explicitly.
+   * Production paths use the real `defaultAlive` and get the real 250ms
+   * settle.
+   */
+  startSettleMs?: number;
   /**
    * Override the hub origin passed to services as PARACHUTE_HUB_ORIGIN. If
    * unset, `start` derives it from `expose-state.json` (when exposed) or
@@ -168,6 +186,7 @@ interface Resolved {
   log: (line: string) => void;
   killWaitMs: number;
   pollIntervalMs: number;
+  startSettleMs: number;
   hubOrigin: string | undefined;
   ensureHub: (opts: EnsureHubOpts) => Promise<EnsureHubResult>;
   stopHubFn: (opts: StopHubOpts) => Promise<boolean>;
@@ -186,6 +205,14 @@ function resolve(opts: LifecycleOpts): Resolved {
     log: opts.log ?? ((line) => console.log(line)),
     killWaitMs: opts.killWaitMs ?? 10_000,
     pollIntervalMs: opts.pollIntervalMs ?? 200,
+    // See `LifecycleOpts.startSettleMs` doc. Production (no spawner
+    // override, no alive override) gets the 250ms settle. Tests that
+    // inject a stub spawner without a stub alive get 0 — `defaultAlive`
+    // against a fake pid would always report dead and break unrelated
+    // tests. Tests that want to exercise the settle path explicitly
+    // override `alive`, which re-enables the default 250ms.
+    startSettleMs:
+      opts.startSettleMs ?? (opts.spawner === undefined || opts.alive !== undefined ? 250 : 0),
     hubOrigin: resolveHubOrigin(opts.hubOrigin, configDir),
     ensureHub: opts.hub?.ensureRunning ?? ensureHubRunning,
     stopHubFn: opts.hub?.stop ?? stopHub,
@@ -371,16 +398,38 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
     if (entry.installDir) spawnerOpts.cwd = entry.installDir;
     const passOpts =
       spawnerOpts.env !== undefined || spawnerOpts.cwd !== undefined ? spawnerOpts : undefined;
+    let pid: number;
     try {
-      const pid = r.spawner.spawn(cmd, logFile, passOpts);
-      writePid(short, pid, r.configDir);
-      r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
-      if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
+      pid = r.spawner.spawn(cmd, logFile, passOpts);
     } catch (err) {
       failures++;
       const msg = err instanceof Error ? err.message : String(err);
       r.log(`✗ ${short} failed to start: ${msg}`);
+      continue;
+    }
+    writePid(short, pid, r.configDir);
+
+    // Settle-poll for spawn-then-immediately-die (hub#194). A spawn returning
+    // a pid only proves the kernel forked the process; the child may exit
+    // microseconds later if its main code path throws before listening
+    // (e.g. notes-serve's Bun.resolveSync failing for bun-linked installs).
+    // Without this poll, we'd report success and the operator would chase
+    // a phantom 502.
+    if (r.startSettleMs > 0) {
+      await r.sleep(r.startSettleMs);
+      if (!r.alive(pid)) {
+        clearPid(short, r.configDir);
+        failures++;
+        r.log(
+          `✗ ${short} failed to start: spawned pid ${pid} but the process exited within ${r.startSettleMs}ms.`,
+        );
+        r.log(`  Tail the log for details: tail -50 ${logFile}`);
+        continue;
+      }
     }
+
+    r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
+    if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
   }
   return failures === 0 ? 0 : 1;
 }

package/src/commands/status.ts

@@ -1,7 +1,7 @@
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
 import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
-import { getSpec, shortNameForManifest } from "../service-spec.ts";
+import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
 
 export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
@@ -74,6 +74,14 @@ interface StatusRow {
   url: string | undefined;
   healthy: boolean;
   skipped: boolean;
+  /**
+   * Canonical-port drift warning. Set when the entry has a known canonical
+   * port (first-party / known short) AND the actual port differs. Surfaced
+   * as a continuation line under the row so operators see a silent miswire
+   * (e.g. parachute-hub#195: scribe + agent both at 1944) without us
+   * hard-erroring on a deliberate operator port change.
+   */
+  driftWarning?: string;
 }
 
 /**
@@ -157,6 +165,19 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
 
       const url = urlForEntry(entry, short);
 
+      // Canonical-port drift detection (hub#195). Only fires for known
+      // first-party services where we have a canonical assignment. Third-party
+      // rows have no canonical to compare against. Warning is informational —
+      // operators may have moved a service off canonical deliberately.
+      // Note: multi-vault instance rows (`parachute-vault-<instance>`) don't
+      // match a canonical manifest name, so drift warnings don't fire for
+      // them. Intentional — see `canonicalPortForManifest` for the rationale.
+      const canonical = canonicalPortForManifest(entry.name);
+      const driftWarning =
+        canonical !== undefined && canonical !== entry.port
+          ? `canonical port is ${canonical}`
+          : undefined;
+
       // Only skip probe when we know the process is dead (PID file was
       // present but kill(pid, 0) failed). "unknown" status (no PID file)
       // still probes — externally-managed services should report health.
@@ -173,6 +194,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           url,
           healthy: false,
           skipped: true,
+          driftWarning,
         };
       }
 
@@ -194,6 +216,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         url,
         healthy: p.healthy,
         skipped: false,
+        driftWarning,
       };
     }),
   );
@@ -228,6 +251,10 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     if (!cells || !row) continue;
     print(formatRow(cells, widths));
     if (row.url) print(`  → ${row.url}`);
+    // Drift warning rides as its own continuation line. Plain ASCII (no
+    // emoji / unicode glyphs) for terminal compatibility — the same
+    // surface that prints to scripts piping `parachute status`.
+    if (row.driftWarning) print(`  ! ${row.driftWarning}`);
   }
 
   /**

package/src/help.ts

@@ -44,9 +44,9 @@ Services:
 What it does:
   1. bun add -g @openparachute/<service>[@<tag>]
   2. run any service-specific init (e.g. \`parachute-vault init\`)
-  3. assign a canonical port (1939–1949) and write \`PORT=<port>\` into
-     \`~/.parachute/<service>/.env\`. Idempotent — an existing PORT wins, so
-     re-installs and operator-edited ports survive across upgrades.
+  3. assign a canonical port (1939–1949) and reflect it in
+     \`~/.parachute/services.json\` — the single source of truth at boot
+     (services follow a 4-tier resolvePort ladder; services.json wins).
   4. verify the service registered itself in ~/.parachute/services.json
   5. for scribe in a TTY: prompt for transcription provider + API key
      (or take \`--scribe-provider\` / \`--scribe-key\`)