@blockrun/clawrouter 0.12.276 → 0.12.277

package/README.md

@@ -767,9 +767,24 @@ For basic usage, no configuration needed. For advanced options:
 | `CLAWROUTER_DISABLED`       | `false`                               | Disable smart routing                                                                                                       |
 | `CLAWROUTER_DEBUG_HEADERS`  | `on`                                  | Set to `off` to suppress `x-clawrouter-*` debug response headers                                                            |
 | `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint — balance checks and payment signing                                                                    |
+| `TWZRD_AUTO_GATE`           | unset (off)                           | Set to `1` to compose TWZRD AutoGate after SpendControl on the x402 pre-sign hook                                           |
 
 **Full reference:** [docs/configuration.md](docs/configuration.md)
 
+### Pre-spend trust (TWZRD AutoGate, opt-in)
+
+Default **off**. Spend limits and counterparty lists (`clawrouter policy`) stay the vendor-neutral path. This is not a default-on vendor lock.
+
+To also run TWZRD wash/preflight on the same `onBeforePaymentCreation` chain — after SpendControl, before the wallet signs:
+
+```bash
+export TWZRD_AUTO_GATE=1
+```
+
+Equivalent flag: `TWZRD_GATE_ENABLED=true`. Requires optional dependency `twzrd-x402-gate@0.9.3` (forks that omit it still install). A refuse stamps `X-Twzrd-Caller: clawrouter/<version>` so it is attributable. Unset the flag to go back to SpendControl only.
+
+**It gates Solana, not Base.** The gate scores Solana recipients; Base/EVM classifies as `network_not_scored` and is waved through without a lookup. On Solana it POSTs the resource URL, `payTo`, price and chain to `intel.twzrd.xyz` before each signature — payment metadata leaves your machine when this is on. We bound that call at `TWZRD_GATE_TIMEOUT_MS` (default 2000) and proceed if it does not answer, because SpendControl is the guarantee and a third party must not be able to stop your payments; set `TWZRD_FAIL_OPEN=false` to refuse instead.
+
 ### Model Exclusion
 
 Block specific models from being routed to. Useful if a model doesn't follow your agent instructions or you want to control costs.

package/dist/cli.js

@@ -39085,6 +39085,14 @@ var init_models = __esm({
         id: "google/gemini-3.8-flash",
         name: "Gemini 3.8 Flash",
         version: "3.8",
+        // ⏰ PROMOTIONAL RATE, expires 2027-01-01. Google prices the whole 3.6/3.7/3.8
+        // Flash band at 0.75/3.75 only through 2026-12-31, reverting to 1.50/7.50
+        // (ai.google.dev/gemini-api/docs/pricing; blockrun's src/lib/models.ts carries
+        // the same dated note). These numbers are not decoration here: calculateModelCost
+        // feeds the maxCostPerRun projection and every `cost` in the usage journal, so
+        // leaving them at the promo rate past the reversion under-reports spend 2x and
+        // lets the cap run to twice its stated limit. Re-price this AND gemini-3.6-flash
+        // together — they revert on the same day.
         inputPrice: 0.75,
         outputPrice: 3.75,
         contextWindow: 1048576,
@@ -39096,6 +39104,8 @@ var init_models = __esm({
       {
         // Newest-generation Flash with built-in thinking mode (blockrun #329,
         // 2026-08-03). 17% cheaper output than 3.5 Flash.
+        // ⏰ Same promotional 0.75/3.75 as gemini-3.8-flash above, and the same
+        // 2027-01-01 reversion to 1.50/7.50 — re-price both together.
         id: "google/gemini-3.6-flash",
         name: "Gemini 3.6 Flash",
         version: "3.6",
@@ -60450,6 +60460,149 @@ var init_api_key = __esm({
   }
 });
 
+// src/twzrd-autogate.ts
+import { randomUUID } from "crypto";
+function normalizeFlag(value) {
+  const trimmed = value?.trim().toLowerCase();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function isTwzrdAutoGateEnabled(env = process.env) {
+  const auto = normalizeFlag(env.TWZRD_AUTO_GATE);
+  const gate = normalizeFlag(env.TWZRD_GATE_ENABLED);
+  if (auto !== void 0 && FALSY.has(auto) || gate !== void 0 && FALSY.has(gate)) {
+    return false;
+  }
+  return auto !== void 0 && TRUTHY.has(auto) || gate !== void 0 && TRUTHY.has(gate);
+}
+function isMissingTwzrdGateModule(err) {
+  const code = err?.code;
+  const msg = err instanceof Error ? err.message : String(err);
+  const missingModule = code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find module/i.test(msg) || /Cannot find package/i.test(msg);
+  return missingModule && new RegExp(String.raw`['"]${TWZRD_GATE_PACKAGE}['"]`).test(msg);
+}
+function twzrdGateTimeoutMs(env = process.env) {
+  const raw = normalizeFlag(env.TWZRD_GATE_TIMEOUT_MS);
+  if (raw === void 0) return TWZRD_GATE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : TWZRD_GATE_TIMEOUT_MS;
+}
+function twzrdGateFailOpen(env = process.env) {
+  const raw = normalizeFlag(env.TWZRD_FAIL_OPEN);
+  return !(raw !== void 0 && FALSY.has(raw));
+}
+function twzrdAutoGateInstallOptions(env = process.env, runId = randomUUID) {
+  return {
+    refuseWashFlagged: true,
+    gateOnCanSpend: false,
+    unsupportedNetworkMode: "observe",
+    failOpen: twzrdGateFailOpen(env),
+    attribution: {
+      integration: `clawrouter/${VERSION}`,
+      runId: runId()
+    }
+  };
+}
+async function runTwzrdGateWithTimeout(run, opts) {
+  const log = opts.log ?? console;
+  let timer2;
+  try {
+    const raced = await Promise.race([
+      // Swallow here, not at the race, so a late rejection never goes unhandled.
+      Promise.resolve().then(run).catch((err) => ({ __twzrdError: err })),
+      new Promise((resolve) => {
+        timer2 = setTimeout(() => resolve(TIMED_OUT), opts.timeoutMs);
+      })
+    ]);
+    if (raced === TIMED_OUT) {
+      return decideOnGateFailure(`did not answer within ${opts.timeoutMs}ms`, opts.failOpen, log);
+    }
+    if (raced && typeof raced === "object" && "__twzrdError" in raced) {
+      const err = raced.__twzrdError;
+      const msg = err instanceof Error ? err.message : String(err);
+      return decideOnGateFailure(`threw: ${msg.slice(0, 120)}`, opts.failOpen, log);
+    }
+    return raced;
+  } finally {
+    if (timer2) clearTimeout(timer2);
+  }
+}
+function decideOnGateFailure(what, failOpen, log) {
+  const reason = `twzrd gate ${what}`;
+  if (failOpen) {
+    log.warn(
+      `[ClawRouter] ${reason} \u2014 proceeding. SpendControl still applied. Set TWZRD_FAIL_OPEN=false to refuse instead.`
+    );
+    return void 0;
+  }
+  log.warn(`[ClawRouter] ${reason} \u2014 refusing the payment (TWZRD_FAIL_OPEN=false).`);
+  return { abort: true, reason };
+}
+async function defaultLoadTwzrdGate() {
+  const specifier = TWZRD_GATE_PACKAGE;
+  return import(specifier);
+}
+async function maybeComposeTwzrdAutoGate(x402, options) {
+  const env = options?.env ?? process.env;
+  const log = options?.log ?? console;
+  if (!isTwzrdAutoGateEnabled(env)) {
+    return { status: "skipped" };
+  }
+  const load = options?.loadGate ?? defaultLoadTwzrdGate;
+  let gate;
+  try {
+    gate = await load();
+  } catch (err) {
+    if (isMissingTwzrdGateModule(err)) {
+      const reason = `${TWZRD_GATE_PACKAGE} is not installed`;
+      log.warn(
+        `[ClawRouter] TWZRD AutoGate opted in but ${reason} \u2014 skipping. npm i ${TWZRD_GATE_PACKAGE}@0.9.3`
+      );
+      return { status: "unavailable", reason };
+    }
+    throw err;
+  }
+  const installOpts = twzrdAutoGateInstallOptions(env);
+  const timeoutMs = twzrdGateTimeoutMs(env);
+  const ready = (via) => log.log(
+    `[ClawRouter] TWZRD AutoGate ON (opt-in, after SpendControl, ${via}; ${timeoutMs}ms budget, failOpen=${installOpts.failOpen}). Unset TWZRD_AUTO_GATE to disable.`
+  );
+  if (typeof gate.createTwzrdBeforePaymentHook === "function") {
+    const hook = gate.createTwzrdBeforePaymentHook(installOpts);
+    x402.onBeforePaymentCreation(
+      async (ctx) => runTwzrdGateWithTimeout(() => hook(ctx.selectedRequirements, ctx), {
+        timeoutMs,
+        failOpen: installOpts.failOpen,
+        log
+      })
+    );
+    ready("createTwzrdBeforePaymentHook");
+    return { status: "composed", via: "createTwzrdBeforePaymentHook" };
+  }
+  if (typeof gate.installTwzrdAutoGate === "function") {
+    gate.installTwzrdAutoGate(x402, installOpts);
+    log.warn(
+      "[ClawRouter] TWZRD AutoGate installed via installTwzrdAutoGate \u2014 that entry point registers its own hook, so the timeout budget does not apply and it replaces onBeforePaymentCreation on this client. Prefer a gate build exporting createTwzrdBeforePaymentHook."
+    );
+    ready("installTwzrdAutoGate");
+    return { status: "composed", via: "installTwzrdAutoGate" };
+  }
+  throw new Error(
+    `[ClawRouter] ${TWZRD_GATE_PACKAGE} is installed but exports neither installTwzrdAutoGate nor createTwzrdBeforePaymentHook`
+  );
+}
+var TWZRD_GATE_PACKAGE, TRUTHY, FALSY, TWZRD_GATE_TIMEOUT_MS, TIMED_OUT;
+var init_twzrd_autogate = __esm({
+  "src/twzrd-autogate.ts"() {
+    "use strict";
+    init_version4();
+    TWZRD_GATE_PACKAGE = "twzrd-x402-gate";
+    TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+    FALSY = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+    TWZRD_GATE_TIMEOUT_MS = 2e3;
+    TIMED_OUT = { __twzrdTimedOut: true };
+  }
+});
+
 // src/compression/types.ts
 var DEFAULT_COMPRESSION_CONFIG;
 var init_types2 = __esm({
@@ -92034,6 +92187,7 @@ async function startProxy(options) {
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
     const spendControl = options.spendControl ?? getSharedSpendControl();
     registerSpendPolicyHook(x402, spendControl);
+    await maybeComposeTwzrdAutoGate(x402);
     registerExactEvmScheme(x402, { signer: evmSigner });
   }
   let solanaAddress;
@@ -95619,6 +95773,7 @@ var init_proxy = __esm({
     init_auth();
     init_api_key();
     init_spend_control();
+    init_twzrd_autogate();
     init_compression();
     init_errors5();
     init_version4();
@@ -228676,7 +228831,7 @@ import {
 } from "fs";
 import { readFile as readFileAsync } from "fs/promises";
 import { homedir as homedir15 } from "os";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { join as join18 } from "path";
 async function waitForProxyHealth(port, timeoutMs = 3e3) {
   const start = Date.now();
@@ -228691,7 +228846,7 @@ async function waitForProxyHealth(port, timeoutMs = 3e3) {
   return false;
 }
 function writePrivateJsonSync(path5, value) {
-  const temporary = `${path5}.tmp.${randomUUID()}`;
+  const temporary = `${path5}.tmp.${randomUUID2()}`;
   try {
     writeFileSync3(temporary, JSON.stringify(value, null, 2), { mode: 384 });
     renameSync2(temporary, path5);
@@ -231182,6 +231337,7 @@ Environment Variables:
   BLOCKRUN_API_KEY        BlockRun API key (brk_...) \u2014 wins over the wallet when set
   BLOCKRUN_WALLET_KEY     Private key for x402 payments (auto-generated if not set)
   BLOCKRUN_PROXY_PORT     Default proxy port (default: 8402)
+  TWZRD_AUTO_GATE         Set to 1 to compose TWZRD AutoGate after SpendControl (default off)
 
 For more info: https://blockrun.ai/clawrouter.md
 `);

package/dist/index.js

@@ -1270,6 +1270,14 @@ var init_models = __esm({
         id: "google/gemini-3.8-flash",
         name: "Gemini 3.8 Flash",
         version: "3.8",
+        // ⏰ PROMOTIONAL RATE, expires 2027-01-01. Google prices the whole 3.6/3.7/3.8
+        // Flash band at 0.75/3.75 only through 2026-12-31, reverting to 1.50/7.50
+        // (ai.google.dev/gemini-api/docs/pricing; blockrun's src/lib/models.ts carries
+        // the same dated note). These numbers are not decoration here: calculateModelCost
+        // feeds the maxCostPerRun projection and every `cost` in the usage journal, so
+        // leaving them at the promo rate past the reversion under-reports spend 2x and
+        // lets the cap run to twice its stated limit. Re-price this AND gemini-3.6-flash
+        // together — they revert on the same day.
         inputPrice: 0.75,
         outputPrice: 3.75,
         contextWindow: 1048576,
@@ -1281,6 +1289,8 @@ var init_models = __esm({
       {
         // Newest-generation Flash with built-in thinking mode (blockrun #329,
         // 2026-08-03). 17% cheaper output than 3.5 Flash.
+        // ⏰ Same promotional 0.75/3.75 as gemini-3.8-flash above, and the same
+        // 2027-01-01 reversion to 1.50/7.50 — re-price both together.
         id: "google/gemini-3.6-flash",
         name: "Gemini 3.6 Flash",
         version: "3.6",
@@ -60203,6 +60213,149 @@ var init_api_key = __esm({
   }
 });
 
+// src/twzrd-autogate.ts
+import { randomUUID } from "crypto";
+function normalizeFlag(value) {
+  const trimmed = value?.trim().toLowerCase();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function isTwzrdAutoGateEnabled(env = process.env) {
+  const auto = normalizeFlag(env.TWZRD_AUTO_GATE);
+  const gate = normalizeFlag(env.TWZRD_GATE_ENABLED);
+  if (auto !== void 0 && FALSY.has(auto) || gate !== void 0 && FALSY.has(gate)) {
+    return false;
+  }
+  return auto !== void 0 && TRUTHY.has(auto) || gate !== void 0 && TRUTHY.has(gate);
+}
+function isMissingTwzrdGateModule(err) {
+  const code = err?.code;
+  const msg = err instanceof Error ? err.message : String(err);
+  const missingModule = code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find module/i.test(msg) || /Cannot find package/i.test(msg);
+  return missingModule && new RegExp(String.raw`['"]${TWZRD_GATE_PACKAGE}['"]`).test(msg);
+}
+function twzrdGateTimeoutMs(env = process.env) {
+  const raw = normalizeFlag(env.TWZRD_GATE_TIMEOUT_MS);
+  if (raw === void 0) return TWZRD_GATE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : TWZRD_GATE_TIMEOUT_MS;
+}
+function twzrdGateFailOpen(env = process.env) {
+  const raw = normalizeFlag(env.TWZRD_FAIL_OPEN);
+  return !(raw !== void 0 && FALSY.has(raw));
+}
+function twzrdAutoGateInstallOptions(env = process.env, runId = randomUUID) {
+  return {
+    refuseWashFlagged: true,
+    gateOnCanSpend: false,
+    unsupportedNetworkMode: "observe",
+    failOpen: twzrdGateFailOpen(env),
+    attribution: {
+      integration: `clawrouter/${VERSION}`,
+      runId: runId()
+    }
+  };
+}
+async function runTwzrdGateWithTimeout(run, opts) {
+  const log = opts.log ?? console;
+  let timer2;
+  try {
+    const raced = await Promise.race([
+      // Swallow here, not at the race, so a late rejection never goes unhandled.
+      Promise.resolve().then(run).catch((err) => ({ __twzrdError: err })),
+      new Promise((resolve) => {
+        timer2 = setTimeout(() => resolve(TIMED_OUT), opts.timeoutMs);
+      })
+    ]);
+    if (raced === TIMED_OUT) {
+      return decideOnGateFailure(`did not answer within ${opts.timeoutMs}ms`, opts.failOpen, log);
+    }
+    if (raced && typeof raced === "object" && "__twzrdError" in raced) {
+      const err = raced.__twzrdError;
+      const msg = err instanceof Error ? err.message : String(err);
+      return decideOnGateFailure(`threw: ${msg.slice(0, 120)}`, opts.failOpen, log);
+    }
+    return raced;
+  } finally {
+    if (timer2) clearTimeout(timer2);
+  }
+}
+function decideOnGateFailure(what, failOpen, log) {
+  const reason = `twzrd gate ${what}`;
+  if (failOpen) {
+    log.warn(
+      `[ClawRouter] ${reason} \u2014 proceeding. SpendControl still applied. Set TWZRD_FAIL_OPEN=false to refuse instead.`
+    );
+    return void 0;
+  }
+  log.warn(`[ClawRouter] ${reason} \u2014 refusing the payment (TWZRD_FAIL_OPEN=false).`);
+  return { abort: true, reason };
+}
+async function defaultLoadTwzrdGate() {
+  const specifier = TWZRD_GATE_PACKAGE;
+  return import(specifier);
+}
+async function maybeComposeTwzrdAutoGate(x402, options) {
+  const env = options?.env ?? process.env;
+  const log = options?.log ?? console;
+  if (!isTwzrdAutoGateEnabled(env)) {
+    return { status: "skipped" };
+  }
+  const load = options?.loadGate ?? defaultLoadTwzrdGate;
+  let gate;
+  try {
+    gate = await load();
+  } catch (err) {
+    if (isMissingTwzrdGateModule(err)) {
+      const reason = `${TWZRD_GATE_PACKAGE} is not installed`;
+      log.warn(
+        `[ClawRouter] TWZRD AutoGate opted in but ${reason} \u2014 skipping. npm i ${TWZRD_GATE_PACKAGE}@0.9.3`
+      );
+      return { status: "unavailable", reason };
+    }
+    throw err;
+  }
+  const installOpts = twzrdAutoGateInstallOptions(env);
+  const timeoutMs = twzrdGateTimeoutMs(env);
+  const ready = (via) => log.log(
+    `[ClawRouter] TWZRD AutoGate ON (opt-in, after SpendControl, ${via}; ${timeoutMs}ms budget, failOpen=${installOpts.failOpen}). Unset TWZRD_AUTO_GATE to disable.`
+  );
+  if (typeof gate.createTwzrdBeforePaymentHook === "function") {
+    const hook = gate.createTwzrdBeforePaymentHook(installOpts);
+    x402.onBeforePaymentCreation(
+      async (ctx) => runTwzrdGateWithTimeout(() => hook(ctx.selectedRequirements, ctx), {
+        timeoutMs,
+        failOpen: installOpts.failOpen,
+        log
+      })
+    );
+    ready("createTwzrdBeforePaymentHook");
+    return { status: "composed", via: "createTwzrdBeforePaymentHook" };
+  }
+  if (typeof gate.installTwzrdAutoGate === "function") {
+    gate.installTwzrdAutoGate(x402, installOpts);
+    log.warn(
+      "[ClawRouter] TWZRD AutoGate installed via installTwzrdAutoGate \u2014 that entry point registers its own hook, so the timeout budget does not apply and it replaces onBeforePaymentCreation on this client. Prefer a gate build exporting createTwzrdBeforePaymentHook."
+    );
+    ready("installTwzrdAutoGate");
+    return { status: "composed", via: "installTwzrdAutoGate" };
+  }
+  throw new Error(
+    `[ClawRouter] ${TWZRD_GATE_PACKAGE} is installed but exports neither installTwzrdAutoGate nor createTwzrdBeforePaymentHook`
+  );
+}
+var TWZRD_GATE_PACKAGE, TRUTHY, FALSY, TWZRD_GATE_TIMEOUT_MS, TIMED_OUT;
+var init_twzrd_autogate = __esm({
+  "src/twzrd-autogate.ts"() {
+    "use strict";
+    init_version4();
+    TWZRD_GATE_PACKAGE = "twzrd-x402-gate";
+    TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+    FALSY = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+    TWZRD_GATE_TIMEOUT_MS = 2e3;
+    TIMED_OUT = { __twzrdTimedOut: true };
+  }
+});
+
 // src/compression/types.ts
 var DEFAULT_COMPRESSION_CONFIG;
 var init_types2 = __esm({
@@ -91787,6 +91940,7 @@ async function startProxy(options) {
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
     const spendControl = options.spendControl ?? getSharedSpendControl();
     registerSpendPolicyHook(x402, spendControl);
+    await maybeComposeTwzrdAutoGate(x402);
     registerExactEvmScheme(x402, { signer: evmSigner });
   }
   let solanaAddress;
@@ -95372,6 +95526,7 @@ var init_proxy = __esm({
     init_auth();
     init_api_key();
     init_spend_control();
+    init_twzrd_autogate();
     init_compression();
     init_errors5();
     init_version4();
@@ -228160,7 +228315,7 @@ import {
 } from "fs";
 import { readFile as readFileAsync } from "fs/promises";
 import { homedir as homedir14 } from "os";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { join as join17 } from "path";
 async function waitForProxyHealth(port, timeoutMs = 3e3) {
   const start = Date.now();
@@ -228175,7 +228330,7 @@ async function waitForProxyHealth(port, timeoutMs = 3e3) {
   return false;
 }
 function writePrivateJsonSync(path5, value) {
-  const temporary = `${path5}.tmp.${randomUUID()}`;
+  const temporary = `${path5}.tmp.${randomUUID2()}`;
   try {
     writeFileSync3(temporary, JSON.stringify(value, null, 2), { mode: 384 });
     renameSync2(temporary, path5);

package/docs/configuration.md

@@ -15,6 +15,7 @@ Complete reference for ClawRouter configuration options.
 - [Tier Overrides](#tier-overrides)
 - [Scoring Weights](#scoring-weights)
 - [Spend Control & Counterparty Policy](#spend-control--counterparty-policy)
+- [TWZRD AutoGate (opt-in)](#twzrd-autogate-opt-in)
 - [Testing Configuration](#testing-configuration)
 
 ---
@@ -32,6 +33,9 @@ Complete reference for ClawRouter configuration options.
 | `CLAWROUTER_WORKER`         | -                                     | Set to `1` to enable Worker Mode (earn USDC by running health checks).                                                                                      |
 | `CLAWROUTER_DEBUG_HEADERS`  | (on)                                  | Set to `off`/`false`/`0` to suppress the `x-clawrouter-*` debug response headers.                                                                           |
 | `BLOCKRUN_WEB_SEARCH`       | (auto-enabled)                        | Set to `off` to disable BlockRun's Exa web search provider registration.                                                                                    |
+| `TWZRD_AUTO_GATE`           | unset (off)                           | Set to `1` to compose TWZRD AutoGate after SpendControl on the x402 pre-sign hook. Also `TWZRD_GATE_ENABLED=true`.                                          |
+| `TWZRD_GATE_TIMEOUT_MS`     | `2000`                                | How long the gate may take to answer before the payment proceeds on its own. Only meaningful with the gate on.                                              |
+| `TWZRD_FAIL_OPEN`           | `true`                                | Set to `false` to refuse payments when the gate is unreachable instead of proceeding. Only meaningful with the gate on.                                     |
 
 ---
 
@@ -732,6 +736,66 @@ placement, `clawrouter doctor`'s probe) are not covered.
 
 ---
 
+## TWZRD AutoGate (opt-in)
+
+Default **off**. This is not a re-open of default-on vendor lock. SpendControl
+above remains the vendor-neutral path; TWZRD is composed only when you ask.
+
+```bash
+export TWZRD_AUTO_GATE=1
+# equivalent:
+export TWZRD_GATE_ENABLED=true
+```
+
+When set, `startProxy` registers the gate's `createTwzrdBeforePaymentHook` on the
+**same** x402 client, **after** `registerSpendPolicyHook`. SpendControl lists
+still run first. A wash `payTo` is refused before `signTransaction`.
+
+### What it actually covers
+
+**Solana, not Base.** The gate's reputation corpus is Solana. `classifyNetwork`
+returns `network_not_scored` for `base` / `eip155:*`, and under our
+`unsupportedNetworkMode: "observe"` those are waved through with verdict
+`unknown` and no network call. The x402 client is shared between both chains, so
+the hook is registered once and applies to Solana payments; `refuseWashFlagged`
+can only ever fire there.
+
+### What leaves your machine
+
+On a Solana payment the gate POSTs the resource URL, `payTo`, price and chain to
+`https://intel.twzrd.xyz/v1/intel/preflight`, stamped with
+`X-TWZRD-Integration: clawrouter/<version>` and a per-process run id. Nothing is
+sent when the flag is unset, and nothing is sent for Base.
+
+### Availability
+
+The gate's own preflight sets no timeout, and the package defaults to
+`failOpen: false` — an outage there would refuse every paid Solana call. That is
+the shape of the v0.12.271 outage, where an unreachable third party made every
+Solana payment fail with a bare `fetch failed`. So:
+
+- We bound the answer at `TWZRD_GATE_TIMEOUT_MS` (default `2000`).
+- We pass `failOpen: true`. On timeout, rejection, or outage the payment
+  proceeds and a warning names the reason. SpendControl still applies — it is
+  the vendor-neutral guarantee and is untouched by any of this.
+- `TWZRD_FAIL_OPEN=false` restores refuse-on-outage if you would rather stop
+  paying than pay unscored.
+
+### Other notes
+
+- Optional dependency: `twzrd-x402-gate@0.9.3`. Forks that omit it still install.
+- Missing gate package (`MODULE_NOT_FOUND` for `twzrd-x402-gate` itself): fail
+  open — proxy boots, payments unguarded by TWZRD. Any other load/install error
+  fails closed.
+- We register the hook ourselves rather than calling `installTwzrdAutoGate`,
+  which replaces `onBeforePaymentCreation` on the client — that would make every
+  hook registered afterwards skippable via `TWZRD_AUTO_GATE=0`, including ours.
+- Identity: preflight stamps `X-Twzrd-Caller: clawrouter/<version>` so a refuse
+  is attributable.
+- Unset the flag to return to SpendControl only.
+
+---
+
 ## Testing Configuration
 
 ### Dry Run (No Payments)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.276",
+  "version": "0.12.277",
   "description": "Smart LLM router — save 84% on inference costs. 76 models (7 free). Pay by credit card (API key) or USDC (x402 wallet).",
   "type": "module",
   "main": "dist/index.js",
@@ -106,6 +106,9 @@
     "undici": "^8.10.0",
     "viem": "^2.39.3"
   },
+  "optionalDependencies": {
+    "twzrd-x402-gate": "0.9.3"
+  },
   "peerDependencies": {
     "openclaw": ">=2025.1.0"
   },