@vellumai/cli 0.8.8-dev.202606081515.c77a9b6 → 0.8.8-dev.202606081859.f7bdc00

package/node_modules/@vellumai/local-mode/src/__tests__/loopback-auth.test.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { headerHostIsLoopback, originIsAllowed } from "../util";
+import { isActiveAssistant } from "../lockfile";
+
+describe("headerHostIsLoopback", () => {
+  test("rejects DNS-rebound hosts", () => {
+    expect(headerHostIsLoopback("attacker.example")).toBe(false);
+    expect(headerHostIsLoopback("evil.com:3000")).toBe(false);
+  });
+
+  test("accepts loopback hosts", () => {
+    expect(headerHostIsLoopback("127.0.0.1:3000")).toBe(true);
+    expect(headerHostIsLoopback("localhost:3000")).toBe(true);
+    expect(headerHostIsLoopback("localhost")).toBe(true);
+    expect(headerHostIsLoopback("[::1]:3000")).toBe(true);
+  });
+
+  test("rejects undefined/empty", () => {
+    expect(headerHostIsLoopback(undefined)).toBe(false);
+    expect(headerHostIsLoopback("")).toBe(false);
+  });
+});
+
+describe("originIsAllowed", () => {
+  test("rejects cross-origin requests", () => {
+    expect(originIsAllowed("https://attacker.example")).toBe(false);
+    expect(originIsAllowed("http://evil.com")).toBe(false);
+  });
+
+  test("accepts localhost origins", () => {
+    expect(originIsAllowed("http://localhost:3000")).toBe(true);
+    expect(originIsAllowed("http://127.0.0.1:3000")).toBe(true);
+  });
+
+  test("allows absent origin (non-browser clients)", () => {
+    expect(originIsAllowed(undefined)).toBe(true);
+  });
+});
+
+describe("isActiveAssistant", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function makeTempDir(): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "vellum-local-mode-test-"));
+    tempDirs.push(dir);
+    return dir;
+  }
+
+  test("returns true for the active assistant", () => {
+    const dir = makeTempDir();
+    const lockfilePath = path.join(dir, "lockfile.json");
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({
+        assistants: [{ assistantId: "active" }, { assistantId: "inactive" }],
+        activeAssistant: "active",
+      }),
+    );
+    expect(isActiveAssistant([lockfilePath], "active")).toBe(true);
+  });
+
+  test("returns false for a non-active assistant", () => {
+    const dir = makeTempDir();
+    const lockfilePath = path.join(dir, "lockfile.json");
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({
+        assistants: [{ assistantId: "active" }, { assistantId: "inactive" }],
+        activeAssistant: "active",
+      }),
+    );
+    expect(isActiveAssistant([lockfilePath], "inactive")).toBe(false);
+  });
+
+  test("returns false when lockfile does not exist", () => {
+    expect(isActiveAssistant(["/nonexistent/lockfile.json"], "any")).toBe(false);
+  });
+});

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -9,6 +9,8 @@
 export {
   stripSensitiveFields,
   isLoopbackAddr,
+  headerHostIsLoopback,
+  originIsAllowed,
   resolveDevCliInvocation,
 } from "./util";
 export type { CliInvocation } from "./util";
@@ -19,6 +21,7 @@ export {
   getLockfileData,
   upsertLockfileAssistant,
   replacePlatformAssistants,
+  isActiveAssistant,
 } from "./lockfile";
 export type { LockfileResult, WriteResult } from "./lockfile";
 export { parseLockfile } from "./lockfile-contract";

package/node_modules/@vellumai/local-mode/src/lockfile.ts

@@ -88,6 +88,21 @@ export function upsertLockfileAssistant(
   return { ok: true, lockfile: parseLockfile(stripped) };
 }
 
