@chatpanel/gateway 0.6.4 → 0.6.6

package/README.md

@@ -43,9 +43,14 @@ You need the [ChatPanel bridge](https://github.com/chatpanel/chatpanel-bridge)
 running and logged into codex/claude (the same bridge the extension uses).
 
 ```bash
+# Standalone binary — no Node.js required:
+curl -fsSL https://dl.chatpanel.net/gateway/install.sh | bash   # macOS / Linux
+#   Windows (PowerShell):  irm https://dl.chatpanel.net/gateway/install.ps1 | iex
+
+# Or via npm (needs Node):
 npm install -g @chatpanel/gateway
 chatpanel-gateway
-# → ChatPanel Privacy Gateway v0.1.0 on http://127.0.0.1:4320
+# → ChatPanel Privacy Gateway on http://127.0.0.1:4320
 #     backend  : bridge (agent: codex, via http://127.0.0.1:4319)
 ```
 
@@ -68,16 +73,42 @@ before codex sees it, and the reply is restored before opencode renders it. The
 request's `model` (`codex`/`claude`/`opencode`/`pi`) picks which agent the bridge
 drives; otherwise the configured default (`codex`) is used.
 
-### Using the api backend instead (local models / BYO keys)
+### Quick start (api backend — no bridge)
 
-Set `backend: "api"` (see config) and the gateway forwards redacted traffic to a
-real provider endpoint, passing your `Authorization` / `x-api-key` through:
+If all you want is the gateway as a **redacting proxy in front of an API model**,
+you do **not** need the bridge. Set `backend: "api"` and (optionally) point the
+gateway's upstream at your provider — in `~/.chatpanel/gateway.config.json`:
+
+```json
+{
+  "backend": "api",
+  "upstreams": {
+    "openai":    { "baseUrl": "https://api.openai.com" },
+    "anthropic": { "baseUrl": "https://api.anthropic.com" }
+  }
+}
+```
+
+Then point your **client** at the gateway and send your **own** API key — the
+gateway redacts, forwards to the provider with your key (it stores none), and
+restores the reply:
 
 ```bash
-export OPENAI_BASE_URL=http://127.0.0.1:4320/v1     # OpenAI / codex / aider / cursor
+# In your CLIENT's environment (NOT the gateway's — see the footgun below):
+export OPENAI_BASE_URL=http://127.0.0.1:4320/v1     # OpenAI-compatible: codex / aider / cursor / SDKs
 export ANTHROPIC_BASE_URL=http://127.0.0.1:4320     # Claude Code / Anthropic SDK
 ```
 
+To target a non-OpenAI provider (a local model, OpenRouter, Azure, …) change the
+**gateway's** `upstreams.*.baseUrl` in the config above — that's where the gateway
+forwards to. Flow: `client → gateway (redact) → provider (your key) → gateway (restore) → client`.
+
+> ⚠️ **Footgun:** `OPENAI_BASE_URL` means two different things — for your *client*
+> it's "where the gateway is", for the *gateway* it's "where my upstream is". Don't
+> set `OPENAI_BASE_URL=…:4320` in the **gateway's own** environment, or it forwards
+> to itself (the loop guard returns 508). Set the gateway's upstream in the config
+> file; use the env var only in the client's shell.
+
 ## Name/org redaction is built in (in-process NER, no Python)
 
 Deterministic redaction (emails, phones, cards, SSNs, API keys, IPs) needs no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@chatpanel/pii": "^0.2.6",
+    "@chatpanel/pii": "^0.2.9",
     "@huggingface/transformers": "^4.2.0",
     "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c"
   },

package/src/config.js

