@openparachute/hub 0.5.13-rc.13 → 0.5.13-rc.21

package/src/api-modules-ops.ts

@@ -36,6 +36,7 @@ import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
+import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
 import { readModuleManifest } from "./module-manifest.ts";
@@ -325,6 +326,37 @@ function defaultRun(cmd: readonly string[]): Promise<number> {
   return proc.exited;
 }
 
+/**
+ * Resolve which `<pkg>@<channel>` the API install path should ship,
+ * given the per-request override (POST body `channel`) and the
+ * cascading defaults. See `runInstall` for the precedence chain.
+ *
+ * Exported (test-only) so the api-modules-ops tests can assert the
+ * resolution without re-driving a full install through the registry.
+ */
+function resolveApiInstallChannel(
+  channelOverride: string | undefined,
+  deps: ApiModulesOpsDeps,
+): string {
+  // 1. Per-request override.
+  if (channelOverride === "rc" || channelOverride === "latest") return channelOverride;
+  // 2. `PARACHUTE_INSTALL_CHANNEL` env var — cluster-wide cascade.
+  const fromEnv = process.env[PARACHUTE_INSTALL_CHANNEL_ENV];
+  if (typeof fromEnv === "string") {
+    if (fromEnv === "rc" || fromEnv === "latest") return fromEnv;
+    if (fromEnv.length > 0) {
+      // Garbage env value — log once per op so the operator notices, then
+      // fall through to the DB-stored channel. Don't crash the install.
+      console.warn(
+        `[api-modules-ops] ${PARACHUTE_INSTALL_CHANNEL_ENV}="${fromEnv}" is not a valid channel — falling back to admin-toggle setting.`,
+      );
+    }
+  }
+  // 3. Admin-toggle setting (hub#275). Seeds from `PARACHUTE_MODULE_CHANNEL`
+  // on first read; after that the row is source of truth.
+  return getModuleInstallChannel(deps.db);
+}
+
 /**
  * Resolve the `installDir` for `spec` from `findGlobalInstall`. Null when
  * the dep isn't wired (tests without a stub) or the package can't be
@@ -392,6 +424,32 @@ export async function handleInstall(
   const authFail = await authorize(req, deps);
   if (authFail) return authFail;
 
+  // Optional `{ channel: "rc" | "latest" }` in the body — per-call override
+  // for the SPA's "install X at rc" affordance (hub#337). Missing body /
+  // empty body / non-JSON body all fall through silently to the env →
+  // DB-stored channel resolution chain. A malformed `channel` value (not
+  // in the union) is rejected — operators shouldn't get a silent fallback
+  // on a typo they explicitly typed.
+  let bodyChannel: string | undefined;
+  if (req.headers.get("content-type")?.includes("application/json")) {
+    try {
+      const body = (await req.json()) as { channel?: unknown };
+      if (body && typeof body.channel === "string") {
+        if (body.channel !== "rc" && body.channel !== "latest") {
+          return jsonError(
+            400,
+            "invalid_channel",
+            `channel must be "rc" or "latest" (got "${body.channel}")`,
+          );
+        }
+        bodyChannel = body.channel;
+      }
+    } catch {
+      // Empty body / unparseable JSON — silently ignore; the env/DB
+      // resolution chain still applies.
+    }
+  }
+
   const registry = deps.registry ?? defaultRegistry;
   const op = registry.create("install", short);
 
@@ -409,7 +467,7 @@ export async function handleInstall(
   // Kick off the async work. We DON'T await — the response goes back
   // 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).catch((err) => {
+  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}`);
   });
@@ -432,14 +490,22 @@ export async function runInstall(
   short: CuratedModuleShort,
   spec: ServiceSpec,
   deps: ApiModulesOpsDeps,
+  channelOverride?: string,
 ): Promise<void> {
   const registry = deps.registry ?? defaultRegistry;
   const run = deps.run ?? defaultRun;
-  // hub#275: operator-settable channel (`latest` | `rc`). Read on every
-  // op so a toggle change applies to the next install without a hub
-  // restart. The hub-settings layer seeds from PARACHUTE_MODULE_CHANNEL
-  // on first read; after that the row is source of truth.
-  const channel = getModuleInstallChannel(deps.db);
+  // Channel resolution (hub#337) — precedence:
+  //   1. per-request `channelOverride` (POST body `{channel}`)
+  //   2. `PARACHUTE_INSTALL_CHANNEL` env var (platform-default cascade for
+  //      Render-style deploys that ship hub on rc and want rc for every
+  //      module installed via /admin/modules too)
+  //   3. `hub_settings.module_install_channel` (admin SPA toggle, hub#275 —
+  //      seeded from `PARACHUTE_MODULE_CHANNEL` on first read)
+  //   4. "latest" fallback
+  //
+  // Read on every op so a toggle change applies to the next install
+  // without a hub restart.
+  const channel = resolveApiInstallChannel(channelOverride, deps);
   const spec_str = `${spec.package}@${channel}`;
   registry.update(opId, { status: "running" }, `running bun add -g ${spec_str}`);
   const code = await run(["bun", "add", "-g", spec_str]);
@@ -598,7 +664,13 @@ async function runUpgrade(
 ): Promise<void> {
   const registry = deps.registry ?? defaultRegistry;
   const run = deps.run ?? defaultRun;
-  const channel = getModuleInstallChannel(deps.db);
+  // Mirror runInstall's precedence so PARACHUTE_INSTALL_CHANNEL=rc cascades
+  // to admin-SPA-driven upgrades too. Without this, a Render deploy with
+  // env=rc would install at @rc but upgrade through the SPA at whatever
+  // the DB toggle says — asymmetric + surprising to the operator.
+  // (Operators who want different install vs upgrade channels can still
+  // do so via the DB toggle when no env is set.)
+  const channel = resolveApiInstallChannel(undefined, deps);
   const spec_str = `${spec.package}@${channel}`;
   registry.update(opId, { status: "running" }, `running bun add -g ${spec_str}`);
   const code = await run(["bun", "add", "-g", spec_str]);

package/src/api-modules.ts

@@ -30,6 +30,10 @@ import {
   setModuleInstallChannel,
 } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
+import {
+  type ModuleManifest,
+  readModuleManifest as defaultReadModuleManifest,
+} from "./module-manifest.ts";
 import { FIRST_PARTY_FALLBACKS, KNOWN_MODULES } from "./service-spec.ts";
 // `FIRST_PARTY_FALLBACKS` and `KNOWN_MODULES` are both consulted by
 // `lookupModule` below — the former for notes/channel (vendored manifests
@@ -107,6 +111,13 @@ export interface ApiModulesDeps {
   cacheTtlMs?: number;
   /** Test seam over wall-clock. */
   now?: () => number;
