@vellumai/assistant 0.11.4-dev.202608201513.9b3b830 → 0.11.4-dev.202608201710.fcf0423

package/AGENTS.md

@@ -18,7 +18,7 @@ When you introduce a new env var that the assistant process needs to read at run
 
 The daemon must **never** block startup due to **subsystem** failures (DB, Qdrant, plugins, feature flags, etc.). If an individual subsystem fails, log the error and continue in degraded mode so the process remains reachable for health checks and diagnostics.
 
-**Exception — duplicate daemon detection:** If the daemon cannot establish **any** client-facing transport because another daemon already holds both the IPC socket and HTTP port, it must exit immediately. A daemon with no transport is unmanageable (invisible to health checks, unreachable by stop commands) yet still runs background jobs (scheduler, memory worker, background wake) against the shared database, causing duplicate side effects.
+**Exception, occupied client-facing transports:** A **transport** is not a subsystem. If either client-facing transport's address is taken (the IPC socket in `ipc/assistant-server.ts`, the runtime HTTP port in `runtime/http-server.ts`), the daemon exits with an `EADDRINUSE`-coded error so `emitDaemonError` reports `PORT_IN_USE`. Half a daemon is worse than none: missing IPC makes it unmanageable while its background jobs still write the shared database, and missing HTTP makes it read healthy over IPC while the gateway proxies `/v1/*` to a foreign listener. Bind failures that are not address collisions (permission denied, fd exhaustion) stay non-fatal.
 
 ## DB migration readiness gating
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.4-dev.202608201513.9b3b830",
+  "version": "0.11.4-dev.202608201710.fcf0423",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/cli/commands/__tests__/channel-verification-sessions.test.ts

@@ -13,10 +13,12 @@
  *   - `revoke` with no flags (channel: undefined)
  *   - `revoke --channel phone` sends channel param
  *   - `create --channel fax` → invalid channel, exits with code 1, IPC not called
+ *   - the accepted `--channel` set is the canonical CHANNEL_IDS vocabulary
  */
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { CHANNEL_IDS } from "@vellumai/service-contracts/channels";
 import { Command } from "commander";
 
 // ---------------------------------------------------------------------------
@@ -242,6 +244,35 @@ describe("channel-verification-sessions create", () => {
     expect(lastIpcCall).toBeNull();
   });
 
