@antseed/node 0.2.25 → 0.2.27

package/dist/node.js

@@ -1,9 +1,10 @@
 import { EventEmitter } from "node:events";
 import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadOrCreateIdentity } from "./p2p/identity.js";
-import { ANTSEED_STREAMING_RESPONSE_HEADER, } from "./types/http.js";
+import { ANTSEED_STREAMING_RESPONSE_HEADER, ANTSEED_SPENDING_AUTH_HEADER, } from "./types/http.js";
 import { MeteringStorage } from "./metering/storage.js";
 import { ReceiptGenerator } from "./metering/receipt-generator.js";
 import { ConnectionState } from "./types/connection.js";
@@ -20,13 +21,58 @@ import { KeepaliveManager, buildPongPayload } from "./p2p/keepalive.js";
 import { MessageType } from "./types/protocol.js";
 import { NatTraversal } from "./p2p/nat-traversal.js";
 import { signUtf8Ed25519 } from "./p2p/identity.js";
-import { verifyMessage, getBytes } from "ethers";
-import { BalanceManager, BaseEscrowClient, identityToEvmWallet, buildLockMessageHash, buildReceiptMessage, buildAckMessage, signMessageEd25519, verifyMessageEd25519, } from "./payments/index.js";
-import { hexToBytes, bytesToHex } from "./utils/hex.js";
+// verifyMessage/getBytes removed — no longer needed after SpendingAuth refactor
+import { BalanceManager, BaseEscrowClient, SessionStore, } from "./payments/index.js";
+import { parseJsonObject, extractUsage } from "@antseed/api-adapter";
 import { debugLog, debugWarn } from "./utils/debug.js";
 import { parsePublicAddress } from "./discovery/public-address.js";
 import { BuyerPaymentManager } from "./payments/buyer-payment-manager.js";
+import { SellerPaymentManager } from "./payments/seller-payment-manager.js";
 import { identityToEvmAddress } from "./payments/evm/keypair.js";
+import { IdentityClient } from "./payments/evm/identity-client.js";
+import { verifyReputation } from "./discovery/reputation-verifier.js";
+/**
+ * Extract actual token usage from an LLM provider response body.
+ * Handles both JSON and SSE (streaming) responses. Returns zeros
+ * if usage data is not found (caller should fall back to estimation).
+ */
+function parseResponseUsage(body) {
+    const parsed = parseJsonObject(body);
+    if (parsed) {
+        return extractUsage(parsed);
+    }
+    // SSE streaming: scan data lines for a usage object
+    const text = new TextDecoder().decode(body);
+    let inputTokens = 0;
+    let outputTokens = 0;
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('data:'))
+            continue;
+        const payload = trimmed.slice(5).trim();
+        if (!payload || payload === '[DONE]')
+            continue;
+        try {
+            const event = JSON.parse(payload);
+            const usage = extractUsage(event);
+            if (usage.inputTokens > 0)
+                inputTokens = Math.max(inputTokens, usage.inputTokens);
+            if (usage.outputTokens > 0)
+                outputTokens = Math.max(outputTokens, usage.outputTokens);
+        }
+        catch { /* skip non-JSON lines */ }
+    }
+    return { inputTokens, outputTokens };
+}
+function parsePaymentRequiredBody(body) {
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(body));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 export class AntseedNode extends EventEmitter {
     static _METADATA_REFRESH_DEBOUNCE_MS = 200;
     _config;
@@ -46,6 +92,7 @@ export class AntseedNode extends EventEmitter {
     _receiptGenerator = null;
     _balanceManager = null;
     _escrowClient = null;
+    _identityClient = null;
     _paymentMuxes = new Map();
     _providerLoadCounts = new Map();
     _metadataRefreshTimer = null;
@@ -54,8 +101,23 @@ export class AntseedNode extends EventEmitter {
     _settlementTimers = new Map();
     /** Buyer-side payment manager (initialized when buyer has payment config). */
     _buyerPaymentManager = null;
-    /** Tracks which seller peers the buyer has already initiated a lock for. */
+    /** Seller-side payment manager (initialized when seller has payment config). */
+    _sellerPaymentManager = null;
+    /** Shared session store for payment persistence. */
+    _sessionStore = null;
+    /** Periodic timeout checker interval. */
+    _timeoutCheckerInterval = null;
+    /** Tracks which seller peers the buyer has already negotiated payment for. */
     _buyerLockedPeers = new Set();
+    /** Pending PaymentRequired payloads from sellers, keyed by peerId. Resolvers waiting for them. */
+    _pendingPaymentRequired = new Map();
+    _manualApprovalCache = null;
+    /** Buffered PaymentRequired that arrived before _doNegotiatePayment registered its listener.
+     *  This handles the race where 402 + PaymentRequired arrive in the same I/O tick. */
+    _bufferedPaymentRequired = new Map();
+    /** Per-peer mutex to prevent concurrent payment negotiations. */
+    _paymentNegotiationLocks = new Map();
+    /** Peers the caller has manually approved by retrying after a 402. */
     constructor(config) {
         super();
         this._config = config;
@@ -108,10 +170,6 @@ export class AntseedNode extends EventEmitter {
                 totalTokens: session.totalTokens,
                 avgLatencyMs: session.totalRequests > 0 ? session.totalLatencyMs / session.totalRequests : 0,
                 settling: Boolean(session.settling),
-                lockCommitted: session.lockCommitted,
-                lockedAmountUSDC: session.lockedAmount.toString(),
-                runningTotalUSDC: session.runningTotal.toString(),
-                ackedRequestCount: session.ackedRequestCount,
             });
         }
         return snapshots;
@@ -132,7 +190,7 @@ export class AntseedNode extends EventEmitter {
         }
         const dataDir = this._config.dataDir ?? join(homedir(), ".antseed");
         // Load or create identity
-        this._identity = await loadOrCreateIdentity(dataDir);
+        this._identity = await loadOrCreateIdentity(this._config.identityStore ?? dataDir);
         debugLog(`[Node] Identity loaded: ${this._identity.peerId.slice(0, 12)}...`);
         // Determine bootstrap nodes — merge official + any user-configured nodes unless
         // noOfficialBootstrap is set (e.g. isolated local testing).
@@ -213,12 +271,35 @@ export class AntseedNode extends EventEmitter {
             }
             this._metering = null;
         }
+        if (this._timeoutCheckerInterval) {
+            clearInterval(this._timeoutCheckerInterval);
+            this._timeoutCheckerInterval = null;
+        }
+        if (this._sessionStore) {
+            try {
+                this._sessionStore.close();
+            }
+            catch {
+                // ignore close errors
+            }
+            this._sessionStore = null;
+        }
         this._peerLookup = null;
         this._receiptGenerator = null;
         this._balanceManager = null;
         this._escrowClient = null;
+        this._identityClient = null;
         this._buyerPaymentManager = null;
+        this._sellerPaymentManager = null;
         this._buyerLockedPeers.clear();
+        // Clean up payment negotiation state
+        for (const [, pending] of this._pendingPaymentRequired) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Node stopped'));
+        }
+        this._pendingPaymentRequired.clear();
+        this._bufferedPaymentRequired.clear();
+        this._paymentNegotiationLocks.clear();
         this._started = false;
         this.emit("stopped");
     }