+  /**
+   * Override the per-module `.parachute/module.json` reader. Production
+   * reads from disk via `module-manifest.readModuleManifest`; tests
+   * inject a fake. Used to surface `managementUrl` on the wire shape
+   * (hub#342 — drives the admin SPA Modules page's "Open" button).
+   */
+  readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
 }
 
 /**
@@ -158,6 +169,30 @@ interface ModuleWireShape {
    * design doc §12.
    */
   uis: UiSubUnitWireShape[];
+  /**
+   * Canonical user-facing URL for this module's own UI (hub#342). Drives
+   * the admin SPA Modules page's "Open" button — clicking lands the
+   * operator on the module's own surface (combining view + configure
+   * per Aaron's framing: each module ships its own UI handling both).
+   *
+   * Resolution order:
+   *   1. Module's `managementUrl` from `<installDir>/.parachute/module.json`,
+   *      resolved against the module's mounted URL — matches the
+   *      well-known doc's resolution for vault rows.
+   *   2. Module's `uiUrl` from the same manifest, when it's the only
+   *      declared surface — for modules where the user-facing UI IS
+   *      the operator UI (App today).
+   *   3. Null when the module hasn't declared either field — the SPA
+   *      renders a disabled "Open" tooltip ("module hasn't shipped an
+   *      admin UI yet"). Tracked as follow-up issues per module
+   *      (scribe#53, runner#8 today).
+   *
+   * Always an absolute path on the hub origin (leading `/`) — the SPA
+   * navigates same-origin, no need to worry about cross-origin
+   * managementUrls (those are an escape hatch for off-origin admin
+   * surfaces, unused by first-party modules today).
+   */
+  management_url: string | null;
 }
 
 interface ModulesResponse {
@@ -251,7 +286,12 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   const manifest = readManifest(deps.manifestPath);
   const installedByShort = new Map<
     string,
-    { version: string; installDir?: string; uis?: Record<string, UiSubUnit> }
+    {
+      version: string;
+      installDir?: string;
+      uis?: Record<string, UiSubUnit>;
+      mountPath?: string;
+    }
   >();
   for (const entry of manifest.services) {
     // Join services.json rows to CURATED_MODULES by manifestName. The
@@ -266,14 +306,69 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
           version: string;
           installDir?: string;
           uis?: Record<string, UiSubUnit>;
+          mountPath?: string;
         } = { version: entry.version };
         if (entry.installDir !== undefined) value.installDir = entry.installDir;
         if (entry.uis !== undefined) value.uis = entry.uis;
+        // First non-`.parachute` path is the module's user-facing mount
+        // (`/app`, `/scribe`, `/vault/<name>`). Used below to resolve
+        // a relative `managementUrl` to a full hub-origin path. Skips
+        // `.parachute` entries because those are protocol mounts, not
+        // user surfaces — every module declares one.
+        const userPath = (entry.paths ?? []).find(
+          (p) => p !== "/.parachute" && !p.startsWith("/.parachute/"),
+        );
+        if (userPath !== undefined) value.mountPath = userPath;
         installedByShort.set(short, value);
       }
     }
   }
 