+  test("--channel discord reaches IPC (canonical vocabulary, not a local copy)", async () => {
+    const { exitCode } = await runCommand([
+      "channel-verification-sessions",
+      "create",
+      "--channel",
+      "discord",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(lastIpcCall!.method).toBe("channel_verification_sessions_create");
+    expect(lastIpcCall!.params).toMatchObject({
+      body: { channel: "discord", purpose: "guardian" },
+    });
+  });
+
+  test("every canonical channel id is accepted", async () => {
+    for (const channel of CHANNEL_IDS) {
+      const { exitCode } = await runCommand([
+        "channel-verification-sessions",
+        "create",
+        "--channel",
+        channel,
+      ]);
+
+      expect(exitCode).toBe(0);
+      expect(lastIpcCall!.params).toMatchObject({ body: { channel } });
+    }
+  });
+
   test("IPC error results in exit code 1", async () => {
     mockIpcResult = { ok: false, error: "Could not connect" };
 

package/src/cli/commands/channel-verification-sessions.help.ts

@@ -10,15 +10,16 @@ export const channelVerificationSessionsHelp: CliCommandHelp = {
   ],
   helpText: `
 Verification sessions are used to verify guardian bindings and trusted
-contacts across channels (telegram, phone, slack, email). Three flows exist:
+contacts across channels (telegram, phone, slack, discord, email). Three
+flows exist:
 
   1. Inbound challenge — the assistant generates a secret code and waits
      for the guardian to send it back on the channel. Used when the
      guardian can already message the assistant.
 
   2. Outbound verification — the assistant sends a verification code to
-     a destination (Telegram handle, phone number, Slack user ID) and
-     waits for confirmation. Used when bootstrapping a new channel.
+     a destination (Telegram handle, phone number, Slack or Discord user
+     ID) and waits for confirmation. Used when bootstrapping a new channel.
 
   3. Trusted contact verification — verifies a contact channel that
      already exists in the contact graph, sending a code to the channel
@@ -36,7 +37,7 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone, slack, email)",
+          description: "Channel type (telegram, phone, slack, discord, email)",
         },
         {
           flags: "--destination <destination>",
@@ -72,8 +73,8 @@ Routes between three creation modes based on the provided options:
 
   2. Outbound: --channel <ch> --destination <dest>
      Sends a verification code to the given destination. Supports telegram
-     (handle or chat ID), phone (E.164 number), slack (user ID), and email.
-     Use --rebind to replace an existing guardian binding.
+     (handle or chat ID), phone (E.164 number), slack and discord (user ID),
+     and email. Use --rebind to replace an existing guardian binding.
 
   3. Inbound: --channel <ch> (no --destination)
      Generates a challenge secret for the guardian to send back on the
@@ -113,7 +114,7 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone, slack, email)",
+          description: "Channel type (telegram, phone, slack, discord, email)",
           required: true,
         },
         {
@@ -137,7 +138,7 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone, slack, email)",
+          description: "Channel type (telegram, phone, slack, discord, email)",
           required: true,
         },
       ],

package/src/cli/commands/channel-verification-sessions.ts

@@ -1,3 +1,12 @@
+// `cli/no-daemon-internals` forbids hoisting `channels/types.js`, so the CLI
+// reads the vocabulary straight from the contract package that file re-exports.
+// Both sides then validate `--channel` against the same set.
+
+import {
+  CHANNEL_IDS,
+  type ChannelId,
+  isChannelId,
+} from "@vellumai/service-contracts/channels";
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
@@ -6,25 +15,6 @@ import { registerCommand } from "../lib/register-command.js";
 import { writeOutput } from "../output.js";
 import { channelVerificationSessionsHelp } from "./channel-verification-sessions.help.js";
 
-// ---------------------------------------------------------------------------
-// Local channel validation (replaces daemon-internal channels/types.js import)
-// ---------------------------------------------------------------------------
-
-const VALID_CHANNEL_IDS = [
-  "telegram",
-  "phone",
-  "vellum",
-  "whatsapp",
-  "slack",
-  "email",
-  "platform",
-] as const;
-type ChannelId = (typeof VALID_CHANNEL_IDS)[number];
-
-function isChannelId(raw: string): raw is ChannelId {
-  return (VALID_CHANNEL_IDS as readonly string[]).includes(raw);
-}
-
 /**
  * Validate the --channel option. Returns the validated ChannelId or writes an
  * error and returns `false`. When `required` is false an absent value is fine
@@ -49,7 +39,7 @@ function validateChannelOpt(
     if (required) {
       writeOutput(cmd, {
         ok: false,
-        error: `The "channel" option is required. Valid values: ${VALID_CHANNEL_IDS.join(", ")}`,
+        error: `The "channel" option is required. Valid values: ${CHANNEL_IDS.join(", ")}`,
       });
       process.exitCode = 1;
       return false;
@@ -59,7 +49,7 @@ function validateChannelOpt(
   if (!isChannelId(raw)) {
     writeOutput(cmd, {
       ok: false,
-      error: `Invalid channel "${raw}". Valid values: ${VALID_CHANNEL_IDS.join(", ")}`,
+      error: `Invalid channel "${raw}". Valid values: ${CHANNEL_IDS.join(", ")}`,
     });
     process.exitCode = 1;
     return false;

package/src/daemon/lifecycle.ts

@@ -198,8 +198,10 @@ export async function runDaemon(): Promise<void> {
     }
   }
 
-  // Start the runtime HTTP server early so /healthz answers ASAP. A bind
-  // failure is non-fatal — the daemon falls back to IPC-only operation.
+  // Start the runtime HTTP server early so /healthz answers ASAP. Throws on
+  // EADDRINUSE to abort startup: another process holds the port every HTTP
+  // client (and the gateway's /v1/* proxy) targets, so an IPC-only daemon
+  // would look healthy while all HTTP traffic 502s.
   await startRuntimeHttpServer();
 
   // Warms the configured-probe cache (credential reads only, no DB). Fired

package/src/daemon/startup-error.ts

@@ -23,6 +23,22 @@ export interface DaemonStartupError {
 
 const DAEMON_ERROR_PREFIX = "DAEMON_ERROR:";
 
+/**
+ * Build an `EADDRINUSE`-coded error so callers (and {@link categorizeDaemonError})
+ * can branch on `err.code` and surface the structured "already running"
+ * guidance instead of a generic UNKNOWN. Used by every transport that detects
+ * an occupied address itself rather than receiving a kernel-coded error.
+ */
+export function makeAddrInUseError(
+  message: string,
+  cause?: unknown,
+): NodeJS.ErrnoException {
+  const err = new Error(message, cause === undefined ? undefined : { cause });
+  const errno = err as NodeJS.ErrnoException;
+  errno.code = "EADDRINUSE";
+  return errno;
+}
+
 /**
  * Inspect an error and return a categorized {@link DaemonStartupError}.
  */

package/src/ipc/socket-cleanup.ts

@@ -15,6 +15,8 @@ import {
   removeIpcEndpointFile,
 } from "@vellumai/ipc-server-utils";
 
+import { makeAddrInUseError } from "../daemon/startup-error.js";
+
 /**
  * Maximum time to wait for the probe `connect()` to settle before declaring
  * the path occupied. Without a bound, a hung process holding the socket would
@@ -25,17 +27,6 @@ import {
  */
 const PROBE_CONNECT_TIMEOUT_MS = 2000;
 
-/**
- * Build an `EADDRINUSE`-coded error so callers (and `categorizeDaemonError`)
- * can branch on `err.code` and surface the structured "already running"
- * guidance instead of a generic UNKNOWN.
- */
-function makeAddrInUseError(message: string): NodeJS.ErrnoException {
-  const err = new Error(message) as NodeJS.ErrnoException;
-  err.code = "EADDRINUSE";
-  return err;
-}
-
 /**
  * Probe-connect to `socketPath`. Behavior:
  *   - Path doesn't exist → return.

package/src/runtime/__tests__/runtime-http-port-collision.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { emitDaemonError } from "../../daemon/startup-error.js";
+import {
+  startRuntimeHttpServer,
+  stopRuntimeHttpServer,
+} from "../http-server.js";
+
+/**
+ * The daemon binds two client-facing transports. An occupied runtime HTTP port
+ * must abort startup the same way an occupied IPC socket does, so the daemon
+ * can never answer IPC (reading healthy to `vellum ps` and platform status)
+ * while the gateway proxies /v1/* to a foreign listener.
+ */
+describe("runtime HTTP port collision", () => {
+  const originalPort = process.env.RUNTIME_HTTP_PORT;
+
+  afterEach(async () => {
+    await stopRuntimeHttpServer();
+    if (originalPort === undefined) {
+      delete process.env.RUNTIME_HTTP_PORT;
+    } else {
+      process.env.RUNTIME_HTTP_PORT = originalPort;
+    }
+  });
+
+  test("aborts startup when a foreign process holds the runtime HTTP port", async () => {
+    /**
+     * Tests that a runtime HTTP bind collision fails daemon startup instead of
+     * silently degrading to IPC-only operation.
+     */
+
+    // GIVEN a foreign process holding a port
+    const foreign = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("foreign"),
+    });
+
+    // AND the daemon configured to serve HTTP on that same port
+    process.env.RUNTIME_HTTP_PORT = String(foreign.port);
+
+    try {
+      // WHEN the daemon starts its runtime HTTP server
+      const err = await startRuntimeHttpServer().then(
+        () => null,
+        (e: unknown) => e,
+      );
+
+      // THEN startup fails rather than continuing without HTTP
+      expect(err).toBeInstanceOf(Error);
+
+      // AND the failure carries the address-collision code the daemon's
+      // startup-error categorization branches on
+      expect((err as NodeJS.ErrnoException).code).toBe("EADDRINUSE");
+
+      // AND the message names the occupied port and the env var that moves it
+      expect((err as Error).message).toContain(String(foreign.port));
+      expect((err as Error).message).toContain("RUNTIME_HTTP_PORT");
+    } finally {
+      foreign.stop(true);
+    }
+  });
+
+  test("reports a runtime HTTP port collision as PORT_IN_USE on stderr", async () => {
+    /**
+     * Tests that the bind failure reaches consumers that parse the daemon's
+     * structured startup-error line (e.g. the macOS app) as PORT_IN_USE.
+     */
+
+    // GIVEN a foreign process holding the daemon's runtime HTTP port
+    const foreign = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("foreign"),
+    });
+    process.env.RUNTIME_HTTP_PORT = String(foreign.port);
+
+    // AND stderr captured so the structured startup-error line is observable
+    const written: string[] = [];
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      written.push(chunk.toString());
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      // WHEN the daemon's startup error handler reports the bind failure
+      const err = await startRuntimeHttpServer().then(
+        () => null,
+        (e: unknown) => e,
+      );
+      emitDaemonError(err);
+
+      // THEN the structured line categorizes the failure as PORT_IN_USE
+      const line = written.find((entry) => entry.includes("DAEMON_ERROR:"));
+      expect(line).toBeDefined();
+      const structured = JSON.parse(
+        (line as string).replace("DAEMON_ERROR:", "").trim(),
+      ) as Record<string, unknown>;
+      expect(structured.error).toBe("PORT_IN_USE");
+    } finally {
+      process.stderr.write = originalWrite;
+      foreign.stop(true);
+    }
+  });
+
+  test("binds and leaves the singleton serving when the port is free", async () => {
+    /**
+     * Tests that the collision guard does not turn ordinary startup into a
+     * failure: a free port still yields a listening HTTP server.
+     */
+
+    // GIVEN a free port for the runtime HTTP server
+    const probe = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("probe"),
+    });
+    const freePort = probe.port;
+    probe.stop(true);
+    process.env.RUNTIME_HTTP_PORT = String(freePort);
+
+    // WHEN the daemon starts its runtime HTTP server
+    await startRuntimeHttpServer();
+
+    // THEN the server answers its liveness probe
+    const response = await fetch(`http://127.0.0.1:${freePort}/healthz`);
+    expect(response.status).toBe(200);
+  });
+});

