@vellumai/cli 0.8.9-staging.1 → 0.8.9-staging.3

package/src/components/DefaultMainScreen.tsx

@@ -12,7 +12,12 @@ import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 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 {
+  guardianTokenDueForRenewal,
+  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 +198,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 +225,21 @@ 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);
+  // Only refresh once the token is actually due for renewal, so a forged 401
+  // on a still-valid token can't coax out the long-lived refresh credential.
+  if (!guardianTokenDueForRenewal(stored)) return false;
+  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

@@ -1,7 +1,11 @@
 import { afterEach, beforeEach, describe, test, expect } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
 import {
   ASSISTANT_INTERNAL_PORT,
   AVATAR_DEVICE_ENV_VAR,
+  collectWatchTargets,
   dockerResourceNames,
   resolveAvatarDevicePath,
   resolveDockerHatchMode,
@@ -277,3 +281,98 @@ describe("resolveDockerHatchMode", () => {
     ).toEqual({ build: false, watcher: false, fellBackToPull: true });
   });
 });
+
+describe("collectWatchTargets", () => {
+  let repoRoot: string;
+
+  beforeEach(() => {
+    repoRoot = mkdtempSync(join(tmpdir(), "vellum-watch-"));
+  });
+
+  afterEach(() => {
+    rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  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) writeFileSync(join(repoRoot, relDir, "package.json"), "{}");
+    if (dockerfile) writeFileSync(join(repoRoot, relDir, "Dockerfile"), "");
+  }
+
+  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");
+
+    // WHEN we collect the watch targets
+    const { dirs, files } = collectWatchTargets(repoRoot);
+
+    // THEN only the src/ directories are watched recursively
+    expect(dirs.sort()).toEqual(
+      [
+        join(repoRoot, "assistant", "src"),
+        join(repoRoot, "credential-executor", "src"),
+        join(repoRoot, "gateway", "src"),
+        join(repoRoot, "packages", "local-mode", "src"),
+        join(repoRoot, "packages", "service-contracts", "src"),
+      ].sort(),
+    );
+
+    // 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(),
+    );
+  });
+
+  test("never watches .claude/ command symlinks that crash the watcher", () => {
+    // GIVEN an assistant service whose .claude/commands holds a dangling
+    // symlink (as it does in a fresh checkout)
+    scaffold("assistant");
+    mkdirSync(join(repoRoot, "assistant", ".claude", "commands"), {
+      recursive: true,
+    });
+    symlinkSync(
+      join(repoRoot, "does-not-exist", "do.md"),
+      join(repoRoot, "assistant", ".claude", "commands", "do.md"),
+    );
+
+    // WHEN we collect the watch targets
+    const { dirs, files } = collectWatchTargets(repoRoot);
+
+    // THEN no watched path reaches into the .claude/ tree
+    const all = [...dirs, ...files];
+    expect(all.some((p) => p.includes(".claude"))).toBe(false);
+    expect(dirs).toContain(join(repoRoot, "assistant", "src"));
+  });
+
+  test("skips roots missing a src/ directory or package.json", () => {
+    // GIVEN a service with only a manifest and a package with only a src/ dir
+    scaffold("gateway", { src: false, pkg: true });
+    scaffold("packages/contracts-only", { src: true, pkg: false });
+
+    // WHEN we collect the watch targets
+    const { dirs, files } = collectWatchTargets(repoRoot);
+
+    // THEN absent paths are not emitted
+    expect(dirs).toEqual([join(repoRoot, "packages", "contracts-only", "src")]);
+    expect(files).toEqual([join(repoRoot, "gateway", "package.json")]);
+  });
+});

package/src/lib/assistant-client.ts

@@ -14,7 +14,11 @@
 
 import { resolveAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
-import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+  guardianTokenDueForRenewal,
+} from "./guardian-token.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -219,21 +223,35 @@ export class AssistantClient {
 
     const response = await doFetch();
 