@@ -34,14 +34,16 @@ const DEFAULTS = {
   allowedOrigins: [],
   maxBodyBytes: 26214400,
 
-  // Monetization: the gateway is free to try, paid to rely on. Free = deterministic
-  // redaction (basic tier) + a daily request cap. Paste a ChatPanel Pro entitlement
-  // token (the same offline-signed token the extension/bridge use) to unlock
-  // full-tier redaction (NER names/orgs + full dictionary) and unlimited usage.
+  // Monetization: the gateway is free to try, paid to rely on. Free = full-tier
+  // redaction (the real thing — NER names/orgs + dictionary) for a FIXED LIFETIME
+  // allowance (freegate.FREE_TOTAL_CAP redactions), then it stops. Paste a
+  // ChatPanel Pro entitlement token (the same offline-signed token the extension/
+  // bridge use) to unlock unlimited usage. `free.used` is the running lifetime
+  // count (server-authoritative; persisted here so it survives restarts).
   pro: {
     entitlementToken: '',
     free: {
-      maxRequestsPerDay: 25,
+      used: 0,
     },
   },
 
@@ -96,6 +98,14 @@ const DEFAULTS = {
 
   // Log one line per request (method, tokens redacted) without any raw values.
   logRequests: true,
+
+  // Optional per-request redaction breakdown attached to each log entry (shown
+  // expandable in the extension). Memory-only — never persisted to disk with the
+  // captured values; only the MODE is saved.
+  //   'off'    — counts only (default; the privacy-safe baseline)
+  //   'types'  — entity types + placeholder tokens (e.g. PERSON_1), no real values
+  //   'values' — real → placeholder mapping (the actual PII; opt-in, debugging)
+  logDetail: 'off',
 };
 
 function deepMerge(base, over) {

package/src/configstore.js

@@ -5,6 +5,7 @@
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import os from 'node:os';
+import { usage } from './freegate.js';
 
 // Default to a writable per-user location, NOT process.cwd(): when the gateway
 // runs as a login service its cwd is "/" (read-only → EROFS on save).
@@ -22,7 +23,7 @@ export function persistConfig(cfg, path = configPath()) {
     destinations: cfg.destinations,
     bridge: cfg.bridge, upstreams: cfg.upstreams, redaction: cfg.redaction,
     ner: cfg.ner, allowedOrigins: cfg.allowedOrigins, maxBodyBytes: cfg.maxBodyBytes,
-    pro: cfg.pro, logRequests: cfg.logRequests, tools: cfg.tools,
+    pro: cfg.pro, logRequests: cfg.logRequests, logDetail: cfg.logDetail, tools: cfg.tools,
   };
   writeFileSync(path, JSON.stringify(out, null, 2));
 }
@@ -45,8 +46,11 @@ export function publicConfig(cfg, { proUnlocked = false } = {}) {
     },
     ner: cfg.ner,
     allowedOrigins: Array.isArray(cfg.allowedOrigins) ? cfg.allowedOrigins : [],
-    pro: { unlocked: proUnlocked, hasToken: !!cfg.pro?.entitlementToken, free: cfg.pro?.free },
+    // free = lifetime trial usage ({ used, cap, remaining }) — read-only; the cap
+    // is fixed and the count is server-authoritative (never settable from the UI).
+    pro: { unlocked: proUnlocked, hasToken: !!cfg.pro?.entitlementToken, free: usage(cfg) },
     logRequests: !!cfg.logRequests,
+    logDetail: ['types', 'values'].includes(cfg.logDetail) ? cfg.logDetail : 'off',
     tools: {
       autoNarrow: cfg.tools?.autoNarrow !== false,
       maxPerTurn: Number(cfg.tools?.maxPerTurn) > 0 ? Number(cfg.tools.maxPerTurn) : 8,
@@ -101,10 +105,12 @@ export function applyConfigPatch(cfg, patch = {}) {
   if (Array.isArray(patch.allowedOrigins)) cfg.allowedOrigins = patch.allowedOrigins;
   if (patch.pro && typeof patch.pro === 'object') {
     if (typeof patch.pro.entitlementToken === 'string') cfg.pro.entitlementToken = patch.pro.entitlementToken;
-    const cap = patch.pro.free?.maxRequestsPerDay;
-    if (Number.isFinite(cap) && cap >= 0) cfg.pro.free.maxRequestsPerDay = cap;
+    // NOTE: the free trial is a FIXED lifetime cap (freegate.FREE_TOTAL_CAP) and
+    // its `used` count is server-authoritative — neither is editable here, so a
+    // client can't raise the cap or reset its own trial.
   }
   if (typeof patch.logRequests === 'boolean') cfg.logRequests = patch.logRequests;
+  if (['off', 'types', 'values'].includes(patch.logDetail)) cfg.logDetail = patch.logDetail;
   if (patch.tools && typeof patch.tools === 'object') {
     cfg.tools = cfg.tools || {};
     if ('autoNarrow' in patch.tools) cfg.tools.autoNarrow = !!patch.tools.autoNarrow;

package/src/entitlement-refresh.js

@@ -0,0 +1,94 @@
+// Online entitlement re-validation — closes the refund/revoke abuse window.
+//
+// The gateway stores ONE offline-signed entitlement token (pushed once from the
+// extension via POST /config). Verified purely offline (entitlement.js), that token
+// keeps unlocking Pro until its `exp` — up to 7 days — EVEN AFTER the subscription
+// is refunded, cancelled, or the seat is revoked. The extension/bridge avoid this
+// by re-polling the license worker; the gateway didn't, so a refund left unlimited
+// redaction open for the rest of the token's life.
+//
+// So we also re-check ONLINE on an interval: poll the worker's /entitlement for the
+// token's install_id and either
+//   • REFRESH the stored token (still entitled) — so it never lapses while paid, and
+//   • CLEAR it (worker says valid:false → refunded/cancelled/revoked) — dropping the
+//     gateway to Free immediately instead of riding the offline exp.
+// Network/worker errors NEVER revoke (fail-open for paying users); the offline `exp`
+// still bounds the worst case. Bounds post-refund Pro to <= CHECK_INTERVAL_MS.
+
+import { persistConfig, configPath } from './configstore.js';
+
+// Same worker the extension/bridge use. Overridable for self-hosted/test.
+const API_BASE = (process.env.CHATPANEL_API_BASE || 'https://api.chatpanel.net').replace(/\/+$/, '');
+const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1h — the autonomous post-refund Pro window
+const FIRST_CHECK_DELAY_MS = 30 * 1000;   // let the server settle before first poll
+const MIN_RECHECK_MS = 2 * 60 * 1000;     // throttle on-demand (/status) re-checks
+
+let lastCheckAt = 0;
+
+// The token payload carries { typ, plan, install_id, sub, exp }; we only need the
+// install_id to ask the worker whether that seat is still entitled.
+function installIdFromToken(token) {
+  try {
+    const head = String(token).split('.')[0];
+    const json = Buffer.from(head.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+    const p = JSON.parse(json);
+    return typeof p.install_id === 'string' && p.install_id ? p.install_id : null;
+  } catch {
+    return null;
+  }
+}
+
+async function revalidate(cfg) {
+  lastCheckAt = Date.now();
+  const token = cfg.pro?.entitlementToken;
+  if (!token) return;
+  const installId = installIdFromToken(token);
+  if (!installId) return; // legacy/opaque token — leave the offline exp to bound it
+
+  let data;
+  try {
+    const r = await fetch(`${API_BASE}/entitlement?install_id=${encodeURIComponent(installId)}`, {
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!r.ok) return; // worker hiccup → fail-open, retry next interval
+    data = await r.json();
+  } catch {
+    return; // offline / network error → fail-open (never revoke a paying user)
+  }
+
+  if (data && data.valid && typeof data.token === 'string' && data.token) {
+    // Still entitled — adopt the freshly-signed token so Pro never lapses while paid.
+    if (data.token !== token) {
+      cfg.pro.entitlementToken = data.token;
+      try { persistConfig(cfg, configPath()); } catch { /* best effort */ }
+    }
+  } else if (data && data.valid === false) {
+    // Refunded / cancelled / seat revoked → drop Pro NOW (don't wait out the exp).
+    cfg.pro.entitlementToken = '';
+    try { persistConfig(cfg, configPath()); } catch { /* best effort */ }
+    console.log('[gateway] entitlement no longer valid — Pro deactivated (refund/revoke/seat lost).');
+  }
+}
+
+// On-demand, throttled re-check — fire-and-forget from a hot path (the extension's
+// /status poll) so deactivation shows up within ~minutes of opening the gateway
+// tab, not just on the hourly tick. Never awaited; safe to call often.
+export function maybeRevalidate(cfg) {
+  if (process.env.CHATPANEL_NO_REVALIDATE) return;
+  if (!cfg.pro?.entitlementToken) return;
+  if (Date.now() - lastCheckAt < MIN_RECHECK_MS) return;
+  lastCheckAt = Date.now(); // claim the slot before the async hop (avoid stampede)
+  revalidate(cfg).catch(() => {});
+}
+
+// Start the periodic re-check. Timers are unref'd so they never keep the process
+// alive on their own. Returns a handle with stop() for clean shutdown.
+export function startEntitlementRefresh(cfg) {
+  if (process.env.CHATPANEL_NO_REVALIDATE) return { stop() {} };
+  const tick = () => { revalidate(cfg).catch(() => {}); };
+  const first = setTimeout(tick, FIRST_CHECK_DELAY_MS);
+  const iv = setInterval(tick, CHECK_INTERVAL_MS);
+  if (typeof first.unref === 'function') first.unref();
+  if (typeof iv.unref === 'function') iv.unref();
+  return { stop() { clearTimeout(first); clearInterval(iv); } };
+}

package/src/freegate.js

@@ -1,20 +1,28 @@
 // Free vs Pro for the gateway runtime — the "taste" gate.
 //
-// Free (no entitlement token): deterministic redaction only (basic tier) + a
-// capped number of metered requests per day, so anyone can try it. Pro (a valid
-// ChatPanel entitlement token — the same offline-signed token the extension and
-// bridge use) unlocks full-tier redaction (names/orgs via NER + full dictionary)
-// and unlimited usage. The cryptographic check (entitlement.js) means a forked UI
-// can't unlock it — only the configured/paid token does.
+// Free (no entitlement token): full-tier redaction works, but only for a fixed
+// LIFETIME number of redactions (FREE_TOTAL_CAP) — a real trial of the genuine
+// thing, then you buy. Pro (a valid ChatPanel entitlement token — the same
+// offline-signed token the extension and bridge use) unlocks UNLIMITED redaction.
+// The cryptographic check (entitlement.js) means a forked UI can't unlock it —
+// only the configured/paid token does.
+//
+// The cap is LIFETIME (overall), not per-day, and it is NOT user-editable — so a
+// free user gets exactly FREE_TOTAL_CAP genuine redactions, full stop. The count
+// persists in cfg.pro.free.used (written via configstore.persistConfig), so it
+// survives restarts.
 
 import { isProEntitled } from './entitlement.js';
 
+// The lifetime free allowance. Fixed — deliberately NOT configurable.
+export const FREE_TOTAL_CAP = 100;
+
 const proCache = { token: null, val: false };
-const counts = { day: '', n: 0 };
 
-// Today's metered usage — for the gateway's /status (the extension's monitoring).
+// Lifetime free usage — for the gateway's /status (the extension's monitoring).
 export function usage(cfg) {
-  return { day: counts.day, used: counts.n, cap: cfg.pro?.free?.maxRequestsPerDay ?? 25 };
+  const used = Number(cfg.pro?.free?.used) || 0;
+  return { used, cap: FREE_TOTAL_CAP, remaining: Math.max(0, FREE_TOTAL_CAP - used) };
 }
 
 export async function resolvePro(token) {
@@ -26,19 +34,23 @@ export async function resolvePro(token) {
   return val;
 }
 
-// UTC day bucket. (Runtime — Date is available here, unlike workflow scripts.)
-function dayKey() {
-  return new Date().toISOString().slice(0, 10);
+// May this request still redact? Pro = always. Free = allowed until the lifetime
+// cap is reached, then refused so the client gets a clear upsell. This only
+// CHECKS — the count is advanced by consume() AFTER a redaction actually happens,
+// so requests with nothing to redact don't burn the allowance.
+export function checkQuota(cfg, isPro) {
+  if (isPro) return { allowed: true, remaining: Infinity, isPro: true };
+  const used = Number(cfg.pro?.free?.used) || 0;
+  if (used >= FREE_TOTAL_CAP) return { allowed: false, remaining: 0, used, cap: FREE_TOTAL_CAP, isPro: false };
+  return { allowed: true, remaining: FREE_TOTAL_CAP - used, used, cap: FREE_TOTAL_CAP, isPro: false };
 }
 
-// Meter one redactable request. Pro = always allowed. Free = allowed until the
-// daily cap, then refused so the client gets a clear upsell.
-export function meter(cfg, isPro) {
-  if (isPro) return { allowed: true, remaining: Infinity, isPro: true };
-  const cap = cfg.pro?.free?.maxRequestsPerDay ?? 25;
-  const d = dayKey();
-  if (counts.day !== d) { counts.day = d; counts.n = 0; }
-  if (counts.n >= cap) return { allowed: false, remaining: 0, cap, isPro: false };
-  counts.n += 1;
-  return { allowed: true, remaining: cap - counts.n, cap, isPro: false };
+// Record one consumed free redaction (lifetime). No-op for Pro. Mutates cfg so
+// the caller can persist it. Returns the new used count.
+export function consume(cfg, isPro) {
+  if (isPro) return Infinity;
+  cfg.pro = cfg.pro || {};
+  cfg.pro.free = cfg.pro.free || {};
+  cfg.pro.free.used = (Number(cfg.pro.free.used) || 0) + 1;
+  return cfg.pro.free.used;
 }

package/src/redact.js

@@ -8,22 +8,24 @@
 // mapping is self-consistent within the request. (Same reasoning as the
 // extension's pii-pipeline.)
 
-import { createVault, redactText, detectEntities, effectiveTier, gatedDictionary } from '@chatpanel/pii';
+import { createVault, redactText, detectEntities, gatedDictionary } from '@chatpanel/pii';
 import * as engine from './ner-engine.js';
 
 // tier: 'basic' | 'full'. For 'full' we run the local detector over the combined
 // text to harvest names/orgs, then redact every segment against that entity set.
-// `isPro` applies the SAME free/Pro gating as the extension (shared package):
-// free → deterministic 'basic' tier + a capped dictionary; Pro → full tier.
+//
+// Free vs Pro on the gateway: the free trial is limited by a REQUEST QUOTA
+// (freegate.js), not by downgrading quality — so free users get the REAL tier
+// (names/orgs via NER) within their allowance. The custom dictionary, though, is
+// still a Pro power feature: gatedDictionary caps it to FREE_DICT_LIMIT for free.
 export async function redactSegments(segments, redactionCfg, { signal, isPro = true } = {}) {
   const vault = createVault();
   const texts = segments.map((s) => s.get()).filter((t) => typeof t === 'string' && t);
   if (texts.length === 0) return { vault, count: 0 };
 
-  // effectiveTier downgrades 'full'→'basic' for free; gatedDictionary trims to the
-  // free limit. This reuses chatpanel-pii's gating so the gateway and extension
-  // enforce free/Pro identically.
-  const tier = effectiveTier({ tier: redactionCfg.tier }, isPro);
+  // Use the configured tier as-is (no free downgrade — the quota is the free gate),
+  // but keep the dictionary capped for free via the shared chatpanel-pii gate.
+  const tier = redactionCfg.tier === 'full' ? 'full' : 'basic';
   const dictionary = gatedDictionary(redactionCfg, isPro);
 
   // Detection source: a USER-configured external detector takes precedence; else

package/src/server.js

@@ -19,23 +19,24 @@
 
 import { createServer } from 'node:http';
 import { loadConfig } from './config.js';
+import { startEntitlementRefresh, maybeRevalidate } from './entitlement-refresh.js';
 import { redactSegments } from './redact.js';
 import { pipeRestoredStream, pipeRestoredOpenAIStream, makeTokenRestorer } from './stream.js';
-import { restoreText, effectiveTier, gatedDictionary, narrowSpecs, makeToolHarness, placeholderToolNote } from '@chatpanel/pii';
+import { restoreText, gatedDictionary, narrowSpecs, makeToolHarness, placeholderToolNote } from '@chatpanel/pii';
 import { streamBridgeChat, readBridgeToken, openBridgeChat } from './bridge.js';
 import { createRelaySession, getRelaySession, endRelaySession, pumpBridgeStream, deliverToolResult, toolsToSpecs, parseToolCallId } from './toolrelay.js';
 import { shaperFor } from './shape.js';
 import { startNer } from './ner.js';
 import * as nerEngine from './ner-engine.js';
 import { MODEL_CATALOG, isKnownModel } from './models.js';
-import { resolvePro, meter, usage } from './freegate.js';
+import { resolvePro, checkQuota, consume, usage } from './freegate.js';
 import { publicConfig, applyConfigPatch, persistConfig, configPath } from './configstore.js';
 import { resolveDestination, aggregateModelsAsync } from './router.js';
 import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.4';
+export const VERSION = '0.6.6';
 
 const KNOWN_AGENTS = new Set(['codex', 'claude', 'opencode', 'pi', 'kiro', 'antigravity']);
 
@@ -100,12 +101,62 @@ function setCors(res, origin) {
 
 const STARTED_AT = Date.now();
 
-// In-memory ring of recent request SUMMARIES for the extension's monitoring view.
-// Counts only — never any prompt/response text or values.
-const recentRequests = [];
-function recordRequest(entry) {
-  recentRequests.push(entry);
-  if (recentRequests.length > 50) recentRequests.shift();
+// Render a timings map as a compact one-liner for the console log.
+function fmtTimings(t) {
+  if (!t) return '';
+  const label = { redact: 'redact', upstream: 'model', stream: 'stream', restore: 'restore', total: 'total' };
+  return Object.keys(t).map((k) => `${label[k] || k} ${t[k]}ms`).join(' · ');
+}
+
+// Per-request timing + summary. Created ONLY when logging is on — when it's off
+// the handler passes a null trace and every `trace?.…` call short-circuits, so we
+// don't even read the clock: logging then adds zero latency. The committed entry
+// is flushed to the in-memory ring via setImmediate, i.e. AFTER the response has
+// been handed back, so recording (and the console line) never sits on the request
+// path. `timings` are wall-clock ms per stage of the flow:
+//   redact   prompt → harness[redact] → model input
+//   upstream model input → model output. Non-stream: full call. Stream: time to
+//            first token (model/connection latency). Shown as "model".
+//   stream   first token → last token (generation), streaming responses only
+//   restore  model output → harness[restore] → user response (non-stream; for
+//            streams restore is inline per chunk, so it's folded into stream)
+//   total    end-to-end through the gateway
+function mkTrace(sink) {
+  const start = performance.now();
+  const timings = {};
+  let done = false;
+  const mark = (name, ms) => { timings[name] = Math.round(ms * 10) / 10; };
+  return {
+    meta: {}, timings, mark,
+    // Stamp the duration of an already-completed stage (`t0` from clock()).
+    lap(name, t0) { mark(name, performance.now() - t0); },
+    clock() { return performance.now(); },
+    commit() {
+      if (done) return; done = true;
+      mark('total', performance.now() - start);
+      const entry = /** @type {any} */ ({ ...this.meta, timings });
+      setImmediate(() => {
+        sink(entry);
+        console.log(`[gateway] model=${entry.model || '-'} → ${entry.dest ? `${entry.dest}(${entry.type})` : 'none'} · redacted ${entry.redacted || 0}${entry.narrowed ? ` · narrowed -${entry.narrowed}` : ''} · ${fmtTimings(timings)}`);
+      });
+    },
+  };
+}
+
+// Build the optional per-request redaction breakdown from the request's vault.
+// 'types'  → [{ token:'PERSON_1', type:'PERSON' }]            (no real values)
+// 'values' → [{ token:'PERSON_1', type:'PERSON', value:'…' }] (the real PII; opt-in)
+// Lives only in the in-memory ring — never written to disk by persistConfig.
+function redactionDetail(vault, mode) {
+  if (!vault || !vault.byToken || (mode !== 'types' && mode !== 'values')) return undefined;
+  const out = [];
+  for (const [token, value] of vault.byToken) {
+    const m = /^\[\[([A-Z][A-Z0-9]*)_\d+\]\]$/.exec(token);
+    const t = m ? m[1] : 'PII';
+    const bare = token.replace(/^\[\[|\]\]$/g, '');
+    out.push(mode === 'values' ? { token: bare, type: t, value } : { token: bare, type: t });
+  }
+  return out;
 }
 
 // Classify a request: which protocol kind + adapter, whether it's a redactable
@@ -213,27 +264,38 @@ function forwardHeaders(headers, base) {
 // ---- backend: bridge -------------------------------------------------------
 
 // Stream the bridge SSE through the OpenAI shaper, parking on a tool call.
-async function pumpRelay(res, s, shaper) {
+// `trace` (when present) times the agent turn: 'upstream' = time to first token,
+// 'stream' = first token → park/done. The turn ends at a tool-call (parked, the
+// client runs the tool and POSTs back, resuming a fresh trace) or at onDone.
+async function pumpRelay(res, s, shaper, trace) {
   const restorer = makeTokenRestorer(s.vault);
+  const t0 = trace ? trace.clock() : 0;
+  let sStart = t0;
+  let first = true;
+  const tick = () => { if (trace && first) { trace.lap('upstream', t0); sStart = trace.clock(); first = false; } };
   await pumpBridgeStream(s, {
-    onText: (text) => { const r = restorer.push(text); if (r) res.write(shaper.sseDelta(r)); },
+    onText: (text) => { tick(); const r = restorer.push(text); if (r) res.write(shaper.sseDelta(r)); },
     onToolRequest: ({ name, restoredArgs, toolId }) => {
+      tick();
       const tail = restorer.flush(); if (tail) res.write(shaper.sseDelta(tail));
       res.write(shaper.sseToolCalls([{ id: toolId, name, arguments: JSON.stringify(restoredArgs) }]));
       res.write(shaper.sseToolFinish());
-      res.end(); // park: turn ends with tool_calls; the session stays alive for the follow-up
+      if (trace) trace.lap('stream', sStart);
+      res.end(); trace?.commit(); // park: turn ends with tool_calls; the session stays alive for the follow-up
     },
-    onDone: () => { const tail = restorer.flush(); if (tail) res.write(shaper.sseDelta(tail)); res.write(shaper.sseTail()); res.end(); endRelaySession(s.id); },
-    onError: (e) => { res.write(`data: ${JSON.stringify({ error: { message: e.message, type: 'bridge_error' } })}\n\n`); res.end(); endRelaySession(s.id); },
+    onDone: () => { const tail = restorer.flush(); if (tail) res.write(shaper.sseDelta(tail)); res.write(shaper.sseTail()); if (trace) trace.lap('stream', sStart); res.end(); endRelaySession(s.id); trace?.commit(); },
+    onError: (e) => { res.write(`data: ${JSON.stringify({ error: { message: e.message, type: 'bridge_error' } })}\n\n`); res.end(); endRelaySession(s.id); trace?.commit(); },
   });
 }
 
 // New tool-enabled turn: open the bridge with the client's tools as MCP specs.
-async function startRelay(req, res, { kind, adapter, agent }, body, vault, cfg, isPro, tools, harness = null) {
+async function startRelay(req, res, { kind, adapter, agent }, body, vault, cfg, isPro, tools, harness = null, trace = null) {
   const { messages, system } = adapter.toTurn(body);
   const token = readBridgeToken(cfg.bridge.token);
   const shaper = shaperFor(kind, body?.model || agent);
-  const redactOpts = { tier: effectiveTier({ tier: cfg.redaction.tier }, isPro), dictionary: gatedDictionary(cfg.redaction, isPro), entities: [] };
+  // Full tier for everyone here (the free allowance is enforced by the quota gate
+  // in the main handler), but the custom dictionary stays capped for free.
+  const redactOpts = { tier: cfg.redaction.tier === 'full' ? 'full' : 'basic', dictionary: gatedDictionary(cfg.redaction, isPro), entities: [] };
   const s = createRelaySession({ vault, redactOpts, bridgeUrl: cfg.bridge.url, token, harness });
   const ttl = setTimeout(() => endRelaySession(s.id), 135_000); // bridge tool-call timeout is 120s
   // The placeholder note is already in `system` (injected into the body after
@@ -241,40 +303,48 @@ async function startRelay(req, res, { kind, adapter, agent }, body, vault, cfg,
   let resp;
   try {
     resp = await openBridgeChat({ bridgeUrl: cfg.bridge.url, agent, token, messages, system, specs: toolsToSpecs(tools), options: {}, signal: undefined });
-  } catch (e) { clearTimeout(ttl); endRelaySession(s.id); return sendJson(res, 502, { error: { message: `bridge: ${e.message}`, type: 'bridge_error' } }); }
+  } catch (e) { clearTimeout(ttl); endRelaySession(s.id); trace?.commit(); return sendJson(res, 502, { error: { message: `bridge: ${e.message}`, type: 'bridge_error' } }); }
   s.reader = resp.body.getReader();
   res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
   res.write(shaper.sseHead());
-  return pumpRelay(res, s, shaper);
+  return pumpRelay(res, s, shaper, trace);
 }
 
 // Follow-up turn carrying a tool result: feed it to the parked agent + resume.
-async function resumeRelay(res, s, toolContent, model) {
-  try { await deliverToolResult(s, toolContent); }
-  catch (e) { endRelaySession(s.id); return sendJson(res, 502, { error: { message: `tool-result: ${e.message}`, type: 'bridge_error' } }); }
+// The relay redacts the tool result with ITS vault (the main handler skips
+// redaction for a relay-resume), so time that here as the 'redact' leg.
+async function resumeRelay(res, s, toolContent, model, trace = null) {
+  try {
+    const rd0 = trace ? trace.clock() : 0;
+    await deliverToolResult(s, toolContent);
+    if (trace) trace.lap('redact', rd0);
+  } catch (e) { endRelaySession(s.id); trace?.commit(); return sendJson(res, 502, { error: { message: `tool-result: ${e.message}`, type: 'bridge_error' } }); }
   const shaper = shaperFor('openai', model || 'codex');
   res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
   res.write(shaper.sseHead());
-  return pumpRelay(res, s, shaper);
+  return pumpRelay(res, s, shaper, trace);
 }
 
-async function handleBridge(req, res, { kind, adapter, redactable, pathname, agentOverride, harness }, body, vault, cfg, isPro) {
+async function handleBridge(req, res, { kind, adapter, redactable, pathname, agentOverride, harness, trace }, body, vault, cfg, isPro) {
   if (!redactable) {
+    trace?.commit();
     return sendJson(res, 404, { error: `endpoint ${pathname} not supported by the bridge backend` });
   }
 
   // Tool relay (OpenAI protocol + agent destinations). A follow-up request carries
   // a tool result for a parked session; a new request with `tools` starts one.
+  // The relay streams its own multi-turn flow and commits the trace when its turn
+  // ends (parked on a tool call, or done).
   if (kind === 'openai') {
     const toolResult = adapter.extractLatestToolResult(body);
     if (toolResult) {
       const parsed = parseToolCallId(toolResult.tool_call_id);
       const s = parsed && getRelaySession(parsed.gwId);
-      if (s) return resumeRelay(res, s, toolResult.content, body?.model);
+      if (s) return resumeRelay(res, s, toolResult.content, body?.model, trace);
     }
     const tools = adapter.extractTools(body);
     if (tools.length && body?.stream === true) {
-      return startRelay(req, res, { kind, adapter, agent: agentOverride || pickAgent(body?.model, cfg) }, body, vault, cfg, isPro, tools, harness);
+      return startRelay(req, res, { kind, adapter, agent: agentOverride || pickAgent(body?.model, cfg) }, body, vault, cfg, isPro, tools, harness, trace);
     }
   }
 
@@ -291,10 +361,17 @@ async function handleBridge(req, res, { kind, adapter, redactable, pathname, age
   if (!wantStream) {
     try {
       let full = '';
+      const up0 = trace ? trace.clock() : 0;
       await streamBridgeChat(turn, (t) => { full += t; });
+      if (trace) trace.lap('upstream', up0);
+      const rs0 = trace ? trace.clock() : 0;
+      const out = shaper.full(restoreText(full, vault));
+      if (trace) trace.lap('restore', rs0);
       res.writeHead(200, { 'content-type': shaper.contentType });
-      return res.end(shaper.full(restoreText(full, vault)));
+      res.end(out);
+      return trace?.commit();
     } catch (e) {
+      trace?.commit();
       return sendJson(res, 502, { error: { message: `bridge backend failed: ${e.message}`, type: 'bridge_error' } });
     }
   }
@@ -302,8 +379,12 @@ async function handleBridge(req, res, { kind, adapter, redactable, pathname, age
   res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
   res.write(shaper.sseHead());
   const restorer = makeTokenRestorer(vault);
+  const up0 = trace ? trace.clock() : 0;
+  let sStart = up0;
   try {
+    let first = true;
     await streamBridgeChat(turn, (chunk) => {
+      if (trace && first) { trace.lap('upstream', up0); sStart = trace.clock(); first = false; } // time-to-first-token
       const restored = restorer.push(chunk);
       if (restored) res.write(shaper.sseDelta(restored));
     });
@@ -313,13 +394,16 @@ async function handleBridge(req, res, { kind, adapter, redactable, pathname, age
   } catch (e) {
     res.write(`data: ${JSON.stringify({ error: { message: e.message, type: 'bridge_error' } })}\n\n`);
   }
+  if (trace) trace.lap('stream', sStart);
   res.end();
+  trace?.commit();
 }
 
 // ---- backend: api ----------------------------------------------------------
 
-async function handleApi(req, res, { adapter, kind, pathname, search, base, destKey, destProtocol, harness }, outBody, vault) {
+async function handleApi(req, res, { adapter, kind, pathname, search, base, destKey, destProtocol, harness, trace }, outBody, vault) {
   let upstream;
+  const up0 = trace ? trace.clock() : 0;
   try {
     const headers = forwardHeaders(req.headers, base);
     // If the destination carries its own key (imported from a configured API),
@@ -334,6 +418,7 @@ async function handleApi(req, res, { adapter, kind, pathname, search, base, dest
       body: ['GET', 'HEAD'].includes(req.method) ? undefined : outBody,
     });
   } catch (e) {
+    trace?.commit();
     return sendJson(res, 502, { error: `upstream fetch failed: ${e.message}` });
   }
 
@@ -342,29 +427,47 @@ async function handleApi(req, res, { adapter, kind, pathname, search, base, dest
   upstream.headers.forEach((v, k) => { if (!HOP_BY_HOP.has(k.toLowerCase())) resHeaders[k] = v; });
 
   if (ct.includes('text/event-stream') && upstream.body) {
+    if (trace) trace.lap('upstream', up0); // model latency to response headers
+    const sStart = trace ? trace.clock() : 0;
     res.writeHead(upstream.status, resHeaders);
     // OpenAI streaming: restore tool-call args via the harness (real, or kept
     // redacted for remote MCP under redactRemote) while keeping visible text
-    // pseudonymized. Other protocols: generic restore.
-    if (kind === 'openai') return pipeRestoredOpenAIStream(upstream.body, res, vault, harness);
-    return pipeRestoredStream(upstream.body, res, vault);
+    // pseudonymized. Other protocols: generic restore. The 'stream' leg spans
+    // the body; commit once it finishes (total then covers the whole response).
+    const piped = kind === 'openai'
+      ? pipeRestoredOpenAIStream(upstream.body, res, vault, harness)
+      : pipeRestoredStream(upstream.body, res, vault);
+    return Promise.resolve(piped).finally(() => { if (trace) trace.lap('stream', sStart); trace?.commit(); });
   }
 
   const buf = Buffer.from(await upstream.arrayBuffer());
+  if (trace) trace.lap('upstream', up0);
   if (vault && ct.includes('application/json')) {
     try {
+      const rs0 = trace ? trace.clock() : 0;
       const json = adapter.restoreResponse(JSON.parse(buf.toString('utf8')), vault, harness);
+      if (trace) trace.lap('restore', rs0);
       res.writeHead(upstream.status, { ...resHeaders, 'content-type': 'application/json' });
-      return res.end(Buffer.from(JSON.stringify(json), 'utf8'));
+      res.end(Buffer.from(JSON.stringify(json), 'utf8'));
+      return trace?.commit();
     } catch { /* fall through */ }
   }
   res.writeHead(upstream.status, resHeaders);
   res.end(buf);
+  trace?.commit();
 }
 
 // ---- server ----------------------------------------------------------------
 
 export function createGateway(cfg = loadConfig()) {
+  // Per-gateway ring of recent request summaries for the extension's monitoring
+  // view (newest last). Counts + optional redaction detail + per-stage timings —
+  // see mkTrace. Lives only here, never persisted to disk.
+  const recentRequests = [];
+  const recordRequest = (entry) => {
+    recentRequests.push(entry);
+    if (recentRequests.length > 50) recentRequests.shift();
+  };
   return createServer(async (req, res) => {
     const url = new URL(req.url, 'http://127.0.0.1');
     const pathname = url.pathname;
@@ -382,6 +485,7 @@ export function createGateway(cfg = loadConfig()) {
 
     // --- Config API (the extension's "Gateway" tab is a client of these) ---
     if (pathname === '/status' && req.method === 'GET') {
+      maybeRevalidate(cfg); // throttled, fire-and-forget: reflect a refund/revoke quickly
       const proUnlocked = await resolvePro(cfg.pro?.entitlementToken);
       const health = await probeNerHealth(cfg); // live GET /health on the detector
       return sendJson(res, 200, {
@@ -461,7 +565,7 @@ export function createGateway(cfg = loadConfig()) {
       }
     }
     if (pathname === '/logs' && req.method === 'GET') {
-      return sendJson(res, 200, { entries: [...recentRequests].reverse() }); // newest first; counts only
+      return sendJson(res, 200, { entries: [...recentRequests].reverse() }); // newest first; counts only, unless logDetail enriches each entry
     }
     if (pathname === '/config' && req.method === 'GET') {
       const proUnlocked = await resolvePro(cfg.pro?.entitlementToken);
@@ -511,6 +615,9 @@ export function createGateway(cfg = loadConfig()) {
     let redactedCount = 0;
     let narrowedTools = 0;
     let isPro = true;
+    // Off the hot path: only build a trace when logging is on, so it adds nothing
+    // when off (no clock reads, no record, no console line).
+    const trace = (cfg.logRequests && r.redactable && req.method === 'POST') ? mkTrace(recordRequest) : null;
     if (r.redactable && req.method === 'POST' && raw.length) {
       try { body = JSON.parse(raw.toString('utf8')); } catch { body = null; }
       if (body && isRelayResume(body, r.kind)) {
@@ -531,21 +638,34 @@ export function createGateway(cfg = loadConfig()) {
           body.tools = narrowSpecs(body.tools, latestUserText(body, r.kind), { cap, keep, name: toolName, description: toolDesc });
           narrowedTools = before - body.tools.length;
         }
-        // Free/Pro gate: meter the request and pick the effective tier.
+        // Free/Pro gate: free users get the REAL thing (full-tier redaction), but
+        // only for a fixed lifetime allowance — checked here, consumed below once a
+        // redaction actually happens. Over the cap → 402 upsell.
         isPro = await resolvePro(cfg.pro?.entitlementToken);
-        const allow = meter(cfg, isPro);
+        const allow = checkQuota(cfg, isPro);
         if (!allow.allowed) {
           return sendJson(res, 402, { error: {
-            message: `ChatPanel Gateway free limit reached (${allow.cap}/day). Add a ChatPanel Pro entitlement token to unlock unlimited usage + full-tier redaction (names/orgs).`,
+            message: `ChatPanel Gateway free trial used up (${allow.cap} redactions). Add a ChatPanel Pro entitlement token to unlock unlimited full-tier redaction (names/orgs).`,
             type: 'free_limit_reached',
           } });
         }
         const segs = r.adapter.collectSegments(body, cfg.redaction);
         const ac = new AbortController();
         req.on('close', () => ac.abort());
+        const rd0 = trace ? trace.clock() : 0;
+        // Redact at the configured tier for everyone (free users get genuine
+        // name/org redaction within their allowance, not a downgraded preview);
+        // the custom dictionary stays capped for free (isPro decides that inside).
         const { vault: v, count } = await redactSegments(segs, cfg.redaction, { signal: ac.signal, isPro });
+        if (trace) trace.lap('redact', rd0);
         vault = v;
         redactedCount = count;
+        // Burn one lifetime free credit only when we actually redacted something,
+        // then persist so the count survives a restart. (No-op / no write for Pro.)
+        if (!isPro && count > 0) {
+          consume(cfg, isPro);
+          try { persistConfig(cfg, configPath()); } catch { /* best effort — usage is advisory */ }
+        }
         // When tools are armed, tell the model placeholders are auto-restored for
         // tools (so privacy-aware models USE them instead of refusing). Injected
         // AFTER redaction so the note isn't itself redacted. Covers BOTH the API
@@ -566,31 +686,35 @@ export function createGateway(cfg = loadConfig()) {
     // Route by the requested model → a destination (agent via the bridge, or an
     // API we forward to). Falls back to the legacy backend when none configured.
     const dest = resolveDestination(body?.model, cfg, r.kind);
-    if (cfg.logRequests && r.redactable) {
-      recordRequest({ t: Date.now(), model: body?.model || null, dest: dest ? dest.id : null, type: dest ? dest.type : null, redacted: redactedCount, narrowed: narrowedTools });
-      console.log(`[gateway] ${req.method} ${pathname} · model=${body?.model || '-'} → ${dest ? `${dest.id}(${dest.type})` : 'none'} · redacted ${redactedCount}${narrowedTools ? ` · narrowed -${narrowedTools} tools` : ''}`);
+    if (trace) {
+      trace.meta = { t: Date.now(), model: body?.model || null, dest: dest ? dest.id : null, type: dest ? dest.type : null, redacted: redactedCount, narrowed: narrowedTools, detail: redactionDetail(vault, cfg.logDetail) };
     }
     if (dest && dest.type === 'api') {
-      if (!dest.baseUrl) return sendJson(res, 502, { error: `destination "${dest.id}" has no baseUrl` });
+      if (!dest.baseUrl) { trace?.commit(); return sendJson(res, 502, { error: `destination "${dest.id}" has no baseUrl` }); }
       if (isSelfUrl(dest.baseUrl, cfg)) {
+        trace?.commit();
         return sendJson(res, 508, { error: { message: `destination "${dest.id}" points back at the gateway (${dest.baseUrl}) — refusing to forward (would loop).`, type: 'loop_detected' } });
       }
-      return handleApi(req, res, { ...r, pathname, search: url.search, base: dest.baseUrl, destKey: dest.apiKey, destProtocol: dest.protocol, harness }, outBody, vault);
+      return handleApi(req, res, { ...r, pathname, search: url.search, base: dest.baseUrl, destKey: dest.apiKey, destProtocol: dest.protocol, harness, trace }, outBody, vault);
     }
-    return handleBridge(req, res, { ...r, pathname, agentOverride: dest?.agent, harness }, body, vault, cfg, isPro);
+    return handleBridge(req, res, { ...r, pathname, agentOverride: dest?.agent, harness, trace }, body, vault, cfg, isPro);
   });
 }
 
 export function start(cfg = loadConfig()) {
   const server = createGateway(cfg);
   const ner = startNer(cfg); // may mutate cfg.redaction when it comes up
+  // Re-validate the stored Pro entitlement online on an interval, so a refunded /
+  // revoked subscription drops the gateway to Free instead of riding the offline
+  // token to its exp (see entitlement-refresh.js).
+  const entitlement = startEntitlementRefresh(cfg);
   server.listen(cfg.port, cfg.host, () => {
     console.log(`ChatPanel Privacy Gateway v${VERSION} on http://${cfg.host}:${cfg.port}`);
     console.log(`  backend  : ${cfg.backend}` + (cfg.backend === 'bridge' ? ` (agent: ${cfg.bridge.agent}, via ${cfg.bridge.url})` : ''));
     console.log(`  redaction: ${cfg.redaction.tier}` + (cfg.redaction.detection?.backend && cfg.redaction.detection.backend !== 'off'
       ? ` + ${cfg.redaction.detection.backend} detector` : (cfg.ner?.autostart ? ' (+ NER starting…)' : '')));
   });
-  const shutdown = () => { ner?.stop(); server.close(() => process.exit(0)); };
+  const shutdown = () => { ner?.stop(); entitlement.stop(); server.close(() => process.exit(0)); };
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
   return server;