watchmyagents 1.0.3 → 1.1.0

package/README.md

@@ -107,7 +107,7 @@ Each entry carries: `id`, `agent_id`, `framework`, `timestamp`, `action_type`, `
 ```bash
 wma-fetch (--agent-id <agent_id> | --all-agents) [--session-id <sess_id>] [--since 1h]
          [--log-dir ./watchmyagents-logs] [--dump-raw]
-         [--watch [--interval 5m] [--upload]]
+         [--watch [--interval 1m] [--upload]]
 ```
 
 | Flag | Effect |
@@ -119,11 +119,12 @@ wma-fetch (--agent-id <agent_id> | --all-agents) [--session-id <sess_id>] [--sin
 | `--log-dir ./logs` | Where to write NDJSON (default `./watchmyagents-logs`) |
 | `--dump-raw` | Also save raw API events alongside (forensic / debugging) |
 | `--watch` | **Continuous daemon** — loop forever, incrementally capturing NEW events (deduped by stable event id) until `Ctrl+C` |
-| `--interval 5m` | Poll interval in watch mode (default `5m`; accepts `30s`/`1h`/…) |
+| `--interval 1m` | Poll interval in watch mode (default `1m` since v1.1.0; was `5m` in v1.0.x; accepts `30s`/`1h`/…). At each tick Watch re-discovers the fleet AND polls for new events on tracked sessions. |
 | `--upload` | In watch mode, anonymize each new window and ship signals to Fortress (needs `WMA_API_KEY` + `WMA_FORTRESS_BASE_URL` + `WMA_SIGNALS_SALT`). Raw stays local. |
 | `--discovery-since 7d` | Window for discovering NEW sessions (default `7d`). Sessions already being tracked are re-fetched regardless of age, so long-running ones never drop out. |
 | `--no-send-agent-names` | Opt-out: send only the agent id as the Fortress `display_name`. **By default, the human agent name** (sanitized) is sent so dashboards/decisions stay legible. Pass this flag if your agent names themselves carry client/project info you'd rather keep pseudonymized. |
 | `--api-key sk-ant-…` | Override the `ANTHROPIC_API_KEY` env var. **Discouraged** — visible in shell history & process list. Prefer the env var. |
+| `--discover-now` | **One-shot fast-register mode** (v1.1.0+). Lists every agent your Anthropic key can see and pushes a discovery signal to Fortress so they appear in the dashboard immediately — no waiting for the next Watch cycle, no need to trigger activity first. Requires the same env (`WMA_API_KEY`, `WMA_FORTRESS_BASE_URL`, `WMA_SIGNALS_SALT`) as `--upload`. Exits when done. Typical use: after creating a new agent in the Anthropic console, run `wma-fetch --discover-now` and it shows up in Fortress in ~2 seconds. |
 
 Logs land in `./watchmyagents-logs/<agent_id>/<date>.ndjson` (file mode `0600`, dir `0700`).
 
@@ -198,7 +199,7 @@ export WMA_API_KEY="wma_..."
 export WMA_FORTRESS_BASE_URL="https://<project>.supabase.co/functions/v1"
 export WMA_SIGNALS_SALT="..."                                 # stable per-customer salt
 
-wma-service install (--agent-id agent_01ABC... | --all-agents) [--interval 5m] [--with-shield]
+wma-service install (--agent-id agent_01ABC... | --all-agents) [--interval 1m] [--with-shield]
 wma-service status
 wma-service uninstall [--with-shield]
 ```