+  // Read each installed module's `.parachute/module.json` so we can
+  // surface `managementUrl` on the wire shape (hub#342). Quiet on
+  // per-entry errors: a malformed manifest on one module shouldn't 500
+  // the whole catalog response — its row just renders with a null
+  // management_url and the SPA shows the disabled "Open" tooltip.
+  const readModuleManifestFn = deps.readModuleManifest ?? defaultReadModuleManifest;
+  const managementUrlByShort = new Map<string, string>();
+  await Promise.all(
+    Array.from(installedByShort.entries()).map(async ([short, value]) => {
+      if (!value.installDir) return;
+      try {
+        const m = await readModuleManifestFn(value.installDir);
+        if (!m) return;
+        // Resolution per the module-ui-declaration.md hierarchy:
+        // managementUrl > uiUrl. Both are EITHER an absolute
+        // http(s) URL OR a relative path. Relative paths are joined
+        // against the module's mount path (entry.paths[0]) since both
+        // surfaces conventionally live under it (vault's `/admin`,
+        // app's `/admin`). Absolute URLs pass through verbatim.
+        const candidate = m.managementUrl ?? m.uiUrl;
+        if (candidate === undefined) return;
+        if (/^https?:\/\//i.test(candidate)) {
+          managementUrlByShort.set(short, candidate);
+          return;
+        }
+        const mount = value.mountPath;
+        if (mount === undefined) {
+          // No user-facing mount declared — we can't resolve a relative
+          // path. Skip rather than guess. Vault rows hit this when
+          // services.json was hand-edited to remove the mount; the
+          // disabled-tooltip state in the SPA is the right surface.
+          return;
+        }
+        // Join mount + candidate path. Both pieces have leading slashes
+        // already (mount per services.json convention; candidate per
+        // managementUrl validation). Drop one to avoid `//`.
+        const tail = candidate.startsWith("/") ? candidate : `/${candidate}`;
+        managementUrlByShort.set(short, `${mount}${tail}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`api-modules: skipping managementUrl for ${short}: ${msg}`);
+      }
+    }),
+  );
+
   // Supervisor state — per-module run status snapshot.
   const supervisor = deps.supervisor;
   const stateByShort = new Map<string, ModuleState>();
@@ -331,6 +426,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       pid: state?.pid ?? null,
       install_dir: installed?.installDir ?? null,
       uis: toUisWireShape(installed?.uis),
+      management_url: managementUrlByShort.get(short) ?? null,
     });
   }
 

package/src/cli.ts

@@ -315,7 +315,22 @@ async function main(argv: string[]): Promise<number> {
         console.error(`parachute install: ${tagExtract.error}`);
         return 1;
       }
-      const providerExtract = extractNamedFlag(tagExtract.rest, "--scribe-provider");
+      const channelExtract = extractNamedFlag(tagExtract.rest, "--channel");
+      if (channelExtract.error) {
+        console.error(`parachute install: ${channelExtract.error}`);
+        return 1;
+      }
+      if (
+        channelExtract.value !== undefined &&
+        channelExtract.value !== "rc" &&
+        channelExtract.value !== "latest"
+      ) {
+        console.error(
+          `parachute install: --channel must be "rc" or "latest" (got "${channelExtract.value}")`,
+        );
+        return 1;
+      }
+      const providerExtract = extractNamedFlag(channelExtract.rest, "--scribe-provider");
       if (providerExtract.error) {
         console.error(`parachute install: ${providerExtract.error}`);
         return 1;
@@ -329,7 +344,9 @@ async function main(argv: string[]): Promise<number> {
       const installArgs = keyExtract.rest.filter((a) => a !== "--no-start");
       const service = installArgs[0];
       if (!service) {
-        console.error("usage: parachute install <service|all> [--tag <name>] [--no-start]");
+        console.error(
+          "usage: parachute install <service|all> [--channel rc|latest] [--tag <name>] [--no-start]",
+        );
         console.error(
           "       parachute install scribe [--scribe-provider <name>] [--scribe-key <key>]",
         );
@@ -338,6 +355,9 @@ async function main(argv: string[]): Promise<number> {
       }
       const installOpts: Parameters<typeof install>[1] = {};
       if (tagExtract.tag) installOpts.tag = tagExtract.tag;
+      if (channelExtract.value === "rc" || channelExtract.value === "latest") {
+        installOpts.channel = channelExtract.value;
+      }
       if (noStart) installOpts.noStart = true;
       if (providerExtract.value) installOpts.scribeProvider = providerExtract.value;
       if (keyExtract.value) installOpts.scribeKey = keyExtract.value;
@@ -549,14 +569,40 @@ async function main(argv: string[]): Promise<number> {
         console.error(`parachute upgrade: ${tagExtract.error}`);
         return 1;
       }
-      const remaining = tagExtract.rest;
+      const channelExtract = extractNamedFlag(tagExtract.rest, "--channel");
+      if (channelExtract.error) {
+        console.error(`parachute upgrade: ${channelExtract.error}`);
+        return 1;
+      }
+      if (
+        channelExtract.value !== undefined &&
+        channelExtract.value !== "rc" &&
+        channelExtract.value !== "latest"
+      ) {
+        console.error(
+          `parachute upgrade: --channel must be "rc" or "latest" (got "${channelExtract.value}")`,
+        );
+        return 1;
+      }
+      let remaining = channelExtract.rest;
+      const allowDowngradeIdx = remaining.indexOf("--allow-downgrade");
+      const allowDowngrade = allowDowngradeIdx !== -1;
+      if (allowDowngrade) {
+        remaining = remaining.filter((a) => a !== "--allow-downgrade");
+      }
       if (remaining.length > 1) {
         console.error(`parachute upgrade: unexpected argument "${remaining[1]}"`);
-        console.error("usage: parachute upgrade [<service>] [--tag <name>]");
+        console.error(
+          "usage: parachute upgrade [<service>] [--channel rc|latest] [--allow-downgrade] [--tag <name>]",
+        );
         return 1;
       }
       const upgradeOpts: Parameters<typeof upgrade>[1] = {};
       if (tagExtract.tag) upgradeOpts.tag = tagExtract.tag;
+      if (channelExtract.value === "rc" || channelExtract.value === "latest") {
+        upgradeOpts.channel = channelExtract.value;
+      }
+      if (allowDowngrade) upgradeOpts.allowDowngrade = true;
       return await upgrade(remaining[0], upgradeOpts);
     }
 

package/src/commands/install.ts

@@ -37,6 +37,67 @@ import {
 
 export type Runner = (cmd: readonly string[]) => Promise<number>;
 
+/**
+ * Env var that defaults the install channel for `parachute install <svc>`
+ * (hub#337). When set to `rc` or `latest`, becomes the default channel for
+ * every `bun add -g <pkg>@<channel>` the install command composes. The
+ * explicit `--channel` flag (and `--tag`) override the env var per call.
+ *
+ * Rationale: the canonical Render deploy ships the hub container from
+ * `main` (which tracks the rc chain per governance rule 2). Without this
+ * env var the supervisor's `/admin/modules` install API would still
+ * resolve `@latest` for vault / app / scribe / runner — leaving a hub-on-rc
+ * cluster bootstrapping its other modules on stable, which silently
+ * fragments the cluster's version axis. Setting `PARACHUTE_INSTALL_CHANNEL=rc`
+ * at the platform level cascades the rc-ness across every module install,
+ * matching what an `npm i -g @openparachute/hub@rc` operator does on the
+ * CLI side.
+ *
+ * Garbage values (`PARACHUTE_INSTALL_CHANNEL=banana`) fall back to `latest`
+ * with a warning so an operator typo can't crash the install path.
+ */
+export const PARACHUTE_INSTALL_CHANNEL_ENV = "PARACHUTE_INSTALL_CHANNEL";
+
+const VALID_INSTALL_CHANNELS = ["latest", "rc"] as const;
+export type InstallChannel = (typeof VALID_INSTALL_CHANNELS)[number];
+
+function isInstallChannel(v: string): v is InstallChannel {
+  return (VALID_INSTALL_CHANNELS as readonly string[]).includes(v);
+}
+
+/**
+ * Resolve the dist-tag to use for `bun add -g <pkg>@<tag>` in `parachute
+ * install`. Precedence (highest → lowest):
+ *
+ *   1. explicit `--tag <name>` (programmatic — exact pin, may be a version)
+ *   2. explicit `--channel rc|latest` (operator-facing dist-tag override)
+ *   3. `PARACHUTE_INSTALL_CHANNEL` env var (platform-default cascade)
+ *   4. `"latest"` fallback (the npm default; back-compat for existing operators)
+ *
+ * Garbage env-var values fall back to `"latest"` with a warning. The
+ * `env` + `warn` knobs are test seams; production uses `process.env` +
+ * `console.warn`.
+ */
+export function resolveInstallChannel(opts: {
+  tag?: string;
+  channel?: string;
+  env?: NodeJS.ProcessEnv;
+  warn?: (msg: string) => void;
+}): string {
+  if (opts.tag) return opts.tag;
+  if (opts.channel) return opts.channel;
+  const env = opts.env ?? process.env;
+  const fromEnv = env[PARACHUTE_INSTALL_CHANNEL_ENV];
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (isInstallChannel(fromEnv)) return fromEnv;
+    const warn = opts.warn ?? ((msg: string) => console.warn(msg));
+    warn(
+      `[parachute install] ${PARACHUTE_INSTALL_CHANNEL_ENV}="${fromEnv}" is not a valid channel — expected one of ${VALID_INSTALL_CHANNELS.join(", ")}. Falling back to "latest".`,
+    );
+  }
+  return "latest";
+}
+
 /**
  * Transition aliases for services that were renamed. Accepted for one
  * release cycle with a rename notice, then removed. `lens → notes`
@@ -77,8 +138,26 @@ export interface InstallOpts {
    * `bun add -g` call is composed as `<package>@<tag>` so RC testers can
    * pin a pre-release channel. `isLinked` still short-circuits — if the
    * package is bun-linked locally, the tag is moot.
+   *
+   * Precedence: `tag` > `channel` > `PARACHUTE_INSTALL_CHANNEL` env > `"latest"`.
    */
   tag?: string;
+  /**
+   * Operator-facing channel (`--channel rc|latest`, hub#337). Picks a npm
+   * dist-tag for the `bun add -g <pkg>@<channel>` call. Wins over the
+   * `PARACHUTE_INSTALL_CHANNEL` env var but loses to `tag` (which is the
+   * programmatic-pin escape hatch — e.g. an exact version string). The
+   * CLI argv parser rejects values outside `rc`/`latest` before this
+   * point; the install command itself trusts the caller's input.
+   */
+  channel?: string;
+  /**
+   * Override `process.env` for channel resolution (test seam). Production
+   * reads from `process.env`. Tests inject a deterministic object to
+   * exercise the `PARACHUTE_INSTALL_CHANNEL` precedence + invalid-value
+   * fallback without polluting the real environment.
+   */
+  envOverride?: NodeJS.ProcessEnv;
   /**
    * Override the random-token source for the vault↔scribe auto-wire.
    * Tests pass a deterministic string; production uses crypto.randomBytes.
@@ -498,12 +577,35 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
   } else if (target.kind === "local-path" && localAlreadyLinkedTo === targetReal) {
     log(`${target.packageName} is already linked at ${target.absPath} — skipping bun add.`);
   } else {
-    const addSpec =
-      target.kind === "local-path"
-        ? target.absPath
-        : opts.tag
-          ? `${target.packageName}@${opts.tag}`
-          : target.packageName;
+    // Channel resolution (hub#337): `--tag` > `--channel` > env > "latest".
+    // Local-path installs always pass the absolute path through verbatim
+    // (no channel applies — we're installing from the filesystem, not npm).
+    let addSpec: string;
+    if (target.kind === "local-path") {
+      addSpec = target.absPath;
+    } else {
+      const resolveOpts: Parameters<typeof resolveInstallChannel>[0] = {
+        warn: (msg) => log(`⚠ ${msg}`),
+      };
+      if (opts.tag !== undefined) resolveOpts.tag = opts.tag;
+      if (opts.channel !== undefined) resolveOpts.channel = opts.channel;
+      if (opts.envOverride !== undefined) resolveOpts.env = opts.envOverride;
+      const channel = resolveInstallChannel(resolveOpts);
+      // Suppress `@latest` from the displayed/composed spec when nothing
+      // was explicitly requested — bun resolves bare names to @latest
+      // anyway, and keeping the spec bare preserves byte-identical
+      // back-compat with pre-hub#337 logs ("Installing @openparachute/vault…"
+      // not "Installing @openparachute/vault@latest…"). Any explicit
+      // tag/channel/env value still flows through.
+      const explicit = opts.tag !== undefined || opts.channel !== undefined;
+      const envSet =
+        opts.envOverride !== undefined
+          ? typeof opts.envOverride[PARACHUTE_INSTALL_CHANNEL_ENV] === "string" &&
+            opts.envOverride[PARACHUTE_INSTALL_CHANNEL_ENV] !== ""
+          : typeof process.env[PARACHUTE_INSTALL_CHANNEL_ENV] === "string" &&
+            process.env[PARACHUTE_INSTALL_CHANNEL_ENV] !== "";
+      addSpec = explicit || envSet ? `${target.packageName}@${channel}` : target.packageName;
+    }
     log(`Installing ${addSpec}…`);
     const addCode = await runner(["bun", "add", "-g", addSpec]);
     if (addCode !== 0) {

package/src/commands/lifecycle.ts

@@ -594,6 +594,11 @@ export interface LogsOpts {
   /** Number of trailing lines to print (default 200). */
   lines?: number;
   follow?: boolean;
+  /**
+   * Liveness probe seam — tests inject deterministic pid-alive answers.
+   * Defaults to the group-aware `defaultAlive` (hub#88).
+   */
+  alive?: AliveFn;
 }
 
 export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
@@ -602,6 +607,7 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
   const log = opts.log ?? ((line) => console.log(line));
   const lines = opts.lines ?? 200;
   const follow = opts.follow ?? false;
+  const alive = opts.alive ?? defaultAlive;
 
   // logs only needs a valid short name to find the log file. First-party
   // wins via the spec lookup; third-party rows match by `entry.name`; the
@@ -620,6 +626,20 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
 
   const path = logPathFor(svc, configDir);
   if (!existsSync(path)) {
+    // Distinguish "daemon never started" from "daemon is running but the
+    // log file is missing" (hub#335). The latter shape surfaces when a
+    // module self-registers + spawns its own logger without going through
+    // `parachute start <svc>` (no hub-managed log file), or when an
+    // operator deletes the log mid-run. Previously both shapes printed the
+    // same `parachute start ${svc}` hint, leading operators to think their
+    // running daemon hadn't started.
+    const state = processState(svc, configDir, alive);
+    if (state.status === "running") {
+      log(
+        `${svc} is running (pid ${state.pid}) but no log file at ${path}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+      );
+      return 0;
+    }
     log(`no logs yet for ${svc}. \`parachute start ${svc}\` to begin.`);
     return 0;
   }