-    // Reactive auto-refresh: a paired/local guardian access token that has
-    // expired comes back 401. Refresh it once via the stored refresh credential
-    // and retry. Self-gating — refreshGuardianToken returns null unless a usable
-    // refresh token is stored, so ephemeral (`--token`) and access-only sessions
-    // just see the original 401. The platform session-auth path is never
-    // refreshed here (its token is managed by the Vellum platform).
+    // Reactive auto-refresh on a 401 for the guardian (non-session) path.
+    // Ephemeral (`--token`) and access-only sessions have no stored refresh
+    // credential and just see the original 401; the platform session-auth path
+    // is never refreshed here (its token is managed by the Vellum platform).
     if (response.status === 401 && !this.isSessionAuth) {
-      const refreshed = await refreshGuardianToken(
-        this.runtimeUrl,
-        this._assistantId,
-      );
-      if (refreshed?.accessToken) {
-        this.token = refreshed.accessToken;
+      const stored = loadGuardianToken(this._assistantId);
+
+      // Another process may have already rotated and persisted a fresh access
+      // token (e.g. a concurrent `vellum events`). Adopt it and retry — this
+      // sends no refresh credential, just picks up the newer local token.
+      if (stored?.accessToken && stored.accessToken !== this.token) {
+        this.token = stored.accessToken;
         return doFetch();
       }
+
+      // Otherwise only disclose the long-lived refresh token when our access
+      // token is actually due for renewal. A 401 on a still-valid token (e.g. a
+      // forged 401 from an impostor endpoint trying to coax out the refresh
+      // credential) is surfaced as-is, not refreshed.
+      if (stored?.refreshToken && guardianTokenDueForRenewal(stored)) {
+        const refreshed = await refreshGuardianToken(
+          this.runtimeUrl,
+          this._assistantId,
+        );
+        if (refreshed?.accessToken) {
+          this.token = refreshed.accessToken;
+          return doFetch();
+        }
+      }
     }
 
     return response;

package/src/lib/docker.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   watch as fsWatch,
 } from "fs";
 import { arch, platform } from "os";