@@ -248,19 +329,30 @@ export class AntseedNode extends EventEmitter {
             }
         }
         // Optional reputation verification: replace claimed data with verified on-chain data
-        if (this._escrowClient) {
+        if (this._identityClient) {
             for (const p of peers) {
-                if (p.evmAddress && p.onChainReputation !== undefined) {
-                    try {
-                        const rep = await this._escrowClient.getReputation(p.evmAddress);
-                        p.onChainReputation = rep.weightedAverage;
-                        p.onChainSessionCount = rep.sessionCount;
-                        p.onChainDisputeCount = rep.disputeCount;
-                        p.trustScore = rep.weightedAverage;
-                    }
-                    catch {
-                        // Use claimed data if verification fails
-                    }
+                if (!p.evmAddress)
+                    continue;
+                try {
+                    const metadata = {
+                        peerId: p.peerId,
+                        version: 0,
+                        providers: [],
+                        region: "",
+                        timestamp: 0,
+                        signature: "",
+                        evmAddress: p.evmAddress,
+                        onChainReputation: p.onChainReputation,
+                        onChainSessionCount: p.onChainSessionCount,
+                        onChainDisputeCount: p.onChainDisputeCount,
+                    };
+                    const result = await verifyReputation(this._identityClient, metadata);
+                    p.onChainReputation = result.actualReputation;
+                    p.onChainSessionCount = result.actualSessionCount;
+                    p.onChainDisputeCount = result.actualDisputeCount;
+                }
+                catch {
+                    // Identity contract lookup failed for this peer — keep claimed data
                 }
             }
         }
@@ -295,12 +387,22 @@ export class AntseedNode extends EventEmitter {
         const conn = await this._getOrCreateConnection(peer);
         debugLog(`[Node] Connection to ${peer.peerId.slice(0, 12)}... state=${conn.state}`);
         const mux = this._getOrCreateMux(peer.peerId, conn);
-        // Buyer-side: initiate lock and wait for confirmation on first request to a new peer
-        if (this._buyerPaymentManager && !this._buyerLockedPeers.has(peer.peerId)) {
-            await this._initiateBuyerLock(peer, conn);
+        // Extract and strip x-antseed-spending-auth header if present (manual approval flow)
+        const externalSpendingAuth = req.headers[ANTSEED_SPENDING_AUTH_HEADER] ?? null;
+        if (externalSpendingAuth) {
+            const { [ANTSEED_SPENDING_AUTH_HEADER]: _, ...cleanHeaders } = req.headers;
+            req = { ...req, headers: cleanHeaders };
+        }
+        // If we already have a payment session with this peer, skip negotiation.
+        const needsPaymentNegotiation = this._buyerPaymentManager
+            && !this._buyerLockedPeers.has(peer.peerId);
+        // If an external spending auth was provided, apply it before sending the request.
+        if (externalSpendingAuth && needsPaymentNegotiation) {
+            debugLog(`[Node] Applying external spending auth for ${peer.peerId.slice(0, 12)}...`);
+            await this._applyExternalSpendingAuth(peer, conn, externalSpendingAuth);
         }
         const startTime = Date.now();
-        return new Promise((resolve, reject) => {
+        const executeRequest = () => new Promise((resolve, reject) => {
             const timeoutMs = this._config.requestTimeoutMs ?? 30_000;
             const maxStreamBufferBytes = Math.max(1, this._config.maxStreamBufferBytes ?? 16 * 1024 * 1024);
             const maxStreamDurationMs = Math.max(1, this._config.maxStreamDurationMs ?? 5 * 60_000);
@@ -473,6 +575,78 @@ export class AntseedNode extends EventEmitter {
                 });
             });
         });
+        // Execute the request. If we get a 402 and payment negotiation is needed,
+        // wait for the seller's PaymentRequired message, negotiate, and retry.
+        const response = await executeRequest();
+        if (response.statusCode === 402 && needsPaymentNegotiation && !externalSpendingAuth) {
+            const manualApproval = await this._isManualApprovalEnabled();
+            const directPaymentBody = parsePaymentRequiredBody(response.body);
+            const responseAlreadyHasRequirements = Boolean(directPaymentBody?.sellerEvmAddr);
+            const waitMs = manualApproval ? 10_000 : 2_000;
+            const buffered = responseAlreadyHasRequirements
+                ? null
+                : await this._awaitPaymentRequired(peer.peerId, conn, waitMs);
+            if (buffered)
+                this._bufferedPaymentRequired.delete(peer.peerId);
+            // Helper: return enriched 402 so the caller can show an approval / add-credits card
+            const returnPaymentRequired = (reason) => {
+                debugLog(`[Node] Got 402 from ${peer.peerId.slice(0, 12)}... — returning to caller (${reason})`);
+                if (responseAlreadyHasRequirements) {
+                    return response;
+                }
+                if (buffered) {
+                    const enrichedBody = JSON.stringify({
+                        error: 'payment_required',
+                        peerId: peer.peerId,
+                        sellerEvmAddr: buffered.sellerEvmAddr,
+                        tokenRate: buffered.tokenRate,
+                        firstSignCap: buffered.firstSignCap,
+                        suggestedAmount: buffered.suggestedAmount,
+                    });
+                    return {
+                        ...response,
+                        headers: { ...response.headers, 'content-type': 'application/json' },
+                        body: new TextEncoder().encode(enrichedBody),
+                    };
+                }
+                return response;
+            };
+            // If manual approval is on, always return the 402 to the caller
+            if (manualApproval) {
+                return returnPaymentRequired(responseAlreadyHasRequirements ? 'manual approval (direct body)' : 'manual approval');
+            }
+            // Auto mode: check if we can actually pay before attempting negotiation
+            if (!this._escrowClient || !this._identity || !this._buyerPaymentManager) {
+                return returnPaymentRequired('no escrow configured');
+            }
+            // Check on-chain balance — if insufficient, return 402 instead of failing mid-negotiate
+            try {
+                const buyerAddr = identityToEvmAddress(this._identity);
+                const balance = await this._escrowClient.getBuyerBalance(buyerAddr);
+                if (balance.available <= 0n) {
+                    return returnPaymentRequired('insufficient credits');
+                }
+            }
+            catch (err) {
+                debugWarn(`[Node] Failed to check buyer balance: ${err instanceof Error ? err.message : err}`);
+                // Fall through to negotiate — let it fail naturally if balance is truly insufficient
+            }
+            // Auto-negotiate: sign SpendingAuth internally and retry
+            // Re-buffer the PaymentRequired so _doNegotiatePayment can consume it
+            if (buffered)
+                this._bufferedPaymentRequired.set(peer.peerId, buffered);
+            debugLog(`[Node] Got 402 from ${peer.peerId.slice(0, 12)}... — auto-negotiating payment`);
+            try {
+                await this._negotiatePayment(peer, conn);
+                debugLog(`[Node] Payment negotiated with ${peer.peerId.slice(0, 12)}... — retrying request`);
+                return executeRequest();
+            }
+            catch (err) {
+                this._buyerLockedPeers.delete(peer.peerId);
+                throw err;
+            }
+        }
+        return response;
     }
     _createDHTConfig(port, bootstrapNodes) {
         return {
@@ -545,8 +719,23 @@ export class AntseedNode extends EventEmitter {
                 this._muxes.get(peerId)?.abortPendingUploads();
                 this._muxes.delete(peerId);
                 this._paymentMuxes.delete(peerId);
+                this._bufferedPaymentRequired.delete(peerId);
+                // Cancel any in-flight PaymentRequired wait so _doNegotiatePayment
+                // fails immediately instead of blocking for 10s on a dead connection.
+                const pendingPR = this._pendingPaymentRequired.get(peerId);
+                if (pendingPR) {
+                    clearTimeout(pendingPR.timer);
+                    this._pendingPaymentRequired.delete(peerId);
+                    pendingPR.reject(new Error(`Peer ${peerId.slice(0, 12)}... disconnected during payment negotiation`));
+                }
+                // Don't delete _paymentNegotiationLocks here — the pending rejection
+                // causes _doNegotiatePayment to throw, and its finally block owns cleanup.
+                // Deleting here would race with a new negotiation started on reconnect.
                 this._decoders.delete(peerId);
-                // Handle buyer disconnect (ghost scenario)
+                // Handle buyer disconnect
+                if (this._sellerPaymentManager) {
+                    this._sellerPaymentManager.onBuyerDisconnect(peerId);
+                }
                 void this._finalizeSession(peerId, "disconnect");
             }
         });
@@ -654,6 +843,7 @@ export class AntseedNode extends EventEmitter {
                 ])),
                 reannounceIntervalMs: DEFAULT_DHT_CONFIG.reannounceIntervalMs,
                 signalingPort: actualSignalingPort,
