@hua-labs/tap 0.2.2 → 0.2.4

package/dist/index.d.mts

@@ -88,7 +88,7 @@ interface HeadlessConfig {
     qualitySeverityFloor: "critical" | "high" | "medium";
 }
 interface AppServerAuthState {
-    mode: "query-token";
+    mode: "subprotocol" | "query-token";
     protectedUrl: string;
     upstreamUrl: string;
     tokenPath: string;
@@ -442,6 +442,8 @@ declare function getConfig(options?: StateApiOptions): {
 interface HttpServerOptions extends StateApiOptions {
     /** Port to listen on (default: 4580) */
     port?: number;
+    /** Pre-set API token (default: auto-generated) */
+    token?: string;
 }
 /**
  * Start a localhost-only HTTP server for the tap State API.
@@ -449,6 +451,7 @@ interface HttpServerOptions extends StateApiOptions {
  */
 declare function startHttpServer(options?: HttpServerOptions): Promise<{
     port: number;
+    token: string;
     close: () => Promise<void>;
 }>;
 

package/dist/index.mjs

@@ -27,8 +27,8 @@ function findRepoRoot(startDir = process.cwd()) {
     if (fs.existsSync(path.join(dir, "package.json"))) {
       if (!_noGitWarned) {
         _setNoGitWarned();
-        logWarn(
-          "No .git directory found. Resolved repo root via package.json \u2014 comms directory may be created in an unexpected location. Use --comms-dir to specify explicitly."
+        log(
+          "No .git directory found. Resolved tap root via package.json. That's fine outside git; use --comms-dir to choose a different comms location."
         );
       }
       return dir;
@@ -39,8 +39,8 @@ function findRepoRoot(startDir = process.cwd()) {
   }
   if (!_noGitWarned) {
     _setNoGitWarned();
-    logWarn(
-      "No git repository or package.json found. Using current directory as root. Run 'git init' first, or use --comms-dir to specify the comms path."
+    log(
+      "No git repository or package.json found. Using the current directory as tap root. That's fine outside git; use --comms-dir to choose a different comms location."
     );
   }
   return process.cwd();
@@ -82,9 +82,6 @@ function log(message) {
 function logSuccess(message) {
   if (!_jsonMode) console.log(`  + ${message}`);
 }
-function logWarn(message) {
-  if (!_jsonMode) console.log(`  ! ${message}`);
-}
 function logError(message) {
   if (!_jsonMode) console.error(`  x ${message}`);
 }
@@ -93,6 +90,16 @@ function logHeader(message) {
   ${message}
 `);
 }
+function parseIntFlag(value, name, min, max) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new RangeError(
+      `Invalid ${name}: ${value}. Must be an integer between ${min} and ${max}.`
+    );
+  }
+  return parsed;
+}
 function resolveInstanceId(identifier, state) {
   if (state.instances[identifier]) {
     return { ok: true, instanceId: identifier };
@@ -140,8 +147,8 @@ function findRepoRoot2(startDir = process.cwd()) {
     if (fs2.existsSync(path2.join(dir, "package.json"))) {
       if (!_noGitWarned) {
         _setNoGitWarned();
-        console.error(
-          "[tap] warning: No .git directory found. Resolved via package.json. Use --comms-dir to specify explicitly."
+        log(
+          "No .git directory found. Resolved tap root via package.json. That's fine outside git; use --comms-dir to choose a different comms location."
         );
       }
       return dir;
@@ -152,8 +159,8 @@ function findRepoRoot2(startDir = process.cwd()) {
   }
   if (!_noGitWarned) {
     _setNoGitWarned();
-    console.error(
-      "[tap] warning: No git repository found. Using cwd as root. Run 'git init' or use --comms-dir."
+    log(
+      "No git repository or package.json found. Using the current directory as tap root. That's fine outside git; use --comms-dir to choose a different comms location."
     );
   }
   return process.cwd();
@@ -556,18 +563,18 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
     return { command: null, args: [], env, sourcePath, warnings, issues };
   }
   const isBundled = sourcePath.endsWith(".mjs");
+  const isEphemeralSource = isEphemeralPath(sourcePath);
   let command = bunCommand;
   let args = [toForwardSlashPath(sourcePath)];
-  if (!command && isBundled) {
-    const isEphemeralSource = isEphemeralPath(sourcePath);
+  if (isEphemeralSource && isBundled) {
+    command = "npx";
+    args = ["@hua-labs/tap", "serve"];
+    warnings.push(
+      "Detected npx cache path. Using `npx @hua-labs/tap serve` as stable MCP launcher."
+    );
+  } else if (!command && isBundled) {
     const isEphemeralNode = isEphemeralPath(process.execPath);
-    if (isEphemeralSource) {
-      command = "npx";
-      args = ["@hua-labs/tap", "serve"];
-      warnings.push(
-        "Detected npx cache path. Using `npx @hua-labs/tap serve` as stable MCP launcher."
-      );
-    } else if (isEphemeralNode) {
+    if (isEphemeralNode) {
       command = "node";
       warnings.push(
         "Detected ephemeral node path. Using `node` from PATH for MCP config stability."
@@ -575,11 +582,9 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
     } else {
       command = toForwardSlashPath(process.execPath);
     }
-    if (!isEphemeralSource) {
-      warnings.push(
-        "bun not found; using node to run the compiled MCP server. Install bun for better performance."
-      );
-    }
+    warnings.push(
+      "bun not found; using node to run the compiled MCP server. Install bun for better performance."
+    );
   }
   if (!command) {
     issues.push(
@@ -840,8 +845,11 @@ function resolvePowerShellCommand() {
 function resolveAuthGatewayScript(repoRoot) {
   const moduleDir = path7.dirname(fileURLToPath3(import.meta.url));
   const candidates = [
-    path7.join(moduleDir, "..", "bridges", "codex-app-server-auth-gateway.mjs"),
-    path7.join(moduleDir, "..", "bridges", "codex-app-server-auth-gateway.ts"),
+    // Bundled: dist/bridges/ sibling (npm install / built package)
+    path7.join(moduleDir, "bridges", "codex-app-server-auth-gateway.mjs"),
+    // Source: src/bridges/ sibling (monorepo dev with ts runner)
+    path7.join(moduleDir, "bridges", "codex-app-server-auth-gateway.ts"),
+    // Monorepo dist fallback
     path7.join(
       repoRoot,
       "packages",
@@ -894,10 +902,8 @@ async function allocateLoopbackPort(hostname) {
     });
   });
 }
-function buildProtectedAppServerUrl(publicUrl, token) {
-  const url = new URL(publicUrl);
-  url.searchParams.set(APP_SERVER_AUTH_QUERY_PARAM, token);
-  return url.toString().replace(/\/(?=\?|$)/, "");
+function buildProtectedAppServerUrl(publicUrl, _token) {
+  return publicUrl;
 }
 function readGatewayTokenFromPath(tokenPath) {
   return fs7.readFileSync(tokenPath, "utf8").trim();
@@ -1012,7 +1018,7 @@ async function createManagedAppServerAuth(options) {
     throw new Error("Failed to spawn app-server auth gateway");
   }
   return {
-    mode: "query-token",
+    mode: "subprotocol",
     protectedUrl,
     upstreamUrl: upstreamUrl.toString().replace(/\/$/, ""),
     tokenPath,
@@ -1199,7 +1205,7 @@ async function findNextAvailableAppServerPort(state, baseUrl, basePort = 4501, e
     `Failed to find a free app-server port starting at ${basePort}`
   );
 }
-async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_MS) {
+async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_MS, gatewayToken) {
   const WebSocket = getWebSocketCtor();
   if (!WebSocket) {
     return false;
@@ -1221,7 +1227,8 @@ async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_M
     };
     const timer = setTimeout(() => finish(false), timeoutMs);
     try {
-      socket = new WebSocket(url);
+      const protocols = gatewayToken ? [`${AUTH_SUBPROTOCOL_PREFIX}${gatewayToken}`] : void 0;
+      socket = new WebSocket(url, protocols);
       socket.addEventListener("open", () => finish(true), { once: true });
       socket.addEventListener("error", () => finish(false), { once: true });
       socket.addEventListener("close", () => finish(false), { once: true });
@@ -1230,10 +1237,14 @@ async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_M
     }
   });
 }
-async function waitForAppServerHealth(url, timeoutMs) {
+async function waitForAppServerHealth(url, timeoutMs, gatewayToken) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    if (await checkAppServerHealth(url)) {
+    if (await checkAppServerHealth(
+      url,
+      APP_SERVER_HEALTH_TIMEOUT_MS,
+      gatewayToken
+    )) {
       return true;
     }
     await delay(APP_SERVER_HEALTH_RETRY_MS);
@@ -1498,8 +1509,9 @@ Or start it manually:
     throw new Error("Tap auth gateway token is missing after startup.");
   }
   const gatewayHealthy = await waitForAppServerHealth(
-    buildProtectedAppServerUrl(effectiveUrl, gatewayToken),
-    APP_SERVER_GATEWAY_START_TIMEOUT_MS
+    effectiveUrl,
+    APP_SERVER_GATEWAY_START_TIMEOUT_MS,
+    gatewayToken
   );
   if (!gatewayHealthy) {
     await terminateProcess(pid, options.platform);
@@ -1856,7 +1868,7 @@ function getBridgeStatus(stateDir, instanceId) {
   }
   return "running";
 }
-var DEFAULT_APP_SERVER_URL2, APP_SERVER_HEALTH_TIMEOUT_MS, APP_SERVER_START_TIMEOUT_MS, APP_SERVER_GATEWAY_START_TIMEOUT_MS, APP_SERVER_HEALTH_RETRY_MS, APP_SERVER_AUTH_QUERY_PARAM, APP_SERVER_AUTH_FILE_MODE;
+var DEFAULT_APP_SERVER_URL2, APP_SERVER_HEALTH_TIMEOUT_MS, APP_SERVER_START_TIMEOUT_MS, APP_SERVER_GATEWAY_START_TIMEOUT_MS, APP_SERVER_HEALTH_RETRY_MS, AUTH_SUBPROTOCOL_PREFIX, APP_SERVER_AUTH_FILE_MODE;
 var init_bridge = __esm({
   "src/engine/bridge.ts"() {
     "use strict";
@@ -1868,7 +1880,7 @@ var init_bridge = __esm({
     APP_SERVER_START_TIMEOUT_MS = 2e4;
     APP_SERVER_GATEWAY_START_TIMEOUT_MS = 5e3;
     APP_SERVER_HEALTH_RETRY_MS = 250;
-    APP_SERVER_AUTH_QUERY_PARAM = "tap_token";
+    AUTH_SUBPROTOCOL_PREFIX = "tap-auth-";
     APP_SERVER_AUTH_FILE_MODE = 384;
   }
 });
@@ -2496,13 +2508,12 @@ function verifyManagedToml(content, ctx, configPath) {
     });
   }
   if (mainTable && managed.command) {
+    const expectedArgs = managed.args.map((a) => `"${a.replace(/\\/g, "\\\\")}"`).join(", ");
     checks.push({
       name: "Managed command configured",
       passed: mainTable.includes(
         `command = "${managed.command.replace(/\\/g, "\\\\")}"`
-      ) && mainTable.includes(
-        `args = ["${managed.args[0]?.replace(/\\/g, "\\\\") ?? ""}"]`
-      ),
+      ) && mainTable.includes(`args = [${expectedArgs}]`),
       message: "Managed tap-comms command/args do not match expected values"
     });
   }
@@ -3052,11 +3063,11 @@ function redactProtectedUrl(url) {
   try {
     const parsed = new URL(url);
     if (parsed.searchParams.has("tap_token")) {
-      parsed.searchParams.set("tap_token", "***");
+      parsed.searchParams.delete("tap_token");
     }
     return parsed.toString().replace(/\/$/, "");
   } catch {
-    return url.replace(/tap_token=[^&]+/g, "tap_token=***");
+    return url.replace(/[?&]tap_token=[^&]+/g, "");
   }
 }
 function loadCurrentBridgeState(stateDir, instanceId, fallback) {
@@ -3139,37 +3150,37 @@ async function bridgeStart(identifier, agentName, flags = {}) {
     };
   }
   const instanceId = resolved.instanceId;
-  let instance = state.instances[instanceId];
-  if (!instance?.installed) {
+  let instance2 = state.instances[instanceId];
+  if (!instance2?.installed) {
     return {
       ok: false,
       command: "bridge",
       instanceId,
-      runtime: instance?.runtime,
+      runtime: instance2?.runtime,
       code: "TAP_INSTANCE_NOT_FOUND",
-      message: `${instanceId} is not installed. Run: npx @hua-labs/tap add ${instance?.runtime ?? identifier}`,
+      message: `${instanceId} is not installed. Run: npx @hua-labs/tap add ${instance2?.runtime ?? identifier}`,
       warnings: [],
       data: {}
     };
   }
-  const adapter = getAdapter(instance.runtime);
+  const adapter = getAdapter(instance2.runtime);
   const mode = adapter.bridgeMode();
   if (mode !== "app-server") {
     return {
       ok: true,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_NO_OP",
       message: `${instanceId} uses ${mode} mode \u2014 no bridge needed.`,
       warnings: [],
       data: { bridgeMode: mode }
     };
   }
-  const resolvedAgentName = agentName ?? instance.agentName ?? void 0;
-  if (agentName && agentName !== instance.agentName) {
-    instance = { ...instance, agentName };
-    const updatedState = updateInstanceState(state, instanceId, instance);
+  const resolvedAgentName = agentName ?? instance2.agentName ?? void 0;
+  if (agentName && agentName !== instance2.agentName) {
+    instance2 = { ...instance2, agentName };
+    const updatedState = updateInstanceState(state, instanceId, instance2);
     saveState(repoRoot, updatedState);
     state = updatedState;
   }
@@ -3180,7 +3191,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       ok: false,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_BRIDGE_SCRIPT_MISSING",
       message: `Bridge script not found for ${instanceId}. Ensure the runtime is properly configured.`,
       warnings: [],
@@ -3189,8 +3200,8 @@ async function bridgeStart(identifier, agentName, flags = {}) {
   }
   const { config: resolvedConfig } = resolveConfig({}, repoRoot);
   const runtimeCommand = resolvedConfig.runtimeCommand;
-  const manageAppServer = instance.runtime === "codex" && flags["no-server"] !== true;
-  let effectivePort = instance.port;
+  const manageAppServer = instance2.runtime === "codex" && flags["no-server"] !== true;
+  let effectivePort = instance2.port;
   if (effectivePort == null && manageAppServer) {
     effectivePort = await findNextAvailableAppServerPort(
       state,
@@ -3198,8 +3209,8 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       4501,
       instanceId
     );
-    instance = { ...instance, port: effectivePort };
-    const updatedState = updateInstanceState(state, instanceId, instance);
+    instance2 = { ...instance2, port: effectivePort };
+    const updatedState = updateInstanceState(state, instanceId, instance2);
     saveState(repoRoot, updatedState);
     state = updatedState;
   }
@@ -3215,19 +3226,19 @@ async function bridgeStart(identifier, agentName, flags = {}) {
   if (effectivePort != null) log(`Port:          ${effectivePort}`);
   if (resolvedAgentName) log(`Agent name:    ${resolvedAgentName}`);
   const noAuth = flags["no-auth"] === true;
-  if (!manageAppServer && instance.runtime === "codex") {
+  if (!manageAppServer && instance2.runtime === "codex") {
     log("Auto server:   disabled (--no-server)");
   }
   if (noAuth && manageAppServer) {
     log("Auth gateway:  disabled (--no-auth)");
   }
-  const willBeHeadless = flags["headless"] === true || instance.headless?.enabled;
+  const willBeHeadless = flags["headless"] === true || instance2.headless?.enabled;
   if (willBeHeadless) {
-    const role = (typeof flags["role"] === "string" ? flags["role"] : null) ?? instance.headless?.role ?? "reviewer";
+    const role = (typeof flags["role"] === "string" ? flags["role"] : null) ?? instance2.headless?.role ?? "reviewer";
     log(`Headless:      ${role}`);
   }
   try {
-    if (!manageAppServer && instance.runtime === "codex") {
+    if (!manageAppServer && instance2.runtime === "codex") {
       log("Checking app-server health...");
       const healthy = await checkAppServerHealth(appServerUrl);
       if (healthy) {
@@ -3238,7 +3249,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
           ok: false,
           command: "bridge",
           instanceId,
-          runtime: instance.runtime,
+          runtime: instance2.runtime,
           code: "TAP_BRIDGE_START_FAILED",
           message: `App server not reachable at ${appServerUrl}. Start it first: codex app-server --listen ${appServerUrl}`,
           warnings: [],
@@ -3252,7 +3263,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         ok: false,
         command: "bridge",
         instanceId,
-        runtime: instance.runtime,
+        runtime: instance2.runtime,
         code: "TAP_INVALID_ARGUMENT",
         message: `Invalid --busy-mode: ${String(busyModeRaw)}. Must be "steer" or "wait".`,
         warnings: [],
@@ -3260,9 +3271,38 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       };
     }
     const busyMode = busyModeRaw;
-    const pollSeconds = typeof flags["poll-seconds"] === "string" ? parseInt(flags["poll-seconds"], 10) : void 0;
-    const reconnectSeconds = typeof flags["reconnect-seconds"] === "string" ? parseInt(flags["reconnect-seconds"], 10) : void 0;
-    const messageLookbackMinutes = typeof flags["message-lookback-minutes"] === "string" ? parseInt(flags["message-lookback-minutes"], 10) : void 0;
+    const pollSecondsRaw = typeof flags["poll-seconds"] === "string" ? flags["poll-seconds"] : void 0;
+    const reconnectSecondsRaw = typeof flags["reconnect-seconds"] === "string" ? flags["reconnect-seconds"] : void 0;
+    const lookbackRaw = typeof flags["message-lookback-minutes"] === "string" ? flags["message-lookback-minutes"] : void 0;
+    let pollSeconds;
+    let reconnectSeconds;
+    let messageLookbackMinutes;
+    try {
+      pollSeconds = parseIntFlag(pollSecondsRaw, "--poll-seconds", 1, 3600);
+      reconnectSeconds = parseIntFlag(
+        reconnectSecondsRaw,
+        "--reconnect-seconds",
+        1,
+        3600
+      );
+      messageLookbackMinutes = parseIntFlag(
+        lookbackRaw,
+        "--message-lookback-minutes",
+        1,
+        10080
+      );
+    } catch (err) {
+      return {
+        ok: false,
+        command: "bridge",
+        instanceId,
+        runtime: instance2.runtime,
+        code: "TAP_INVALID_ARGUMENT",
+        message: err instanceof Error ? err.message : String(err),
+        warnings: [],
+        data: {}
+      };
+    }
     const threadId = typeof flags["thread-id"] === "string" ? flags["thread-id"] : void 0;
     const ephemeral = flags["ephemeral"] === true;
     const processExistingMessages = flags["process-existing-messages"] === true;
@@ -3274,7 +3314,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         ok: false,
         command: "bridge",
         instanceId,
-        runtime: instance.runtime,
+        runtime: instance2.runtime,
         code: "TAP_INVALID_ARGUMENT",
         message: `Invalid --role: ${roleArg}. Must be: ${validRoles.join(", ")}`,
         warnings: [],
@@ -3286,10 +3326,10 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       role: roleArg ?? "reviewer",
       maxRounds: 5,
       qualitySeverityFloor: "high"
-    } : instance.headless;
+    } : instance2.headless;
     const bridge = await startBridge({
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       stateDir: ctx.stateDir,
       commsDir: ctx.commsDir,
       bridgeScript,
@@ -3330,14 +3370,14 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         log(`TUI connect:  ${bridge.appServer.url}`);
       }
     }
-    const updated = { ...instance, bridge, manageAppServer, noAuth };
+    const updated = { ...instance2, bridge, manageAppServer, noAuth };
     const newState = updateInstanceState(state, instanceId, updated);
     saveState(repoRoot, newState);
     return {
       ok: true,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_BRIDGE_START_OK",
       message: `Bridge for ${instanceId} started (PID: ${bridge.pid})`,
       warnings: [],
@@ -3350,7 +3390,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       ok: false,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_BRIDGE_START_FAILED",
       message: msg,
       warnings: [],
@@ -3452,11 +3492,11 @@ async function bridgeStopOne(identifier) {
   }
   const instanceId = resolved.instanceId;
   const ctx = createAdapterContext(state.commsDir, repoRoot);
-  const instance = state.instances[instanceId];
+  const instance2 = state.instances[instanceId];
   const bridgeState = loadCurrentBridgeState(
     ctx.stateDir,
     instanceId,
-    instance?.bridge
+    instance2?.bridge
   );
   const appServer = bridgeState?.appServer ?? null;
   logHeader(`@hua-labs/tap bridge stop ${instanceId}`);
@@ -3504,8 +3544,8 @@ async function bridgeStopOne(identifier) {
       }
     }
   }
-  if (instance) {
-    const updated = { ...instance, bridge: null };
+  if (instance2) {
+    const updated = { ...instance2, bridge: null };
     const newState = updateInstanceState(state, instanceId, updated);
     saveState(repoRoot, newState);
   }
@@ -3577,9 +3617,9 @@ async function bridgeStopAll() {
       logSuccess(`Stopped bridge for ${instanceId}`);
       stopped.push(instanceId);
     }
-    const instance = state.instances[instanceId];
-    if (instance?.bridge) {
-      state.instances[instanceId] = { ...instance, bridge: null };
+    const instance2 = state.instances[instanceId];
+    if (instance2?.bridge) {
+      state.instances[instanceId] = { ...instance2, bridge: null };
       stateChanged = true;
     }
   }
@@ -3875,8 +3915,22 @@ async function bridgeRestart(identifier, flags) {
     };
   }
   const { config: resolvedConfig } = resolveConfig({}, repoRoot);
-  const drainStr = typeof flags["drain-timeout"] === "string" ? flags["drain-timeout"] : "30";
-  const drainTimeout = parseInt(drainStr, 10) || 30;
+  const drainStr = typeof flags["drain-timeout"] === "string" ? flags["drain-timeout"] : void 0;
+  let drainTimeout;
+  try {
+    drainTimeout = parseIntFlag(drainStr, "--drain-timeout", 1, 300) ?? 30;
+  } catch (err) {
+    return {
+      ok: false,
+      command: "bridge",
+      instanceId,
+      runtime: instance.runtime,
+      code: "TAP_INVALID_ARGUMENT",
+      message: err instanceof Error ? err.message : String(err),
+      warnings: [],
+      data: {}
+    };
+  }
   logHeader(`@hua-labs/tap bridge restart ${instanceId}`);
   log(`Drain timeout: ${drainTimeout}s`);
   try {
@@ -4042,7 +4096,7 @@ Subcommands:
 
 Options:
   --agent-name <name>              Agent identity for bridge (or set TAP_AGENT_NAME env)
-                                   Saved to state \u2014 only needed on first start
+                                   Overrides the stored name from 'tap add' when needed
   --all                            Start all registered app-server instances
   --busy-mode <steer|wait>         How to handle active turns (default: steer)
   --poll-seconds <n>               Inbox poll interval (default: 5)
@@ -4349,11 +4403,38 @@ function getConfig(options) {
 import {
   createServer as createServer2
 } from "http";
+import { randomBytes as randomBytes2, timingSafeEqual } from "crypto";
 var CORS_HEADERS = {
   "Access-Control-Allow-Origin": "http://localhost:3000",
   "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-  "Access-Control-Allow-Headers": "Content-Type"
+  "Access-Control-Allow-Headers": "Content-Type, Authorization"
 };
+function tokensMatch(presentedToken, expectedToken) {
+  if (!presentedToken) {
+    return false;
+  }
+  const presented = Buffer.from(presentedToken, "utf8");
+  const expected = Buffer.from(expectedToken, "utf8");
+  if (presented.length !== expected.length) {
+    return false;
+  }
+  return timingSafeEqual(presented, expected);
+}
+function verifyBearerToken(req, expectedToken) {
+  const header = req.headers.authorization;
+  if (!header?.startsWith("Bearer ")) {
+    return false;
+  }
+  return tokensMatch(header.slice(7), expectedToken);
+}
+function verifySseToken(req, expectedToken, serverUrl) {
+  if (verifyBearerToken(req, expectedToken)) {
+    return true;
+  }
+  const url = new URL(req.url ?? "/", serverUrl);
+  const queryToken = url.searchParams.get("token");
+  return tokensMatch(queryToken, expectedToken);
+}
 function jsonResponse(res, data, status = 200) {
   res.writeHead(status, {
     "Content-Type": "application/json",
@@ -4396,6 +4477,7 @@ function handleHealth(res, apiOptions) {
 async function startHttpServer(options) {
   const port = options?.port ?? 4580;
   const host = "127.0.0.1";
+  const token = options?.token ?? randomBytes2(24).toString("base64url");
   const apiOptions = {
     repoRoot: options?.repoRoot,
     commsDir: options?.commsDir
@@ -4409,21 +4491,32 @@ async function startHttpServer(options) {
         res.end();
         return;
       }
+      if (req.method === "GET" && pathname === "/health") {
+        handleHealth(res, apiOptions);
+        return;
+      }
+      if (req.method === "GET" && pathname === "/api/events") {
+        const serverUrl = `http://${host}:${port}`;
+        if (!verifySseToken(req, token, serverUrl)) {
+          jsonResponse(res, { error: "Unauthorized" }, 401);
+          return;
+        }
+        await handleEvents(req, res, apiOptions);
+        return;
+      }
+      if (!verifyBearerToken(req, token)) {
+        jsonResponse(res, { error: "Unauthorized" }, 401);
+        return;
+      }
       try {
         if (req.method === "GET") {
           switch (pathname) {
             case "/api/snapshot":
               handleSnapshot(res, apiOptions);
               return;
-            case "/api/events":
-              await handleEvents(req, res, apiOptions);
-              return;
             case "/api/config":
               handleConfig(res, apiOptions);
               return;
-            case "/health":
-              handleHealth(res, apiOptions);
-              return;
           }
         }
         if (req.method === "POST") {
@@ -4461,6 +4554,7 @@ async function startHttpServer(options) {
   });
   return {
     port,
+    token,
     close: () => new Promise((resolve8, reject) => {
       server.close((err) => err ? reject(err) : resolve8());
     })