@mycadet/cli 0.12.10 → 0.12.11

package/src/lib/hatch-local.ts

@@ -52,7 +52,6 @@ import {
 import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { printInstanceDetails } from "./instance-details.js";
 import { checkProviderApiKey } from "./api-key-check.js";
-import { loopbackSafeFetch } from "./loopback-fetch.js";
 import {
   describeLoginError,
   ensureCloudLoginInteractive,
@@ -156,8 +155,6 @@ export interface HatchLocalParams {
   name?: string | null;
   /** Build from a local source tree and hot-reload on change. */
   watch?: boolean;
-  /** Stay attached after hatch and poll the gateway until it stops. */
-  keepAlive?: boolean;
   /** Hatch-time config values (key → value). */
   configValues?: Record<string, string>;
   /** Extra env vars forwarded into the assistant process. */
@@ -192,13 +189,7 @@ export interface HatchLocalResult {
 export async function hatchLocal(
   params: HatchLocalParams = {},
 ): Promise<HatchLocalResult> {
-  const {
-    name,
-    watch = false,
-    keepAlive = false,
-    configValues = {},
-    flagEnvVars = {},
-  } = params;
+  const { name, watch = false, configValues = {}, flagEnvVars = {} } = params;
   const reporter = params.reporter ?? consoleLifecycleReporter;
   const verbose = params.verbose ?? false;
   const setupProviderCredentials = params.setupProviderCredentials !== false;
@@ -454,46 +445,5 @@ export async function hatchLocal(
     guardianAccessToken,
   };
 
-  if (keepAlive) {
-    const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
-    const healthTarget = "Gateway";
-    const POLL_INTERVAL_MS = 5000;
-    const MAX_FAILURES = 3;
-    let consecutiveFailures = 0;
-
-    const shutdown = async (): Promise<void> => {
-      reporter.log("\nShutting down local processes...");
-      await stopLocalProcesses(resources);
-      process.exit(0);
-    };
-
-    process.on("SIGTERM", () => void shutdown());
-    process.on("SIGINT", () => void shutdown());
-
-    // Poll the health endpoint until it stops responding.
-    while (true) {
-      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-      try {
-        const res = await loopbackSafeFetch(healthUrl, {
-          signal: AbortSignal.timeout(3000),
-        });
-        if (res.ok) {
-          consecutiveFailures = 0;
-        } else {
-          consecutiveFailures++;
-        }
-      } catch {
-        consecutiveFailures++;
-      }
-      if (consecutiveFailures >= MAX_FAILURES) {
-        reporter.log(
-          `\n⚠️  ${healthTarget} stopped responding — shutting down.`,
-        );
-        await stopLocalProcesses(resources);
-        process.exit(1);
-      }
-    }
-  }
-
   return result;
 }

package/src/lib/hatch-next-steps.ts

@@ -1,8 +1,21 @@
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
+function cliCommand(): string {
+  // Production keeps the bare `cadet` binary; every non-production
+  // environment installs as `cadet-<env>` (the same rule as the config and
+  // state dirs — see environments/paths.ts).
+  const env = getCurrentEnvironment();
+  return env.name === "production" ? "cadet" : `cadet-${env.name}`;
+}
+
 export function logHatchNextSteps(log: (message: string) => void): void {
+  const command = cliCommand();
   log("Next steps:");
-  log("  - Run `cadet client` to interact with your cadet via the terminal");
   log(
-    "  - Run `cadet tunnel` to make your cadet publicly accessible and interact with it via the browser",
+    `  - Run \`${command} client\` to interact with your cadet via the terminal`,
+  );
+  log(
+    `  - Run \`${command} tunnel\` to make your cadet publicly accessible and interact with it via the browser`,
   );
   log("");
 }

package/src/lib/live-voice/tunnel.ts

@@ -28,7 +28,7 @@
  * mint again rather than reuse what resolution returned.
  */
 
-import { tunnelHostForPlatformHost } from "@mycadet/service-contracts/ingress";
+import { tunnelHostForCloudHost } from "@mycadet/service-contracts/ingress";
 
 import { authHeaders } from "../cloud-client.js";
 
@@ -66,7 +66,7 @@ export function tunnelHostForCloudUrl(cloudUrl: string): string {
   }
   try {
     return (
-      tunnelHostForPlatformHost(new URL(cloudUrl).host) ??
+      tunnelHostForCloudHost(new URL(cloudUrl).host) ??
       DEFAULT_TUNNEL_HOST
     );
   } catch {

package/src/lib/local.ts

@@ -79,7 +79,7 @@ import {
 } from "./process.js";
 import { stopTunnelProcess } from "./tunnel.js";
 import { stripVersionPrefix } from "./version-compat.js";
-import { openLogFile, pipeToLogFile } from "./xdg-log.js";
+import { openLogFile, openRuntimeLogFile, pipeToLogFile } from "./xdg-log.js";
 
 const _require = createRequire(import.meta.url);
 
@@ -839,7 +839,7 @@ async function startDaemonFromSource(
         windowsHide: true,
       })
     : (() => {
-        const daemonLogFd = openLogFile("hatch.log");
+        const daemonLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "assistant");
         const c = spawn(bunPath, ["run", resolve(daemonMainPath)], {
           cwd: spawnStateRoot(),
           detached: true,
@@ -912,7 +912,7 @@ async function startDaemonWatchFromSource(
   // detect the in-progress spawn and wait instead of racing.
   writeFileSync(pidFile, "starting", "utf-8");
 
-  const daemonLogFd = openLogFile("hatch.log");
+  const daemonLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "assistant");
   const child = spawn(
     resolveBunExecutable(),
     ["--watch", "run", resolve(mainPath)],
@@ -1699,7 +1699,7 @@ export async function startLocalDaemon(
             windowsHide: true,
           })
         : (() => {
-            const daemonLogFd = openLogFile("hatch.log");
+            const daemonLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "assistant");
             const c = spawn(daemonBinary, [], {
               cwd: spawnStateRoot(),
               detached: true,
@@ -1905,7 +1905,7 @@ export async function startGateway(
     // Use the compiled gateway binary when available (desktop app or compiled
     // CLI invoked from the terminal). In watch mode, skip the bundled binary
     // and use source (bun --watch only works with source files).
-    const gatewayLogFd = openLogFile("hatch.log");
+    const gatewayLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "gateway");
     gateway = spawn(gatewayBinary, [], {
       cwd: spawnStateRoot(),
       detached: true,
@@ -1921,7 +1921,7 @@ export async function startGateway(
     const bunArgs = watch
       ? ["--watch", "run", gatewayEntry, "--cadet-gateway"]
       : ["run", gatewayEntry, "--cadet-gateway"];
-    const gwLogFd = openLogFile("hatch.log");
+    const gwLogFd = openRuntimeLogFile(resources?.instanceDir ?? spawnStateRoot(), "gateway");
     gateway = spawn(resolveBunExecutable(), bunArgs, {
       cwd: spawnStateRoot(),
       detached: true,

package/src/lib/nginx-ingress.ts

@@ -13,6 +13,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { createServer } from "node:net";
 import { networkInterfaces } from "node:os";
 import { join } from "node:path";
 
@@ -166,7 +167,23 @@ export function cloudWebHubUrl(env: string | undefined): string {
 // must always run: it is reached through this self-hosted edge however the
 // cadet itself is hosted. "cloud" is never stamped (the cloud serves its
 // own bundles).
-const EDGE_SERVED_REMOTE: RemoteHost = "custom";
+/** The lockfile's recorded remote kind for the assistant, if one is found. */
+function lockfileAssistantRemote(assistantId: string): string | undefined {
+  const result = lookupAssistantByIdentifier(assistantId);
+  return result.status === "found" ? result.entry.cloud : undefined;
+}
+
+/**
+ * The remote kind stamped into the served SPA config. Docker and custom
+ * cadets are stamped truthfully; every other hosting shape — a local cadet
+ * reached through this edge, paired remotes, unknown entries — reads as
+ * "custom" so the served bundle always runs the remote-gateway machinery
+ * (this edge serves remote browsers however the cadet itself is hosted).
+ * "cloud" is never stamped: the cloud serves its own bundles.
+ */
+export function edgeServedRemote(recorded: string | undefined): RemoteHost {
+  return recorded === "docker" ? "docker" : "custom";
+}
 
 function remoteWebIngressConfig(
   opts: Pick<
@@ -175,7 +192,9 @@ function remoteWebIngressConfig(
   >,
 ): Record<string, unknown> {
   return {
-    remote: EDGE_SERVED_REMOTE,
+    remote: edgeServedRemote(
+      opts.assistantId ? lockfileAssistantRemote(opts.assistantId) : undefined,
+    ),
     apiBaseUrl: "/v1",
     ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
     ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
@@ -192,14 +211,24 @@ function remoteWebIngressConfig(
 export const EDGE_TEMPLATE_VERSION = 10;
 
 /**
- * Stable fingerprint of the SPA config injected into the served index and
- * `/assistant/__config`, plus the template that renders them. Recorded
+ * Stable fingerprint of the injected SPA config, its source bundle, and
+ * the template that renders them. Recorded
  * alongside the edge state so a reuse decision can tell whether a running edge
  * already serves the requested config (see `IngressState.remoteWebConfigHash`).
  */
-function remoteWebConfigFingerprint(config: Record<string, unknown>): string {
+function remoteWebConfigFingerprint(
+  config: Record<string, unknown>,
+  webDistDir: string,
+): string {
   return createHash("sha256")
-    .update(JSON.stringify({ template: EDGE_TEMPLATE_VERSION, config }))
+    .update(
+      JSON.stringify({
+        template: EDGE_TEMPLATE_VERSION,
+        config,
+        webDistDir,
+        indexHtml: readFileSync(join(webDistDir, "index.html"), "utf-8"),
+      }),
+    )
     .digest("hex");
 }
 
@@ -278,6 +307,44 @@ export function hasIpv6Loopback(): boolean {
     .some((addr) => addr.address === "::1");
 }
 
+/** Whether a TCP listener already holds `port` on the given loopback host. */
+async function isPortInUse(
+  port: number,
+  host: "127.0.0.1" | "::1",
+): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(true));
+    probe.once("listening", () => {
+      probe.close(() => resolve(false));
+    });
+    probe.listen(port, host);
+  });
+}
+
+/**
+ * The first free loopback port at or above `startPort`, scanning a short band,
+ * or null when the whole band is busy. Both stacks the edge may bind are
+ * probed (the IPv4 loopback always, the IPv6 loopback when the host has one),
+ * so the returned port is one nginx can actually take.
+ */
+export async function findAvailableIngressPort(
+  startPort: number,
+  attempts = 20,
+): Promise<number | null> {
+  const checkIpv6 = hasIpv6Loopback();
+  for (let port = startPort; port < startPort + attempts; port++) {
+    if (await isPortInUse(port, "127.0.0.1")) {
+      continue;
+    }
+    if (checkIpv6 && (await isPortInUse(port, "::1"))) {
+      continue;
+    }
+    return port;
+  }
+  return null;
+}
+
 /**
  * Build the nginx config that forwards tunnel web traffic to the gateway.
  */
@@ -574,7 +641,7 @@ export interface IngressState {
    */
   gatewayPort?: number;
   /**
-   * Fingerprint of the SPA config injected into the served index. Undefined
+   * Fingerprint of the injected SPA config and its source bundle. Undefined
    * for webhooks-only edges and for SPA records that predate the field; an
    * SPA edge without a recorded fingerprint is treated as drifted and
    * restarted so the served index provably carries the requested config.
@@ -688,6 +755,7 @@ export function startIngressNginx(opts: {
       ? {
           remoteWebConfigHash: remoteWebConfigFingerprint(
             remoteWebIngress.config,
+            remoteWebIngress.webDistDir,
           ),
         }
       : {}),
@@ -857,7 +925,7 @@ export async function startRemoteWebIngress(opts: {
     listenPort: number;
   }) => void;
 }): Promise<StartRemoteWebIngressResult> {
-  const listenPort = opts.listenPort ?? getNginxIngressPort();
+  let listenPort = opts.listenPort ?? getNginxIngressPort();
   const includeWebApp = opts.includeWebApp ?? true;
 
   const version = getNginxVersion();
@@ -868,6 +936,13 @@ export async function startRemoteWebIngress(opts: {
   const running = isIngressRunning(opts.workspaceDir);
   const recorded = running ? readIngressState(opts.workspaceDir) : null;
   const recordedMode = recorded?.includeWebApp ?? true;
+  if (
+    recorded &&
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    listenPort = recorded.listenPort;
+  }
   // The SPA config the served index must carry, computed up front so the
   // reuse decision and the actual spawn share one value and cannot drift.
   const spaOptions = includeWebApp
@@ -877,9 +952,17 @@ export async function startRemoteWebIngress(opts: {
         ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
       }
     : undefined;
-  const requestedConfigHash = spaOptions
-    ? remoteWebConfigFingerprint(remoteWebIngressConfig(spaOptions))
-    : undefined;
+  const webDistDir = includeWebApp ? findWebDistDir() : null;
+  if (includeWebApp && !webDistDir) {
+    return { status: "web-dist-missing" };
+  }
+  const requestedConfigHash =
+    spaOptions && webDistDir
+      ? remoteWebConfigFingerprint(
+          remoteWebIngressConfig(spaOptions),
+          webDistDir,
+        )
+      : undefined;
   // Both sides are undefined in webhooks-only mode; an SPA record without a
   // fingerprint predates the field and counts as drifted (see IngressState).
   const configMatches = recorded?.remoteWebConfigHash === requestedConfigHash;
@@ -906,14 +989,6 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
-  let webDistDir: string | null = null;
-  if (includeWebApp) {
-    webDistDir = findWebDistDir();
-    if (!webDistDir) {
-      return { status: "web-dist-missing" };
-    }
-  }
-
   // The running edge serves the other mode, targets a different gateway
   // port, or injects a stale SPA config; restart it with the requested
   // config. A false stop can mean the old edge exited on its own after the
@@ -926,6 +1001,23 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
+  // A foreign process squatting the default edge port (another assistant's
+  // edge, a stale dev server) must not kill the tunnel: the edge port is
+  // loopback-local and the public tunnel URL never carries it, so moving to
+  // the next free port is invisible to remote clients. Explicit pins
+  // (opts.listenPort / CADET_NGINX_INGRESS_PORT) keep their intent and still
+  // fail on a collision.
+  if (
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    const discovered = await findAvailableIngressPort(listenPort);
+    if (discovered !== null && discovered !== listenPort) {
+      console.log(`Port ${listenPort} in use; using ${discovered} instead.`);
+      listenPort = discovered;
+    }
+  }
+
   opts.onStarting?.({ version, webDistDir, listenPort });
 
   const child = startIngressNginx({
@@ -1042,6 +1134,7 @@ export async function stopContainerTunnelEdge(
 function stampAppProcessEntry(
   workspaceDir: string,
   assistantId?: string,
+  port = getNginxIngressPort(),
 ): void {
   const pid = getIngressPid(workspaceDir);
   if (pid !== null) {
@@ -1049,6 +1142,7 @@ function stampAppProcessEntry(
       pid,
       startedAt: new Date().toISOString(),
       assistantId,
+      port,
     });
   }
 }
@@ -1116,7 +1210,11 @@ export async function ensureTunnelEdge(opts: {
 
   switch (result.status) {
     case "started":
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: true,
@@ -1150,7 +1248,11 @@ export async function ensureTunnelEdge(opts: {
             stuckEdgeRecoveryHint(opts.workspaceDir),
         );
       }
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: false,

package/src/lib/tunnel.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import { TUNNEL_PROVIDERS } from "@mycadet/service-contracts/ingress";
 import {
   clearRootProcess,
   loadAllAssistants,
@@ -24,26 +26,24 @@ import { waitForDaemonReady } from "./http-client.js";
 import {
   hasWebhookIntegrations,
   IngressConfigSchema,
-  isNgrokProcess,
   maybeStartNgrokTunnel,
   NGROK_TUNNEL_META,
-  runNgrokTunnel,
+  NGROK_PROVIDER,
   saveNgrokDomain,
 } from "./tunnels/ngrok.js";
-import { stopProcess } from "./process.js";
 import { shellArg } from "./shell-arg.js";
 import { notifyGatewayOfPublicUrl } from "./tunnels/gateway-notify.js";
 import {
   selectRestartTunnelRecord,
   type TunnelProviderName,
 } from "@mycadet/service-contracts/ingress";
-import { runCadetTunnel, CADET_TUNNEL_META } from "./tunnels/cadet.js";
+import { CADET_PROVIDER, CADET_TUNNEL_META } from "./tunnels/cadet.js";
 import {
-  runCloudflareTunnel,
+  CLOUDFLARE_PROVIDER,
   CLOUDFLARE_TUNNEL_META,
 } from "./tunnels/cloudflare.js";
 import {
-  runTailscaleTunnel,
+  TAILSCALE_PROVIDER,
   TAILSCALE_TUNNEL_META,
 } from "./tunnels/tailscale.js";
 
@@ -119,6 +119,25 @@ export interface ProviderTunnelResult {
   waitForExit: Promise<void>;
 }
 
+export interface ProviderStopOptions {
+  record: RootProcessRecord;
+  assistantId?: string;
+  workspaceDir?: string;
+}
+
+export interface TunnelProvider {
+  run(opts: ProviderTunnelOptions): Promise<ProviderTunnelResult>;
+  stop(opts: ProviderStopOptions): Promise<boolean>;
+}
+
+const providers: Record<TunnelProviderName, TunnelProvider> = {
+  ngrok: NGROK_PROVIDER,
+  cloudflare: CLOUDFLARE_PROVIDER,
+  tailscale: TAILSCALE_PROVIDER,
+  cadet: CADET_PROVIDER,
+};
+const providerNameSchema = z.enum(TUNNEL_PROVIDERS);
+
 /**
  * Run a tunnel provider by name — the dispatch `cadet tunnel` uses, so the
  * command layer never names a provider implementation directly. Notifies the
@@ -140,29 +159,7 @@ function runProvider(
   provider: TunnelProviderName,
   opts: ProviderTunnelOptions,
 ): Promise<ProviderTunnelResult> {
-  const base = {
-    port: opts.port,
-    assistantId: opts.assistantId,
-    workspaceDir: opts.workspaceDir,
-  };
-  if (provider === "ngrok") {
-    return runNgrokTunnel({
-      ...base,
-      ...(opts.domain ? { domain: opts.domain } : {}),
-    });
-  }
-  if (provider === "cadet") {
-    return runCadetTunnel(opts);
-  }
-  if (provider === "cloudflare") {
-    return runCloudflareTunnel(base);
-  }
-  return runTailscaleTunnel({
-    ...base,
-    ...(opts.preserveIngressUrl
-      ? { preserveIngressUrl: opts.preserveIngressUrl }
-      : {}),
-  });
+  return providers[provider].run(opts);
 }
 
 /** Drop the saved reserved-domain record (providers that keep one). */
@@ -176,13 +173,31 @@ export function clearReservedDomain(): void {
  * signaling — a stale entry after PID reuse must not kill an unrelated
  * process.
  */
-export async function stopTunnelProcess(): Promise<void> {
+export async function stopTunnelProcess(
+  assistantId?: string,
+  workspaceDir?: string,
+): Promise<boolean> {
   const recorded: RootProcessRecord | undefined = readRootProcesses().tunnel;
-  if (!recorded) return;
-  if (isNgrokProcess(recorded.pid)) {
-    await stopProcess(recorded.pid, "tunnel");
+  if (!recorded) return false;
+  if (
+    assistantId &&
+    recorded.assistantId &&
+    recorded.assistantId !== assistantId
+  ) {
+    throw new Error(
+      `The recorded tunnel belongs to '${recorded.assistantId}', not '${assistantId}'.`,
+    );
   }
-  clearRootProcess("tunnel");
+  const provider = providerNameSchema.parse(
+    recorded.provider ?? DEFAULT_TUNNEL_PROVIDER,
+  );
+  const stopped = await providers[provider].stop({
+    record: recorded,
+    assistantId,
+    workspaceDir,
+  });
+  clearRootProcess("tunnel", recorded.pid);
+  return stopped;
 }
 
 /**
@@ -197,6 +212,43 @@ export function adoptedTunnelStopNotice(pid: number | undefined): string {
   );
 }
 
+/**
+ * Pull the single most meaningful failure line out of a tunnel log so the
+ * `cadet tunnel` wrapper can name why the child died instead of only pointing
+ * at the log file. Priority: nginx emerg/bind failures, ngrok error codes,
+ * auth/usage failures, then any generic error/fatal/failed line — the LAST
+ * match wins (the freshest), capped to keep the console line readable. Falls
+ * back to the last non-empty log line, or null for an empty log.
+ */
+export function summarizeStartupFailure(logText: string): string | null {
+  const lines = logText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length === 0) {
+    return null;
+  }
+  const patterns: RegExp[] = [
+    /\[emerg\]/,
+    /bind\(\).*failed/i,
+    /address already in use/i,
+    /ERR_NGROK_\d+/,
+    /authtoken|authentication failed|usage limit|unauthorized/i,
+    /\berror\b|\bfatal\b|\bfailed\b/i,
+  ];
+  const cap = (line: string): string =>
+    line.length > 200 ? `${line.slice(0, 200)}…` : line;
+  for (const pattern of patterns) {
+    const matches = lines.filter((line) => pattern.test(line));
+    const last = matches.at(-1);
+    if (last !== undefined) {
+      return cap(last);
+    }
+  }
+  const lastLine = lines.at(-1);
+  return lastLine === undefined ? null : cap(lastLine);
+}
+
 export {
   ADOPTED_TUNNEL_RE,
   hasWebhookIntegrationsConfigured,

package/src/lib/tunnels/cadet.ts

@@ -1,5 +1,9 @@
 import { STALE_CLI_UPDATE_HINT } from "../stale-cli-hint.js";
-import type { ProviderMeta, ProviderTunnelOptions } from "../tunnel.js";
+import type {
+  TunnelProvider,
+  ProviderMeta,
+  ProviderTunnelOptions,
+} from "../tunnel.js";
 
 /**
  * The managed `cadet` tunnel. It is listed in the shared registry so the
@@ -27,3 +31,10 @@ export async function runCadetTunnel(
 ): Promise<never> {
   throw cadetTunnelComingSoonError("cadet");
 }
+
+export const CADET_PROVIDER: TunnelProvider = {
+  run: runCadetTunnel,
+  async stop() {
+    throw cadetTunnelComingSoonError("cadet");
+  },
+};