package/src/runtime/http-server.ts

@@ -27,6 +27,7 @@ import {
   isDbMigrationGateBypassed,
 } from "../daemon/daemon-readiness.js";
 import { processMessage } from "../daemon/process-message.js";
+import { makeAddrInUseError } from "../daemon/startup-error.js";
 import {
   createLiveVoiceConnection,
   type LiveVoiceConnection,
@@ -975,9 +976,14 @@ let instance: RuntimeHttpServer | null = null;
 
 /**
  * Start the runtime HTTP server singleton early in daemon startup so /healthz
- * answers ASAP. A bind failure (port in use, permission denied, fd exhaustion)
- * is non-fatal: it is logged and the daemon falls back to IPC-only operation,
- * leaving the singleton unset.
+ * answers ASAP.
+ *
+ * An occupied address (`EADDRINUSE`) aborts startup: whatever holds the port
+ * owns every HTTP client of this workspace, including the gateway proxy that
+ * fronts `/v1/*`. Continuing would leave a daemon that answers IPC (so `vellum
+ * ps` and platform status read healthy) while every proxied HTTP route 502s
+ * against a foreign listener. Any other bind failure (permission denied, fd
+ * exhaustion) is non-fatal, logged with the singleton left unset.
  */
 export async function startRuntimeHttpServer(): Promise<void> {
   const port = getRuntimeHttpPort();
@@ -992,11 +998,20 @@ export async function startRuntimeHttpServer(): Promise<void> {
       "Daemon startup: runtime HTTP server listening",
     );
   } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EADDRINUSE") {
+      log.error(
+        { err, port, hostname },
+        "Runtime HTTP port already in use, aborting startup to avoid an HTTP-blind daemon",
+      );
+      throw makeAddrInUseError(
+        `Runtime HTTP port ${hostname}:${port} is already in use by another process. Stop it, or set RUNTIME_HTTP_PORT to a free port.`,
+        err,
+      );
+    }
     log.warn(
       { err, port },
       "Failed to start runtime HTTP server, continuing without it",
     );
-    instance = null;
   }
 }
 
@@ -1007,7 +1022,7 @@ export async function startRuntimeHttpServer(): Promise<void> {
  * expiry, profile reaping) must still run; the retry sweep additionally skips
  * its cycles while readiness is unready. Never called before migrations settle,
  * so the sweeps can't race a schema mid-migration. No-op if the HTTP server
- * failed to bind (IPC-only mode) or sweeps already started.
+ * isn't running or sweeps already started.
  */
 export function startRuntimeHttpServerBackgroundSweeps(): void {
   instance?.startBackgroundSweeps();