+                ...(this._identityClient ? { identityClient: this._identityClient } : {}),
             };
             this._announcer = new PeerAnnouncer(announcerConfig);
             this._announcer.startPeriodicAnnounce();
@@ -670,6 +860,8 @@ export class AntseedNode extends EventEmitter {
         const identity = this._identity;
         const dhtPort = this._config.dhtPort ?? 0;
         debugLog(`[Node] Starting buyer — DHT port=${dhtPort}`);
+        const dataDir = this._config.dataDir ?? join(homedir(), ".antseed");
+        await this._initializePayments(dataDir);
         // Start DHT with ephemeral port
         this._dht = new DHTNode(this._createDHTConfig(dhtPort, bootstrapNodes));
         await this._dht.start();
@@ -693,14 +885,32 @@ export class AntseedNode extends EventEmitter {
         // Initialize buyer-side payment manager if payments config is provided
         const payments = this._config.payments;
         if (payments?.enabled && payments.rpcUrl && payments.contractAddress && payments.usdcAddress) {
-            const buyerPaymentConfig = {
-                defaultLockAmountUSDC: payments.defaultEscrowAmountUSDC ?? "1000000",
-                rpcUrl: payments.rpcUrl,
-                contractAddress: payments.contractAddress,
-                usdcAddress: payments.usdcAddress,
-            };
-            this._buyerPaymentManager = new BuyerPaymentManager(identity, buyerPaymentConfig);
-            debugLog(`[Node] Buyer payment manager initialized (wallet=${identityToEvmAddress(identity).slice(0, 10)}...)`);
+            const paymentsDir = join(dataDir, "payments");
+            // Create shared SessionStore for both buyer and seller payment managers
+            if (!this._sessionStore) {
+                try {
+                    this._sessionStore = new SessionStore(paymentsDir);
+                    debugLog("[Node] SessionStore initialized (buyer)");
+                }
+                catch (err) {
+                    debugWarn(`[Node] SessionStore unavailable: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            if (this._sessionStore) {
+                const buyerPaymentConfig = {
+                    rpcUrl: payments.rpcUrl,
+                    contractAddress: payments.contractAddress,
+                    usdcAddress: payments.usdcAddress,
+                    identityAddress: payments.identityAddress ?? '',
+                    chainId: payments.chainId ?? 8453,
+                    defaultMaxAmountUsdc: BigInt(payments.defaultMaxAmountUsdc ?? "1000000"),
+                    defaultAuthDurationSecs: payments.defaultAuthDurationSecs ?? 90000, // Must exceed SETTLE_TIMEOUT (24h)
+                    autoAck: payments.autoAck ?? true,
+                    dataDir: paymentsDir,
+                };
+                this._buyerPaymentManager = new BuyerPaymentManager(identity, buyerPaymentConfig, this._sessionStore);
+                debugLog(`[Node] Buyer payment manager initialized (wallet=${identityToEvmAddress(identity).slice(0, 10)}... chainId=${buyerPaymentConfig.chainId} contract=${buyerPaymentConfig.contractAddress.slice(0, 10)}...)`);
+            }
         }
         debugLog(`[Node] Buyer ready — DHT running on port ${this._dht.getPort()}`);
     }
@@ -710,32 +920,68 @@ export class AntseedNode extends EventEmitter {
         const mux = new ProxyMux(conn);
         // Create PaymentMux alongside ProxyMux (seller-side)
         const paymentMux = new PaymentMux(conn);
-        paymentMux.onSessionLockAuth((payload) => {
-            void this._handleSessionLockAuth(buyerPeerId, payload, paymentMux);
-        });
-        paymentMux.onBuyerAck((payload) => {
-            void this._handleBuyerAck(buyerPeerId, payload);
-        });
-        paymentMux.onSessionEnd((payload) => {
-            void this._handleSessionEnd(buyerPeerId, payload);
-        });
-        paymentMux.onTopUpAuth((payload) => {
-            void this._handleTopUpAuth(buyerPeerId, payload);
-        });
+        if (this._sellerPaymentManager) {
+            const spm = this._sellerPaymentManager;
+            paymentMux.onSpendingAuth((payload) => {
+                void spm.handleSpendingAuth(buyerPeerId, payload.buyerEvmAddr, payload, paymentMux);
+            });
+            paymentMux.onBuyerAck((payload) => {
+                void spm.handleBuyerAck(buyerPeerId, payload);
+            });
+        }
+        else {
+            // No SellerPaymentManager — reject SpendingAuth to prevent
+            // accepting payment claims without EIP-712 signature verification
+            paymentMux.onSpendingAuth(() => {
+                debugWarn(`[Node] SpendingAuth rejected — SellerPaymentManager not configured`);
+            });
+        }
         this._paymentMuxes.set(buyerPeerId, paymentMux);
         // Register the ProxyMux request handler that routes to providers
         mux.onProxyRequest(async (request) => {
             debugLog(`[Node] Seller received request: ${request.method} ${request.path} (reqId=${request.requestId.slice(0, 8)})`);
-            // Reject with 402 if lock not committed and escrow client is configured
-            const session = this._sessions.get(buyerPeerId);
-            if (this._escrowClient && (!session || !session.lockCommitted)) {
-                debugWarn(`[Node] Rejecting request from ${buyerPeerId.slice(0, 12)}... — lock not committed`);
-                mux.sendProxyResponse({
-                    requestId: request.requestId,
-                    statusCode: 402,
-                    headers: { "content-type": "text/plain" },
-                    body: new TextEncoder().encode("Payment required: session lock not committed"),
-                });
+            // Reject with 402 if no active payment session and escrow client is configured.
+            // Also send PaymentRequired via PaymentMux so the buyer knows what to sign.
+            const spmAuthorized = this._sellerPaymentManager?.hasSession(buyerPeerId) ?? false;
+            if (this._escrowClient && !spmAuthorized) {
+                // Pass buyerPeerId so seller can suggest higher amount for returning buyers,
+                // and include per-direction pricing from the first registered provider.
+                // Retry init if it failed at startup (e.g. RPC was unreachable)
+                await this._sellerPaymentManager?.ensureInitialized();
+                const firstProvider = this._providers[0];
+                const providerPricing = firstProvider?.pricing?.defaults;
+                const requirements = this._sellerPaymentManager?.getPaymentRequirements(request.requestId, buyerPeerId, providerPricing);
+                if (requirements) {
+                    debugLog(`[Node] No payment session for ${buyerPeerId.slice(0, 12)}... — sending 402 + PaymentRequired`);
+                    const paymentBody = JSON.stringify({
+                        error: 'payment_required',
+                        sellerEvmAddr: requirements.sellerEvmAddr,
+                        tokenRate: requirements.tokenRate,
+                        firstSignCap: requirements.firstSignCap,
+                        suggestedAmount: requirements.suggestedAmount,
+                    });
+                    mux.sendProxyResponse({
+                        requestId: request.requestId,
+                        statusCode: 402,
+                        headers: { "content-type": "application/json" },
+                        body: new TextEncoder().encode(paymentBody),
+                    });
+                    paymentMux.sendPaymentRequired(requirements);
+                }
+                else {
+                    // init() failed — on-chain data not cached. Tell buyer to retry
+                    // rather than letting them wait 10s for a PaymentRequired that won't come.
+                    debugWarn(`[Node] No payment session and seller not ready (init failed?) — returning 402`);
+                    mux.sendProxyResponse({
+                        requestId: request.requestId,
+                        statusCode: 402,
+                        headers: { "content-type": "application/json" },
+                        body: new TextEncoder().encode(JSON.stringify({
+                            error: 'payment_required',
+                            message: 'Seller not ready, try again later',
+                        })),
+                    });
+                }
                 return;
             }
             const requestedService = this._extractRequestedService(request);
@@ -820,11 +1066,13 @@ export class AntseedNode extends EventEmitter {
                 // Record metering
                 const latencyMs = Date.now() - startTime;
                 const requestPricing = this._resolveProviderPricing(provider, request);
-                await this._recordMetering(buyerPeerId, provider.name, requestPricing, request, statusCode, latencyMs, request.body.length, responseBody.length);
-                // Generate bilateral receipt after each request if lock committed (Task 3)
-                const currentSession = this._sessions.get(buyerPeerId);
-                if (currentSession?.lockCommitted) {
-                    await this._sendBilateralReceipt(buyerPeerId, currentSession, requestPricing, responseBody, paymentMux);
+                await this._recordMetering(buyerPeerId, provider.name, requestPricing, request, statusCode, latencyMs, request.body.length, responseBody.length, responseBody);
+                // Send receipt to buyer after each request
+                if (this._sellerPaymentManager?.hasSession(buyerPeerId)) {
+                    const usage = parseResponseUsage(responseBody);
+                    const totalTokens = usage.inputTokens + usage.outputTokens;
+                    debugLog(`[Node] Sending receipt: buyer=${buyerPeerId.slice(0, 12)}... tokens=${totalTokens} (in=${usage.inputTokens} out=${usage.outputTokens})`);
+                    await this._sellerPaymentManager.sendReceipt(buyerPeerId, paymentMux, responseBody, BigInt(totalTokens));
                 }
             }
             finally {
@@ -912,13 +1160,6 @@ export class AntseedNode extends EventEmitter {
                 totalLatencyMs: 0,
                 totalCostCents: 0,
                 provider: providerName,
-                lockCommitted: false,
-                lockedAmount: 0n,
-                runningTotal: 0n,
-                ackedRequestCount: 0,
-                lastAckedTotal: 0n,
-                awaitingAck: false,
-                buyerEvmAddress: null,
             };
             this._sessions.set(buyerPeerId, session);
         }
@@ -941,17 +1182,36 @@ export class AntseedNode extends EventEmitter {
         });
     }
     /** Estimate tokens from byte lengths (rough: ~4 chars per token). */
+    /** Fallback token estimation from byte lengths (~4 bytes per token). */
     _estimateTokens(inputBytes, outputBytes) {
         const inputTokens = Math.max(1, Math.round(inputBytes / 4));
         const outputTokens = Math.max(1, Math.round(outputBytes / 4));
-        return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+        return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens, method: 'content-length', confidence: 'low' };
     }
-    async _recordMetering(buyerPeerId, providerName, providerPricingUsdPerMillion, request, statusCode, latencyMs, inputBytes, outputBytes) {
+    async _recordMetering(buyerPeerId, providerName, providerPricingUsdPerMillion, request, statusCode, latencyMs, inputBytes, outputBytes, responseBody) {
         if (!this._identity)
             return;
         const sellerPeerId = this._identity.peerId;
         const isSSE = request.headers["accept"]?.includes("text/event-stream") ?? false;
-        const tokens = this._estimateTokens(inputBytes, outputBytes);
+        // Use actual token counts from provider response when available,
+        // falling back to byte-based estimation.
+        const providerUsage = parseResponseUsage(responseBody);
+        let tokens;
+        if (providerUsage.inputTokens > 0 || providerUsage.outputTokens > 0) {
+            const totalTokens = providerUsage.inputTokens + providerUsage.outputTokens;
+            tokens = {
+                inputTokens: providerUsage.inputTokens,
+                outputTokens: providerUsage.outputTokens,
+                totalTokens,
+                method: 'provider-usage',
+                confidence: 'high',
+            };
+            debugLog(`[Node] Metering: provider-usage tokens=${totalTokens} (in=${providerUsage.inputTokens} out=${providerUsage.outputTokens})`);
+        }
+        else {
+            tokens = this._estimateTokens(inputBytes, outputBytes);
+            debugLog(`[Node] Metering: estimated tokens=${tokens.totalTokens} from ${inputBytes}+${outputBytes} bytes`);
+        }
         // Get or create session for this buyer
         const session = this._getOrCreateSellerSession(buyerPeerId, providerName);
         if (!session)
@@ -1039,11 +1299,54 @@ export class AntseedNode extends EventEmitter {
             });
             debugLog(`[Node] BaseEscrowClient initialized (contract=${payments.contractAddress.slice(0, 10)}...)`);
         }
+        // Initialize IdentityClient if identity contract address is provided
+        if (payments.rpcUrl && payments.identityAddress) {
+            this._identityClient = new IdentityClient({
+                rpcUrl: payments.rpcUrl,
+                contractAddress: payments.identityAddress,
+            });
+            debugLog(`[Node] IdentityClient initialized (contract=${payments.identityAddress.slice(0, 10)}...)`);
+        }
+        // Initialize SessionStore for persistent payment sessions (shared instance)
+        const paymentsDir = join(dataDir, "payments");
+        if (!this._sessionStore) {
+            try {
+                this._sessionStore = new SessionStore(paymentsDir);
+                debugLog("[Node] SessionStore initialized");
+            }
+            catch (err) {
+                debugWarn(`[Node] SessionStore unavailable: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        // Initialize SellerPaymentManager for seller role
+        if (this._config.role === 'seller' && this._identity && this._sessionStore &&
+            payments.rpcUrl && payments.contractAddress && payments.usdcAddress) {
+            const sellerConfig = {
+                rpcUrl: payments.rpcUrl,
+                contractAddress: payments.contractAddress,
+                usdcAddress: payments.usdcAddress,
+                chainId: payments.chainId ?? 8453,
+                dataDir: paymentsDir,
+                firstSignAmountUsdc: payments.firstSignAmountUsdc,
+                provenSignAmountUsdc: payments.provenSignAmountUsdc,
+            };
+            this._sellerPaymentManager = new SellerPaymentManager(this._identity, sellerConfig, this._sessionStore);
+            await this._sellerPaymentManager.init();
+            debugLog(`[Node] SellerPaymentManager initialized`);
+            // Startup recovery: check for timed-out sessions
+            await this._sellerPaymentManager.checkTimeouts();
+            // Start periodic timeout checker (every 60s)
+            this._timeoutCheckerInterval = setInterval(() => {
+                void this._sellerPaymentManager?.checkTimeouts();
+            }, 60_000);
+            if (typeof this._timeoutCheckerInterval.unref === "function") {
+                this._timeoutCheckerInterval.unref();
+            }
+        }
         if (!this._metering) {
             debugWarn("[Node] Payments enabled but metering storage is unavailable; skipping balance manager wiring");
             return;
         }
-        const paymentsDir = join(dataDir, "payments");
         this._balanceManager = new BalanceManager();
         await this._balanceManager.load(paymentsDir).catch((err) => {
             debugWarn(`[Node] Failed to load payment balances: ${err instanceof Error ? err.message : err}`);
@@ -1074,37 +1377,6 @@ export class AntseedNode extends EventEmitter {
             clearTimeout(timer);
             this._settlementTimers.delete(buyerPeerId);
         }
-        // Bilateral-aware disconnect handling (ghost scenario - Task 7)
-        if (session.lockCommitted && this._escrowClient && this._identity && reason === "disconnect") {
-            const sellerWallet = identityToEvmWallet(this._identity);
-            const sessionIdHex = "0x" + bytesToHex(session.sessionIdBytes);
-            try {
-                if (session.lastAckedTotal > 0n) {
-                    // Buyer acked some work — open dispute with last acked total
-                    debugLog(`[Node] Ghost buyer — opening dispute with lastAckedTotal=${session.lastAckedTotal}`);
-                    await this._escrowClient.openDispute(sellerWallet, sessionIdHex, session.lastAckedTotal);
-                }
-                else if (session.runningTotal > 0n) {
-                    // No acks but work was done — open dispute with running total
-                    debugLog(`[Node] Ghost buyer — opening dispute with runningTotal=${session.runningTotal}`);
-                    await this._escrowClient.openDispute(sellerWallet, sessionIdHex, session.runningTotal);
-                }
-                else {
-                    // No work done — lock expires after 1 hour automatically
-                    debugLog(`[Node] Ghost buyer — no work done, lock will expire`);
-                }
-            }
-            catch (err) {
-                debugWarn(`[Node] Failed to handle ghost buyer for session ${session.sessionId}: ${err instanceof Error ? err.message : err}`);
-            }
-            this._sessions.delete(buyerPeerId);
-            this.emit("session:finalized", {
-                buyerPeerId,
-                sessionId: session.sessionId,
-                reason: "ghost-disconnect",
-            });
-            return;
-        }
         if (!this._metering || !this._identity) {
             this._sessions.delete(buyerPeerId);
             return;
@@ -1235,249 +1507,300 @@ export class AntseedNode extends EventEmitter {
         this._muxes.set(peerId, mux);
         return mux;
     }
-    // ── Seller-side bilateral payment handlers ─────────────────────
+    // ── Buyer-side payment helpers ─────────────────────────────────
     /**
-     * Handle SessionLockAuth from buyer (Task 2).
-     * Recovers buyer address, commits lock on-chain, initializes bilateral state.
+     * Create a PaymentMux for a buyer-side outbound connection and register
+     * buyer-side handlers (lock confirm, lock reject, seller receipt, top-up request).
      */
-    async _handleSessionLockAuth(buyerPeerId, payload, paymentMux) {
-        if (!this._identity || !this._escrowClient) {
-            paymentMux.sendSessionLockReject({
-                sessionId: payload.sessionId,
-                reason: "Escrow client not configured",
-            });
-            return;
-        }
-        try {
-            const sellerWallet = identityToEvmWallet(this._identity);
-            const lockedAmount = BigInt(payload.lockedAmount);
-            // Recover buyer address from ECDSA signature
-            const lockMsgHash = buildLockMessageHash(payload.sessionId, sellerWallet.address, lockedAmount);
-            const buyerEvmAddress = verifyMessage(getBytes(lockMsgHash), payload.buyerSig);
-            // Submit commit_lock on-chain
-            const txHash = await this._escrowClient.commitLock(sellerWallet, buyerEvmAddress, payload.sessionId, lockedAmount, payload.buyerSig);
-            // Initialize or update bilateral session state
-            let session = this._sessions.get(buyerPeerId);
-            if (!session) {
-                session = this._getOrCreateSellerSession(buyerPeerId, this._providers[0]?.name ?? "unknown");
+    _getOrCreateBuyerPaymentMux(peerId, conn) {
+        const existing = this._paymentMuxes.get(peerId);
+        if (existing)
+            return existing;
+        const pmux = new PaymentMux(conn);
+        this._paymentMuxes.set(peerId, pmux);
+        const bpm = this._buyerPaymentManager;
+        if (!bpm)
+            return pmux;
+        pmux.onAuthAck((payload) => {
+            bpm.handleAuthAck(peerId, payload);
+        });
+        pmux.onSellerReceipt((receipt) => {
+            void bpm.handleSellerReceipt(peerId, receipt, pmux);
+        });
+        pmux.onTopUpRequest((request) => {
+            void bpm.handleTopUpRequest(peerId, request, pmux);
+        });
+        pmux.onPaymentRequired((payload) => {
+            const pending = this._pendingPaymentRequired.get(peerId);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this._pendingPaymentRequired.delete(peerId);
+                pending.resolve(payload);
             }
-            if (session) {
-                // Override sessionId with the one from the lock auth (buyer-chosen)
-                session.sessionId = payload.sessionId;
-                session.sessionIdBytes = hexToBytes(payload.sessionId.replace(/^0x/, ""));
-                session.lockCommitted = true;
-                session.lockedAmount = lockedAmount;
-                session.runningTotal = 0n;
-                session.ackedRequestCount = 0;
-                session.lastAckedTotal = 0n;
-                session.awaitingAck = false;
-                session.buyerEvmAddress = buyerEvmAddress;
+            else {
+                // Buffer: 402 and PaymentRequired can arrive in the same I/O tick,
+                // before _doNegotiatePayment registers its listener.
+                this._bufferedPaymentRequired.set(peerId, payload);
+                debugLog(`[Node] PaymentRequired from ${peerId.slice(0, 12)}... buffered (listener not yet registered)`);
             }
-            debugLog(`[Node] Lock committed for buyer ${buyerPeerId.slice(0, 12)}... amount=${lockedAmount} tx=${txHash.slice(0, 12)}...`);
-            paymentMux.sendSessionLockConfirm({
-                sessionId: payload.sessionId,
-                txSignature: txHash,
-            });
-        }
-        catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
-            debugWarn(`[Node] Failed to commit lock for ${buyerPeerId.slice(0, 12)}...: ${reason}`);
-            paymentMux.sendSessionLockReject({
-                sessionId: payload.sessionId,
-                reason,
-            });
-        }
-    }
-    /**
-     * Generate and send a bilateral receipt after processing a request (Task 3).
-     */
-    async _sendBilateralReceipt(_buyerPeerId, session, providerPricingUsdPerMillion, responseBody, paymentMux) {
-        if (!this._identity)
-            return;
-        // Calculate incremental cost in USDC base units (6 decimals)
-        // Estimate tokens from response body size
-        const tokens = this._estimateTokens(0, responseBody.length);
-        const costUSD = (tokens.inputTokens * providerPricingUsdPerMillion.inputUsdPerMillion +
-            tokens.outputTokens * providerPricingUsdPerMillion.outputUsdPerMillion) /
-            1_000_000;
-        const costBaseUnits = BigInt(Math.round(costUSD * 1_000_000));
-        // Update running total
-        session.runningTotal += costBaseUnits;
-        // SHA-256 hash of response body for proof of work
-        const responseHash = createHash("sha256").update(responseBody).digest();
-        // Build receipt message and sign with Ed25519
-        const receiptMsg = buildReceiptMessage(session.sessionIdBytes, session.runningTotal, session.totalRequests, new Uint8Array(responseHash));
-        const sellerSig = await signMessageEd25519(this._identity, receiptMsg);
-        paymentMux.sendSellerReceipt({
-            sessionId: session.sessionId,
-            runningTotal: session.runningTotal.toString(),
-            requestCount: session.totalRequests,
-            responseHash: bytesToHex(new Uint8Array(responseHash)),
-            sellerSig: bytesToHex(sellerSig),
         });
-        session.awaitingAck = true;
-        // Send TopUpRequest if running total > 80% of locked amount
-        if (session.lockedAmount > 0n && session.runningTotal * 100n > session.lockedAmount * 80n) {
-            const additionalAmount = session.lockedAmount; // Request same amount again
-            paymentMux.sendTopUpRequest({
-                sessionId: session.sessionId,
-                additionalAmount: additionalAmount.toString(),
-                currentRunningTotal: session.runningTotal.toString(),
-                currentLockedAmount: session.lockedAmount.toString(),
-            });
-            debugLog(`[Node] TopUpRequest sent for session ${session.sessionId.slice(0, 8)}... (running=${session.runningTotal}, locked=${session.lockedAmount})`);
-        }
+        return pmux;
     }
     /**
-     * Handle BuyerAck (Task 4).
-     * Verifies buyer's Ed25519 ack signature and updates session state.
+     * Wait for the seller's PaymentRequired message, sign a SpendingAuth with
+     * the seller's real requirements, and wait for AuthAck.
+     * Uses a per-peer mutex so concurrent requests wait for the first negotiation.
      */
-    async _handleBuyerAck(buyerPeerId, payload) {
-        const session = this._sessions.get(buyerPeerId);
-        if (!session || !session.lockCommitted) {
-            debugWarn(`[Node] Received BuyerAck for unknown/uncommitted session from ${buyerPeerId.slice(0, 12)}...`);
-            return;
+    /** Read requireManualApproval from config.json so changes take effect without restart. */
+    async _isManualApprovalEnabled() {
+        const now = Date.now();
+        if (this._manualApprovalCache && now - this._manualApprovalCache.at < 5_000) {
+            return this._manualApprovalCache.value;
         }
         try {
-            // Verify buyer's Ed25519 ack signature
-            const buyerPublicKey = hexToBytes(buyerPeerId);
-            const ackMsg = buildAckMessage(session.sessionIdBytes, BigInt(payload.runningTotal), payload.requestCount);
-            const sigBytes = hexToBytes(payload.buyerSig);
-            const valid = await verifyMessageEd25519(buyerPublicKey, sigBytes, ackMsg);
-            if (!valid) {
-                debugWarn(`[Node] Invalid BuyerAck signature from ${buyerPeerId.slice(0, 12)}...`);
-                return;
-            }
-            session.ackedRequestCount = payload.requestCount;
-            session.lastAckedTotal = BigInt(payload.runningTotal);
-            session.awaitingAck = false;
-            debugLog(`[Node] BuyerAck received: requestCount=${payload.requestCount} runningTotal=${payload.runningTotal}`);
+            const configPath = this._config.configPath
+                ?? join(this._config.dataDir ?? join(homedir(), '.antseed'), 'config.json');
+            const raw = await readFile(configPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const buyer = parsed.buyer && typeof parsed.buyer === 'object' ? parsed.buyer : {};
+            const value = Boolean(buyer.requireManualApproval);
+            this._manualApprovalCache = { value, at: now };
+            return value;
         }
-        catch (err) {
-            debugWarn(`[Node] Failed to process BuyerAck: ${err instanceof Error ? err.message : err}`);
+        catch {
+            const value = Boolean(this._config.requireManualApproval);
+            this._manualApprovalCache = { value, at: now };
+            return value;
         }
     }
     /**
-     * Handle SessionEnd from buyer (Task 5).
-     * Submits settlement on-chain and cleans up.
+     * Wait for the seller's PaymentRequired payload for a given peer.
+     * Returns a buffered payload immediately when available, otherwise waits up to timeoutMs.
      */
-    async _handleSessionEnd(buyerPeerId, payload) {
-        const session = this._sessions.get(buyerPeerId);
-        if (!session || !session.lockCommitted) {
-            debugWarn(`[Node] Received SessionEnd for unknown/uncommitted session from ${buyerPeerId.slice(0, 12)}...`);
-            return;
-        }
-        if (!this._identity || !this._escrowClient) {
-            debugWarn(`[Node] Cannot process SessionEnd — escrow client not available`);
-            return;
-        }
-        try {
-            const sellerWallet = identityToEvmWallet(this._identity);
-            const sessionIdHex = "0x" + bytesToHex(session.sessionIdBytes);
-            // Submit settlement on-chain with buyer's ECDSA signature and score
-            const txHash = await this._escrowClient.settle(sellerWallet, sessionIdHex, BigInt(payload.runningTotal), payload.score, payload.buyerSig);
-            debugLog(`[Node] Session settled on-chain: ${session.sessionId.slice(0, 8)}... tx=${txHash.slice(0, 12)}... score=${payload.score}`);
-            // Clean up session
-            this._sessions.delete(buyerPeerId);
-            const timer = this._settlementTimers.get(buyerPeerId);
-            if (timer) {
-                clearTimeout(timer);
-                this._settlementTimers.delete(buyerPeerId);
+    async _awaitPaymentRequired(peerId, conn, timeoutMs) {
+        const buffered = this._bufferedPaymentRequired.get(peerId);
+        if (buffered) {
+            return buffered;
+        }
+        // Ensure the buyer-side PaymentMux exists before waiting so incoming frames
+        // are captured even when 402 and PaymentRequired arrive close together.
+        this._getOrCreateBuyerPaymentMux(peerId, conn);
+        return await new Promise((resolve) => {
+            const already = this._bufferedPaymentRequired.get(peerId);
+            if (already) {
+                resolve(already);
+                return;
             }
-            this.emit("session:settled", {
-                buyerPeerId,
-                sessionId: session.sessionId,
-                runningTotal: payload.runningTotal,
-                score: payload.score,
-                txHash,
+            const existing = this._pendingPaymentRequired.get(peerId);
+            if (existing) {
+                const wrapper = {
+                    resolve: (payload) => {
+                        clearTimeout(existing.timer);
+                        clearTimeout(wrapper.timer);
+                        if (this._pendingPaymentRequired.get(peerId) === wrapper) {
+                            this._pendingPaymentRequired.delete(peerId);
+                        }
+                        existing.resolve(payload);
+                        resolve(payload);
+                    },
+                    reject: (err) => {
+                        clearTimeout(existing.timer);
+                        clearTimeout(wrapper.timer);
+                        if (this._pendingPaymentRequired.get(peerId) === wrapper) {
+                            this._pendingPaymentRequired.delete(peerId);
+                        }
+                        existing.reject(err);
+                        resolve(null);
+                    },
+                    timer: setTimeout(() => {
+                        clearTimeout(existing.timer);
+                        if (this._pendingPaymentRequired.get(peerId) === wrapper) {
+                            this._pendingPaymentRequired.delete(peerId);
+                        }
+                        resolve(null);
+                    }, timeoutMs),
+                };
+                this._pendingPaymentRequired.set(peerId, wrapper);
+                return;
+            }
+            const timer = setTimeout(() => {
+                if (this._pendingPaymentRequired.get(peerId)?.timer === timer) {
+                    this._pendingPaymentRequired.delete(peerId);
+                }
+                resolve(null);
+            }, timeoutMs);
+            this._pendingPaymentRequired.set(peerId, {
+                resolve: (payload) => {
+                    clearTimeout(timer);
+                    if (this._pendingPaymentRequired.get(peerId)?.timer === timer) {
+                        this._pendingPaymentRequired.delete(peerId);
+                    }
+                    resolve(payload);
+                },
+                reject: () => {
+                    clearTimeout(timer);
+                    if (this._pendingPaymentRequired.get(peerId)?.timer === timer) {
+                        this._pendingPaymentRequired.delete(peerId);
+                    }
+                    resolve(null);
+                },
+                timer,
             });
-        }
-        catch (err) {
-            debugWarn(`[Node] Failed to settle session ${session.sessionId}: ${err instanceof Error ? err.message : err}`);
-        }
+        });
     }
     /**
-     * Handle TopUpAuth from buyer (Task 6).
-     * Calls extendLock on-chain and updates session.
+     * Apply a pre-signed SpendingAuth from the x-antseed-spending-auth header.
+     * Sends it to the seller via PaymentMux and waits for AuthAck.
      */
-    async _handleTopUpAuth(buyerPeerId, payload) {
-        const session = this._sessions.get(buyerPeerId);
-        if (!session || !session.lockCommitted) {
-            debugWarn(`[Node] Received TopUpAuth for unknown/uncommitted session from ${buyerPeerId.slice(0, 12)}...`);
-            return;
+    async _applyExternalSpendingAuth(peer, conn, headerValue) {
+        const pmux = this._getOrCreateBuyerPaymentMux(peer.peerId, conn);
+        let payload;
+        try {
+            const decoded = Buffer.from(headerValue, 'base64').toString('utf-8');
+            payload = JSON.parse(decoded);
+        }
+        catch {
+            throw new Error('Invalid x-antseed-spending-auth header: failed to decode');
         }
-        if (!this._identity || !this._escrowClient) {
-            debugWarn(`[Node] Cannot process TopUpAuth — escrow client not available`);
+        debugLog(`[Node] External SpendingAuth: session=${payload.sessionId.slice(0, 18)}... amount=${payload.maxAmountUsdc}`);
+        // Store session so handleAuthAck can find it
+        if (this._sessionStore) {
+            const sellerEvmAddr = payload.sellerEvmAddr ?? '';
+            this._sessionStore.upsertSession({
+                sessionId: payload.sessionId,
+                peerId: peer.peerId,
+                role: 'buyer',
+                sellerEvmAddr,
+                buyerEvmAddr: payload.buyerEvmAddr,
+                nonce: payload.nonce,
+                authMax: payload.maxAmountUsdc,
+                deadline: payload.deadline,
+                previousSessionId: payload.previousSessionId,
+                previousConsumption: payload.previousConsumption,
+                tokensDelivered: '0',
+                requestCount: 0,
+                reservedAt: Date.now(),
+                settledAt: null,
+                settledAmount: null,
+                status: 'active',
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+            });
+        }
+        // Send the pre-signed SpendingAuth to the seller
+        pmux.sendSpendingAuth(payload);
+        debugLog(`[Node] External SpendingAuth sent to seller ${peer.peerId.slice(0, 12)}..., waiting for AuthAck...`);
+        await this._waitForLockConfirmation(peer.peerId);
+        debugLog(`[Node] AuthAck received from seller ${peer.peerId.slice(0, 12)}...`);
+        this._buyerLockedPeers.add(peer.peerId);
+        this.emit('payment:signed', {
+            peerId: peer.peerId,
+            sellerEvmAddr: payload.sellerEvmAddr ?? '',
+            amount: payload.maxAmountUsdc,
+        });
+    }
+    async _negotiatePayment(peer, conn) {
+        // Per-peer mutex: if another request is already negotiating, wait for it
+        const existing = this._paymentNegotiationLocks.get(peer.peerId);
+        if (existing) {
+            await existing;
             return;
         }
+        const negotiation = this._doNegotiatePayment(peer, conn);
+        this._paymentNegotiationLocks.set(peer.peerId, negotiation);
         try {
-            const sellerWallet = identityToEvmWallet(this._identity);
-            const sessionIdHex = "0x" + bytesToHex(session.sessionIdBytes);
-            const additionalAmount = BigInt(payload.additionalAmount);
-            const txHash = await this._escrowClient.extendLock(sellerWallet, sessionIdHex, additionalAmount, payload.buyerSig);
-            session.lockedAmount += additionalAmount;
-            debugLog(`[Node] TopUp committed: session=${session.sessionId.slice(0, 8)}... additional=${additionalAmount} newTotal=${session.lockedAmount} tx=${txHash.slice(0, 12)}...`);
+            await negotiation;
         }
-        catch (err) {
-            debugWarn(`[Node] Failed to extend lock for session ${session.sessionId}: ${err instanceof Error ? err.message : err}`);
+        finally {
+            this._paymentNegotiationLocks.delete(peer.peerId);
         }
     }
-    // ── Buyer-side payment helpers ─────────────────────────────────
-    /**
-     * Create a PaymentMux for a buyer-side outbound connection and register
-     * buyer-side handlers (lock confirm, lock reject, seller receipt, top-up request).
-     */
-    _getOrCreateBuyerPaymentMux(peerId, conn) {
-        const existing = this._paymentMuxes.get(peerId);
-        if (existing)
-            return existing;
-        const pmux = new PaymentMux(conn);
-        this._paymentMuxes.set(peerId, pmux);
-        const bpm = this._buyerPaymentManager;
-        if (!bpm)
-            return pmux;
-        pmux.onSessionLockConfirm((payload) => {
-            bpm.handleLockConfirm(peerId, payload);
-        });
-        pmux.onSessionLockReject((payload) => {
-            bpm.handleLockReject(peerId, payload);
-        });
-        pmux.onSellerReceipt((receipt) => {
-            void bpm.handleSellerReceipt(peerId, receipt, pmux);
-        });
-        pmux.onTopUpRequest((request) => {
-            void bpm.handleTopUpRequest(peerId, request, pmux);
-        });
-        return pmux;
-    }
-    /**
-     * Initiate a lock with a seller peer. Creates PaymentMux, signs lock auth,
-     * and waits for confirmation before returning.
-     */
-    async _initiateBuyerLock(peer, conn) {
+    async _doNegotiatePayment(peer, conn) {
         const bpm = this._buyerPaymentManager;
-        if (!bpm)
+        if (!bpm) {
+            throw new Error('Payment negotiation unavailable — no escrow contract configured');
+        }
+        // If already locked from a previous successful negotiation, skip
+        if (this._buyerLockedPeers.has(peer.peerId))
             return;
-        // Mark as locked so we don't re-initiate
-        this._buyerLockedPeers.add(peer.peerId);
         const pmux = this._getOrCreateBuyerPaymentMux(peer.peerId, conn);
-        // Determine seller EVM address — prefer from peer metadata
-        const sellerEvmAddress = peer.evmAddress ?? "";
-        if (!sellerEvmAddress) {
-            debugWarn(`[Node] Seller ${peer.peerId.slice(0, 12)}... has no EVM address; skipping lock initiation`);
-            return;
+        // Check if PaymentRequired was already buffered (arrives in same I/O tick as 402)
+        const buffered = this._bufferedPaymentRequired.get(peer.peerId);
+        if (buffered) {
+            this._bufferedPaymentRequired.delete(peer.peerId);
+            debugLog(`[Node] Using buffered PaymentRequired from ${peer.peerId.slice(0, 12)}...`);
+        }
+        const PAYMENT_REQUIRED_TIMEOUT_MS = 10_000;
+        const requirements = buffered ?? await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pendingPaymentRequired.delete(peer.peerId);
+                reject(new Error(`PaymentRequired timeout from seller ${peer.peerId.slice(0, 12)}...`));
+            }, PAYMENT_REQUIRED_TIMEOUT_MS);
+            this._pendingPaymentRequired.set(peer.peerId, { resolve, reject, timer });
+        });
+        debugLog(`[Node] PaymentRequired from ${peer.peerId.slice(0, 12)}...: rate=${requirements.tokenRate} cap=${requirements.firstSignCap} suggested=${requirements.suggestedAmount}`);
+        // Fetch on-chain context so the UI can show the buyer real data
+        let approvalContext = null;
+        if (this._escrowClient && this._identity) {
+            try {
+                const buyerAddr = identityToEvmAddress(this._identity);
+                approvalContext = await this._escrowClient.getBuyerApprovalContext(buyerAddr, requirements.sellerEvmAddr);
+                debugLog(`[Node] Approval context: balance=${approvalContext.buyerBalance.available} isFirstSign=${approvalContext.isFirstSign} cooldown=${approvalContext.cooldownRemainingSecs}s`);
+            }
+            catch (err) {
+                debugWarn(`[Node] Failed to fetch approval context: ${err instanceof Error ? err.message : err}`);
+            }
         }
+        // Cap amount before building approval info so the displayed amount
+        // matches what will actually be signed via authorizeSpending.
+        let amount;
         try {
-            await bpm.initiateLock(peer.peerId, sellerEvmAddress, pmux);
-            debugLog(`[Node] Lock initiated for seller ${peer.peerId.slice(0, 12)}..., waiting for confirmation...`);
-            // Wait for lock confirmation (polls every 200ms, 30s timeout)
+            amount = BigInt(requirements.suggestedAmount);
+        }
+        catch {
+            throw new Error(`Invalid suggestedAmount from seller ${peer.peerId.slice(0, 12)}...: "${requirements.suggestedAmount}"`);
+        }
+        if (approvalContext) {
+            const available = approvalContext.buyerBalance.available;
+            if (amount > available)
+                amount = available;
+            if (approvalContext.isFirstSign) {
+                const cap = approvalContext.firstSignCap;
+                if (amount > cap)
+                    amount = cap;
+            }
+        }
+        if (amount <= 0n) {
+            throw new Error(`Insufficient escrow balance to authorize payment to ${peer.peerId.slice(0, 12)}...`);
+        }
+        const approvalInfo = {
+            peerId: peer.peerId,
+            sellerEvmAddr: requirements.sellerEvmAddr,
+            tokenRate: requirements.tokenRate,
+            firstSignCap: requirements.firstSignCap,
+            suggestedAmount: amount.toString(),
+            buyerAvailableUsdc: approvalContext ? approvalContext.buyerBalance.available.toString() : null,
+            isFirstSign: approvalContext?.isFirstSign ?? null,
+            cooldownRemainingSecs: approvalContext?.cooldownRemainingSecs ?? null,
+        };
+        this.emit('payment:required', approvalInfo);
+        try {
+            await bpm.authorizeSpending(peer.peerId, requirements.sellerEvmAddr, pmux, amount);
+            debugLog(`[Node] SpendingAuth sent to seller ${peer.peerId.slice(0, 12)}..., waiting for AuthAck...`);
             await this._waitForLockConfirmation(peer.peerId);
-            debugLog(`[Node] Lock confirmed for seller ${peer.peerId.slice(0, 12)}...`);
+            debugLog(`[Node] AuthAck received from seller ${peer.peerId.slice(0, 12)}...`);
+            this._buyerLockedPeers.add(peer.peerId);
+            // Notify listeners what was signed
+            this.emit('payment:signed', {
+                peerId: peer.peerId,
+                sellerEvmAddr: requirements.sellerEvmAddr,
+                amount: amount.toString(),
+                tokenRate: requirements.tokenRate,
+            });
         }
         catch (err) {
-            debugWarn(`[Node] Lock initiation/confirmation failed for ${peer.peerId.slice(0, 12)}...: ${err instanceof Error ? err.message : err}`);
-            // Remove from locked set so next request can retry
-            this._buyerLockedPeers.delete(peer.peerId);
+            debugWarn(`[Node] Payment negotiation failed for ${peer.peerId.slice(0, 12)}...: ${err instanceof Error ? err.message : err}`);
+            throw err;
         }
     }
     /**
@@ -1503,23 +1826,16 @@ export class AntseedNode extends EventEmitter {
         throw new Error(`Lock confirmation timed out for seller ${sellerPeerId.slice(0, 12)}... (${timeoutMs}ms)`);
     }
     /**
-     * End all active buyer payment sessions (called during shutdown).
+     * Clean up buyer payment sessions on shutdown.
+     * Sessions are persisted in SessionStore and will be resumed on next connect.
      */
     async _endAllBuyerSessions() {
         const bpm = this._buyerPaymentManager;
         if (!bpm)
             return;
-        const sessions = bpm.getActiveSessions();
-        if (sessions.length === 0)
-            return;
-        debugLog(`[Node] Ending ${sessions.length} buyer payment session(s)...`);
-        await Promise.allSettled(sessions.map((session) => {
-            const pmux = this._paymentMuxes.get(session.sellerPeerId);
-            if (pmux) {
-                return bpm.endSession(session.sellerPeerId, pmux, 80);
-            }
-            return Promise.resolve();
-        }));
+        // Sessions persist in SQLite; no explicit end needed.
+        // The buyer will reference them as previousSession on next connect.
+        debugLog(`[Node] Buyer sessions persisted for next reconnection`);
     }
     _resolvePublicAddress(result) {
         const metadataPublicAddress = result.metadata.publicAddress?.trim();