@@ -661,6 +662,7 @@ export async function startContainers(
     bootstrapSecret?: string;
     cesServiceToken?: string;
     extraAssistantEnv?: Record<string, string>;
+    extraGatewayEnv?: Record<string, string>;
     gatewayPort: number;
     imageTags: Record<ServiceName, string>;
     instanceName: string;
@@ -788,6 +790,56 @@ export async function captureImageRefs(
   return hasAll ? (refs as Record<ServiceName, string>) : null;
 }
 
+/**
+ * Build the set of paths the hot-reload watcher should observe, scoped to
+ * 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
+ * checkout because they point at the separately-cloned `claude-skills`
+ * 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/`, 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`.
+ */
+export function collectWatchTargets(repoRoot: string): {
+  dirs: string[];
+  files: string[];
+} {
+  const packagesDir = join(repoRoot, "packages");
+  const packageRoots = existsSync(packagesDir)
+    ? readdirSync(packagesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(packagesDir, entry.name))
+    : [];
+
+  const serviceRoots = [
+    join(repoRoot, "assistant"),
+    join(repoRoot, "credential-executor"),
+    join(repoRoot, "gateway"),
+    ...packageRoots,
+  ];
+
+  const dirs: string[] = [];
+  const files: string[] = [];
+  for (const root of serviceRoots) {
+    const srcDir = join(root, "src");
+    if (existsSync(srcDir)) dirs.push(srcDir);
+    for (const name of ["package.json", "Dockerfile"]) {
+      const file = join(root, name);
+      if (existsSync(file)) files.push(file);
+    }
+  }
+  return { dirs, files };
+}
+
 /**
  * Determine which services are affected by a changed file path relative
  * to the repository root.
@@ -821,9 +873,10 @@ function affectedServices(
 }
 
 /**
- * Watch for file changes in the assistant, gateway, credential-executor,
- * and packages directories. When changes are detected, rebuild the affected
- * images and restart their containers.
+ * Watch for source changes across the assistant, gateway, credential-executor,
+ * 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: {
   signingKey?: string;
@@ -837,12 +890,7 @@ function startFileWatcher(opts: {
 }): () => void {
   const { gatewayPort, imageTags, instanceName, repoRoot, res } = opts;
 
-  const watchDirs = [
-    join(repoRoot, "assistant"),
-    join(repoRoot, "credential-executor"),
-    join(repoRoot, "gateway"),
-    join(repoRoot, "packages"),
-  ];
+  const { dirs: watchDirs, files: watchFiles } = collectWatchTargets(repoRoot);
 
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let pendingServices = new Set<ServiceName>();
@@ -919,37 +967,53 @@ function startFileWatcher(opts: {
 
   const watchers: ReturnType<typeof fsWatch>[] = [];
 
+  function onChange(fullPath: string): void {
+    const services = affectedServices(fullPath, repoRoot);
+    if (services.size === 0) return;
+
+    for (const s of services) {
+      pendingServices.add(s);
+    }
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      rebuildAndRestart();
+    }, 500);
+  }
+
   for (const dir of watchDirs) {
-    if (!existsSync(dir)) continue;
     const watcher = fsWatch(dir, { recursive: true }, (_event, filename) => {
       if (!filename) return;
-      if (
-        filename.includes("node_modules") ||
-        filename.includes(".env") ||
-        filename.startsWith(".")
-      ) {
+      if (filename.includes("node_modules") || filename.includes(".env")) {
         return;
       }
+      onChange(join(dir, filename));
+    });
+    // fs.watch surfaces transient errors (e.g. an unreadable entry) as an
+    // `error` event, which would otherwise crash the process. Log and keep
+    // the remaining watchers running.
+    watcher.on("error", (err) => {
+      console.error(
+        `⚠️  File watcher error for ${dir}: ${err instanceof Error ? err.message : err}`,
+      );
+    });
+    watchers.push(watcher);
+  }
 
-      const fullPath = join(dir, filename);
-      const services = affectedServices(fullPath, repoRoot);
-      if (services.size === 0) return;
-
-      for (const s of services) {
-        pendingServices.add(s);
-      }
-
-      if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        debounceTimer = null;
-        rebuildAndRestart();
-      }, 500);
+  for (const file of watchFiles) {
+    const watcher = fsWatch(file, () => onChange(file));
+    watcher.on("error", (err) => {
+      console.error(
+        `⚠️  File watcher error for ${file}: ${err instanceof Error ? err.message : err}`,
+      );
     });
     watchers.push(watcher);
   }
 
   console.log("👀 Watching for file changes in:");
-  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 () => {
@@ -979,6 +1043,7 @@ export async function hatchDocker(
   name: string | null,
   watch: boolean = false,
   configValues: Record<string, string> = {},
+  flagEnvVars: Record<string, string> = {},
   options: HatchDockerOptions = {},
 ): Promise<void> {
   resetLogFile("hatch.log");
@@ -1258,12 +1323,15 @@ export async function hatchDocker(
       : ownSecret;
 
     emitProgress(4, 6, "Starting containers...");
+    const extraGatewayEnv =
+      Object.keys(flagEnvVars).length > 0 ? flagEnvVars : undefined;
     await startContainers(
       {
         signingKey,
         bootstrapSecret,
         cesServiceToken,
         extraAssistantEnv,
+        extraGatewayEnv,
         gatewayPort,
         imageTags,
         instanceName,

package/src/lib/flag-args.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test, spyOn } from "bun:test";
+
+import { parseFeatureFlagArgs } from "./flag-args";
+
+describe("parseFeatureFlagArgs", () => {
+  test("single flag produces env var and empty remaining", () => {
+    const result = parseFeatureFlagArgs(["--flag", "voice-mode=true"]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_VOICE_MODE: "true" },
+      remaining: [],
+    });
+  });
+
+  test("multiple flags produce multiple env vars", () => {
+    const result = parseFeatureFlagArgs([
+      "--flag",
+      "a=1",
+      "--flag",
+      "b=0",
+    ]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_A: "1", VELLUM_FLAG_B: "0" },
+      remaining: [],
+    });
+  });
+
+  test("flags mixed with other args preserves remaining", () => {
+    const result = parseFeatureFlagArgs([
+      "--watch",
+      "--flag",
+      "x=y",
+      "--name",
+      "foo",
+    ]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_X: "y" },
+      remaining: ["--watch", "--name", "foo"],
+    });
+  });
+
+  test("exits with error when --flag has no following argument", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag"])).toThrow("process.exit");
+    expect(errorSpy).toHaveBeenCalledWith(
+      "Error: --flag requires a key=value argument",
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when value has no equals sign", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "noequals"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: --flag value must be in key=value format, got "noequals"',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when key is not kebab-case", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "UPPER=true"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: invalid flag key "UPPER". Keys must be kebab-case (e.g. "voice-mode")',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

package/src/lib/flag-args.ts

@@ -0,0 +1,74 @@
+/** Only allow simple kebab-case keys (e.g. "voice-mode", "ces-tools"). */
+const ALLOWED_KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Extract repeatable `--flag key=value` pairs from a CLI arg list.
+ *
+ * Each `--flag` consumes the next argument as `key=value`. Keys are validated
+ * against a kebab-case pattern, then converted to env var names of the form
+ * `VELLUM_FLAG_<UPPER_SNAKE>`. All `--flag` pairs are stripped from the
+ * returned `remaining` array so downstream parsers never see them.
+ */
+export function parseFeatureFlagArgs(args: string[]): {
+  envVars: Record<string, string>;
+  remaining: string[];
+} {
+  const envVars: Record<string, string> = {};
+  const remaining: string[] = [];
+
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === "--flag") {
+      if (i + 1 >= args.length) {
+        console.error("Error: --flag requires a key=value argument");
+        process.exit(1);
+      }
+
+      const pair = args[i + 1]!;
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) {
+        console.error(
+          `Error: --flag value must be in key=value format, got "${pair}"`,
+        );
+        process.exit(1);
+      }
+
+      const key = pair.slice(0, eqIdx);
+      const value = pair.slice(eqIdx + 1);
+
+      if (!ALLOWED_KEY_RE.test(key)) {
+        console.error(
+          `Error: invalid flag key "${key}". Keys must be kebab-case (e.g. "voice-mode")`,
+        );
+        process.exit(1);
+      }
+
+      const envName = `VELLUM_FLAG_${key.toUpperCase().replace(/-/g, "_")}`;
+      envVars[envName] = value;
+      i += 2;
+    } else {
+      remaining.push(args[i]!);
+      i += 1;
+    }
+  }
+
+  return { envVars, remaining };
+}
+
+const ENV_FLAG_PREFIX = "VELLUM_FLAG_";
+
+/**
+ * Scan `process.env` for ambient `VELLUM_FLAG_*` entries.
+ * Returns them as-is (same `Record<string, string>` shape as
+ * `parseFeatureFlagArgs().envVars`) so callers can merge both
+ * sources with `--flag` args winning over ambient env vars.
+ */
+export function readAmbientFlagEnvVars(): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(ENV_FLAG_PREFIX) && value !== undefined) {
+      vars[key] = value;
+    }
+  }
+  return vars;
+}

