talon-agent 5.14.0 → 5.18.2

package/src/core/mesh/links/bridge-links.ts

@@ -24,6 +24,22 @@ import {
   type NodeBinaryResolver,
 } from "./node-binaries.js";
 import { installOneLiner, NodeProvisionStore } from "./node-provision.js";
+import {
+  DEFAULT_COMPANION_SCOPES,
+  NODE_SCOPES,
+  type CredentialOrigin,
+  type MeshScope,
+} from "../credentials/index.js";
+
+/**
+ * Mints the per-device credential a pairing link or installer carries,
+ * unbound until the device first names itself with it. Absent (tests,
+ * embedders without a credential store) = links carry the shared token.
+ */
+export type PairingCredentialMinter = (
+  scopes: readonly MeshScope[],
+  origin: CredentialOrigin,
+) => string;
 
 /**
  * What the native bridge tells the mesh about itself once it's listening —
@@ -45,6 +61,10 @@ export type MeshBridgeInfo = {
    * address isn't reachable as-is (containers, NAT, proxies).
    */
   publicUrl?: string;
+  /** `native.legacySharedToken`: whether remote clients may still use `token`. */
+  legacySharedToken?: boolean;
+  /** Scopes a companion's pairing credential carries (`native.companionScopes`). */
+  companionScopes?: readonly MeshScope[];
 };
 
 export class BridgeLinks {
@@ -54,7 +74,24 @@ export class BridgeLinks {
   private readonly companionPairs = new CompanionPairStore();
   private bridgeInfo: MeshBridgeInfo | null = null;
 
-  constructor(private readonly resolveNode: NodeBinaryResolver) {}
+  constructor(
+    private readonly resolveNode: NodeBinaryResolver,
+    private readonly mintCredential?: PairingCredentialMinter,
+  ) {}
+
+  /**
+   * The bearer a link hands a new device: its own credential when the mesh
+   * has a credential store, else the shared bridge token (legacy).
+   */
+  private linkCredential(
+    sharedToken: string,
+    scopes: readonly MeshScope[],
+    origin: CredentialOrigin,
+  ): string {
+    return this.mintCredential
+      ? this.mintCredential(scopes, origin)
+      : sharedToken;
+  }
 
   /** The native bridge reports its reachable identity here (null on stop). */
   setBridgeInfo(info: MeshBridgeInfo | null): void {
@@ -133,7 +170,7 @@ export class BridgeLinks {
       size: bin.size,
       version: bin.version,
       bridgeUrl: base,
-      bearerToken: info.token,
+      bearerToken: this.linkCredential(info.token, NODE_SCOPES, "install"),
       ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
     });
     return {
@@ -185,9 +222,14 @@ export class BridgeLinks {
     }
     const base = this.bridgeBaseUrl(info, bridgeUrl);
     if (typeof base !== "string") return { ok: false, text: base.error };
+    const token = this.linkCredential(
+      info.token,
+      info.companionScopes ?? DEFAULT_COMPANION_SCOPES,
+      "pair",
+    );
     const grant = this.companionPairs.create({
       bridgeUrl: base,
-      bearerToken: info.token,
+      bearerToken: token,
       ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
       ...(typeof label === "string" && label.trim()
         ? { label: label.trim() }
@@ -197,7 +239,7 @@ export class BridgeLinks {
       ok: true,
       link: pairLink(grant),
       url: base,
-      token: info.token,
+      token,
       ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
     };
   }

package/src/core/mesh/links/node-binaries.ts

@@ -57,7 +57,7 @@ export const NODE_TARGETS: readonly NodeTarget[] = [
 ];
 
 const SUMS_ASSET = "talon-node-SHA256SUMS";
-const RELEASE_BASE = "https://github.com/dylanneve1/talon/releases/download";
+const RELEASE_BASE = "https://github.com/thefalconry/talon/releases/download";
 const DOWNLOAD_TIMEOUT_MS = 120_000;
 const BUILD_TIMEOUT_MS = 300_000;
 

package/src/core/mesh/links/node-provision.ts

@@ -166,7 +166,13 @@ echo "Done — this host is now on the mesh. Check with: $BIN status"
 `;
 }
 
-/** PowerShell installer (Windows PowerShell 5+ compatible). */
+/**
+ * PowerShell installer (Windows PowerShell 5+ compatible). The binary lands in
+ * the installing user's %LOCALAPPDATA% and `talon-node install` registers a
+ * boot task that runs as that same user (never SYSTEM — a SYSTEM task would
+ * run a binary the user can rewrite). Registering a boot task needs an
+ * elevated PowerShell.
+ */
 function powershellInstaller(grant: NodeProvisionGrant): string {
   const nameArg = grant.name ? `, "--name", "${grant.name}"` : "";
   const fpArg = grant.fingerprint
@@ -184,6 +190,7 @@ Invoke-WebRequest -UseBasicParsing "$bridge/node/binary?provision=${grant.token}
 $got = (Get-FileHash $bin -Algorithm SHA256).Hash.ToLower()
 if ($got -ne "${grant.sha256}") { Remove-Item $bin; throw "talon-node download failed its checksum - refusing to install" }
 Write-Host "Installed $bin"
+Write-Host "Registering the boot task to run as $env:USERDOMAIN\\$env:USERNAME (not SYSTEM)..."
 & $bin install --bridge $bridge --token "${grant.bearerToken}"${fpArg}${nameArg}
 Write-Host "Done - this host is now on the mesh. Check with: $bin status"
 `;

package/src/core/models/active-model.ts

@@ -14,7 +14,7 @@
  * a single global-default fallback that ignored the per-chat backend.
  * That produced two recurring bug classes:
  *
- *   1. **Reset-on-non-default-backend** (Dylan, 2026-05-21): chat on
+ *   1. **Reset-on-non-default-backend** (Ada, 2026-05-21): chat on
  *      Codex, user hits Reset, code clears the override, read side
  *      returns `config.model = "claude-opus-4-7"`. Codex chat then
  *      tries to run an Anthropic id.

package/src/core/plugin/loader.ts

@@ -15,6 +15,7 @@ import type {
 } from "./types.js";
 import { isMcpPlugin } from "./types.js";
 import { registry, _deps } from "./registry.js";
+import { GATEWAY_TOKEN_ENV } from "../engine/gateway-auth.js";
 
 /**
  * Candidate entry point paths, checked in order. Exported for
@@ -67,6 +68,9 @@ export async function loadPlugins(
 
 function applyEnvVars(envVars: Record<string, string>): void {
   for (const [key, value] of Object.entries(envVars)) {
+    // The gateway token is the daemon's own credential; a plugin may read
+    // it but never replace it.
+    if (key === GATEWAY_TOKEN_ENV) continue;
     process.env[key] = value;
   }
 }

package/src/core/plugin/mcp.ts

@@ -10,6 +10,7 @@ import { wrapMcpServer } from "../mcp-hub/launcher.js";
 import { isBunRuntime } from "../../util/runtime.js";
 import { registry, reloadState } from "./registry.js";
 import type { McpServerConfig } from "./types.js";
+import { GATEWAY_TOKEN_ENV, gatewayToken } from "../engine/gateway-auth.js";
 
 function buildBridgeEnv(
   bridgeUrl: string,
@@ -19,6 +20,9 @@ function buildBridgeEnv(
   return {
     ...envVars,
     TALON_BRIDGE_URL: bridgeUrl,
+    // Plugins that call back into the gateway (POST /action) must send
+    // this as `Authorization: Bearer <token>`.
+    [GATEWAY_TOKEN_ENV]: gatewayToken(),
     TALON_CHAT_ID: chatId,
     TALON_RELOAD_AT: reloadState.lastReloadAt,
   };

package/src/core/tools/bridge.ts

@@ -12,6 +12,7 @@
 
 import { Agent, fetch as undiciFetch } from "undici";
 import { isBunRuntime } from "../../util/runtime.js";
+import { gatewayAuthHeaders } from "../engine/gateway-auth.js";
 import type { BridgeFunction } from "./types.js";
 
 /** Default wall-clock budget for a bridge action. */
@@ -91,7 +92,7 @@ export function createBridge(
     const timeoutMs = LONG_ACTION_TIMEOUTS_MS[action] ?? DEFAULT_TIMEOUT_MS;
     const init = {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...gatewayAuthHeaders() },
       // chat_id stays in body when set — gateway uses its presence as the
       // "explicit routing" signal. _chatId is the routing key either way.
       body: JSON.stringify({ action, ...params, _chatId: effectiveChatId }),

package/src/core/types.ts

@@ -227,6 +227,19 @@ export type ExecuteParams = {
   senderName: string;
   /** Sender's platform handle without `@` (Telegram username, Discord username). */
   senderHandle?: string;
+  /**
+   * Every key the ONE person behind this turn is known by, in operator-id
+   * form (Telegram user id, `wa_dm_<number>`, `discord:<id>`,
+   * `teams:<id>`, or `LOCAL_OPERATOR_SENDER`). Decides the turn's tool
+   * scope (core/mcp-hub/guest-scope.ts). Omit when the sender is unknown
+   * or the turn batches several senders — the turn is then guest-scoped.
+   */
+  senderKeys?: readonly string[];
+  /**
+   * Frontend-attested: the operator is a member of this group chat. With
+   * `guestDmScope.operatorGroups` on, such a turn keeps the full surface.
+   */
+  operatorInChat?: boolean;
   isGroup: boolean;
   /** Provider message ID. Numeric for Telegram, string snowflake for Discord. */
   messageId?: number | string;

package/src/core/weaver/weaver.ts

@@ -29,6 +29,12 @@ import { recordSessionTurnPhases } from "../../storage/sessions.js";
 import type { TurnPhase } from "../../storage/session-record.js";
 import { retrieveForTurn, type TurnMemory } from "../memory/turn-retrieval.js";
 import { TalonError } from "../errors.js";
+import { backendEnforcesGuestScope } from "../agent-runtime/backend-registry.js";
+import {
+  enterTurnScope,
+  resolveTurnScope,
+  scopePrompt,
+} from "../mcp-hub/guest-scope.js";
 import { Loom } from "./loom.js";
 import { carryTurnEvents, startShuttleTiming } from "./shuttle.js";
 import type { Thread, ThreadSnapshot } from "./thread.js";
@@ -184,23 +190,22 @@ export class Weaver {
     });
     phases.warpResolve = Date.now() - warpStartedAt;
     if (!warp.ok) {
-      // Refusals are delivered through the same event sink the backend
-      // would use for output (as an `assistant_message` event, so the
-      // frontend delivers it normally).
-      try {
-        await params.onEvent?.({
-          type: "assistant_message",
-          text: warp.message,
-        });
-      } catch (err) {
-        logWarn(
-          "dispatcher",
-          `onEvent(no-model) threw: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }
+      await deliverRefusal(params, warp.message, "no-model");
       return this.emptyResult(warp.message, params);
     }
 
+    // Tool scope is decided per sender: a non-operator gets the guest
+    // surface, and a backend that can't enforce it doesn't get the turn.
+    const scope = resolveTurnScope(params);
+    if (scope === "guest" && !backendEnforcesGuestScope(backend.id)) {
+      logWarn(
+        "dispatcher",
+        `[${reqId}] guest-scoped turn refused chat=${params.chatId}: backend "${backend.id}" cannot enforce the guest tool scope`,
+      );
+      await deliverRefusal(params, GUEST_BACKEND_REFUSAL, "guest-scope");
+      return this.emptyResult(GUEST_BACKEND_REFUSAL, params);
+    }
+
     // Bind the warp — record the model/backend actually resolved for this turn
     // on the Thread. `weaver.snapshot()` reports it, and a change since the
     // last turn (per-chat rebind, per-run override, or config drift) is logged
@@ -235,6 +240,7 @@ export class Weaver {
       `[${reqId}] ${params.source} chat=${params.chatId} started (active=${this.activeCount})`,
     );
     context.acquire(params.numericChatId, params.chatId);
+    const releaseScope = enterTurnScope(params.chatId, scope);
     const stopTyping = startTypingLoop(
       this.deps.sendTyping,
       params.numericChatId,
@@ -251,7 +257,7 @@ export class Weaver {
       const stream = backend.chat.runChatTurn({
         chatId: params.chatId,
         model: warp.ref,
-        text: params.prompt,
+        text: scopePrompt(scope, params.prompt),
         senderName: params.senderName,
         senderHandle: params.senderHandle,
         isGroup: params.isGroup,
@@ -293,6 +299,7 @@ export class Weaver {
       return this.toExecuteResult(agentResult, params);
     } finally {
       stopTyping();
+      releaseScope();
       context.release(params.numericChatId, params.chatId);
     }
   }
@@ -331,6 +338,31 @@ export class Weaver {
   }
 }
 
+const GUEST_BACKEND_REFUSAL =
+  "I can't answer this here: messages from anyone but the operator run with a " +
+  "limited tool set, and this chat's current model backend can't enforce it. " +
+  "The operator can switch this chat to a backend that does (Claude).";
+
+/**
+ * Refusals are delivered through the same event sink the backend would use
+ * for output (as an `assistant_message` event, so the frontend delivers it
+ * normally).
+ */
+async function deliverRefusal(
+  params: ExecuteParams,
+  text: string,
+  kind: string,
+): Promise<void> {
+  try {
+    await params.onEvent?.({ type: "assistant_message", text });
+  } catch (err) {
+    logWarn(
+      "dispatcher",
+      `onEvent(${kind}) threw: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 /**
  * This turn's retrieved memory (`core/memory/turn-retrieval.ts`) — off
  * unless `TALON_MEMORY_STORE=1`, fail-closed, and a pure read: nothing

package/src/frontend/discord/callbacks/components/agent-buttons.ts

@@ -64,6 +64,7 @@ export async function forwardToAgent(
       numericChatId,
       prompt,
       senderName: sender,
+      senderKeys: [`discord:${interaction.user.id}`],
       isGroup,
       source: "message",
       onEvent: async (event) => {

package/src/frontend/discord/handlers/delivery.ts

@@ -25,6 +25,8 @@ export type ProcessAndReplyParams = {
   isGroup: boolean;
   senderUsername?: string;
   senderId: string;
+  /** False when the batch mixes senders — the turn is then guest-scoped. */
+  singleSender?: boolean;
   channel: TextBasedChannel;
   chatTitle?: string;
 };
@@ -53,6 +55,7 @@ export async function processAndReply(p: ProcessAndReplyParams): Promise<void> {
     prompt: p.prompt,
     senderName: p.senderName,
     senderHandle: p.senderUsername,
+    senderKeys: p.singleSender === false ? [] : [`discord:${p.senderId}`],
     isGroup: p.isGroup,
     // Use the real Discord snowflake string, not the hashed numeric.
     // The hash collides with Telegram-style 32-bit IDs and Discord's API

package/src/frontend/discord/handlers/queue.ts

@@ -83,6 +83,7 @@ async function flushQueue(chatId: string): Promise<void> {
       isGroup: last.isGroup,
       senderUsername: last.senderUsername,
       senderId: last.senderId,
+      singleSender: messages.every((m) => m.senderId === last.senderId),
       channel: last.channel,
       chatTitle: last.chatTitle,
     });

package/src/frontend/native/bridge/auth-guard.ts

@@ -0,0 +1,277 @@
+/**
+ * Auth guard — how the bridge answers credentials that don't check out.
+ *
+ * The token itself is the security (256 bits when Talon mints it); this
+ * module decides how a wrong one is answered so an internet-facing bridge
+ * can't be hammered for free, and so the operator hears about it.
+ *
+ * Three layers, all keyed on the remote address (behind a reverse proxy that
+ * is the proxy):
+ *
+ *   1. Progressive backoff: the first few wrong tokens from an address get an
+ *      immediate 401; after that each 401 waits longer (base doubling to a
+ *      cap). Only failures wait. A correct token is never delayed.
+ *   2. Lockout: after `lockoutMaxFailures` wrong tokens in the window the
+ *      address gets 429s (even with the right token) until the window lapses.
+ *   3. Global failure budget: if wrong tokens across ALL addresses exceed
+ *      `globalMaxFailures` in `globalWindowMs`, that is distributed guessing
+ *      dodging (1) and (2). The bridge enters a cooldown: wrong tokens get
+ *      429 at once, tokenless requests are slowed, the operator is alerted
+ *      once. Authenticated traffic keeps working throughout.
+ *
+ * Only presented-and-wrong tokens count as failures. Tokenless probes are
+ * scanners finding a locked door. Waits are timers, never a blocked event
+ * loop, and the number of responses held at once is capped so the delays
+ * can't be turned into a socket-exhaustion lever.
+ *
+ * Every event logs one `bridge.auth event=…` line with the address and a
+ * reason. Token material never reaches this module.
+ */
+
+import { log, logWarn } from "../../../util/log.js";
+import type { AuthState } from "./routes/table.js";
+
+export type AuthGuardPolicy = {
+  /** Wrong tokens from one address inside the window before 429s. */
+  lockoutMaxFailures: number;
+  lockoutWindowMs: number;
+  /** Hard cap on tracked addresses so the map can't become a memory lever. */
+  maxTracked: number;
+  /** Wrong tokens answered without delay (typos happen). */
+  freeFailures: number;
+  backoffBaseMs: number;
+  backoffMaxMs: number;
+  /** Wrong tokens across every address, per window, before a cooldown. */
+  globalMaxFailures: number;
+  globalWindowMs: number;
+  globalCooldownMs: number;
+  /** How long a tokenless request is held during a cooldown. */
+  cooldownAnonDelayMs: number;
+  /** Most responses held at once; past this, refuse instead of waiting. */
+  maxPendingDelays: number;
+};
+
+const DEFAULT_AUTH_GUARD_POLICY: AuthGuardPolicy = {
+  lockoutMaxFailures: 20,
+  lockoutWindowMs: 15 * 60_000,
+  maxTracked: 10_000,
+  freeFailures: 2,
+  backoffBaseMs: 250,
+  backoffMaxMs: 8_000,
+  globalMaxFailures: 100,
+  globalWindowMs: 5 * 60_000,
+  globalCooldownMs: 10 * 60_000,
+  cooldownAnonDelayMs: 1_000,
+  maxPendingDelays: 512,
+};
+
+export type AuthVerdict =
+  | { kind: "allow" }
+  /** Hold the response this long, then carry on as normal. */
+  | { kind: "delay"; ms: number }
+  | {
+      kind: "reject";
+      reason: "lockout" | "cooldown";
+      retryAfterSec: number;
+    };
+
+type Entry = { count: number; resetAt: number };
+
+export class AuthGuard {
+  private readonly policy: AuthGuardPolicy;
+  private readonly now: () => number;
+  private readonly onAlert: ((message: string) => void) | undefined;
+  private readonly failures = new Map<string, Entry>();
+  private globalCount = 0;
+  private globalWindowStart = 0;
+  private cooldownUntil = 0;
+  private cooling = false;
+  private suppressed = 0;
+  private saturatedLogged = false;
+  private pending = 0;
+
+  constructor(
+    policy: Partial<AuthGuardPolicy> = {},
+    deps: { now?: () => number; onAlert?: (message: string) => void } = {},
+  ) {
+    this.policy = { ...DEFAULT_AUTH_GUARD_POLICY, ...policy };
+    this.now = deps.now ?? Date.now;
+    this.onAlert = deps.onAlert;
+  }
+
+  /** Addresses currently tracked (tests and diagnostics). */
+  trackedCount(): number {
+    return this.failures.size;
+  }
+
+  /** True while the global failure budget is exhausted. */
+  inCooldown(): boolean {
+    this.refreshCooldown(this.now());
+    return this.cooling;
+  }
+
+  /**
+   * Decide how to answer a request whose credential has been evaluated.
+   * Called once per request, before routing.
+   */
+  check(remote: string, auth: AuthState): AuthVerdict {
+    const now = this.now();
+    this.refreshCooldown(now);
+    const entry = this.liveEntry(remote, now);
+    if (entry && entry.count >= this.policy.lockoutMaxFailures) {
+      return {
+        kind: "reject",
+        reason: "lockout",
+        retryAfterSec: Math.max(1, Math.ceil((entry.resetAt - now) / 1000)),
+      };
+    }
+    if (auth === "ok") {
+      this.failures.delete(remote);
+      return { kind: "allow" };
+    }
+    if (auth === "anonymous") {
+      return this.cooling
+        ? { kind: "delay", ms: this.policy.cooldownAnonDelayMs }
+        : { kind: "allow" };
+    }
+    return this.fail(remote, now);
+  }
+
+  /**
+   * Wait `ms` on a timer. Resolves false, without waiting, when too many
+   * responses are already held — the caller refuses instead.
+   */
+  async hold(ms: number): Promise<boolean> {
+    if (this.pending >= this.policy.maxPendingDelays) return false;
+    this.pending++;
+    try {
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+      });
+      return true;
+    } finally {
+      this.pending--;
+    }
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  private fail(remote: string, now: number): AuthVerdict {
+    const count = this.recordFailure(remote, now);
+    this.recordGlobalFailure(now);
+    if (this.cooling) {
+      this.suppressed++;
+      return {
+        kind: "reject",
+        reason: "cooldown",
+        retryAfterSec: Math.max(
+          1,
+          Math.ceil((this.cooldownUntil - now) / 1000),
+        ),
+      };
+    }
+    const delay = count === null ? 0 : this.backoffFor(count);
+    logWarn(
+      "native",
+      `bridge.auth event=failure addr=${remote} reason=bad_token` +
+        (count === null ? " tracked=no" : ` failures=${count}`) +
+        ` delayMs=${delay}`,
+    );
+    if (count === this.policy.lockoutMaxFailures) {
+      logWarn(
+        "native",
+        `bridge.auth event=lockout addr=${remote} reason=too_many_failures failures=${count} windowMin=${this.policy.lockoutWindowMs / 60_000}`,
+      );
+    }
+    return delay > 0 ? { kind: "delay", ms: delay } : { kind: "allow" };
+  }
+
+  private backoffFor(count: number): number {
+    const n = count - this.policy.freeFailures;
+    if (n <= 0) return 0;
+    // 2^(n-1) overflows nothing useful past ~30 doublings; clamp first.
+    const factor = 2 ** Math.min(n - 1, 30);
+    return Math.min(
+      this.policy.backoffMaxMs,
+      this.policy.backoffBaseMs * factor,
+    );
+  }
+
+  private liveEntry(remote: string, now: number): Entry | undefined {
+    const entry = this.failures.get(remote);
+    if (entry && now >= entry.resetAt) {
+      this.failures.delete(remote);
+      return undefined;
+    }
+    return entry;
+  }
+
+  /** Bump the address's count; null when the address couldn't be tracked. */
+  private recordFailure(remote: string, now: number): number | null {
+    const entry = this.liveEntry(remote, now);
+    if (entry) return ++entry.count;
+    if (this.failures.size >= this.policy.maxTracked) {
+      for (const [ip, e] of this.failures) {
+        if (now >= e.resetAt) this.failures.delete(ip);
+      }
+      // Still saturated after pruning live entries — under that much churn
+      // dropping the newest address beats unbounded growth. The global
+      // budget still counts it.
+      if (this.failures.size >= this.policy.maxTracked) {
+        if (!this.saturatedLogged) {
+          this.saturatedLogged = true;
+          logWarn(
+            "native",
+            `bridge.auth event=tracking_saturated reason=address_cap tracked=${this.failures.size}`,
+          );
+        }
+        return null;
+      }
+    }
+    this.saturatedLogged = false;
+    this.failures.set(remote, {
+      count: 1,
+      resetAt: now + this.policy.lockoutWindowMs,
+    });
+    return 1;
+  }
+
+  private recordGlobalFailure(now: number): void {
+    if (now - this.globalWindowStart >= this.policy.globalWindowMs) {
+      this.globalWindowStart = now;
+      this.globalCount = 0;
+    }
+    this.globalCount++;
+    if (this.globalCount <= this.policy.globalMaxFailures) return;
+    // Sustained guessing keeps pushing the end of the cooldown out.
+    this.cooldownUntil = now + this.policy.globalCooldownMs;
+    if (this.cooling) return;
+    this.cooling = true;
+    this.suppressed = 0;
+    const message =
+      `bridge.auth event=global_cooldown reason=failure_budget failures=${this.globalCount} ` +
+      `windowSec=${this.policy.globalWindowMs / 1000} cooldownSec=${this.policy.globalCooldownMs / 1000}`;
+    logWarn("native", message);
+    try {
+      this.onAlert?.(
+        `⚠️ Talon bridge: ${this.globalCount} failed auth attempts across all addresses in ` +
+          `${this.policy.globalWindowMs / 60_000} min, which looks like distributed token guessing ` +
+          "(or a token rotation left devices with a stale token). Failed and tokenless " +
+          `requests are being refused or slowed for ${this.policy.globalCooldownMs / 60_000} min; ` +
+          "paired clients are unaffected.",
+      );
+    } catch {
+      // An alert that can't be delivered must never break request handling.
+    }
+  }
+
+  private refreshCooldown(now: number): void {
+    if (!this.cooling || now < this.cooldownUntil) return;
+    this.cooling = false;
+    log(
+      "native",
+      `bridge.auth event=global_cooldown_end reason=expired refused=${this.suppressed}`,
+    );
+    this.suppressed = 0;
+  }
+}