@@ -217,7 +218,7 @@ After this, the full Watch→Guardian→Shield loop runs hands-off.
 If you'd rather run the loop in a terminal you control (the service wraps this):
 
 ```bash
-wma-fetch --agent-id agent_01ABC... --watch --upload --interval 5m
+wma-fetch --agent-id agent_01ABC... --watch --upload --interval 1m
 ```
 
 It loops until `Ctrl+C`, dedupes by the stable Anthropic event id (no duplicate
@@ -286,6 +287,12 @@ wma-shield --agent-id agent_xxx --policies-source fortress
 
 In Fortress mode, Shield also POSTs each enforcement decision back to Fortress (`/functions/v1/ingest-decisions`), so the dashboard's live timeline + Loop Visualizer light up in real time.
 
+### Realtime policy propagation (v1.1.0+)
+
+When you accept a Guardian suggestion or deploy a manual rule in the Fortress dashboard, Shield is notified within ~100ms via a persistent Server-Sent Events (SSE) connection to `/functions/v1/policies-stream` and refreshes its ruleset immediately. Shield falls back gracefully to its 60s polling cadence if the SSE endpoint isn't deployed yet on your Fortress instance (HTTP 404), so the SDK ships safely either way.
+
+Why SSE (not WebSocket): zero runtime dependencies preserved (HTTPS = Node built-in), firewall-friendly (many enterprise proxies block raw WS but pass `text/event-stream` cleanly), and the protocol is one-way push-only — exactly what we need.
+
 ### Enforcement mode auto-detection
 
 Shield auto-detects the best mode at startup:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Security observability + real-time policy enforcement for AI agents. Local-first NDJSON capture with a continuous Watch daemon that auto-uploads anonymized signals, Shield CLI that blocks policy violations live (with policies pulled from Fortress cloud), anonymizer producing signals-only payloads, bidirectional sync with WatchMyAgents Fortress, and one-command install as an always-on launchd/systemd service — closing the recursive Watch→Guardian→Shield security loop.",
   "type": "module",
   "files": [

package/scripts/fetch-anthropic.js

@@ -159,6 +159,80 @@ async function uploadSignals(uploadCtx, agentId, displayName, entries, classific
   return resp;
 }
 
+// v1.1.0 L2 — minimal one-shot registration signal sent to Fortress so
+// a freshly-created Anthropic agent appears in the dashboard immediately,
+// without waiting for the next Watch cycle AND without waiting for actual
+// activity. The signal carries an empty SignalsAggregator payload + a
+// degenerate window (window_start == window_end == now) so Fortress's
+// ingest-signals upserts the agent row but contributes zero metrics.
+// Used by --discover-now CLI mode.
+async function uploadDiscoverySignal(uploadCtx, agentId, displayName, enforcementMode) {
+  const now = new Date().toISOString();
+  const body = JSON.stringify({
+    provider: AnthropicManagedSource.providerName,
+    native_agent_id: agentId,
+    anthropic_agent_id: agentId,
+    parent_agent_id: null,
+    composition_pattern: 'solo',
+    enforcement_mode: enforcementMode || AnthropicManagedSource.enforcementMode,
+    display_name: displayName,
+    window_start: now,
+    window_end: now,
+    payload: {
+      counts: {},
+      tool_counts: {},
+      latencies_p50_ms: {},
+      latencies_p95_ms: {},
+      error_rate_by_tool: {},
+      ioc_hashes: [],
+      sequences_top10: [],
+      stop_reasons: {},
+      tokens_total: 0,
+      session_ids: [],
+    },
+  });
+  const { status, body: resp } = await postJson(
+    uploadCtx.url, { authorization: `Bearer ${uploadCtx.apiKey}` }, body,
+  );
+  if (status < 200 || status >= 300) {
+    throw new Error(`ingest-signals HTTP ${status}: ${typeof resp === 'string' ? resp.slice(0, 200) : JSON.stringify(resp)}`);
+  }
+  return resp;
+}
+
+// One-shot "discover and register" mode: list every agent the customer's
+// Anthropic key can see, derive each effective enforcement mode, and push
+// a discovery signal to Fortress so the agent appears in the dashboard
+// immediately. Exits when done — no watch loop, no event polling.
+async function runDiscoverNow({ apiKey, uploadCtx, sendNames }) {
+  info('discover-now: listing agents from Anthropic…');
+  let agents;
+  try { agents = await listAgents(apiKey); }
+  catch (e) { die(`failed to list agents: ${e.message}`); }
+  info(`discover-now: ${agents.length} agent(s) found`);
+
+  let registered = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const a of agents) {
+    if (!a.id || !isValidAgentId(a.id)) { skipped++; continue; }
+    const displayName = sendNames ? cleanLabel(a.name) || a.id : a.id;
+    // Resolve effective enforcement mode best-effort; fall back to provider max.
+    let mode;
+    try { mode = await effectiveEnforcementMode(apiKey, a.id); }
+    catch (e) { warn(`  enforcement_mode resolution failed for ${a.id}: ${e.message} (using provider max)`); }
+    try {
+      const resp = await uploadDiscoverySignal(uploadCtx, a.id, displayName, mode);
+      registered++;
+      info(`  ✓ ${a.id} (${displayName})${resp?.registered_new_agent ? ' 🆕' : ''}`);
+    } catch (e) {
+      failed++;
+      warn(`  ✗ ${a.id}: ${e.message}`);
+    }
+  }
+  info(`discover-now: done — ${registered} registered, ${skipped} skipped, ${failed} failed`);
+}
+
 // Preload already-written entry ids so a restarted daemon doesn't re-append
 // events captured in a previous run (dedup by the stable Anthropic event id).
 async function preloadSeenIds(logDir, agentId) {
@@ -374,8 +448,23 @@ async function main() {
   const watch = !!args.watch;
   const upload = !!args.upload;
   const allAgents = !!args['all-agents'];
+  const discoverNow = !!args['discover-now'];
 
   if (!apiKey) die('error: --api-key or ANTHROPIC_API_KEY required');
+  // --discover-now is its own mode: list+register every agent immediately, exit.
+  // It requires the same Fortress credentials as --upload (it IS a one-shot upload).
+  if (discoverNow) {
+    const wmaKey = process.env.WMA_API_KEY;
+    const salt = process.env.WMA_SIGNALS_SALT;
+    const base = resolveFortressBase({});
+    if (!wmaKey) die('error: --discover-now needs WMA_API_KEY env (from Fortress dashboard → Settings → API Keys)');
+    if (!base) die('error: --discover-now needs WMA_FORTRESS_BASE_URL env');
+    if (!salt) die('error: --discover-now needs WMA_SIGNALS_SALT env');
+    if (salt.length < 16) die('error: WMA_SIGNALS_SALT too short (need ≥16 hex chars)');
+    const uploadCtx = { apiKey: wmaKey, salt, url: fortressEndpoint(base, 'ingest-signals') };
+    const sendNames = args['no-send-agent-names'] !== true;
+    return runDiscoverNow({ apiKey, uploadCtx, sendNames });
+  }
   if (!allAgents && !agentId) die('error: --agent-id required (or --all-agents for fleet mode)');
   if (allAgents && !watch) die('error: --all-agents requires --watch (fleet daemon). For a one-shot, target a single --agent-id.');
   if (agentId && !isValidAgentId(agentId)) {
@@ -404,7 +493,13 @@ async function main() {
   }
 
   if (watch) {
-    const intervalMs = parseDurationMs(args.interval, 5 * 60_000);
+    // v1.1.0 Phase 1 L1: default Watch cycle = 60s (was 300s/5min). At this
+    // cadence both event polling AND fleet re-discovery happen every minute,
+    // bringing the agent-to-Fortress visibility from 5min worst-case down to
+    // ~60s. ~1440 list/get calls/day against Anthropic — well inside free
+    // tier limits, no behavioral risk. Operators who want the legacy 5min
+    // cadence can still pass --interval 5m explicitly.
+    const intervalMs = parseDurationMs(args.interval, 60_000);
     // Discovery window for NEW sessions (default 7d, configurable). Sessions we
     // already track are re-fetched regardless of age, so long-lived ones don't drop.
     const windowMs = parseDurationMs(args['discovery-since'], 7 * 24 * 3600_000);

package/scripts/shield.js

@@ -35,7 +35,8 @@ import {
 import { DecisionLogger } from '../src/shield/decisions.js';
 import { listSessions, listAgents } from '../src/sources/anthropic-managed.js';
 import { FortressPolicySource, postDecision } from '../src/shield/sources/fortress.js';
-import { resolveFortressBase } from '../src/fortress/url.js';
+import { resolveFortressBase, fortressEndpoint } from '../src/fortress/url.js';
+import { PolicyStream } from '../src/shield/policy-stream.js';
 import { isValidAgentId, isValidSessionId } from '../src/validate.js';
 
 function parseArgs(argv) {
@@ -482,9 +483,11 @@ async function main() {
   // Shared infra: one shutdown signal, one fortress-source registry, one pusher.
   const ac = new AbortController();
   const fortressSources = [];
+  const fortressStreams = [];  // v1.1.0 Phase 2 PolicyStream instances
   const shutdown = (sig) => {
     info(`${sig} received, shutting down…`);
     for (const fp of fortressSources) fp.stop();
+    for (const ps of fortressStreams) ps.close();
     ac.abort();
   };
   process.on('SIGINT',  () => shutdown('SIGINT'));
@@ -508,8 +511,13 @@ async function main() {
     let fortressPolicies = null;
     let ruleset = sharedLocalRuleset;
     if (policiesSource === 'fortress') {
+      // v1.1.0 Phase 1 L3.5: policy refresh from Fortress every 60s
+      // (was 5min). Combined with Phase 2 realtime subscription work,
+      // this brings new-policy-deployed-to-Shield latency from 5min
+      // worst-case down to ~60s, with the Phase 2 push model taking
+      // it to sub-second later.
       fortressPolicies = new FortressPolicySource({
-        apiKey: wmaApiKey, base: fortressBase, anthropicAgentId: aid, refreshIntervalMs: 5 * 60_000,
+        apiKey: wmaApiKey, base: fortressBase, anthropicAgentId: aid, refreshIntervalMs: 60_000,
         onError: (e) => warn(`${tag}policy refresh failed (keeping cached): ${e.message}`),
         onRefresh: ({ policies, fetched_at, initial }) => info(`${tag}policies ${initial ? 'loaded' : 'refreshed'} from Fortress — ${policies.length} active (fetched_at: ${fetched_at})`),
       });
@@ -519,6 +527,27 @@ async function main() {
         die(`error fetching policies from Fortress: ${e.message}\n       Check WMA_FORTRESS_BASE_URL and WMA_API_KEY.`);
       }
       fortressSources.push(fortressPolicies);
+      // v1.1.0 Phase 2: persistent SSE connection to Fortress for instant
+      // policy updates (~100ms latency vs 60s poll). Falls back silently
+      // when the /policies-stream endpoint isn't deployed yet (HTTP 404),
+      // so the SDK ships safely even if the companion Lovable prompt
+      // hasn't landed on a given Fortress instance.
+      const streamUrl = fortressEndpoint(fortressBase, 'policies-stream');
+      const policyStream = new PolicyStream({
+        url: streamUrl,
+        apiKey: wmaApiKey,
+        anthropicAgentId: aid,
+        onError: (e) => warn(`${tag}policy-stream: ${e.message}`),
+        onInfo: (msg) => info(`${tag}${msg}`),
+      });
+      policyStream.on('policy_changed', () => {
+        // Fortress pushed a policy change for this agent — trigger an
+        // immediate refresh through the standard path so all the existing
+        // compile/validation logic applies.
+        fortressPolicies.refresh().catch((e) => warn(`${tag}stream-triggered refresh failed: ${e.message}`));
+      });
+      policyStream.start();
+      fortressStreams.push(policyStream);
       ruleset = fortressPolicies.current();
     }
 
@@ -572,9 +601,11 @@ async function main() {
   if (armed.size === 0) {
     die(`error: no agents could be armed (${agentIds.length} discovered; all policy fetches failed). Check WMA_API_KEY / WMA_FORTRESS_BASE_URL.`);
   }
-  info(`fleet: ${armed.size}/${agentIds.length} agent(s) armed; reconciling every 60s for new agents.`);
+  // v1.1.0 Phase 1 L3: supervisor reconcile every 30s (was 60s) so a
+  // freshly-created Anthropic agent gets armed sub-30s instead of sub-minute.
+  info(`fleet: ${armed.size}/${agentIds.length} agent(s) armed; reconciling every 30s for new agents.`);
   while (!ac.signal.aborted) {
-    await sleep(60_000, ac.signal);
+    await sleep(30_000, ac.signal);
     if (ac.signal.aborted) break;
     let all;
     try { all = await listAgents(apiKey); }

package/src/shield/policy-stream.js

@@ -0,0 +1,209 @@
+// ────────────────────────────────────────────────────────────────────────
+// PolicyStream — Server-Sent Events consumer for instant policy propagation
+// ────────────────────────────────────────────────────────────────────────
+//
+// v1.1.0 Phase 2: instead of polling Fortress every 60s for new policies
+// (the FortressPolicySource refreshIntervalMs path), Shield maintains a
+// persistent SSE connection to /functions/v1/policies-stream and refreshes
+// its ruleset within ~100ms of a policy change in Fortress.
+//
+// Why SSE (not WebSocket):
+//   - Zero runtime dependencies preserved: HTTPS + SSE = node:https built-in,
+//     no @supabase/realtime-js, no custom Phoenix Channels client.
+//   - Node 18+ compat preserved: no native WebSocket needed.
+//   - Firewall-friendly: SSE rides on standard HTTPS — many enterprise
+//     proxies block raw WebSocket but pass through text/event-stream cleanly.
+//   - Realtime is uni-directional (Fortress → Shield) anyway. SSE is the
+//     right tool for one-way push notifications.
+//
+// Graceful fallback:
+//   - On HTTP 404 from the SSE endpoint (Fortress side not yet upgraded
+//     with the Lovable prompt), this stream goes into "fallback mode" and
+//     stops trying to reconnect aggressively. The FortressPolicySource's
+//     existing poll cadence (60s in v1.1.0) covers the gap.
+//   - On HTTP 401, this is a config error — logged once, stream stays
+//     down.
+//   - On network errors / disconnects, reconnect with exponential backoff
+//     (1s → 60s cap).
+//
+// Per-agent: each PolicyStream targets a single anthropic_agent_id so the
+// Fortress side can scope the channel to "this customer + this agent".
+
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { EventEmitter } from 'node:events';
+
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+const FALLBACK_RETRY_INTERVAL_MS = 5 * 60_000;
+const PERMANENT_FAILURE_LOG_INTERVAL_MS = 5 * 60_000;
+
+export class PolicyStream extends EventEmitter {
+  constructor({ url, apiKey, anthropicAgentId, onError, onInfo }) {
+    super();
+    if (!url) throw new Error('PolicyStream requires url');
+    if (!apiKey) throw new Error('PolicyStream requires apiKey');
+    if (!anthropicAgentId) throw new Error('PolicyStream requires anthropicAgentId');
+    this.url = url;
+    this.apiKey = apiKey;
+    this.agentId = anthropicAgentId;
+    this.onError = onError || (() => {});
+    this.onInfo = onInfo || (() => {});
+    this._req = null;
+    this._closed = false;
+    this._started = false;
+    this._backoffMs = RECONNECT_MIN_MS;
+    this._inFallback = false;
+    this._lastFallbackLogAt = 0;
+    this._lastConfigErrorLogAt = 0;
+  }
+
+  start() {
+    if (this._closed) return;
+    this._started = true;
+    this._connect();
+  }
+
+  close() {
+    this._closed = true;
+    if (this._req) {
+      try { this._req.destroy(); } catch { /* already destroyed */ }
+      this._req = null;
+    }
+  }
+
+  // Whether the stream is currently the source of truth (i.e., started,
+  // not closed, AND not in fallback mode). Useful for Shield to know
+  // whether to trust SSE or rely on its own polling cadence.
+  isLive() {
+    return this._started && !this._inFallback && !this._closed;
+  }
+
+  _connect() {
+    if (this._closed) return;
+    const u = new URL(this.url);
+    // Query-param scoping so Fortress can filter to this agent's channel.
+    u.searchParams.set('agent_id', this.agentId);
+    if (u.protocol !== 'https:') {
+      this.onError(new Error(`policy-stream: refusing non-https URL: ${this.url}`));
+      return;
+    }
+
+    const req = httpsRequest({
+      hostname: u.hostname,
+      port: u.port || 443,
+      path: u.pathname + (u.search || ''),
+      method: 'GET',
+      headers: {
+        'authorization': `Bearer ${this.apiKey}`,
+        'accept': 'text/event-stream',
+        'cache-control': 'no-cache',
+        'connection': 'keep-alive',
+      },
+      rejectUnauthorized: true,
+    }, (res) => {
+      this._req = req;
+
+      // 404 — Fortress side hasn't deployed the endpoint yet. Silent
+      // fallback: log once per 5 min, retry every 5 min, don't spam.
+      if (res.statusCode === 404) {
+        this._inFallback = true;
+        const now = Date.now();
+        if (now - this._lastFallbackLogAt > PERMANENT_FAILURE_LOG_INTERVAL_MS) {
+          this.onInfo(`policy-stream: SSE endpoint not deployed (HTTP 404). Falling back to polling.`);
+          this._lastFallbackLogAt = now;
+        }
+        res.resume(); // drain to free the socket
+        this._scheduleReconnect(FALLBACK_RETRY_INTERVAL_MS);
+        return;
+      }
+
+      // 401 — auth error. Config bug; log once per 5 min.
+      if (res.statusCode === 401 || res.statusCode === 403) {
+        const now = Date.now();
+        if (now - this._lastConfigErrorLogAt > PERMANENT_FAILURE_LOG_INTERVAL_MS) {
+          this.onError(new Error(`policy-stream: auth error (HTTP ${res.statusCode}) — check WMA_API_KEY`));
+          this._lastConfigErrorLogAt = now;
+        }
+        this._inFallback = true;
+        res.resume();
+        this._scheduleReconnect(FALLBACK_RETRY_INTERVAL_MS);
+        return;
+      }
+
+      if (res.statusCode !== 200) {
+        this.onError(new Error(`policy-stream: unexpected HTTP ${res.statusCode}`));
+        res.resume();
+        this._scheduleReconnect();
+        return;
+      }
+
+      // We're live. Reset backoff + fallback flag.
+      this._backoffMs = RECONNECT_MIN_MS;
+      this._inFallback = false;
+      this.onInfo(`policy-stream: connected for ${this.agentId.slice(0, 16)}…`);
+      res.setEncoding('utf8');
+
+      let buffer = '';
+      res.on('data', (chunk) => {
+        buffer += chunk;
+        // SSE events are separated by a blank line ("\n\n").
+        let eolIdx;
+        while ((eolIdx = buffer.indexOf('\n\n')) !== -1) {
+          const rawEvent = buffer.slice(0, eolIdx);
+          buffer = buffer.slice(eolIdx + 2);
+          this._parseAndEmit(rawEvent);
+        }
+      });
+      res.on('end', () => {
+        if (!this._closed) {
+          this.onInfo('policy-stream: connection closed, reconnecting…');
+          this._scheduleReconnect();
+        }
+      });
+      res.on('error', (e) => {
+        this.onError(new Error(`policy-stream: response error: ${e.message}`));
+        if (!this._closed) this._scheduleReconnect();
+      });
+    });
+
+    req.on('error', (e) => {
+      this.onError(new Error(`policy-stream: request error: ${e.message}`));
+      if (!this._closed) this._scheduleReconnect();
+    });
+    // Stream MUST remain open — no body, no end() until close.
+    req.end();
+  }
+
+  _parseAndEmit(rawEvent) {
+    // SSE spec: each event is a set of "field: value" lines.
+    // We care about the `data:` field (multiple data: lines concatenate).
+    const dataLines = [];
+    for (const line of rawEvent.split('\n')) {
+      // Skip comments (lines starting with ":")
+      if (line.startsWith(':')) continue;
+      if (line.startsWith('data:')) {
+        // Drop leading "data:" and optional space
+        const v = line.slice(5).replace(/^ /, '');
+        dataLines.push(v);
+      }
+    }
+    if (dataLines.length === 0) return;
+    const data = dataLines.join('\n');
+    let parsed;
+    try { parsed = JSON.parse(data); }
+    catch (e) {
+      this.onError(new Error(`policy-stream: invalid JSON in event: ${e.message}`));
+      return;
+    }
+    // Emit 'policy_changed' — consumers should refresh their ruleset.
+    this.emit('policy_changed', parsed);
+  }
+
+  _scheduleReconnect(forceDelay) {
+    if (this._closed) return;
+    const delay = forceDelay != null ? forceDelay : this._backoffMs;
+    this._backoffMs = Math.min(this._backoffMs * 2, RECONNECT_MAX_MS);
+    setTimeout(() => this._connect(), delay);
+  }
+}

package/src/shield/sources/fortress.js

@@ -148,6 +148,17 @@ export class FortressPolicySource {
     return this.ruleset;
   }
 
+  /**
+   * Public refresh hook for out-of-band triggers — e.g. the v1.1.0 SSE
+   * PolicyStream fires this when Fortress pushes a policy_changed event,
+   * collapsing the up-to-60s polling latency to ~100ms.
+   * Safe to call concurrently with the internal interval timer: each
+   * call only performs a single network round-trip.
+   */
+  async refresh() {
+    return this._refresh();
+  }
+
   async _refresh({ initial = false } = {}) {
     if (this._aborted) return;
     try {