@naulon/wayfarer-mcp 0.2.1 → 0.3.0

package/dist/server.js

@@ -37,8 +37,8 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { appraise, articleUrl, authorizeOrigin, buildPopProof, decodeHeld, DEFAULT_POLICY, discover, fetchJwks, fileHeldStore, gatewayBuyer, getWallet, isLive, memoBuyer, probe, probeFailure, quotedTotalAtomic, railBuyer, rereadWithLicense, run, selectBuyer, spendGate, tollgateBase, verifyAgainst, } from "@naulon/wayfarer";
-import { activeNetwork, getConfig, supportsMemo, usdc } from "@naulon/shared";
+import { appraise, articleUrl, authorizeOrigin, buildPopProof, decodeHeld, DEFAULT_POLICY, discover, fetchJwks, fileHeldStore, gatewayBuyer, getWallet, isLive, licenseIdentityFor, memoBuyer, payHostOf, probe, probeFailure, quotedTotalAtomic, railBuyer, rereadWithLicense, resolvedDiscoverySourceUrl, run, selectBuyer, spendGate, tollgateBase, verifyAgainst, } from "@naulon/wayfarer";
+import { activeNetwork, explorerTxUrl, FLEET_ORIGIN, getConfig, isFleetDefaultDiscovery, supportsMemo, usdc } from "@naulon/shared";
 import { cloudSignerFromEnv } from "./cloud-signer.js";
 export const SERVER_NAME = "naulon-wayfarer-mcp";
 /** Keep in step with this package's package.json `version` — it is what the MCP
@@ -61,6 +61,23 @@ function trueTotalUsdc(quoted) {
 function round6(usdcAmount) {
     return Math.round(usdcAmount * 1_000_000) / 1_000_000;
 }
+/** The settlement-network descriptor echoed on every spend envelope and on status —
+ *  the answer to "paid in WHAT, on WHICH chain, is it real money?" that used to be
+ *  absent from every tool result. `testnet:true` means no fiat value. */
+const networkOutputSchema = {
+    network: z.string().describe("CAIP-2 network id, e.g. eip155:5042002 (Arc Testnet) — the chain the toll settles on."),
+    chainId: z.number().describe("EVM chain id."),
+    chainName: z.string().describe("Human network name, e.g. arcTestnet / base."),
+    testnet: z.boolean().describe("TRUE = testnet play-money with NO fiat value (faucet-funded); FALSE = real-money mainnet. Report this honestly — never call a testnet toll 'real money'."),
+    token: z
+        .object({
+        symbol: z.string().describe("Settlement token symbol (USDC)."),
+        address: z.string().describe("ERC-20 token contract address on this chain."),
+        decimals: z.number().describe("Token decimals (6 for USDC)."),
+    })
+        .describe("The token every toll is paid in."),
+    explorer: z.string().optional().describe("Block-explorer origin for this chain when known — settlementRef is viewable at <explorer>/tx/<ref>. Omitted when no verified explorer exists for the chain."),
+};
 /** Lowercased host INCLUDING port — endpoint identity, used for the gate origin pin
  *  (a different port is a different service, so it must not satisfy the pin). */
 function hostOf(u) {
@@ -146,10 +163,24 @@ export function buildServer(opts = {}) {
     // (so it reflects deployment config), but `spentUsdc` accumulates across this
     // server instance's lifetime — one stdio/HTTP session = one budget envelope. The
     // model sees what remains and can plan within it; it can never raise the ceiling.
-    let spentUsdc = 0;
-    // Per-session pays per publisher host — the granular path's half of `perDomainCap` (decide()
-    // enforces it for naulon_research against its own run-scoped counts).
+    // Seeded from the caller's durable prior spend (cloud) so the running total survives a
+    // silent reconnect; 0 for the stdio funnel (one process is the whole session lifetime).
+    let spentUsdc = round6(opts.initialSpentUsdc ?? 0);
+    // Per-session pays per publisher host — the ONE `perDomainCap` counter shared by BOTH spending
+    // paths. naulon_pay_and_read increments it directly (below); naulon_research seeds decide()'s own
+    // per-host tally from it (`decideContext.priorDomainCounts`) before each run and increments it
+    // from that run's `pay` decisions afterward (B3) — so a cap hit through either tool carries to
+    // the other, for the life of this session. Never a second, run-scoped counter.
     const paidByHost = new Map();
+    // WP-2 T2: the distinct hostnames THIS session's most recent naulon_discover call
+    // actually returned. Fleet-default auto-trust for the GRANULAR pay path (naulon_quote /
+    // naulon_pay_and_read) is keyed off this — unlike naulon_research, which discovers
+    // INSIDE run() and derives its own allowDomains fresh each call (RunOptions.
+    // autoTrustDiscoveredDomains), these two tools receive a slug/url the model already
+    // has from an EARLIER naulon_discover call, so "this session's last discovery" is the
+    // only discovery signal available to them. Reset (not merged) on every naulon_discover
+    // call — a stale prior topic's hosts must not linger and widen the allowlist.
+    let lastDiscoveredHosts = [];
     // ── Spend lock ──────────────────────────────────────────────────────────────
     // The budget check and its debit are separated by network I/O (probe → sign → paid GET), and an
     // MCP client may issue tool calls CONCURRENTLY (a normal parallel tool_use block). Without
@@ -167,6 +198,9 @@ export function buildServer(opts = {}) {
     // Where a needs_topup / grant_expired refusal points the agent to fund/renew (default: the
     // portal wallet path). Server-config, resolved once — never a tool arg.
     const buyerWalletUrl = opts.buyerWalletUrl ?? "/buyer/wallet";
+    // WP-3a — resolved once, mirroring every other opt above. Absent/empty on every stdio/self-host
+    // caller (the unchanged default); the 4 guarded handlers below check this BEFORE anything else.
+    const hostedInertSteer = opts.hostedInertSteer;
     // Hosted-wallet opt-in (BUY-2): when the cloud env is configured, tolls are signed by naulon's
     // grant-checked /sign-memo BFF (the custody-free session key), so this process holds NO private
     // key. Unset ⇒ the OSS default (BYO BUYER_PRIVATE_KEY via selectBuyer). Server-config, not a tool
@@ -200,7 +234,26 @@ export function buildServer(opts = {}) {
     // This session's gate: the injected fleet tenant (BUY-4.2) wins over env TOLLGATE_URL.
     // A function so the env default stays fresh per call when no override is supplied.
     // Resolved server-side, never from a tool arg — the model can't aim a payment off it.
-    const gateBase = () => opts.tollgateUrl ?? tollgateBase();
+    //
+    // WP-2: there is NO universal fleet pay-gate (gate.naulon.app/articles/* → 502 — each
+    // publisher tolls at its own origin), so fleet-default zero-config deliberately leaves
+    // TOLLGATE_URL unset. `tollgateBase()` throws in that case (by design — a self-host with
+    // no gate configured at all is a real config error). So: an explicit TOLLGATE_URL (hosted
+    // override or env) always wins; absent that, fall back to FLEET_ORIGIN ONLY when discovery
+    // is the untouched fleet default (never for a self-hosted CATALOG_URL) — this is a
+    // placeholder identity for logging/JWKS/slug-fallback purposes only, since every fleet
+    // candidate carries its own real `url` (see isFleetDefaultDiscovery). Anything else
+    // (self-host with no gate at all) still throws, unchanged.
+    const gateBase = () => {
+        if (opts.tollgateUrl)
+            return opts.tollgateUrl;
+        const cfg = getConfig();
+        if (cfg.TOLLGATE_URL)
+            return cfg.TOLLGATE_URL;
+        if (isFleetDefaultDiscovery(cfg))
+            return FLEET_ORIGIN;
+        return tollgateBase();
+    };
     const slugUrl = (slug) => articleUrl(gateBase(), slug);
     // A non-gated quote must say WHY it isn't gated: a genuine free (2xx) read is very
     // different from a 404 (wrong path — usually the /essays/<slug> fallback missing a
@@ -238,13 +291,54 @@ export function buildServer(opts = {}) {
             killSwitch: cfg.WAYFARER_KILL_SWITCH,
         };
     };
+    // WP-2 T2 (corrected) — fleet-default auto-trust for the GRANULAR pay path (naulon_quote /
+    // naulon_pay_and_read). Unlike naulon_research (which discovers INSIDE run() and derives its
+    // own fresh allowDomains via RunOptions.autoTrustDiscoveredDomains), these tools act on a
+    // slug/url the model already holds from an EARLIER naulon_discover call in this session — so
+    // the fleet-default allowance here is keyed off `lastDiscoveredHosts` (that call's own
+    // hostnames), plus the gate's own host (L-OSS-3 — a slug-only target's resolved pay-URL lands
+    // on the gate host, and once allowDomains is stated the plain identity pin no longer covers
+    // it). Gated identically to isFleetDefaultDiscovery + no explicit WAYFARER_ALLOW_DOMAINS; an
+    // injected `opts.policy` or an explicit allowlist always wins (never overridden). Deliberately
+    // a no-op until `lastDiscoveredHosts` is non-empty (an ACTUAL naulon_discover call happened
+    // this session) — every fresh session (fleet-default is now the zero-config DEFAULT, so this
+    // is the common case) keeps the exact prior behavior (no allowDomains, plain gate-identity
+    // pin) until discovery actually occurs; stating an allowlist for no reason would silently swap
+    // the off-gate refusal from an identity-pin reason to an allowlist reason for every caller.
+    const policyForGranularPay = () => {
+        const base = policyFromConfig();
+        if (base.allowDomains)
+            return base;
+        if (!isFleetDefaultDiscovery(getConfig()) || lastDiscoveredHosts.length === 0)
+            return base;
+        const fleetAllow = [...new Set([hostnameOf(gateBase()) ?? undefined, ...lastDiscoveredHosts].filter((h) => !!h))];
+        return fleetAllow.length ? { ...base, allowDomains: fleetAllow } : base;
+    };
     const remainingUsdc = () => round6(Math.max(0, ceilingUsdc() - spentUsdc));
-    /** The session-budget fields every spend-aware tool echoes so the host LLM always
-     *  sees the live envelope alongside the tool's own result. */
+    /** The settlement network this session tolls on — the fact that was MISSING, so an
+     *  agent could not tell whether a paid read cost real money or testnet play-money
+     *  (it would report a testnet toll as "real USDC"). `testnet:true` = no fiat value.
+     *  Constant for the session (`SETTLEMENT_NETWORK`); echoed alongside every spend
+     *  envelope and on naulon_status. */
+    const networkInfo = () => {
+        const net = activeNetwork();
+        return {
+            network: net.network,
+            chainId: net.chainId,
+            chainName: net.chainName,
+            testnet: net.testnet,
+            token: { symbol: "USDC", address: net.usdc, decimals: 6 },
+            ...(net.explorer ? { explorer: net.explorer } : {}),
+        };
+    };
+    /** The session-budget + network fields every spend-aware tool echoes so the host LLM
+     *  always sees the live envelope — and what chain/token it is spending — alongside the
+     *  tool's own result. */
     const envelope = () => ({
         ceilingUsdc: round6(ceilingUsdc()),
         spentSessionUsdc: round6(spentUsdc),
         remainingUsdc: remainingUsdc(),
+        settlement: networkInfo(),
     });
     // BUY-4.4: hand each buyer decision to the injected audit sink (the cloud writes it to
     // its org audit plane). Best-effort — a misbehaving sink must never break a paid read,
@@ -267,7 +361,12 @@ export function buildServer(opts = {}) {
             "catalog endpoint — set RSS_URL, PUBLISHER_URL, or CATALOG_URL, or use the hosted endpoint). " +
             "Returns FREE public teasers only — slug, title, and summary — with no content and no payment. " +
             "Call this first to see what is available before appraising, quoting, or paying. If no source " +
-            "is configured it refuses with setup guidance rather than inventing sources.",
+            "is configured it refuses with setup guidance rather than inventing sources. " +
+            "A candidate may carry WHY it matched: `matchedInBody` means your terms are inside the paid " +
+            "text (strong — the teaser just does not show it), `matchedSemantic` means only that it is " +
+            "near your query in meaning and your terms are absent (weak — judge the teaser, and do not " +
+            "pay one that is off-topic). Discovery returns the best available matches, never a promise " +
+            "that any of them answers your question.",
         inputSchema: {
             topic: z.string().min(1).describe("The research topic to find candidate sources for."),
         },
@@ -283,21 +382,113 @@ export function buildServer(opts = {}) {
                     .describe("Canonical URL this source is served from (from the RSS <link> / catalog / directory). " +
                     "Pass it back to naulon_quote / naulon_pay_and_read so the toll targets the real link " +
                     "(e.g. /articles/<slug>) instead of a reconstructed /essays/<slug> path."),
+                // Why the source matched. A directory that searches article bodies sets exactly one of
+                // these; an RSS source sets neither (it does not search). They must be DECLARED here or
+                // the SDK strips them from structuredContent — which is what happened until 2026-08-03:
+                // the fleet directory had been sending matchedInBody since it gained body search, and no
+                // stdio buyer ever saw it. The hosted agent had the evidence; a self-host buyer did not.
+                matchedInBody: z
+                    .boolean()
+                    .optional()
+                    .describe("STRONG: your query's terms appear inside this source's full text, which the free " +
+                    "teaser may not show. A flag only — the body itself stays behind the toll."),
+                matchedSemantic: z
+                    .boolean()
+                    .optional()
+                    .describe("WEAK: this source is close to your query in meaning, but your terms do NOT appear " +
+                    "in it. Judge it on the title and teaser; a near-miss looks exactly like this."),
             }))
                 .describe("Free teasers; the agent has paid for nothing at this stage."),
+            refused: z
+                .boolean()
+                .optional()
+                .describe("True if the server refused to run discovery at all (e.g. a hosted ask-only mount) — see note. Never set alongside real candidates."),
+            note: z.string().optional().describe("Present when refused — explains why, and where to go instead."),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async ({ topic }) => {
+        // WP-3a — a hosted ask-only mount (WP-3c) is inert-but-honest for this tool: refuse BEFORE
+        // ever calling discover() (no config read, no network) rather than throwing a raw config
+        // error or fabricating candidates.
+        if (hostedInertSteer)
+            return structured({ candidates: [], refused: true, note: hostedInertSteer });
         const candidates = await discover(topic);
+        // WP-2 T2: remember THIS call's distinct hostnames (reset, not merged — a stale prior
+        // topic's hosts must not linger) for the granular pay path's fleet-default allowance
+        // (see policyForGranularPay). Never widens anything for a non-fleet-default deployment.
+        lastDiscoveredHosts = [
+            ...new Set(candidates.map((c) => (c.url ? hostnameOf(c.url) : null)).filter((h) => h !== null)),
+        ];
         return structured({ candidates });
     });
+    // ── naulon_status (free — the "run first" tool) ─────────────────────────────
+    server.registerTool("naulon_status", {
+        title: "Check wallet, discovery, and gate status",
+        description: "Run this FIRST, before anything else. Reports the buyer wallet address, where discovery " +
+            "is configured to look, and — plain-language — what to do next to get a paid read working " +
+            "(e.g. fund the wallet, or point discovery/the gate at your own publisher). Free, read-only, " +
+            "no network calls beyond resolving local config.",
+        inputSchema: {},
+        outputSchema: {
+            wallet: z.string().describe("The buyer wallet address (0x…40 hex) that pays every toll."),
+            tollgate: z
+                .string()
+                .optional()
+                .describe("The single configured pay-gate (TOLLGATE_URL), when self-hosting one. Absent for the fleet " +
+                "default — there is NO universal fleet pay-gate; each discovered publisher tolls at its own origin."),
+            discovery: z.string().describe("Where naulon_discover looks for candidates (RSS_URL > PUBLISHER_URL/rss.xml > CATALOG_URL)."),
+            ready: z.boolean().describe("True once a wallet address is resolvable — does NOT mean it is funded."),
+            nextStep: z.string().describe("Plain-language guidance for what to do next, given the current config."),
+            settlement: z
+                .object(networkOutputSchema)
+                .describe("The settlement chain + token this wallet tolls on. Read settlement.testnet FIRST: true ⇒ every spend is testnet play-money with no fiat value; false ⇒ real money."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        const cfg = getConfig();
+        // The address that ACTUALLY signs tolls — the injected session EOA on the hosted path, the env
+        // wallet on BYO-key. NOT `getWallet()`: on a custody-free deploy (no BUYER_PRIVATE_KEY, which is
+        // the correct hosted posture) that resolves to the throwaway MOCK dev key, whose private key is
+        // public. This tool is documented "run this FIRST" and its nextStep says "Fund this wallet (0x…)",
+        // so reporting the wrong address does not merely confuse — it directs a buyer to fund an address
+        // that never pays their tolls and that anyone can sweep. Prod 2026-08-03 reported
+        // 0xF0c9…a6F5 (the mock key) while every toll was signed by the session EOA.
+        const wallet = payerAddress();
+        const fleetDefault = isFleetDefaultDiscovery(cfg);
+        // Amendment (wp2-brief): never imply a single universal pay-gate exists for the fleet
+        // default — discovery is fleet-WIDE, but payment is authorized per-publisher (the trusted
+        // directory's own discovered domains, spendGate-capped — WP-2 T2), not one gate.
+        // The funding phrase is network-aware: a testnet gate is faucet-funded play-money, a
+        // mainnet gate is real USDC — never tell an operator to "fund with testnet USDC" on mainnet.
+        const net = activeNetwork();
+        const fundHint = net.testnet
+            ? `with testnet USDC (play-money, no fiat value) — e.g. faucet.circle.com/Arc-Testnet — or connect a token`
+            : `with real USDC on ${net.chainName} (mainnet — real money) — or connect a funded token`;
+        const nextStep = fleetDefault
+            ? `Fund this wallet (${wallet}) ${fundHint}. ` +
+                `Discovery is fleet-wide (the naulon directory); payment is authorized per-publisher for whatever it ` +
+                `discovers (each publisher's own toll, capped by your spend policy) — there is no single pay-gate to configure.`
+            : `Confirm your configured gate (TOLLGATE_URL${cfg.TOLLGATE_URL ? ` = ${cfg.TOLLGATE_URL}` : " is not set yet"}) ` +
+                `is reachable and that this wallet (${wallet}) is funded ${fundHint.replace(/ — .*$/, "")} to pay it.`;
+        return structured({
+            wallet,
+            ...(cfg.TOLLGATE_URL ? { tollgate: cfg.TOLLGATE_URL } : {}),
+            discovery: resolvedDiscoverySourceUrl(),
+            ready: Boolean(wallet),
+            nextStep,
+            settlement: networkInfo(),
+        });
+    });
     // ── naulon_appraise (free) ──────────────────────────────────────────────────
     server.registerTool("naulon_appraise", {
         title: "Appraise candidates for a topic",
         description: "Score how relevant each candidate is to the topic, from its free teaser alone — a 0..1 " +
             "relevance plus a one-line rationale. Pass the candidates you got from naulon_discover (or a " +
-            "curated subset). This is FREE and judges the teaser text only; it does not fetch or pay for " +
-            "any content. Use it to decide what is worth quoting and paying for.",
+            "curated subset), and pass them back WHOLE — `matchedInBody` / `matchedSemantic` tell the " +
+            "scorer WHY the search returned each one, and dropping them makes a body-matched source with " +
+            "a terse teaser look identical to a near-miss with a keyword-ish one. FREE: it reads the " +
+            "teaser and those flags, never paid content, and it fetches and pays for nothing. " +
+            "Use it to decide what is worth quoting and paying for.",
         inputSchema: {
             topic: z.string().min(1).describe("The research topic to score relevance against."),
             candidates: z
@@ -305,9 +496,21 @@ export function buildServer(opts = {}) {
                 slug: z.string(),
                 title: z.string(),
                 summary: z.string().describe("The free teaser to judge — title + summary, no paid content."),
+                // Declared for the same reason naulon_discover declares them on the way out: an
+                // undeclared key is stripped by schema validation. Without these two lines the
+                // evidence survives discovery and dies one tool later, and the scorer is back to
+                // judging a summary it was never safe to judge alone.
+                matchedInBody: z
+                    .boolean()
+                    .optional()
+                    .describe("From naulon_discover: the topic's words are inside this source's full text."),
+                matchedSemantic: z
+                    .boolean()
+                    .optional()
+                    .describe("From naulon_discover: near the topic in meaning only — its words are absent."),
             }))
                 .min(1)
-                .describe("Candidates to appraise (typically from naulon_discover)."),
+                .describe("Candidates to appraise — pass naulon_discover's rows through unmodified."),
         },
         outputSchema: {
             appraised: z.array(z.object({
@@ -319,8 +522,9 @@ export function buildServer(opts = {}) {
         },
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ topic, candidates }) => {
-        // Relevance is judged from the teaser text only — price plays no part, so we
-        // appraise with a zero price and drop it from the output.
+        // Price plays no part in relevance, so appraise at zero and drop it from the output. The
+        // spread carries the match-evidence flags through to the scorer — that is the point of
+        // declaring them above.
         const priced = candidates.map((c) => ({ ...c, price: usdc(0) }));
         const scored = await appraise(topic, priced);
         const appraised = scored.map((a) => ({
@@ -376,14 +580,22 @@ export function buildServer(opts = {}) {
             ceilingUsdc: z.number().describe("The server-configured spend ceiling for this session (cannot be raised from a tool)."),
             spentSessionUsdc: z.number().describe("Total already spent in this MCP session."),
             remainingUsdc: z.number().describe("Budget left for this session — plan spend within this."),
+            settlement: z.object(networkOutputSchema).describe("The chain + token this session settles on. Check settlement.testnet before reporting a spend as real money."),
             note: z.string().optional(),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async ({ slug, url }) => {
+        // WP-3a — a hosted ask-only mount is inert-but-honest for this tool: refuse BEFORE ever
+        // resolving gateBase() or probing, using the SAME refused/note shape the origin refusal
+        // below already returns.
+        if (hostedInertSteer)
+            return structured({ refused: true, note: hostedInertSteer, ...envelope() });
         const target = url ?? slugUrl(slug);
         // Origin + policy even on the free probe: an unauthorized url is an SSRF surface and would
-        // return an attacker-authored price/payTo the model might then act on.
-        const refusal = originRefusal(target, gateBase(), policyFromConfig());
+        // return an attacker-authored price/payTo the model might then act on. policyForGranularPay
+        // (WP-2 T2) is the SAME fleet-default allowance naulon_pay_and_read applies below, so a
+        // fleet-discovered publisher domain can be quoted, not just paid.
+        const refusal = originRefusal(target, gateBase(), policyForGranularPay());
         if (refusal) {
             // A refusal is neither payable nor free: signal refused (not gated:false, which the tool
             // contract defines as "free read — just fetch it" and a buyer would act on).
@@ -437,25 +649,40 @@ export function buildServer(opts = {}) {
             ok: z.boolean(),
             content: z.string().optional().describe("The paid-for content."),
             settlementRef: z.string().optional().describe("On-chain / settlement reference for the payment."),
+            explorerTxUrl: z.string().optional().describe("A clickable block-explorer link for settlementRef (<explorer>/tx/<ref>), when the chain has a known explorer. Cite this so a human can verify the on-chain settlement."),
             paidUsdc: z.number().optional().describe("The author leg paid, in USDC."),
             costUsdc: z.number().optional().describe("The true total debited from the session budget (author + any fee legs)."),
             licenseId: z.string().optional().describe("Citation License jti — cite this as proof of a paid read."),
             licenseVerified: z
                 .boolean()
                 .optional()
-                .describe("True/false if the license signature was checked against the gate's JWKS; omitted if JWKS unavailable."),
+                .describe("True/false if the license was checked against the gate's JWKS and canonical iss/aud identity; " +
+                "omitted if the JWKS or the gate's canonical identity is unavailable (never a fabricated match)."),
             ceilingUsdc: z.number().describe("The server-configured spend ceiling for this session."),
             spentSessionUsdc: z.number().describe("Total spent in this MCP session (after this call)."),
             remainingUsdc: z.number().describe("Budget left for this session (after this call)."),
+            settlement: z.object(networkOutputSchema).describe("The chain + token this toll settled on. If settlement.testnet is true the amount is play-money with no fiat value — report it as such."),
             error: z.string().optional(),
             errorCode: z
-                .enum(["not_gated", "not_found", "toll_moved", "insufficient_funds", "expired", "rejected", "origin_error", "needs_topup", "grant_expired"])
+                .enum([
+                "not_gated",
+                "not_found",
+                "toll_moved",
+                "insufficient_funds",
+                "expired",
+                "rejected",
+                "origin_error",
+                "needs_topup",
+                "grant_expired",
+                "settlement_ambiguous",
+                "payee_refused",
+            ])
                 .optional()
-                .describe("Typed failure reason when ok:false — lets you decide whether to retry. not_found = the probed URL 404'd (pass the canonical url; it is not a free read). needs_topup = the funding session is exhausted/unset — fund it at topUpUrl. grant_expired = the funding window lapsed (funds intact) — renew at topUpUrl."),
+                .describe("Typed failure reason when ok:false — lets you decide whether to retry. not_found = the probed URL 404'd (pass the canonical url; it is not a free read). needs_topup = the funding session is exhausted/unset — fund it at topUpUrl. grant_expired = the funding window lapsed (funds intact) — renew at topUpUrl. settlement_ambiguous = the payment-signature was sent and may have settled, but reading the response failed — do NOT blind-retry (a fresh pay could double-charge); verify via settlementRef or a held license first. payee_refused = the 402 named a payTo this server does not authorize for the origin — a spend-safety stop, nothing was paid; do NOT retry (the same 402 re-refuses)."),
             retryable: z
                 .boolean()
                 .optional()
-                .describe("True if re-quoting/retrying may succeed (toll moved, expired, rejected); false for a hard stop (insufficient funds, needs_topup, grant_expired — the wallet needs funding or renewal, not a retry)."),
+                .describe("True if re-quoting/retrying may succeed (toll moved, expired, rejected); false for a hard stop (insufficient funds, needs_topup, grant_expired — the wallet needs funding or renewal, not a retry; settlement_ambiguous — a retry could double-charge)."),
             topUpUrl: z
                 .string()
                 .optional()
@@ -466,179 +693,200 @@ export function buildServer(opts = {}) {
                 .describe("The toll (true total, USDC) this call could not cover — present on a needs_topup refusal so the operator knows how much the session is short."),
         },
         annotations: { readOnlyHint: false, openWorldHint: true, idempotentHint: false },
-    }, async ({ slug, url }) => withSpendLock(async () => {
-        // Quote first and gate on the SESSION BUDGET before any spend. The price is the
-        // buyer's true total across legs; refusing here is the budget ceiling (the
-        // on-chain insufficient-funds + toll-moved-at-pay tolerance are BUY-1.4).
-        // The canonical url (when the model passes it) is the pay target, verbatim — one
-        // buyer pays any publisher's URL shape (/articles/, custom domain) without a
-        // reconstructed /essays/ template. Absent, fall back to the template.
-        const target = url ?? slugUrl(slug);
-        // Endpoint identity first — refused targets are never even fetched, so an off-gate url
-        // costs nothing and reaches no attacker origin. Operator policy is applied below, once the
-        // toll is known (the approval threshold is price-dependent).
-        const policy = policyFromConfig();
-        const refusal = originRefusal(target, gateBase(), policy);
-        if (refusal) {
-            emitAudit({ slug, action: "skip", reason: refusal, agentId: policy.agentId });
-            return structured({ ok: false, error: refusal, errorCode: "rejected", retryable: false, ...envelope() });
-        }
-        const outcome = await probe(target, KIND, payerAddress());
-        if (outcome.status !== "gated") {
-            const failure = probeFailure(outcome, target);
-            emitAudit({
-                slug,
-                action: "skip",
-                reason: `not payable: ${failure.errorCode ?? "not_gated"} — ${failure.error ?? ""}`.trim(),
-                agentId: policyFromConfig().agentId,
-            });
-            return structured({
-                ok: false,
-                error: failure.error ?? "not gated — no payment is required.",
-                ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
-                ...(failure.retryable === undefined ? {} : { retryable: failure.retryable }),
-                ...envelope(),
-            });
-        }
-        const quoted = outcome.quoted;
-        const cost = round6(trueTotalUsdc(quoted));
-        // Operator policy — the ONE shared evaluator `decide()` uses, so this granular path and
-        // naulon_research enforce byte-identical rules (kill-switch, deny/allow, per-domain cap,
-        // approval threshold). `paidCount`/`remainingUsdc` are omitted: the session envelope below
-        // owns budget accounting with its own message, and maxPaid is a per-run planning cap.
-        const payHost = hostnameOf(target);
-        const verdict = spendGate({
-            host: payHost ?? undefined,
-            priceUsdc: cost,
-            policy,
-            paidForHost: payHost ? (paidByHost.get(payHost) ?? 0) : 0,
-        });
-        if (!verdict.ok) {
-            const reason = verdict.action === "approve"
-                ? `${verdict.reason} — NOT auto-paid. Nothing was spent.`
-                : `${verdict.reason} — nothing was spent.`;
-            emitAudit({ slug, action: verdict.action, reason, priceUsdc: quoted.priceUsdc, agentId: policy.agentId });
-            return structured({ ok: false, error: reason, errorCode: "rejected", retryable: false, ...envelope() });
+    }, async ({ slug, url }) => {
+        // WP-3a — a hosted ask-only mount is inert-but-honest for this tool: refuse BEFORE ever
+        // joining the spend lock or resolving gateBase(), using the SAME ok:false/errorCode shape
+        // the origin refusal below already returns. Nothing is spent.
+        if (hostedInertSteer) {
+            return structured({ ok: false, error: hostedInertSteer, errorCode: "rejected", retryable: false, ...envelope() });
         }
-        if (cost > remainingUsdc()) {
-            emitAudit({
-                slug,
-                action: "skip",
-                reason: `over budget: toll $${cost} exceeds $${remainingUsdc()} remaining (ceiling $${round6(ceilingUsdc())}) — nothing spent`,
-                priceUsdc: quoted.priceUsdc,
-                agentId: policyFromConfig().agentId,
+        return withSpendLock(async () => {
+            // Quote first and gate on the SESSION BUDGET before any spend. The price is the
+            // buyer's true total across legs; refusing here is the budget ceiling (the
+            // on-chain insufficient-funds + toll-moved-at-pay tolerance are BUY-1.4).
+            // The canonical url (when the model passes it) is the pay target, verbatim — one
+            // buyer pays any publisher's URL shape (/articles/, custom domain) without a
+            // reconstructed /essays/ template. Absent, fall back to the template.
+            const target = url ?? slugUrl(slug);
+            // Endpoint identity first — refused targets are never even fetched, so an off-gate url
+            // costs nothing and reaches no attacker origin. Operator policy is applied below, once the
+            // toll is known (the approval threshold is price-dependent). policyForGranularPay (WP-2 T2)
+            // folds in the fleet-default allowance (this session's last naulon_discover hosts) so a
+            // directory-discovered publisher domain is payable, not off-gate-skipped.
+            const policy = policyForGranularPay();
+            const refusal = originRefusal(target, gateBase(), policy);
+            if (refusal) {
+                emitAudit({ slug, action: "skip", reason: refusal, agentId: policy.agentId });
+                return structured({ ok: false, error: refusal, errorCode: "rejected", retryable: false, ...envelope() });
+            }
+            const outcome = await probe(target, KIND, payerAddress());
+            if (outcome.status !== "gated") {
+                const failure = probeFailure(outcome, target);
+                emitAudit({
+                    slug,
+                    action: "skip",
+                    reason: `not payable: ${failure.errorCode ?? "not_gated"} — ${failure.error ?? ""}`.trim(),
+                    agentId: policyFromConfig().agentId,
+                });
+                return structured({
+                    ok: false,
+                    error: failure.error ?? "not gated — no payment is required.",
+                    ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
+                    ...(failure.retryable === undefined ? {} : { retryable: failure.retryable }),
+                    ...envelope(),
+                });
+            }
+            const quoted = outcome.quoted;
+            const cost = round6(trueTotalUsdc(quoted));
+            // Operator policy — the ONE shared evaluator `decide()` uses, so this granular path and
+            // naulon_research enforce byte-identical rules IN THE SAME ORDER (kill-switch, deny/allow,
+            // per-domain cap, budget, approval threshold — decide.ts's order is load-bearing). `remainingUsdc`
+            // MUST be passed: decide()'s spendGate checks budget BEFORE the approval threshold, so omitting
+            // it here let a toll that was BOTH over budget and over the approval threshold fall through to
+            // the approval branch and misreport as "needs human approval" — implying approving it would let
+            // it proceed, which it would not (the toll is over budget regardless). `paidCount` (the maxPaid
+            // gate) stays omitted on purpose — maxPaid is a PER-RUN planning cap for naulon_research's own
+            // loop, not a session-wide cap on this granular tool; passing it would newly enforce a 5-pay
+            // ceiling across the whole MCP session, which nothing here asked for.
+            const payHost = hostnameOf(target);
+            const verdict = spendGate({
+                host: payHost ?? undefined,
+                priceUsdc: cost,
+                policy,
+                paidForHost: payHost ? (paidByHost.get(payHost) ?? 0) : 0,
+                remainingUsdc: remainingUsdc(),
             });
-            return structured({
-                ok: false,
-                error: `Toll is $${cost} but only $${remainingUsdc()} remains in the session budget ` +
-                    `($${round6(ceilingUsdc())} ceiling, $${round6(spentUsdc)} already spent). The ceiling is ` +
-                    `server-configured and cannot be raised from a tool. Nothing was spent.`,
-                ...envelope(),
+            if (!verdict.ok) {
+                const reason = verdict.action === "approve"
+                    ? `${verdict.reason} — NOT auto-paid. Nothing was spent.`
+                    : `${verdict.reason} — nothing was spent.`;
+                emitAudit({ slug, action: verdict.action, reason, priceUsdc: quoted.priceUsdc, agentId: policy.agentId });
+                return structured({ ok: false, error: reason, errorCode: "rejected", retryable: false, ...envelope() });
+            }
+            // NOTE: a redundant `cost > remainingUsdc()` re-check used to live here, AFTER spendGate. It is
+            // now unreachable by construction — spendGate is given the same `cost` and the same
+            // `remainingUsdc()` above, so if this line is reached the budget gate has already passed. Two
+            // implementations of one rule is exactly how the "misreports as approval" bug above happened;
+            // it is not re-introduced.
+            // Hosted path: sign each leg via the cloud session key. With BOTH rail signers (RAS-B mixed
+            // fleet) railBuyer picks the rail from the TENANT's advertised 402 — a gateway 402 signs the
+            // Circle envelope even under a memo-default fleet, and vice-versa. With a single injected signer
+            // (one-network host / stdio) keep the activeNetwork() branch: a memo-LESS network (Base + every
+            // Gateway chain) settles via gatewayBuyer, else memoBuyer. Neither reads BUYER_PRIVATE_KEY.
+            // Default: the BYO-key buyer selectBuyer() picks (which branches the same way for the env path).
+            const buyer = opts.railSigners
+                ? railBuyer(opts.railSigners)
+                : cloudSigner
+                    ? supportsMemo(activeNetwork())
+                        ? memoBuyer(cloudSigner)
+                        : gatewayBuyer(cloudSigner)
+                    : await selectBuyer();
+            await buyer.init();
+            // Re-quote at pay time and abort if the toll moved past the quote we gated the
+            // budget on (BUY-1.4 toll-moved guard). The buyer pays NOTHING if it has moved.
+            const result = await buyer.fetch(target, KIND, {
+                maxTotalAtomic: guardCeilingAtomic(quoted),
+                // Bind the fetched url so the cloud host can resolve the tenant + its owner-declared payees; the
+                // guard passes each leg's payTo through and refuses (payee_refused) any the host does not authorize.
+                ...(opts.authorizePayee ? { authorizePayee: (payTo) => opts.authorizePayee({ url: target, payTo }) } : {}),
             });
-        }
-        // Hosted path: sign each leg via the cloud session key. With BOTH rail signers (RAS-B mixed
-        // fleet) railBuyer picks the rail from the TENANT's advertised 402 — a gateway 402 signs the
-        // Circle envelope even under a memo-default fleet, and vice-versa. With a single injected signer
-        // (one-network host / stdio) keep the activeNetwork() branch: a memo-LESS network (Base + every
-        // Gateway chain) settles via gatewayBuyer, else memoBuyer. Neither reads BUYER_PRIVATE_KEY.
-        // Default: the BYO-key buyer selectBuyer() picks (which branches the same way for the env path).
-        const buyer = opts.railSigners
-            ? railBuyer(opts.railSigners)
-            : cloudSigner
-                ? supportsMemo(activeNetwork())
-                    ? memoBuyer(cloudSigner)
-                    : gatewayBuyer(cloudSigner)
-                : await selectBuyer();
-        await buyer.init();
-        // Re-quote at pay time and abort if the toll moved past the quote we gated the
-        // budget on (BUY-1.4 toll-moved guard). The buyer pays NOTHING if it has moved.
-        const result = await buyer.fetch(target, KIND, { maxTotalAtomic: guardCeilingAtomic(quoted) });
-        if (!result.ok) {
-            // A failed pay is an accountable non-spend: the agent decided to pay, the rail refused.
-            // Audit it as a skip carrying the typed failure so the org can see the attempt + cause.
+            if (!result.ok) {
+                // A failed pay is an accountable non-spend: the agent decided to pay, the rail refused.
+                // Audit it as a skip carrying the typed failure so the org can see the attempt + cause.
+                emitAudit({
+                    slug,
+                    action: "skip",
+                    reason: `payment failed: ${result.errorCode ?? result.error ?? "unknown"} — nothing spent`,
+                    priceUsdc: quoted.priceUsdc,
+                    agentId: policyFromConfig().agentId,
+                });
+                // A hosted session-signer refusal (needs_topup / grant_expired) is actionable, not a dead
+                // end: surface WHERE to fund/renew and HOW MUCH the toll was, so the agent points its
+                // operator at the fix instead of re-calling a pay that can only fail again.
+                const actionable = result.errorCode === "needs_topup" || result.errorCode === "grant_expired";
+                return structured({
+                    ok: false,
+                    error: result.error ?? "payment failed",
+                    ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+                    ...(result.retryable === undefined ? {} : { retryable: result.retryable }),
+                    ...(actionable ? { topUpUrl: buyerWalletUrl, requiredUsdc: cost } : {}),
+                    ...envelope(),
+                });
+            }
+            // Debit the true total the buyer ACTUALLY authorized (result.costUsdc, computed by the
+            // buyer from the quote it signed at pay time), falling back to our pre-pay `cost`. Using
+            // costUsdc closes the gap where a pay-time re-quote within tolerance paid more than the
+            // pre-pay quote we gated on — the ledger would otherwise understate real spend. result.paidUsdc
+            // is only the author leg, so it would under-count a fee'd toll against the budget.
+            spentUsdc = round6(spentUsdc + (result.costUsdc ?? cost));
+            if (payHost)
+                paidByHost.set(payHost, (paidByHost.get(payHost) ?? 0) + 1);
+            let licenseId;
+            let licenseVerified;
+            if (result.license) {
+                const decoded = decodeHeld(result.license);
+                if (decoded) {
+                    licenseId = decoded.jti;
+                    // BEST-EFFORT, exactly like emitAudit: the money has ALREADY moved by here. A hosted
+                    // store (DB/KV) that throws on a transient failure must never turn a successful paid
+                    // read into an error — that would lose the content + receipt the buyer just paid for
+                    // and push the agent to pay again. Persisting the license is a caching nicety; the
+                    // paid read is the product.
+                    try {
+                        const held = await heldStore.load();
+                        // Capture the url actually paid so a later read_held re-fetches THIS link
+                        // verbatim, not a reconstructed /essays/<slug> template that 404s off-shape.
+                        held.set(decoded.slug, { ...decoded, jws: result.license, url: target });
+                        await heldStore.save(held);
+                    }
+                    catch {
+                        /* swallow — a held-license persist failure must never fail an already-paid read */
+                    }
+                }
+                const jwks = await fetchJwks(gateBase());
+                // The canonical identity of the gate this read just settled into — derived from
+                // `target` (the paid url), never from the token's own claims (A4). Cosmetic/log
+                // field only: it does not gate the payment or the license persist above, both of
+                // which already happened by this point regardless of licenseVerified's value.
+                const identity = licenseIdentityFor(target);
+                if (jwks && identity)
+                    licenseVerified = verifyAgainst(result.license, jwks, { issuer: identity, audience: identity });
+            }
             emitAudit({
                 slug,
-                action: "skip",
-                reason: `payment failed: ${result.errorCode ?? result.error ?? "unknown"} — nothing spent`,
+                action: "pay",
+                reason: `paid $${round6(result.paidUsdc ?? 0)} (true total $${cost})`,
                 priceUsdc: quoted.priceUsdc,
+                paidUsdc: result.paidUsdc,
+                costUsdc: cost,
+                ...(result.settlementRef ? { settlementRef: result.settlementRef } : {}),
+                ...(licenseId ? { licenseId } : {}),
                 agentId: policyFromConfig().agentId,
             });
-            // A hosted session-signer refusal (needs_topup / grant_expired) is actionable, not a dead
-            // end: surface WHERE to fund/renew and HOW MUCH the toll was, so the agent points its
-            // operator at the fix instead of re-calling a pay that can only fail again.
-            const actionable = result.errorCode === "needs_topup" || result.errorCode === "grant_expired";
+            const explorerUrl = explorerTxUrl(activeNetwork(), result.settlementRef);
             return structured({
-                ok: false,
-                error: result.error ?? "payment failed",
-                ...(result.errorCode ? { errorCode: result.errorCode } : {}),
-                ...(result.retryable === undefined ? {} : { retryable: result.retryable }),
-                ...(actionable ? { topUpUrl: buyerWalletUrl, requiredUsdc: cost } : {}),
+                ok: true,
+                content: result.content,
+                settlementRef: result.settlementRef,
+                ...(explorerUrl ? { explorerTxUrl: explorerUrl } : {}),
+                paidUsdc: result.paidUsdc,
+                // Report the total ACTUALLY authorized (what the budget was debited), not the pre-pay quote.
+                costUsdc: result.costUsdc ?? cost,
+                ...(licenseId ? { licenseId } : {}),
+                ...(licenseVerified === undefined ? {} : { licenseVerified }),
                 ...envelope(),
             });
-        }
-        // Debit the true total the buyer ACTUALLY authorized (result.costUsdc, computed by the
-        // buyer from the quote it signed at pay time), falling back to our pre-pay `cost`. Using
-        // costUsdc closes the gap where a pay-time re-quote within tolerance paid more than the
-        // pre-pay quote we gated on — the ledger would otherwise understate real spend. result.paidUsdc
-        // is only the author leg, so it would under-count a fee'd toll against the budget.
-        spentUsdc = round6(spentUsdc + (result.costUsdc ?? cost));
-        if (payHost)
-            paidByHost.set(payHost, (paidByHost.get(payHost) ?? 0) + 1);
-        let licenseId;
-        let licenseVerified;
-        if (result.license) {
-            const decoded = decodeHeld(result.license);
-            if (decoded) {
-                licenseId = decoded.jti;
-                // BEST-EFFORT, exactly like emitAudit: the money has ALREADY moved by here. A hosted
-                // store (DB/KV) that throws on a transient failure must never turn a successful paid
-                // read into an error — that would lose the content + receipt the buyer just paid for
-                // and push the agent to pay again. Persisting the license is a caching nicety; the
-                // paid read is the product.
-                try {
-                    const held = await heldStore.load();
-                    // Capture the url actually paid so a later read_held re-fetches THIS link
-                    // verbatim, not a reconstructed /essays/<slug> template that 404s off-shape.
-                    held.set(decoded.slug, { ...decoded, jws: result.license, url: target });
-                    await heldStore.save(held);
-                }
-                catch {
-                    /* swallow — a held-license persist failure must never fail an already-paid read */
-                }
-            }
-            const jwks = await fetchJwks(gateBase());
-            if (jwks)
-                licenseVerified = verifyAgainst(result.license, jwks);
-        }
-        emitAudit({
-            slug,
-            action: "pay",
-            reason: `paid $${round6(result.paidUsdc ?? 0)} (true total $${cost})`,
-            priceUsdc: quoted.priceUsdc,
-            paidUsdc: result.paidUsdc,
-            costUsdc: cost,
-            ...(result.settlementRef ? { settlementRef: result.settlementRef } : {}),
-            ...(licenseId ? { licenseId } : {}),
-            agentId: policyFromConfig().agentId,
         });
-        return structured({
-            ok: true,
-            content: result.content,
-            settlementRef: result.settlementRef,
-            paidUsdc: result.paidUsdc,
-            // Report the total ACTUALLY authorized (what the budget was debited), not the pre-pay quote.
-            costUsdc: result.costUsdc ?? cost,
-            ...(licenseId ? { licenseId } : {}),
-            ...(licenseVerified === undefined ? {} : { licenseVerified }),
-            ...envelope(),
-        });
-    }));
+    });
     // ── naulon_read_held (free) ──────────────────────────────────────────────────
     server.registerTool("naulon_read_held", {
         title: "Re-read a source you already licensed (free)",
         description: "Re-read a source you previously paid for, FREE, using the held Citation License — no second " +
             "payment. If the license is holder-of-key bound, a fresh wallet proof-of-possession is signed " +
-            "automatically. Returns ok:false (telling you to pay) if no live license is held for the slug.",
+            "automatically. Returns ok:false (telling you to pay) if no live license is held for the slug. " +
+            "A citation must always carry a LIVE license (jti): when the held one has expired this returns " +
+            "ok:false — re-read here to re-verify, or pay again. Any locally-cached copy of earlier content " +
+            "is your own continuity only; it carries no live license and must never be cited as a paid read.",
         inputSchema: {
             slug: z.string().min(1).describe("Source slug you previously paid for with naulon_pay_and_read."),
         },
@@ -706,6 +954,7 @@ export function buildServer(opts = {}) {
             spent: z.number().describe("Total actually spent on this run, in USDC."),
             spentSessionUsdc: z.number().describe("Total spent across the whole MCP session (after this run)."),
             remainingUsdc: z.number().describe("Budget left for this session (after this run)."),
+            settlement: z.object(networkOutputSchema).describe("The chain + token these tolls settled on. settlement.testnet true ⇒ play-money with no fiat value."),
             answer: z.string().describe("The grounded answer, citing the paid sources."),
             decisions: z.array(z.object({
                 slug: z.string(),
@@ -726,81 +975,141 @@ export function buildServer(opts = {}) {
             log: z.array(z.string()).describe("The auditable, human-readable decision log for the run."),
         },
         annotations: { readOnlyHint: false, openWorldHint: true, idempotentHint: false },
-    }, async ({ topic, budgetUsdc }) => withSpendLock(async () => {
-        const log = [];
-        // Clamp the requested budget to what the session has left: the model can spend
-        // less than the ceiling, never more. Passing the clamp into run() overrides its
-        // config ceiling for this run only.
-        const effective = round6(Math.min(budgetUsdc ?? ceilingUsdc(), remainingUsdc()));
-        const result = await run(topic, (line) => log.push(line), {
-            budgetUsdc: effective,
-            policy: policyFromConfig(),
-            ...(opts.tollgateUrl ? { tollgateUrl: opts.tollgateUrl } : {}),
-            // Hosted path: pay from the buyer's custody-free session wallet, not the env key
-            // (mirrors naulon_pay_and_read). Both rail signers win — run() then rail-picks PER-402
-            // (mixed fleet), same as the pay_and_read buyer above; a single cloud signer keeps the
-            // fleet-global routing. Absent ⇒ run() falls back to selectBuyer().
-            ...(opts.railSigners
-                ? { railSigners: opts.railSigners }
-                : cloudSigner
-                    ? { signer: cloudSigner }
-                    : {}),
-            // Same per-session isolation + PoP identity for the composite loop's held re-reads.
-            ...(opts.heldStore ? { heldStore: opts.heldStore } : {}),
-            ...(opts.popWallet ? { popWallet: opts.popWallet } : {}),
-        });
-        spentUsdc = round6(spentUsdc + result.spent);
-        // BUY-4.4: audit each decision the run made. run() owns the decide()/pay loop
-        // internally, so we replay its decisions here post-run — enriching a `pay` with the
-        // settlement detail from the matching cited source. agentId is a policy tag (audit
-        // attribution), read once for the whole run.
-        const sourceBySlug = new Map(result.sources.map((s) => [s.slug, s]));
-        const runAgentId = policyFromConfig().agentId;
-        for (const d of result.decisions) {
-            const src = d.action === "pay" ? sourceBySlug.get(d.slug) : undefined;
-            emitAudit({
-                slug: d.slug,
-                action: d.action,
-                reason: d.reason,
-                relevance: d.relevance,
-                priceUsdc: d.price,
-                ...(src
-                    ? {
-                        paidUsdc: src.paidUsdc,
-                        ...(src.settlementRef ? { settlementRef: src.settlementRef } : {}),
-                        ...(src.licenseId ? { licenseId: src.licenseId } : {}),
-                    }
-                    : {}),
-                ...(runAgentId ? { agentId: runAgentId } : {}),
+    }, async ({ topic, budgetUsdc }) => {
+        // WP-3a — a hosted ask-only mount is inert-but-honest for this tool: refuse BEFORE ever
+        // joining the spend lock, calling discover(), or resolving gateBase() inside run(). This
+        // tool's outputSchema has no dedicated ok/error field, so the refusal is carried in the
+        // SAME already-required fields every real run reports (answer, log) — zero spend, zero
+        // decisions, nothing invented.
+        if (hostedInertSteer) {
+            return structured({
+                topic,
+                budget: 0,
+                spent: 0,
+                ...envelope(),
+                answer: hostedInertSteer,
+                decisions: [],
+                sources: [],
+                log: [hostedInertSteer],
             });
         }
-        const wasClamped = budgetUsdc !== undefined && effective < budgetUsdc;
-        return structured({
-            topic: result.topic,
-            budget: round6(result.budget),
-            ...(wasClamped ? { requestedBudgetUsdc: budgetUsdc } : {}),
-            spent: round6(result.spent),
-            ...envelope(),
-            answer: result.answer,
-            decisions: result.decisions.map((d) => ({
-                slug: d.slug,
-                title: d.title,
-                action: d.action,
-                reason: d.reason,
-                relevance: d.relevance,
-                price: d.price,
-            })),
-            sources: result.sources.map((s) => ({
-                slug: s.slug,
-                title: s.title,
-                content: s.content,
-                paidUsdc: s.paidUsdc,
-                ...(s.settlementRef ? { settlementRef: s.settlementRef } : {}),
-                ...(s.licenseId ? { licenseId: s.licenseId } : {}),
-            })),
-            log,
+        return withSpendLock(async () => {
+            const log = [];
+            // Clamp the requested budget to what the session has left: the model can spend
+            // less than the ceiling, never more. Passing the clamp into run() overrides its
+            // config ceiling for this run only.
+            const effective = round6(Math.min(budgetUsdc ?? ceilingUsdc(), remainingUsdc()));
+            const cfg = getConfig();
+            const result = await run(topic, (line) => log.push(line), {
+                budgetUsdc: effective,
+                policy: policyFromConfig(),
+                // Same per-payment payee authority as naulon_pay_and_read: run() binds each candidate's url and
+                // refuses (skips) a leg paying a payTo the host does not authorize. Absent ⇒ no payee check.
+                ...(opts.authorizePayee ? { authorizePayee: opts.authorizePayee } : {}),
+                // B3: seed decide()'s per-host tally from the SAME session `paidByHost` the granular
+                // naulon_pay_and_read path maintains (declared once above), so a perDomainCap already hit
+                // via pay_and_read carries into this run instead of decide() starting every call at 0.
+                // One counter for the whole session — never a second, run-scoped one.
+                decideContext: { priorDomainCounts: Object.fromEntries(paidByHost) },
+                // gateBase() (not opts.tollgateUrl directly): resolves the injected per-session override,
+                // else env TOLLGATE_URL, else — ONLY for fleet-default discovery — FLEET_ORIGIN, so run()
+                // never crashes on an eagerly-evaluated tollgateBase() call when the fleet's zero-config
+                // path deliberately leaves TOLLGATE_URL unset (there is no universal fleet pay-gate).
+                tollgateUrl: gateBase(),
+                // WP-2 T2 (corrected — see oss-fix-architecture.md §G6): discovery happens INSIDE run(),
+                // so this server can only pass the INTENT, not candidates, to policyFromConfig. run()
+                // itself derives the effective allowDomains from ITS OWN discovery when this is true. Gated
+                // exactly like policyForGranularPay: fleet-default discovery AND no operator-stated
+                // WAYFARER_ALLOW_DOMAINS — a self-hosted CATALOG_URL is never auto-trusted.
+                autoTrustDiscoveredDomains: isFleetDefaultDiscovery(cfg) && !cfg.WAYFARER_ALLOW_DOMAINS,
+                // Hosted path: pay from the buyer's custody-free session wallet, not the env key
+                // (mirrors naulon_pay_and_read). Both rail signers win — run() then rail-picks PER-402
+                // (mixed fleet), same as the pay_and_read buyer above; a single cloud signer keeps the
+                // fleet-global routing. Absent ⇒ run() falls back to selectBuyer().
+                ...(opts.railSigners
+                    ? { railSigners: opts.railSigners }
+                    : cloudSigner
+                        ? { signer: cloudSigner }
+                        : {}),
+                // Same per-session isolation + PoP identity for the composite loop's held re-reads.
+                ...(opts.heldStore ? { heldStore: opts.heldStore } : {}),
+                ...(opts.popWallet ? { popWallet: opts.popWallet } : {}),
+            });
+            spentUsdc = round6(spentUsdc + result.spent);
+            // `result.decisions` is decide()'s PLAN, filled in BEFORE the obtain loop runs the actual
+            // pays — a "pay" decision whose buyer.fetch() then fails (rejected, insufficient funds,
+            // toll-moved, settlement_ambiguous, …) never gets its `action` revised, so counting it here
+            // would burn the session per-domain cap for a read that never settled and $0 spent (B3
+            // follow-up). `result.sources` is the outcome, not the plan: agent.ts only pushes a Source
+            // for a "pay" decision AFTER `buyer.fetch()` resolves `ok: true` (see agent.ts's obtain
+            // loop) — a failed pay `continue`s without ever reaching that push. So a slug present here
+            // under a "pay" decision is, by construction, a CONFIRMED settlement, never a free "cache"
+            // re-read (those are pushed under `d.action === "cache"`, filtered out below) and never a
+            // failed attempt. Built BEFORE the increment loop so both loops below share the one Map.
+            const sourceBySlug = new Map(result.sources.map((s) => [s.slug, s]));
+            // B3: fold this run's actual SETTLED pays back into the session counter, resolving each
+            // host via the SAME `payHostOf` decide() itself counts by (never `Decision.url` blindly,
+            // never a second resolver) — so a later naulon_pay_and_read or naulon_research call in this
+            // session sees them too. Gated on `sourceBySlug.has(d.slug)` (confirmed settlement), not
+            // merely `d.action === "pay"` (the plan) — a pay that never settled must never burn the cap.
+            for (const d of result.decisions) {
+                if (d.action !== "pay" || !sourceBySlug.has(d.slug))
+                    continue;
+                const host = payHostOf(d.url, gateBase(), d.slug);
+                if (host)
+                    paidByHost.set(host, (paidByHost.get(host) ?? 0) + 1);
+            }
+            // BUY-4.4: audit each decision the run made. run() owns the decide()/pay loop
+            // internally, so we replay its decisions here post-run — enriching a `pay` with the
+            // settlement detail from the matching cited source. agentId is a policy tag (audit
+            // attribution), read once for the whole run.
+            const runAgentId = policyFromConfig().agentId;
+            for (const d of result.decisions) {
+                const src = d.action === "pay" ? sourceBySlug.get(d.slug) : undefined;
+                emitAudit({
+                    slug: d.slug,
+                    action: d.action,
+                    reason: d.reason,
+                    relevance: d.relevance,
+                    priceUsdc: d.price,
+                    ...(src
+                        ? {
+                            paidUsdc: src.paidUsdc,
+                            ...(src.settlementRef ? { settlementRef: src.settlementRef } : {}),
+                            ...(src.licenseId ? { licenseId: src.licenseId } : {}),
+                        }
+                        : {}),
+                    ...(runAgentId ? { agentId: runAgentId } : {}),
+                });
+            }
+            const wasClamped = budgetUsdc !== undefined && effective < budgetUsdc;
+            return structured({
+                topic: result.topic,
+                budget: round6(result.budget),
+                ...(wasClamped ? { requestedBudgetUsdc: budgetUsdc } : {}),
+                spent: round6(result.spent),
+                ...envelope(),
+                answer: result.answer,
+                decisions: result.decisions.map((d) => ({
+                    slug: d.slug,
+                    title: d.title,
+                    action: d.action,
+                    reason: d.reason,
+                    relevance: d.relevance,
+                    price: d.price,
+                })),
+                sources: result.sources.map((s) => ({
+                    slug: s.slug,
+                    title: s.title,
+                    content: s.content,
+                    paidUsdc: s.paidUsdc,
+                    ...(s.settlementRef ? { settlementRef: s.settlementRef } : {}),
+                    ...(s.licenseId ? { licenseId: s.licenseId } : {}),
+                })),
+                log,
+            });
         });
-    }));
+    });
     // ── Prompts (cross-client slash commands) ───────────────────────────────────
     // MCP prompts are the client-agnostic UX layer: any prompts-capable host (Claude
     // Code / Desktop as `/mcp__<server>__<name>`, Cursor, VS Code, Cline, …) surfaces
@@ -809,6 +1118,18 @@ export function buildServer(opts = {}) {
     // loop); the cloud layers its own `naulon_ask` prompt where that tool lives. Each
     // returns a single user message that steers the host model through the tools; the
     // model still sees every price and spends only when a paying tool is called.
+    //
+    // WP-2 T4 — self-healing: before this, a discovery dead-end (no source configured, or an
+    // empty/failing result) left the model either stuck or — worse — printing a raw env-var name
+    // ("set RSS_URL") at a non-technical user who has no idea what that means. Every prompt now
+    // appends the SAME recovery instruction: on empty/failed discovery, call naulon_status and
+    // relay its plain-language `nextStep` (fund the wallet it shows, or connect a token), then
+    // offer to retry. One shared instruction, not three drifting copies.
+    const SELF_HEAL_PROMPT_TAIL = `\n\nIf naulon_discover comes back empty, or any tool call fails, call naulon_status and relay ` +
+        `its "nextStep" guidance in your own plain language (e.g. fund the wallet address it shows, or ` +
+        `connect a token) — never print a raw environment-variable name to the user. Then offer to retry. ` +
+        `If you fall back to your own general knowledge instead of a naulon-tolled source, say so ` +
+        `explicitly and label it clearly as NOT naulon-cited.`;
     server.registerPrompt("research", {
         title: "Research a topic (naulon)",
         description: "Discover naulon-tolled sources for a topic, see prices before paying, then return a grounded, cited answer within budget.",
@@ -823,7 +1144,8 @@ export function buildServer(opts = {}) {
                         `1. Call naulon_discover("${topic}") — free — to list candidate essays.\n` +
                         `2. Use naulon_appraise and naulon_quote to judge relevance and see exact prices. Nothing is spent until a paying tool runs.\n` +
                         `3. Pay only the most relevant sources with naulon_pay_and_read, or call naulon_research to run the whole discover→quote→pay→ground loop within the session budget.\n\n` +
-                        `Return a grounded answer with numbered citations and report exactly what was spent. Distinguish naulon-cited evidence from your own general knowledge.`,
+                        `Return a grounded answer with numbered citations and report exactly what was spent. Distinguish naulon-cited evidence from your own general knowledge.` +
+                        SELF_HEAL_PROMPT_TAIL,
                 },
             },
         ],
@@ -839,7 +1161,8 @@ export function buildServer(opts = {}) {
                 content: {
                     type: "text",
                     text: `Call naulon_discover("${topic}") and present the candidate essays as a ranked list — title, one-line summary, teaser price, and citation price. ` +
-                        `This is FREE: do not pay for anything. If a grounded answer is wanted next, use the "research" prompt or naulon_research.`,
+                        `This is FREE: do not pay for anything. If a grounded answer is wanted next, use the "research" prompt or naulon_research.` +
+                        SELF_HEAL_PROMPT_TAIL,
                 },
             },
         ],
@@ -857,7 +1180,8 @@ export function buildServer(opts = {}) {
                     text: `Fact-check the claim: "${claim}".\n\n` +
                         `Use naulon_discover to find relevant tolled sources, then naulon_appraise / naulon_quote (free) to see relevance and price. ` +
                         `Only if grounding needs it, pay the most relevant sources with naulon_pay_and_read (or run naulon_research) within budget.\n\n` +
-                        `State whether the claim is SUPPORTED, REFUTED, or UNVERIFIABLE, cite the paid sources by title, and report the spend. Keep naulon-cited evidence separate from your own general knowledge.`,
+                        `State whether the claim is SUPPORTED, REFUTED, or UNVERIFIABLE, cite the paid sources by title, and report the spend. Keep naulon-cited evidence separate from your own general knowledge.` +
+                        SELF_HEAL_PROMPT_TAIL,
                 },
             },
         ],