package/src/lib/guardian-token.ts

@@ -254,10 +254,64 @@ function releaseRefreshLock(lockPath: string): void {
  * process already rotated it while we waited, we return that fresh token
  * instead of replaying our now-stale refresh token.
  */
+/**
+ * The guardian refresh token is long-lived and replayable, so we only transmit
+ * it over a confidential channel: HTTPS, or a loopback host (local dev, or a
+ * same-host reverse proxy / tunnel agent). Refreshing against a non-loopback
+ * plaintext `http://` URL is refused — an on-path attacker could otherwise
+ * capture the refresh token and rotate it into fresh credentials.
+ *
+ * A user-chosen malicious `https://` destination is intentionally out of scope:
+ * HTTPS protects the channel, and the access token already goes wherever the
+ * configured URL points. This guard targets the plaintext-interception vector.
+ */
+function isLoopbackHostname(hostname: string): boolean {
+  const h = hostname.toLowerCase();
+  return (
+    h === "localhost" ||
+    h === "::1" ||
+    h === "[::1]" ||
+    h === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(h)
+  );
+}
+
+function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
+  try {
+    const url = new URL(gatewayUrl);
+    return url.protocol === "https:" || isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when a stored guardian token has reached its renewal point — now is
+ * at/after `refreshAfter` (preferred) or `accessTokenExpiresAt`. Used to gate
+ * refresh so a forged/synthetic 401 on a still-valid token can't coax out the
+ * long-lived refresh credential. Unparseable timestamps → not due.
+ */
+export function guardianTokenDueForRenewal(token: GuardianTokenData): boolean {
+  const raw = token.refreshAfter || token.accessTokenExpiresAt;
+  const at = new Date(raw).getTime();
+  if (!Number.isFinite(at)) return false;
+  return at <= Date.now();
+}
+
 export async function refreshGuardianToken(
   gatewayUrl: string,
   assistantId: string,
 ): Promise<GuardianTokenData | null> {
+  // Never send the long-lived refresh token over a non-loopback plaintext URL.
+  if (!isConfidentialRefreshUrl(gatewayUrl)) {
+    console.warn(
+      `Refusing to refresh the guardian token over an insecure URL (${gatewayUrl}). ` +
+        "The refresh token is only sent over https or a loopback address — " +
+        "use an https URL (e.g. a tunnel) or connect over loopback.",
+    );
+    return null;
+  }
+
   const before = loadGuardianToken(assistantId);
   if (!before) return null;
 

package/src/lib/hatch-local.ts

@@ -164,6 +164,7 @@ export async function hatchLocal(
   watch: boolean = false,
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
+  flagEnvVars: Record<string, string> = {},
   options: HatchLocalOptions = {},
 ): Promise<HatchLocalResult> {
   const reporter = options.reporter ?? consoleLifecycleReporter;
@@ -234,6 +235,7 @@ export async function hatchLocal(
     runtimeUrl = await startGateway(watch, resources, {
       signingKey,
       bootstrapSecret,
+      envOverrides: flagEnvVars,
     });
   } catch (error) {
     // Gateway failed — stop the daemon we just started so we don't leave