+export function isActiveAssistant(
+  lockfilePaths: string[],
+  assistantId: string,
+): boolean {
+  for (const candidate of lockfilePaths) {
+    try {
+      const data = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
+      return data.activeAssistant === assistantId;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+
 export function replacePlatformAssistants(
   lockfilePaths: string[],
   platformAssistants: Array<Record<string, unknown>>,

package/node_modules/@vellumai/local-mode/src/util.ts

@@ -42,6 +42,39 @@ export function stripSensitiveFields(data: Record<string, unknown>): void {
   }
 }
 
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase();
+  return (
+    normalized === "localhost" ||
+    normalized === "[::1]" ||
+    normalized === "::1" ||
+    normalized === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(normalized)
+  );
+}
+
+export function headerHostIsLoopback(hostHeader: string | undefined): boolean {
+  if (!hostHeader) return false;
+  try {
+    return isLoopbackHostname(new URL(`http://${hostHeader}`).hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function originIsAllowed(originHeader: string | undefined): boolean {
+  if (!originHeader) return true;
+  try {
+    const origin = new URL(originHeader);
+    return (
+      (origin.protocol === "http:" || origin.protocol === "https:") &&
+      isLoopbackHostname(origin.hostname)
+    );
+  } catch {
+    return false;
+  }
+}
+
 export function isLoopbackAddr(addr: string): boolean {
   const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
   const normalized = v4Mapped ? v4Mapped[1]! : addr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.8-dev.202606081515.c77a9b6",
+  "version": "0.8.8-dev.202606081859.f7bdc00",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/client-tui-refresh.test.ts

@@ -10,15 +10,30 @@ import { join } from "node:path";
 
 const ORIGINAL_XDG = process.env.XDG_CONFIG_HOME;
 const ORIGINAL_ENV = process.env.VELLUM_ENVIRONMENT;
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
 const ORIGINAL_FETCH = globalThis.fetch;
 
 import { resolveFreshBearerToken } from "../commands/client.js";
+import { saveAssistantEntry } from "../lib/assistant-config.js";
 import { saveGuardianToken } from "../lib/guardian-token.js";
 
 const RUNTIME = "http://10.0.0.9:7830";
 const past = () => new Date(Date.now() - 60_000).toISOString();
 const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
 
+/** Persist a lockfile entry so the refresh URL-binding check has a trusted
+ *  runtimeUrl to compare against (refresh is bound to the persisted entry). */
+function seedEntry(cloud: string): void {
+  saveAssistantEntry({
+    assistantId: "px",
+    name: "Paired",
+    runtimeUrl: RUNTIME,
+    cloud,
+    paired: cloud === "paired",
+    species: "vellum",
+  });
+}
+
 function seed(opts: {
   accessToken: string;
   refreshToken: string;
@@ -37,12 +52,15 @@ function seed(opts: {
   });
 }
 
-/** Stub global fetch; returns whether the refresh endpoint was hit. */
-function stubRefresh(ok: boolean): { hit: () => boolean } {
-  let called = false;
+/** Stub global fetch; returns whether the refresh endpoint was hit and where. */
+function stubRefresh(ok: boolean): {
+  hit: () => boolean;
+  url: () => string | undefined;
+} {
+  let calledUrl: string | undefined;
   globalThis.fetch = (async (url: unknown, _init?: RequestInit) => {
     if (String(url).includes("/v1/guardian/refresh")) {
-      called = true;
+      calledUrl = String(url);
       return new Response(
         ok ? JSON.stringify({ accessToken: "new-acc" }) : "nope",
         {
@@ -53,7 +71,7 @@ function stubRefresh(ok: boolean): { hit: () => boolean } {
     }
     return new Response("", { status: 200 });
   }) as typeof fetch;
-  return { hit: () => called };
+  return { hit: () => calledUrl !== undefined, url: () => calledUrl };
 }
 
 describe("resolveFreshBearerToken", () => {
@@ -62,6 +80,9 @@ describe("resolveFreshBearerToken", () => {
   beforeEach(() => {
     tempHome = mkdtempSync(join(tmpdir(), "client-tui-refresh-test-"));
     process.env.XDG_CONFIG_HOME = tempHome;
+    // Isolate the lockfile too — saveAssistantEntry writes the prod lockfile
+    // (~/.vellum.lock.json) unless VELLUM_LOCKFILE_DIR is set.
+    process.env.VELLUM_LOCKFILE_DIR = tempHome;
     delete process.env.VELLUM_ENVIRONMENT; // prod config dir
   });
 
@@ -69,12 +90,16 @@ describe("resolveFreshBearerToken", () => {
     globalThis.fetch = ORIGINAL_FETCH;
     if (ORIGINAL_XDG === undefined) delete process.env.XDG_CONFIG_HOME;
     else process.env.XDG_CONFIG_HOME = ORIGINAL_XDG;
+    if (ORIGINAL_LOCKFILE_DIR === undefined)
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    else process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
     if (ORIGINAL_ENV === undefined) delete process.env.VELLUM_ENVIRONMENT;
     else process.env.VELLUM_ENVIRONMENT = ORIGINAL_ENV;
     rmSync(tempHome, { recursive: true, force: true });
   });
 
   test("refreshes a stale stored token and returns the new access token", async () => {
+    seedEntry("paired");
     seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
     const refresh = stubRefresh(true);
 
@@ -89,6 +114,24 @@ describe("resolveFreshBearerToken", () => {
     expect(refresh.hit()).toBe(true);
   });
 
+  test("does NOT refresh against an overridden/poisoned runtime URL (no credential leak)", async () => {
+    // --url can override the runtime URL while still reusing the stored guardian
+    // token; a stale token must NOT be refreshed against an attacker origin.
+    seedEntry("paired"); // persisted runtimeUrl = RUNTIME
+    seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
+    const refresh = stubRefresh(true);
+
+    const token = await resolveFreshBearerToken(
+      "http://attacker.example:7830",
+      "px",
+      "old-acc",
+      "paired",
+    );
+
+    expect(token).toBe("old-acc"); // unchanged
+    expect(refresh.hit()).toBe(false); // no refresh POST anywhere
+  });
+
   test("leaves a still-fresh stored token unchanged (no refresh)", async () => {
     seed({
       accessToken: "old-acc",
@@ -140,6 +183,7 @@ describe("resolveFreshBearerToken", () => {
   });
 
   test("falls back to the existing token when refresh fails", async () => {
+    seedEntry("paired");
     seed({ accessToken: "old-acc", refreshToken: "ref", refreshAfter: past() });
     stubRefresh(false); // refresh endpoint returns non-ok
 

package/src/__tests__/message.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "bun:test";
+
+import { parseMessageArgs } from "../commands/message.js";
+
+describe("parseMessageArgs", () => {
+  test("parses an inline message with the active assistant", () => {
+    const r = parseMessageArgs(["hello"]);
+    expect(r).toEqual({
+      ok: true,
+      value: {
+        conversationKey: undefined,
+        jsonOutput: false,
+        inlineMessage: "hello",
+      },
+    });
+  });
+
+  test("parses an explicit assistant plus inline message", () => {
+    const r = parseMessageArgs(["my-assistant", "ping"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.assistantId).toBe("my-assistant");
+    expect(r.value.inlineMessage).toBe("ping");
+    expect(r.value.filePath).toBeUndefined();
+  });
+
+  test("requires message content when nothing is provided", () => {
+    const r = parseMessageArgs([]);
+    expect(r).toEqual({ ok: false, error: "message content is required." });
+  });
+
+  test("reads content from --file with the active assistant", () => {
+    const r = parseMessageArgs(["--file", "prompt.txt"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.filePath).toBe("prompt.txt");
+    expect(r.value.assistantId).toBeUndefined();
+    expect(r.value.inlineMessage).toBeUndefined();
+  });
+
+  test("reads content from --file with an explicit assistant", () => {
+    const r = parseMessageArgs(["my-assistant", "--file", "prompt.txt"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.assistantId).toBe("my-assistant");
+    expect(r.value.filePath).toBe("prompt.txt");
+  });
+
+  test("supports stdin via --file -", () => {
+    const r = parseMessageArgs(["--file", "-"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.filePath).toBe("-");
+  });
+
+  test("rejects combining --file with an inline message", () => {
+    const r = parseMessageArgs(["my-assistant", "extra", "--file", "p.txt"]);
+    expect(r).toEqual({
+      ok: false,
+      error: "--file cannot be combined with an inline message argument.",
+    });
+  });
+
+  test("rejects --file without a path argument", () => {
+    const r = parseMessageArgs(["my-assistant", "--file"]);
+    expect(r).toEqual({
+      ok: false,
+      error: "--file requires a path argument.",
+    });
+  });
+
+  test("preserves --conversation-key and --json alongside --file", () => {
+    const r = parseMessageArgs([
+      "--json",
+      "--conversation-key",
+      "thread-1",
+      "--file",
+      "prompt.txt",
+    ]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.jsonOutput).toBe(true);
+    expect(r.value.conversationKey).toBe("thread-1");
+    expect(r.value.filePath).toBe("prompt.txt");
+  });
+});

package/src/__tests__/tui-midsession-refresh.test.ts

@@ -21,11 +21,12 @@ import { saveGuardianToken } from "../lib/guardian-token";
 const RUNTIME = "http://10.0.0.9:7830";
 const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
 
-function seedEntry(cloud: string): void {
+function seedEntry(cloud: string, localUrl?: string): void {
   saveAssistantEntry({
     assistantId: "px",
     name: "Paired",
     runtimeUrl: RUNTIME,
+    ...(localUrl ? { localUrl } : {}),
     cloud,
     paired: cloud === "paired",
     species: "vellum",
@@ -46,11 +47,14 @@ function seedToken(accessToken: string, refreshToken: string): void {
   });
 }
 
-function stubRefresh(ok: boolean): { hit: () => boolean } {
-  let called = false;
+function stubRefresh(ok: boolean): {
+  hit: () => boolean;
+  url: () => string | undefined;
+} {
+  let calledUrl: string | undefined;
   globalThis.fetch = (async (url: unknown, _init?: RequestInit) => {
     if (String(url).includes("/v1/guardian/refresh")) {
-      called = true;
+      calledUrl = String(url);
       return new Response(
         ok ? JSON.stringify({ accessToken: "new-acc" }) : "x",
         {
@@ -61,7 +65,7 @@ function stubRefresh(ok: boolean): { hit: () => boolean } {
     }
     return new Response("", { status: 200 });
   }) as typeof fetch;
-  return { hit: () => called };
+  return { hit: () => calledUrl !== undefined, url: () => calledUrl };
 }
 
 describe("maybeRefreshAuthHeaders", () => {
@@ -102,6 +106,41 @@ describe("maybeRefreshAuthHeaders", () => {
     expect(refresh.hit()).toBe(true);
   });
 
+  test("does NOT refresh against an overridden/poisoned baseUrl (no credential leak)", async () => {
+    // The CLI lets --url override the runtime URL while still using the stored
+    // paired guardian token. A 401 from that attacker origin must NOT cause us
+    // to POST the refreshToken + deviceId there.
+    seedEntry("paired"); // persisted runtimeUrl = RUNTIME
+    seedToken("old-acc", "ref");
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer old-acc" };
+    const attacker = "http://attacker.example:7830";
+
+    const ok = await maybeRefreshAuthHeaders(attacker, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(auth.Authorization).toBe("Bearer old-acc"); // unchanged
+    expect(refresh.hit()).toBe(false); // no refresh POST anywhere
+  });
+
+  test("refreshes against the matched persisted URL, keeping the session's interface", async () => {
+    // When an entry persists both a loopback localUrl and a different
+    // runtimeUrl, a session on the loopback URL must refresh against THAT URL,
+    // not the external runtimeUrl (which may be unreachable / public-facing).
+    const localUrl = "http://127.0.0.1:7830";
+    seedEntry("paired", localUrl); // runtimeUrl = RUNTIME (10.0.0.9), localUrl = loopback
+    seedToken("old-acc", "ref");
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer old-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(localUrl, "px", auth);
+
+    expect(ok).toBe(true);
+    expect(refresh.hit()).toBe(true);
+    expect(refresh.url()).toContain("127.0.0.1");
+    expect(refresh.url()).not.toContain("10.0.0.9");
+  });
+
   test("does NOT refresh a local assistant (scoped to paired only)", async () => {
     seedEntry("local");
     seedToken("old-acc", "ref"); // even with a refreshable token

package/src/commands/client.ts

@@ -1,6 +1,5 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { hostname } from "node:os";
 import path from "node:path";
 
 import {
@@ -18,7 +17,7 @@ import {
   type Species,
 } from "../lib/constants";
 import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
-import { getLocalLanIPv4 } from "../lib/local";
+import { normalizeRuntimeUrl, trustedRefreshUrl } from "../lib/runtime-url";
 import {
   CLI_INTERFACE_ID,
   WEB_INTERFACE_ID,
@@ -28,6 +27,7 @@ import {
   getLockfileData,
   upsertLockfileAssistant,
   replacePlatformAssistants,
+  isActiveAssistant,
   runHatch,
   runRetire,
   getGuardianAccessToken,
@@ -35,6 +35,8 @@ import {
   resolveGatewayProxyTarget,
   readAllowedGatewayPorts,
   isLoopbackAddr,
+  headerHostIsLoopback,
+  originIsAllowed,
   resolveDevCliInvocation,
   resolveLockfilePaths,
   resolveConfigDir,
@@ -212,7 +214,7 @@ export function parseArgs(): ParsedArgs {
   }
 
   return {
-    runtimeUrl: maybeSwapToLocalhost(runtimeUrl.replace(/\/+$/, "")),
+    runtimeUrl: normalizeRuntimeUrl(runtimeUrl),
     assistantId,
     assistantName,
     species,
@@ -223,45 +225,6 @@ export function parseArgs(): ParsedArgs {
   };
 }
 
-/**
- * If the hostname in `url` matches this machine's local DNS name, LAN IP, or
- * raw hostname, replace it with 127.0.0.1 so the client avoids mDNS round-trips
- * when talking to an assistant running on the same machine.
- */
-function maybeSwapToLocalhost(url: string): string {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return url;
-  }
-
-  const urlHost = parsed.hostname.toLowerCase();
-
-  const localNames: string[] = [];
-
-  const host = hostname();
-  if (host) {
-    localNames.push(host.toLowerCase());
-    // Also consider the bare name without .local suffix
-    if (host.toLowerCase().endsWith(".local")) {
-      localNames.push(host.toLowerCase().slice(0, -".local".length));
-    }
-  }
-
-  const lanIp = getLocalLanIPv4();
-  if (lanIp) {
-    localNames.push(lanIp);
-  }
-
-  if (localNames.includes(urlHost)) {
-    parsed.hostname = "127.0.0.1";
-    return parsed.toString().replace(/\/+$/, "");
-  }
-
-  return url;
-}
-
 function printUsage(): void {
   console.log(`${ANSI.bold}vellum client${ANSI.reset} - Connect to a hatched assistant
 
@@ -424,6 +387,13 @@ async function handleLocalEndpoints(
     return Response.json({ error: "Forbidden" }, { status: 403 });
   }
 
+  if (
+    !headerHostIsLoopback(req.headers.get("host") ?? undefined) ||
+    !originIsAllowed(req.headers.get("origin") ?? undefined)
+  ) {
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
   // Lockfile
   if (LOCKFILE_PATTERN.test(pathname)) {
     if (req.method === "GET") {
@@ -530,6 +500,13 @@ async function handleLocalEndpoints(
       );
     }
 
+    if (!isActiveAssistant(lockfilePaths, assistantId)) {
+      return Response.json(
+        { ok: false, error: "Can only retire the active local assistant" },
+        { status: 403 },
+      );
+    }
+
     let invocation: CliInvocation;
     try {
       invocation = resolveDevCliInvocation(_baseDir);
@@ -853,7 +830,17 @@ export async function resolveFreshBearerToken(
   const renewAt = new Date(renewAtRaw).getTime();
   if (!Number.isFinite(renewAt) || renewAt > Date.now()) return bearerToken;
 
-  const refreshed = await refreshGuardianToken(runtimeUrl, assistantId);
+  // SECURITY: bind the refresh to the entry's persisted URL. `--url`/`-u` can
+  // override `runtimeUrl` while still reusing this stored guardian token, so a
+  // poisoned/attacker URL must not receive the long-lived refreshToken +
+  // deviceId. Refresh only when the URL is one of the entry's persisted URLs,
+  // and send to the trusted persisted URL — not the caller-supplied one.
+  const lookup = lookupAssistantByIdentifier(assistantId);
+  if (lookup.status !== "found") return bearerToken;
+  const refreshUrl = trustedRefreshUrl(lookup.entry, runtimeUrl);
+  if (!refreshUrl) return bearerToken;
+
+  const refreshed = await refreshGuardianToken(refreshUrl, assistantId);
   return refreshed?.accessToken ?? bearerToken;
 }
 

package/src/commands/message.ts

@@ -6,6 +6,8 @@
  * subscribe to SSE events (use `vellum events` for that).
  */
 
+import { readFileSync } from "node:fs";
+
 import { extractFlag } from "../lib/arg-utils.js";
 import { AssistantClient } from "../lib/assistant-client.js";
 
@@ -14,57 +16,145 @@ function printUsage(): void {
 
 USAGE:
     vellum message [assistant] <message>
+    vellum message [assistant] --file <path>
 
 ARGUMENTS:
     [assistant]    Instance name (default: active assistant)
-    <message>      Message content to send
+    <message>      Message content to send (omit when using --file)
 
 OPTIONS:
+    --file <path>             Read message content from a file ("-" reads stdin)
     --conversation-key <key>  Conversation key (default: stable key per channel/interface)
     --json                    Output raw JSON response
 
 EXAMPLES:
     vellum message "hello"
     vellum message my-assistant "ping"
+    vellum message --file prompt.txt
+    vellum message my-assistant --file prompt.txt
+    cat prompt.txt | vellum message --file -
     vellum message --conversation-key my-thread "hello"
     vellum message --json "hello"
 `);
 }
 
-export async function message(): Promise<void> {
-  const rawArgs = process.argv.slice(3);
+interface ParsedMessageArgs {
+  assistantId?: string;
+  conversationKey?: string;
+  jsonOutput: boolean;
+  /** Path to read message content from, or undefined for an inline message. */
+  filePath?: string;
+  /** Inline message content, present only when --file was not used. */
+  inlineMessage?: string;
+}
 
-  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-    printUsage();
-    return;
-  }
+type ParseResult =
+  | { ok: true; value: ParsedMessageArgs }
+  | { ok: false; error: string };
 
+/**
+ * Parse `vellum message` arguments. Pure: does no I/O and never exits, so the
+ * positional/flag rules can be unit-tested. File reading and validation of the
+ * resolved content happen in {@link message}.
+ */
+export function parseMessageArgs(rawArgs: string[]): ParseResult {
   const jsonOutput = rawArgs.includes("--json");
   let args = rawArgs.filter((a) => a !== "--json");
 
-  const [conversationKey, filteredArgs] = extractFlag(
+  const [conversationKey, afterConversationKey] = extractFlag(
     args,
     "--conversation-key",
   );
-  args = filteredArgs;
+  args = afterConversationKey;
+
+  const fileFlagPresent = args.includes("--file");
+  const [filePath, afterFile] = extractFlag(args, "--file");
+  args = afterFile;
+
+  // `extractFlag` strips a trailing value-less `--file`, which would otherwise
+  // make the next positional masquerade as the message content. Reject it.
+  if (fileFlagPresent && filePath === undefined) {
+    return { ok: false, error: "--file requires a path argument." };
+  }
 
-  let assistantId: string | undefined;
-  let messageContent: string | undefined;
+  if (filePath !== undefined) {
+    // vellum message [assistant] --file <path>
+    // The message content comes from the file, so any remaining positional
+    // arg is the assistant target.
+    if (args.length >= 2) {
+      return {
+        ok: false,
+        error: "--file cannot be combined with an inline message argument.",
+      };
+    }
+    return {
+      ok: true,
+      value: { assistantId: args[0], conversationKey, jsonOutput, filePath },
+    };
+  }
 
   if (args.length >= 2) {
     // vellum message <assistant> <message>
-    assistantId = args[0];
-    messageContent = args[1];
-  } else if (args.length === 1) {
+    return {
+      ok: true,
+      value: {
+        assistantId: args[0],
+        conversationKey,
+        jsonOutput,
+        inlineMessage: args[1],
+      },
+    };
+  }
+  if (args.length === 1) {
     // vellum message <message>  (uses active/latest assistant)
-    messageContent = args[0];
+    return {
+      ok: true,
+      value: { conversationKey, jsonOutput, inlineMessage: args[0] },
+    };
   }
 
-  if (!messageContent) {
-    console.error("Error: message content is required.");
-    console.error("");
+  return { ok: false, error: "message content is required." };
+}
+
+function exitWithUsage(error: string): never {
+  console.error(`Error: ${error}`);
+  console.error("");
+  printUsage();
+  process.exit(1);
+}
+
+export async function message(): Promise<void> {
+  const rawArgs = process.argv.slice(3);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
     printUsage();
-    process.exit(1);
+    return;
+  }
+
+  const parsed = parseMessageArgs(rawArgs);
+  if (!parsed.ok) {
+    exitWithUsage(parsed.error);
+  }
+
+  const { assistantId, conversationKey, jsonOutput, filePath, inlineMessage } =
+    parsed.value;
+
+  let messageContent: string;
+  if (filePath !== undefined) {
+    try {
+      messageContent = readFileSync(filePath === "-" ? 0 : filePath, "utf-8");
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.error(
+        `Error: could not read message file "${filePath}": ${reason}`,
+      );
+      process.exit(1);
+    }
+    if (messageContent.length === 0) {
+      exitWithUsage(`message file "${filePath}" is empty.`);
+    }
+  } else {
+    messageContent = inlineMessage ?? "";
   }
 
   const client = new AssistantClient({ assistantId });

package/src/components/DefaultMainScreen.tsx

@@ -13,6 +13,7 @@ import { SPECIES_CONFIG, type Species } from "../lib/constants";
 import { lookupAssistantByIdentifier } from "../lib/assistant-config";
 import { checkHealth } from "../lib/health-check";
 import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
+import { trustedRefreshUrl } from "../lib/runtime-url";
 import { appendHistory, loadHistory } from "../lib/input-history";
 import { tuiLog } from "../lib/tui-log";
 import { segmentsToPlainText } from "../lib/segments-to-plain-text";
@@ -193,6 +194,16 @@ function friendlyErrorMessage(status: number, body: string): string {
  * and access-only tokens. Because the TUI threads one shared `auth` object by
  * reference, mutating it here propagates to every later request and the SSE
  * reconnect — no callback threading needed.
+ *
+ * SECURITY: the refresh is bound to the paired entry's persisted runtime URL.
+ * `vellum client` lets `--url`/`-u` override the runtime URL while still using
+ * the selected paired entry's stored guardian token, so a victim pointed at an
+ * attacker-controlled (or poisoned/redirected) URL that returns 401 must NOT
+ * cause us to POST the long-lived refreshToken + deviceId to that origin. We
+ * therefore (a) refuse to refresh unless `baseUrl` normalizes to one of the
+ * entry's persisted URLs, and (b) send the refresh to the persisted URL rather
+ * than the caller-supplied `baseUrl` — defense in depth if the gate is ever
+ * bypassed.
  */
 export async function maybeRefreshAuthHeaders(
   baseUrl: string,
@@ -210,11 +221,18 @@ export async function maybeRefreshAuthHeaders(
     return false;
   }
 
+  // Bind the refresh origin to the persisted paired entry: refuse (and never
+  // leak credentials) if `baseUrl` was overridden via --url or poisoned to an
+  // origin that isn't one of the entry's persisted URLs. `refreshUrl` is the
+  // trusted persisted URL we actually send to.
+  const refreshUrl = trustedRefreshUrl(lookup.entry, baseUrl);
+  if (!refreshUrl) return false;
+
   const stored = loadGuardianToken(assistantId);
   if (!stored || stored.accessToken !== bearer || !stored.refreshToken) {
     return false;
   }
-  const refreshed = await refreshGuardianToken(baseUrl, assistantId);
+  const refreshed = await refreshGuardianToken(refreshUrl, assistantId);
   if (!refreshed?.accessToken) return false;
   auth["Authorization"] = `Bearer ${refreshed.accessToken}`;
   return true;

package/src/lib/__tests__/docker.test.ts

@@ -293,20 +293,22 @@ describe("collectWatchTargets", () => {
     rmSync(repoRoot, { recursive: true, force: true });
   });
 
-  function scaffold(relDir: string, { src = true, pkg = true } = {}): void {
+  function scaffold(
+    relDir: string,
+    { src = true, pkg = true, dockerfile = false } = {},
+  ): void {
+    mkdirSync(join(repoRoot, relDir), { recursive: true });
     if (src) mkdirSync(join(repoRoot, relDir, "src"), { recursive: true });
-    if (pkg) {
-      mkdirSync(join(repoRoot, relDir), { recursive: true });
-      writeFileSync(join(repoRoot, relDir, "package.json"), "{}");
-    }
+    if (pkg) writeFileSync(join(repoRoot, relDir, "package.json"), "{}");
+    if (dockerfile) writeFileSync(join(repoRoot, relDir, "Dockerfile"), "");
   }
 
-  test("scopes watch targets to each service's src/ tree and package.json", () => {
-    // GIVEN the three services plus a couple of shared packages, each with a
-    // src/ directory and a package.json manifest
-    scaffold("assistant");
-    scaffold("credential-executor");
-    scaffold("gateway");
+  test("scopes watch targets to src/, package.json, and the Dockerfile", () => {
+    // GIVEN the three services (each with a Dockerfile) plus a couple of
+    // shared packages (libraries, no Dockerfile)
+    scaffold("assistant", { dockerfile: true });
+    scaffold("credential-executor", { dockerfile: true });
+    scaffold("gateway", { dockerfile: true });
     scaffold("packages/service-contracts");
     scaffold("packages/local-mode");
 
@@ -324,12 +326,16 @@ describe("collectWatchTargets", () => {
       ].sort(),
     );
 
-    // AND only the package.json manifests are watched as files
+    // AND the package.json manifests and service Dockerfiles are watched as
+    // individual files (packages have no Dockerfile, so none is emitted)
     expect(files.sort()).toEqual(
       [
         join(repoRoot, "assistant", "package.json"),
+        join(repoRoot, "assistant", "Dockerfile"),
         join(repoRoot, "credential-executor", "package.json"),
+        join(repoRoot, "credential-executor", "Dockerfile"),
         join(repoRoot, "gateway", "package.json"),
+        join(repoRoot, "gateway", "Dockerfile"),
         join(repoRoot, "packages", "local-mode", "package.json"),
         join(repoRoot, "packages", "service-contracts", "package.json"),
       ].sort(),

package/src/lib/docker.ts

@@ -791,7 +791,7 @@ export async function captureImageRefs(
 
 /**
  * Build the set of paths the hot-reload watcher should observe, scoped to
- * each service's `src/` tree and `package.json` manifest.
+ * each service's `src/` tree, `package.json` manifest, and `Dockerfile`.
  *
  * We deliberately avoid recursively watching whole service directories.
  * Those contain `.claude/` command symlinks — which dangle in a fresh
@@ -799,8 +799,11 @@ export async function captureImageRefs(
  * repo — as well as `node_modules`. `fs.watch(dir, { recursive: true })`
  * traverses those entries and emits an unhandled `error` event on a broken
  * symlink, which crashes the CLI process. Source code only ever lives under
- * `src/` (plus the manifest), so watching those paths preserves hot-reload
- * without walking into symlinked or generated trees.
+ * `src/`, so watching that tree plus the two manifests that drive the image
+ * build (`package.json` and `Dockerfile`) preserves hot-reload without
+ * walking into symlinked or generated trees. The `Dockerfile` is watched as
+ * an individual file for the same reason — editing build steps should
+ * trigger a rebuild, but the file sits next to the symlinked trees we avoid.
  *
  * Returning a plain record keeps this trivially unit-testable — see
  * `__tests__/docker.test.ts`.
@@ -828,8 +831,10 @@ export function collectWatchTargets(repoRoot: string): {
   for (const root of serviceRoots) {
     const srcDir = join(root, "src");
     if (existsSync(srcDir)) dirs.push(srcDir);
-    const manifest = join(root, "package.json");
-    if (existsSync(manifest)) files.push(manifest);
+    for (const name of ["package.json", "Dockerfile"]) {
+      const file = join(root, name);
+      if (existsSync(file)) files.push(file);
+    }
   }
   return { dirs, files };
 }
@@ -868,8 +873,8 @@ function affectedServices(
 
 /**
  * Watch for source changes across the assistant, gateway, credential-executor,
- * and packages services — scoped to each service's `src/` tree and
- * `package.json` (see `collectWatchTargets`). When changes are detected,
+ * and packages services — scoped to each service's `src/` tree, `package.json`,
+ * and `Dockerfile` (see `collectWatchTargets`). When changes are detected,
  * rebuild the affected images and restart their containers.
  */
 function startFileWatcher(opts: {
@@ -1006,8 +1011,8 @@ function startFileWatcher(opts: {
   }
 
   console.log("👀 Watching for file changes in:");
-  console.log("   <service>/src and <service>/package.json for");
-  console.log("   assistant/, gateway/, credential-executor/, packages/*");
+  console.log("   <service>/src, <service>/package.json, <service>/Dockerfile");
+  console.log("   for assistant/, gateway/, credential-executor/, packages/*");
   console.log("");
 
   return () => {

package/src/lib/runtime-url.ts

@@ -1,3 +1,6 @@
+import { hostname } from "node:os";
+
+import { getLocalLanIPv4 } from "./local";
 import type { AssistantEntry } from "./assistant-config.js";
 
 /**
@@ -50,3 +53,90 @@ export function resolveRuntimeUrl(
   }
   return `${entry.runtimeUrl}/v1/${subpath}`;
 }
+
+/**
+ * If the hostname in `url` matches this machine's local DNS name, LAN IP, or
+ * raw hostname, replace it with 127.0.0.1 so the client avoids mDNS round-trips
+ * when talking to an assistant running on the same machine. Trailing slashes are
+ * stripped on a swap. Returns the input unchanged if it doesn't parse as a URL.
+ */
+function maybeSwapToLocalhost(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+
+  const urlHost = parsed.hostname.toLowerCase();
+
+  const localNames: string[] = [];
+
+  const host = hostname();
+  if (host) {
+    localNames.push(host.toLowerCase());
+    // Also consider the bare name without .local suffix
+    if (host.toLowerCase().endsWith(".local")) {
+      localNames.push(host.toLowerCase().slice(0, -".local".length));
+    }
+  }
+
+  const lanIp = getLocalLanIPv4();
+  if (lanIp) {
+    localNames.push(lanIp);
+  }
+
+  if (localNames.includes(urlHost)) {
+    parsed.hostname = "127.0.0.1";
+    return parsed.toString().replace(/\/+$/, "");
+  }
+
+  return url;
+}
+
+/**
+ * Canonical form of a runtime/base URL used throughout the CLI: trailing
+ * slashes stripped, then localhost-swapped. This is exactly the transform
+ * `vellum client` applies to the runtime URL it hands the TUI, so comparing two
+ * URLs after passing both through this function is a like-for-like comparison.
+ */
+export function normalizeRuntimeUrl(url: string): string {
+  return maybeSwapToLocalhost(url.replace(/\/+$/, ""));
+}
+
+/**
+ * SECURITY: decide whether a guardian-token refresh may be sent to
+ * `candidateUrl`, and to which URL it should actually go.
+ *
+ * `vellum client` lets `--url`/`-u` override the runtime URL while still reusing
+ * the selected entry's stored guardian token, so a victim pointed at an
+ * attacker-controlled (or poisoned/redirected) URL must NOT cause us to POST the
+ * long-lived refreshToken + deviceId there. Refresh is permitted only when
+ * `candidateUrl` normalizes to one of the entry's persisted URLs (`localUrl`,
+ * which the CLI prefers when present, or `runtimeUrl`).
+ *
+ * Returns the persisted URL that the candidate matched — never the
+ * caller-supplied `candidateUrl` verbatim — so credentials only ever reach a
+ * trusted origin even if a caller forgets to use this return value. The matched
+ * URL is preferred over always returning `runtimeUrl` so the refresh stays on
+ * the same interface the session is using: e.g. a local entry may persist both a
+ * loopback `localUrl` (which `vellum client` defaults to) and an externally
+ * discovered `runtimeUrl`, and refreshing the loopback session against the
+ * external address could be unreachable or needlessly cross the public
+ * interface. Returns `null` when the candidate is untrusted (caller must skip
+ * the refresh).
+ */
+export function trustedRefreshUrl(
+  entry: Pick<AssistantEntry, "runtimeUrl" | "localUrl">,
+  candidateUrl: string,
+): string | null {
+  const candidate = normalizeRuntimeUrl(candidateUrl);
+  // localUrl first: it's what the CLI prefers when present, so the candidate is
+  // most likely to match it, and we want to keep the refresh on that interface.
+  for (const persisted of [entry.localUrl, entry.runtimeUrl]) {
+    if (persisted && normalizeRuntimeUrl(persisted) === candidate) {
+      return persisted;
+    }
+  }
+  return null;
+}