@supercuts-walrus/backend 0.1.0 → 0.1.1

package/dist/mcp.js

@@ -8,13 +8,16 @@ import { DealJournal } from "./deal.js";
 import { createConfiguredDealEngine } from "./deal-adapter.js";
 import { LiveDealPorts } from "./live-deal-ports.js";
 import { createRequire } from "node:module";
+import { fail } from "./errors.js";
+import { acquireRoleHomeLease } from "./role-lock.js";
 const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version;
 const MAX_REQUEST_BYTES = 1024 * 1024;
 const home = homePath({});
 const app = new Phase3App(home);
+const roleLease = acquireRoleHomeLease(home);
 const mandate = loadMandate(home);
-const remote = app.profile.role === "buyer" && !app.profile.mock && process.env.SUPERCUTS_SELLER_URL ? new RemoteBuyer(app, mandate, process.env.SUPERCUTS_SELLER_URL) : undefined;
-const eventLog = process.env.SUPERCUTS_EVENT_PATH && process.env.SUPERCUTS_RUN_ID ? new DemoEventLog(process.env.SUPERCUTS_EVENT_PATH, process.env.SUPERCUTS_RUN_ID) : undefined;
+const remote = roleLease.acquired && app.profile.role === "buyer" && !app.profile.mock && process.env.SUPERCUTS_SELLER_URL ? new RemoteBuyer(app, mandate, process.env.SUPERCUTS_SELLER_URL) : undefined;
+const eventLog = roleLease.acquired && process.env.SUPERCUTS_EVENT_PATH && process.env.SUPERCUTS_RUN_ID ? new DemoEventLog(process.env.SUPERCUTS_EVENT_PATH, process.env.SUPERCUTS_RUN_ID) : undefined;
 if (eventLog)
     eventLog.append({ actor: "operator", stage: "run", status: "started", publicDetails: { flow: remote ? "codex-remote" : "codex-deal-v2" }, evidenceHashes: [], explorerLinks: [] });
 let memoryTickRunning = false;
@@ -32,7 +35,7 @@ const memoryTick = async () => {
         memoryTickRunning = false;
     }
 };
-const memoryConfigured = app.profile.role === "buyer" && !app.profile.mock && Boolean(app.store.getSecret("live:memory-config"));
+const memoryConfigured = roleLease.acquired && app.profile.role === "buyer" && !app.profile.mock && Boolean(app.store.getSecret("live:memory-config"));
 if (memoryConfigured)
     app.recoverStaleMemorySubmissions();
 const memoryTimer = memoryConfigured ? setInterval(() => { void memoryTick(); }, 30_000) : undefined;
@@ -41,7 +44,7 @@ if (memoryTimer) {
     void memoryTick();
 }
 const tools = {
-    buyer: "status,doctor,deal.catalog,deal.policy,deal.execute,deal.get,deal.resume,deal.reconcile,deal.evidence,deal.delivery,capability.discover,settlement.plan,wallet.deposit,wallet.balance,wallet.recover,wallet.withdraw,wallet.exit.queue,wallet.exit.status,wallet.exit.finalize,offer.open,offer.propose,offer.accept,offer.show,pay.quote,pay.shielded,pay.x402,pay.status,resource.fetch,memory.remember,memory.recall,memory.status,memory.inventory,remote.catalog,remote.rank-briefs,remote.negotiate,remote.quote,remote.purchase-brief,remote.agreement,remote.settle-analysis,remote.delivery,remote.events,disclose",
+    buyer: "status,doctor,deal.catalog,deal.policy,deal.execute,deal.get,deal.resume,deal.reconcile,deal.evidence,deal.delivery,capability.discover,settlement.plan,wallet.deposit,wallet.balance,wallet.recover,wallet.withdraw,wallet.exit.queue,wallet.exit.status,wallet.exit.finalize,offer.open,offer.propose,offer.accept,offer.show,pay.quote,pay.shielded,pay.x402,pay.status,resource.fetch,memory.remember,memory.recall,memory.status,memory.inventory,remote.catalog,remote.rank-briefs,remote.negotiate,remote.quote,remote.purchase-brief,remote.agreement,remote.settle-analysis,remote.delivery,remote.events,remote.research,disclose",
     seller: "status,doctor,capability.publish,wallet.balance,wallet.recover,wallet.withdraw,wallet.exit.queue,wallet.exit.status,wallet.exit.finalize,offer.counter,offer.show,pay.status,resource.serve,resource.fetch,memory.remember,memory.recall,memory.status",
     auditor: "status,doctor,audit.verify",
 };
@@ -50,6 +53,16 @@ function logTool(name, data) {
     if (!eventLog)
         return;
     const append = (actor, stage, details, hashes = []) => eventLog.append({ actor, stage, status: "complete", publicDetails: details, evidenceHashes: hashes, explorerLinks: [] });
+    if (name === "remote.research") {
+        if (data.replayed === true)
+            return;
+        logTool("remote.rank-briefs", data.selection);
+        logTool("remote.purchase-brief", data.brief);
+        logTool("remote.agreement", data.agreement);
+        logTool("remote.settle-analysis", data.settlement);
+        logTool("remote.delivery", data.analysis);
+        return;
+    }
     if (name === "remote.rank-briefs")
         append("buyer", "seller-selection", { winner: data.winner?.capabilityId, rankings: data.rankings?.map((item) => ({ capabilityId: item.capabilityId, score: item.score, priceMist: item.priceMist })) });
     if (name === "remote.negotiate")
@@ -108,7 +121,7 @@ rl.on("line", (line) => {
                 return send({ jsonrpc: "2.0", id: request.id, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: `supercuts-${app.profile.role}`, version: PACKAGE_VERSION } } });
             if (request.method === "notifications/initialized")
                 return;
-            const available = tools[app.profile.role].split(",").filter((name) => (remote || !name.startsWith("remote.")) && (app.profile.mock || memoryConfigured || !name.startsWith("memory.")) && (!name.startsWith("deal.") || mandate.version === "supercuts.mandate.v2") && (["status", "doctor"].includes(name) || mandate.allowedCommands.includes(name === "deal.reconcile" ? "deal.resume" : name)));
+            const available = tools[app.profile.role].split(",").filter((name) => (roleLease.acquired || name === "status") && (remote || !name.startsWith("remote.")) && (app.profile.mock || memoryConfigured || !name.startsWith("memory.")) && (!name.startsWith("deal.") || mandate.version === "supercuts.mandate.v2") && (["status", "doctor"].includes(name) || mandate.allowedCommands.includes(name === "deal.reconcile" ? "deal.resume" : name)));
             if (request.method === "tools/list")
                 return send({ jsonrpc: "2.0", id: request.id, result: { tools: available.map((name) => { const spec = toolSchema(name); return { name, description: spec.description, inputSchema: spec.inputSchema }; }) } });
             if (request.method === "tools/call") {
@@ -123,7 +136,7 @@ rl.on("line", (line) => {
                     const { validateToolArguments } = await import("./mandate.js");
                     validateToolArguments(spec, raw);
                     if (mandate.version !== "supercuts.mandate.v2" || !mandate.allowedCommands.includes(name === "deal.reconcile" ? "deal.resume" : name) || (name === "deal.execute" || name === "deal.resume") && Date.now() > mandate.expiresAt)
-                        throw new Error("deal tool is not authorized by an active v2 mandate");
+                        fail("DEAL_MANDATE_INACTIVE", "deal tool is not authorized by an active v2 mandate");
                     if (name === "deal.catalog")
                         data = { capabilities: (await new LiveDealPorts(app, mandate).catalog()).map(({ origin, registration }) => ({ origin, manifest: registration.manifest, manifestBlobId: registration.manifestBlobId })) };
                     else if (name === "deal.policy") {
@@ -151,25 +164,31 @@ rl.on("line", (line) => {
                         data = new DealJournal(app.store).get(String(raw.operationId));
                 }
                 else if (name.startsWith("remote.")) {
-                    if (!remote || !mandate.allowedCommands.includes(name) || Date.now() > mandate.expiresAt)
-                        throw new Error("remote buyer tool is not authorized or configured");
+                    const buyer = remote ?? fail("REMOTE_MANDATE_INACTIVE", "remote buyer tool is not configured");
+                    if (!mandate.allowedCommands.includes(name) || Date.now() > mandate.expiresAt)
+                        fail("REMOTE_MANDATE_INACTIVE", "remote buyer tool is not authorized by an active mandate");
+                    if (!["remote.catalog", "remote.rank-briefs"].includes(name) && raw.runId === undefined && process.env.SUPERCUTS_RUN_ID)
+                        raw.runId = process.env.SUPERCUTS_RUN_ID;
                     const spec = toolSchema(name);
                     const { validateToolArguments } = await import("./mandate.js");
                     validateToolArguments(spec, raw);
                     if (process.env.SUPERCUTS_RUN_ID && name !== "remote.catalog" && name !== "remote.rank-briefs" && raw.runId !== undefined && raw.runId !== process.env.SUPERCUTS_RUN_ID)
-                        throw new Error("remote tool run ID differs from this buyer demo run");
-                    data = name === "remote.catalog" ? await remote.catalog() :
-                        name === "remote.rank-briefs" ? await remote.rankBriefs(raw) :
-                            name === "remote.negotiate" ? await remote.negotiate(raw) :
-                                name === "remote.quote" ? await remote.quote(raw) :
-                                    name === "remote.purchase-brief" ? await remote.purchaseBrief(raw) :
-                                        name === "remote.agreement" ? await remote.agreement(raw) :
-                                            name === "remote.settle-analysis" ? await remote.settleAnalysis(raw) :
-                                                name === "remote.delivery" ? await remote.delivery(raw) :
-                                                    name === "remote.events" ? await remote.events(String(raw.runId)) : {};
+                        fail("SESSION_MISMATCH", "remote tool run ID differs from the active buyer session");
+                    data = name === "remote.catalog" ? await buyer.catalog() :
+                        name === "remote.rank-briefs" ? await buyer.rankBriefs(raw) :
+                            name === "remote.negotiate" ? await buyer.negotiate(raw) :
+                                name === "remote.quote" ? await buyer.quote(raw) :
+                                    name === "remote.purchase-brief" ? await buyer.purchaseBrief(raw) :
+                                        name === "remote.agreement" ? await buyer.agreement(raw) :
+                                            name === "remote.settle-analysis" ? await buyer.settleAnalysis(raw) :
+                                                name === "remote.delivery" ? await buyer.delivery(raw) :
+                                                    name === "remote.events" ? await buyer.events(String(raw.runId)) :
+                                                        name === "remote.research" ? await buyer.research({ operationId: String(raw["operation-id"]), runId: String(raw.runId), topic: String(raw.topic), budget: String(raw.budget) }) : {};
                 }
                 else
                     data = await executeMandated(app, mandate, name, raw);
+                if (name === "status")
+                    data = { ...data, session: { runId: process.env.SUPERCUTS_RUN_ID ?? null }, roleHomeLease: roleLease.acquired ? "acquired" : "busy", ...(roleLease.ownerPid ? { roleHomeOwnerPid: roleLease.ownerPid } : {}) };
                 logTool(name, data);
                 const result = { schemaVersion: "supercuts.v1", ok: true, command: name, data };
                 return send({ jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
@@ -182,6 +201,7 @@ rl.on("line", (line) => {
     }).catch((error) => send({ jsonrpc: "2.0", error: { code: -32603, message: error instanceof Error ? error.message : "Internal error" }, id: null }));
 });
 const close = () => { if (memoryTimer)
-    clearInterval(memoryTimer); app.close(); process.exit(0); };
+    clearInterval(memoryTimer); roleLease.release(); app.close(); process.exit(0); };
 process.on("SIGINT", close);
 process.on("SIGTERM", close);
+process.on("exit", () => roleLease.release());

package/dist/onboarding-doctor.js

@@ -42,8 +42,19 @@ export async function onboardingDoctor(home, sellerConfig) {
             }
             const endpoint = app.profile.live?.writeGrpcEndpoint ?? fail("LIVE_PROFILE_INVALID", "buyer write RPC is missing");
             const signer = String(runtime.data.signer ?? "");
-            const { balance } = await writeClient(endpoint).getBalance({ owner: signer, coinType: "0x2::sui::SUI" });
-            return { role: "buyer", healthy: true, runtime: runtime.data, approvedSellers: mandate.allowedCounterparties.length, nativeSuiMist: String(balance.balance), funded: BigInt(balance.balance) > 0n, ...(directoryListings !== undefined ? { directoryListings } : {}) };
+            const [{ balance }, shielded] = await Promise.all([
+                writeClient(endpoint).getBalance({ owner: signer, coinType: "0x2::sui::SUI" }),
+                app.execute("wallet.balance", {}),
+            ]);
+            const nativeSuiMist = String(balance.balance), shieldedMist = String(shielded.data.available ?? "0");
+            const checks = [
+                { id: "runtime", status: "ready", detail: "Pinned deployment, prover, RPC, and Walrus prerequisites verified." },
+                { id: "public-balance", status: BigInt(nativeSuiMist) > 0n ? "ready" : "action_required", detail: BigInt(nativeSuiMist) > 0n ? `${nativeSuiMist} MIST available.` : "Fund only this generated buyer address before a public payment." },
+                { id: "shielded-balance", status: BigInt(shieldedMist) > 0n ? "ready" : "action_required", detail: BigInt(shieldedMist) > 0n ? `${shieldedMist} MIST available in the experimental pool.` : "Create a buyer-owned pool deposit before a shielded deal." },
+                { id: "seller-approval", status: mandate.allowedCounterparties.length > 0 ? "ready" : "action_required", detail: mandate.allowedCounterparties.length > 0 ? `${mandate.allowedCounterparties.length} seller identity or identities approved.` : "Review and approve a signed seller capability locally." },
+                ...(directoryListings !== undefined ? [{ id: "directory", status: directoryListings > 0 ? "ready" : "action_required", detail: `${directoryListings} live directory listing or listings.` }] : []),
+            ];
+            return { role: "buyer", healthy: true, readyForPublicPayment: BigInt(nativeSuiMist) > 0n && mandate.allowedCounterparties.length > 0, readyForShieldedPayment: BigInt(shieldedMist) > 0n && mandate.allowedCounterparties.length > 0, runtime: runtime.data, checks, approvedSellers: mandate.allowedCounterparties.length, nativeSuiMist, shieldedMist, funded: BigInt(nativeSuiMist) > 0n, ...(directoryListings !== undefined ? { directoryListings } : {}) };
         }
         if (app.profile.role === "seller") {
             if (!sellerConfig)

package/dist/phase3.js

@@ -19,7 +19,7 @@ const V2_RELAYER = "0x405f473ed1f7f609b16d3d7dabc7cd04831cfc73b4a7fcebe9fa502d72
 const COIN = "0x2::sui::SUI";
 const WRITE = new Set(["wallet.deposit", "wallet.recover", "wallet.withdraw", "wallet.exit.queue", "wallet.exit.finalize", "offer.open", "offer.propose", "offer.counter", "offer.accept", "pay.shielded", "pay.x402", "resource.serve", "memory.remember", "disclose", "capability.publish", "settlement.plan", "settlement.approve-review", "memory.policy"]);
 const ROLE_COMMANDS = {
-    buyer: new Set(["status", "doctor", "capability.discover", "settlement.plan", "settlement.approve-review", "memory.policy", "wallet.deposit", "wallet.balance", "wallet.recover", "wallet.withdraw", "wallet.exit.queue", "wallet.exit.status", "wallet.exit.finalize", "offer.open", "offer.propose", "offer.accept", "offer.show", "pay.quote", "pay.shielded", "pay.x402", "pay.status", "resource.fetch", "memory.remember", "memory.recall", "memory.status", "memory.inventory", "remote.catalog", "remote.rank-briefs", "remote.negotiate", "remote.quote", "remote.purchase-brief", "remote.agreement", "remote.settle-analysis", "remote.delivery", "remote.events", "disclose"]),
+    buyer: new Set(["status", "doctor", "capability.discover", "settlement.plan", "settlement.approve-review", "memory.policy", "wallet.deposit", "wallet.balance", "wallet.recover", "wallet.withdraw", "wallet.exit.queue", "wallet.exit.status", "wallet.exit.finalize", "offer.open", "offer.propose", "offer.accept", "offer.show", "pay.quote", "pay.shielded", "pay.x402", "pay.status", "resource.fetch", "memory.remember", "memory.recall", "memory.status", "memory.inventory", "remote.catalog", "remote.rank-briefs", "remote.negotiate", "remote.quote", "remote.purchase-brief", "remote.agreement", "remote.settle-analysis", "remote.delivery", "remote.events", "remote.research", "disclose"]),
     seller: new Set(["status", "doctor", "capability.publish", "wallet.balance", "wallet.recover", "wallet.withdraw", "wallet.exit.queue", "wallet.exit.status", "wallet.exit.finalize", "offer.counter", "offer.show", "pay.status", "resource.serve", "resource.fetch", "memory.remember", "memory.recall", "memory.status", "memory.inventory"]),
     auditor: new Set(["status", "doctor", "audit.verify"]),
 };
@@ -444,6 +444,18 @@ export class Phase3App {
             fail("CAPABILITY_LIST_INVALID", "alternatives must be an array");
         for (const item of alternatives)
             validateCapabilityManifest(item);
+        const operationId = required(args, "operation-id"), mandate = this.planningMandate(args);
+        const persisted = this.store.db.prepare("SELECT plan_hash FROM settlement_plans WHERE operation_id=?").get(operationId);
+        if (persisted) {
+            const existing = this.storedPlan(persisted.plan_hash), manifests = [primary, ...alternatives];
+            const requestedAmount = typeof args["requested-amount"] === "string" ? BigInt(args["requested-amount"]) : BigInt(existing.manifestMinimum);
+            const boundedAmount = requestedAmount < BigInt(existing.manifestMinimum) ? BigInt(existing.manifestMinimum) : requestedAmount > BigInt(existing.maximumAmount) ? BigInt(existing.maximumAmount) : requestedAmount;
+            const requestedRail = args["requested-rail"] === "x402" || args["requested-rail"] === "shielded" ? args["requested-rail"] : undefined;
+            if (existing.mandateHash !== settlementMandateHash(mandate) || !manifests.some((manifest) => manifest.manifestHash === existing.manifestHash) || requestedRail && requestedRail !== existing.rail || args["privacy-hint"] === "shielded" && existing.rail !== "shielded" || boundedAmount.toString() !== existing.openingAmount) {
+                fail("OPERATION_ID_CONFLICT", "planning operation already identifies another immutable plan");
+            }
+            return existing;
+        }
         let recalled = this.recalledMockMemories();
         if (!this.profile.mock && this.store.getSecret("live:memory-config")) {
             const encoded = this.store.getSecret("live:memory-config");
@@ -467,7 +479,7 @@ export class Phase3App {
                 manual.destroy();
             }
         }
-        const plan = createSettlementPlan({ operationId: required(args, "operation-id"), mandate: this.planningMandate(args), manifests: [primary, ...alternatives], ...(typeof args["requested-amount"] === "string" ? { requestedAmount: args["requested-amount"] } : {}), ...(args["privacy-hint"] === "shielded" ? { privacyHint: "shielded" } : {}), ...(args["requested-rail"] === "x402" || args["requested-rail"] === "shielded" ? { requestedRail: args["requested-rail"] } : {}), recalled, maxMemoryDistance: this.profile.policy.maxMemoryDistance ?? 0.35 });
+        const plan = createSettlementPlan({ operationId, mandate, manifests: [primary, ...alternatives], ...(typeof args["requested-amount"] === "string" ? { requestedAmount: args["requested-amount"] } : {}), ...(args["privacy-hint"] === "shielded" ? { privacyHint: "shielded" } : {}), ...(args["requested-rail"] === "x402" || args["requested-rail"] === "shielded" ? { requestedRail: args["requested-rail"] } : {}), recalled, maxMemoryDistance: this.profile.policy.maxMemoryDistance ?? 0.35 });
         return this.persistPlan(plan);
     }
     typedMemory(args, provenance) {
@@ -691,8 +703,6 @@ export class Phase3App {
         const plan = this.storedPlan(supplied), rail = command === "pay.x402" ? "x402" : "shielded", now = Date.now();
         if (plan.status !== "approved" || plan.riskLevel === "review_required")
             fail("SETTLEMENT_PLAN_REVIEW_REQUIRED", "settlement plan requires owner review");
-        if (now >= plan.expiresAt)
-            fail("SETTLEMENT_PLAN_EXPIRED", "settlement plan has expired");
         if (plan.mandateHash !== settlementMandateHash(mandate))
             fail("SETTLEMENT_PLAN_MANDATE_MISMATCH", "owner mandate changed after planning");
         const operationId = required(args, "operation-id");
@@ -712,6 +722,8 @@ export class Phase3App {
         const bindingHash = hash(canonicalJson({ domain: "supercuts-settlement-execution-v1", binding })), existing = this.store.db.prepare("SELECT binding_hash FROM settlement_execution_bindings WHERE operation_id=? OR plan_hash=?").get(operationId, plan.planHash);
         if (existing && existing.binding_hash !== bindingHash)
             fail("SETTLEMENT_PLAN_CONSUMED", "plan or operation is already bound to another execution");
+        if (!existing && now >= plan.expiresAt)
+            fail("SETTLEMENT_PLAN_EXPIRED", "settlement plan has expired");
         if (!existing) {
             this.store.db.prepare("INSERT INTO settlement_execution_bindings(operation_id,plan_hash,binding_hash,binding_json,created_at) VALUES(?,?,?,?,?)").run(operationId, plan.planHash, bindingHash, canonicalJson(binding), now);
             this.store.db.prepare("UPDATE settlement_plans SET consumed_at=? WHERE plan_hash=?").run(now, plan.planHash);
@@ -819,6 +831,8 @@ export class Phase3App {
             this.enqueueVerifiedOutcome("settlement", required(args, "operation-id"), evidence, typeof args["plan-hash"] === "string" ? args["plan-hash"] : undefined, { counterparty: String(receipt.counterparty), asset: String(receipt.asset) });
             return output(command, receipt);
         }
+        if (command === "pay.status")
+            return output(command, await runtime.paymentStatus(required(args, "operation-id"), args.reconcile === true));
         if (command === "resource.serve") {
             const requestId = required(args, "request-id"), body = required(args, "body"), resource = { requestId, responseHash: hash(Buffer.from(body, "base64")), body, deliveryStatus: "ready" };
             record(this.store, "resource", requestId, resource);
@@ -1129,7 +1143,9 @@ export class Phase3App {
 export function output(command, data) { return { schemaVersion: "supercuts.v1", ok: true, command, data }; }
 export function errorOutput(error) {
     const known = error instanceof SupercutsError ? error : new SupercutsError("INTERNAL_ERROR", error instanceof Error ? error.message : "unknown error");
-    return { schemaVersion: "supercuts.v1", ok: false, error: { code: known.code, message: known.message, recovery: recovery(known.code) } };
+    const retryable = ["BROADCAST_UNRESOLVED", "DELIVERY_IN_PROGRESS", "DELIVERY_PENDING", "ONBOARDING_SERVICE_UNAVAILABLE", "SELLER_DIRECTORY_UNAVAILABLE", "WALRUS_WRITE_FAILED", "WALRUS_READ_FAILED", "X402_FACILITATOR_UNAVAILABLE"].includes(known.code);
+    const sameOperation = retryable || ["OPERATION_ID_CONFLICT", "DEAL_OPERATION_CONFLICT"].includes(known.code);
+    return { schemaVersion: "supercuts.v1", ok: false, error: { code: known.code, message: known.message, recovery: recovery(known.code), retryable, retryWithSameOperationId: sameOperation } };
 }
 function recovery(code) {
     if (code === "LOCAL_AUTH_REQUIRED")
@@ -1140,5 +1156,19 @@ function recovery(code) {
         return "change the request or update the owner-controlled profile policy";
     if (code === "ARTIFACT_HASH_MISMATCH")
         return "restore the pinned artifact or reinitialize with an audited manifest";
+    if (code === "SESSION_MISMATCH")
+        return "read status.session.runId and retry with that session, or omit runId on the v2 deal path";
+    if (code === "DEAL_MANDATE_INACTIVE")
+        return "renew the owner mandate locally, then resume the same deal operation ID";
+    if (code === "BROADCAST_UNRESOLVED")
+        return "reconcile or resume with the same operation ID; never create a replacement payment";
+    if (code === "DELIVERY_PENDING")
+        return "resume the same root operation ID; completed selection, payment, and agreement stages will not run again";
+    if (code === "X402_FACILITATOR_UNAVAILABLE")
+        return "the signed transaction remains journaled; resume the same operation ID after facilitator health recovers";
+    if (code === "OPERATION_ID_CONFLICT" || code === "DEAL_OPERATION_CONFLICT")
+        return "reuse the original exact input for this operation ID or start a deliberately new deal";
+    if (code === "X402_TRANSACTION_EXPIRY_INVALID")
+        return "run onboarding doctor against the configured Sui RPC and retry the same operation ID after compatibility is restored";
     return "inspect the stable error code and retry with corrected input";
 }

package/dist/remote-buyer.d.ts

@@ -1,6 +1,18 @@
 import { type CapabilityManifest } from "./capability.js";
 import { type AgentMandate } from "./mandate.js";
 import type { Phase3App } from "./phase3.js";
+export declare function analysisAgreementDraft(input: {
+    sessionId: string;
+    transcriptHash: string;
+    serviceHash: string;
+    paymentAmount: string;
+    buyerPublicKey: string[];
+    counterparty: string;
+    capabilityId: string;
+    manifestHash: string;
+    now?: number;
+    scalar?: () => string;
+}): Record<string, unknown>;
 interface Entry {
     manifest: CapabilityManifest;
     blobId: string;
@@ -62,6 +74,12 @@ export declare class RemoteBuyer {
         sessionId: string;
         operationId: string;
     }): Promise<Record<string, unknown>>;
+    research(input: {
+        operationId: string;
+        runId: string;
+        topic: string;
+        budget: string;
+    }): Promise<Record<string, unknown>>;
     events(runId: string): Promise<Record<string, unknown>>;
 }
 export {};

package/dist/remote-buyer.js

@@ -5,10 +5,23 @@ import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
 import { validateCapabilityManifest, verifySignedCapability } from "./capability.js";
 import { fail } from "./errors.js";
 import { executeMandated } from "./mandate.js";
+export function analysisAgreementDraft(input) {
+    const scalar = input.scalar ?? (() => BigInt(`0x${randomBytes(16).toString("hex")}`).toString());
+    return {
+        sessionId: input.sessionId, rail: "shielded", dealId: scalar(), revision: "1",
+        transcriptRootLo: BigInt(`0x${input.transcriptHash.slice(0, 32)}`).toString(),
+        transcriptRootHi: BigInt(`0x${input.transcriptHash.slice(32)}`).toString(),
+        serviceDigestLo: BigInt(`0x${input.serviceHash.slice(0, 32)}`).toString(),
+        serviceDigestHi: BigInt(`0x${input.serviceHash.slice(32)}`).toString(),
+        settlementNonceLo: scalar(), settlementNonceHi: scalar(), paymentAmount: input.paymentAmount,
+        blinding: scalar(), expiry: String((input.now ?? Date.now()) + 30 * 60_000),
+        buyerPublicKey: input.buyerPublicKey, counterparty: input.counterparty,
+        capabilityId: input.capabilityId, manifestHash: input.manifestHash,
+    };
+}
 import { decryptSessionMessage, encryptSessionMessage } from "./negotiation.js";
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 const num = (value, name) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : fail("SELLER_PREVIEW_INVALID", `${name} must be between zero and one`);
-const halves = (content) => { const hash = sha256(content); return [BigInt(`0x${hash.slice(0, 32)}`).toString(), BigInt(`0x${hash.slice(32)}`).toString()]; };
 export class RemoteBuyer {
     app;
     mandate;
@@ -192,10 +205,15 @@ export class RemoteBuyer {
             fail("BUYER_PRIVACY_REQUIRED", "saved owner privacy rule did not select shielded settlement");
         const publicKey = this.app.store.getSecret("identity:x25519-public")?.toString("base64url") ?? fail("IDENTITY_MISSING", "buyer delivery key is missing");
         const identity = (await this.app.execute("doctor", {})).data;
-        const [transcriptRootLo, transcriptRootHi] = [BigInt(`0x${String(negotiated.transcriptHash).slice(0, 32)}`).toString(), BigInt(`0x${String(negotiated.transcriptHash).slice(32)}`).toString()];
-        const [serviceDigestLo, serviceDigestHi] = halves(JSON.stringify({ capabilityId: input.capabilityId, briefHash: input.briefHash, artifactSha256, deliveryPublicKey: publicKey }));
-        const scalar = () => BigInt(`0x${randomBytes(16).toString("hex")}`).toString();
-        const draft = { dealId: scalar(), revision: "1", transcriptRootLo, transcriptRootHi, serviceDigestLo, serviceDigestHi, settlementNonceLo: scalar(), settlementNonceHi: scalar(), paymentAmount: entry.manifest.priceBand.minimum, blinding: scalar(), expiry: String(Date.now() + 30 * 60_000), buyerPublicKey: identity.babyJubPublicKey, counterparty: entry.manifest.sellerId, capabilityId: entry.manifest.capabilityId, manifestHash: entry.manifest.manifestHash };
+        const serviceHash = sha256(JSON.stringify({ capabilityId: input.capabilityId, briefHash: input.briefHash, artifactSha256, deliveryPublicKey: publicKey }));
+        this.app.store.db.exec("CREATE TABLE IF NOT EXISTS remote_buyer_agreements(session_id TEXT PRIMARY KEY,context_hash TEXT NOT NULL,draft_json TEXT NOT NULL,created_at INTEGER NOT NULL)");
+        const contextHash = sha256(JSON.stringify({ capabilityId: input.capabilityId, operationId: input.operationId, sessionId: input.sessionId, runId: input.runId, briefHash: input.briefHash, transcriptHash: negotiated.transcriptHash, serviceHash, artifactSha256 }));
+        const priorDraft = this.app.store.db.prepare("SELECT context_hash AS contextHash,draft_json AS draftJson FROM remote_buyer_agreements WHERE session_id=?").get(input.sessionId);
+        if (priorDraft && priorDraft.contextHash !== contextHash)
+            fail("AGREEMENT_SESSION_CONFLICT", "analysis session identifies a different agreement context");
+        const draft = priorDraft ? JSON.parse(priorDraft.draftJson) : analysisAgreementDraft({ sessionId: input.sessionId, transcriptHash: String(negotiated.transcriptHash), serviceHash, paymentAmount: entry.manifest.priceBand.minimum, buyerPublicKey: identity.babyJubPublicKey, counterparty: entry.manifest.sellerId, capabilityId: entry.manifest.capabilityId, manifestHash: entry.manifest.manifestHash });
+        if (!priorDraft)
+            this.app.store.db.prepare("INSERT INTO remote_buyer_agreements(session_id,context_hash,draft_json,created_at) VALUES(?,?,?,?)").run(input.sessionId, contextHash, JSON.stringify(draft), Date.now());
         const signed = await this.request("/v1/agreement", { method: "POST", body: JSON.stringify({ capabilityId: input.capabilityId, sessionId: input.sessionId, runId: input.runId, briefHash: input.briefHash, deliveryPublicKey: publicKey, agreement: Buffer.from(JSON.stringify(draft)).toString("base64url") }) });
         if (signed.artifactSha256 !== artifactSha256 || signed.capabilityId !== input.capabilityId || signed.sessionId !== input.sessionId)
             fail("AGREEMENT_BINDING_MISMATCH", "seller response changed the prepared artifact or session");
@@ -227,5 +245,41 @@ export class RemoteBuyer {
         const recorded = (await this.app.execute("resource.fetch", { "request-id": input.sessionId, "operation-id": input.operationId, response: artifact.toString("base64url") })).data;
         return { status: "delivered", sessionId: input.sessionId, artifactSha256: response.artifactSha256, body: artifact.toString("utf8"), record: { deliveryStatus: recorded.deliveryStatus, responseHash: recorded.responseHash } };
     }
+    async research(input) {
+        if (!input.operationId || input.operationId.length > 256 || !/^[1-9][0-9]*$/.test(input.budget))
+            fail("BUYER_WORKFLOW_INVALID", "research requires a stable operation ID and positive total budget");
+        this.app.store.db.exec("CREATE TABLE IF NOT EXISTS remote_research_workflows(operation_id TEXT PRIMARY KEY,input_hash TEXT NOT NULL,created_at INTEGER NOT NULL,updated_at INTEGER NOT NULL,completed_at INTEGER)");
+        const inputHash = sha256(JSON.stringify({ runId: input.runId, topic: input.topic, budget: input.budget })), existing = this.app.store.db.prepare("SELECT input_hash AS inputHash,completed_at AS completedAt FROM remote_research_workflows WHERE operation_id=?").get(input.operationId);
+        if (existing && existing.inputHash !== inputHash)
+            fail("DEAL_OPERATION_CONFLICT", "research operation ID identifies another topic, budget, or run");
+        if (!existing)
+            this.app.store.db.prepare("INSERT INTO remote_research_workflows(operation_id,input_hash,created_at,updated_at) VALUES(?,?,?,?)").run(input.operationId, inputHash, Date.now(), Date.now());
+        const checkpoint = async (stage, action) => {
+            const key = `research:${input.operationId}:${stage}`, prior = this.app.store.getSecret(key);
+            if (prior)
+                return JSON.parse(prior.toString());
+            const value = await action();
+            this.app.store.putSecretOnce(key, Buffer.from(JSON.stringify(value)));
+            this.app.store.db.prepare("UPDATE remote_research_workflows SET updated_at=? WHERE operation_id=?").run(Date.now(), input.operationId);
+            return value;
+        };
+        const child = (stage) => `research:${stage}:${sha256(`${input.operationId}:${stage}`).slice(0, 40)}`;
+        const ranked = await checkpoint("selection", () => this.rankBriefs({ topic: input.topic, budget: input.budget }));
+        const winnerCapabilityId = String(ranked.winner?.capabilityId ?? "");
+        const analysisCapabilityId = String(ranked.analysisCapabilityId ?? "");
+        if (!winnerCapabilityId || !analysisCapabilityId)
+            fail("ANALYSIS_UNAVAILABLE", "ranked catalog has no affordable brief and matching analysis");
+        const brief = await checkpoint("brief", () => this.purchaseBrief({ capabilityId: winnerCapabilityId, operationId: child("brief-payment"), requestId: child("brief-request"), runId: input.runId, task: `Sui research: ${input.topic}`, budget: input.budget }));
+        const briefHash = String(brief.artifactSha256);
+        const sessionId = child("analysis-session"), paymentOperationId = child("analysis-payment");
+        const agreement = await checkpoint("agreement", () => this.agreement({ capabilityId: analysisCapabilityId, operationId: paymentOperationId, sessionId, runId: input.runId, briefHash }));
+        const settlement = await checkpoint("settlement", () => this.settleAnalysis({ sessionId, operationId: paymentOperationId }));
+        const analysis = await checkpoint("delivery", async () => {
+            const value = await this.delivery({ sessionId, operationId: paymentOperationId });
+            return value.status === "delivered" ? value : fail("DELIVERY_PENDING", "analysis payment is finalized and seller delivery is still pending; resume the same research operation");
+        });
+        this.app.store.db.prepare("UPDATE remote_research_workflows SET completed_at=COALESCE(completed_at,?),updated_at=? WHERE operation_id=?").run(Date.now(), Date.now(), input.operationId);
+        return { operationId: input.operationId, state: "complete", replayed: Boolean(existing?.completedAt), selection: ranked, brief, agreement, settlement, analysis };
+    }
     async events(runId) { return this.request(`/v1/events?runId=${encodeURIComponent(runId)}`); }
 }

package/dist/role-lock.d.ts

@@ -0,0 +1,8 @@
+export interface RoleHomeLease {
+    acquired: boolean;
+    ownerPid?: number;
+    release(): void;
+}
+/** Best-effort process lease. SQLite still owns data integrity; this prevents
+ * multiple MCP event/memory workers from operating one role home at once. */
+export declare function acquireRoleHomeLease(home: string): RoleHomeLease;

package/dist/role-lock.js

@@ -0,0 +1,54 @@
+import { closeSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+function active(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Best-effort process lease. SQLite still owns data integrity; this prevents
+ * multiple MCP event/memory workers from operating one role home at once. */
+export function acquireRoleHomeLease(home) {
+    const path = join(home, ".mcp.lock"), token = randomUUID();
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            writeSync(fd, `${JSON.stringify({ pid: process.pid, token, startedAt: Date.now() })}\n`);
+            closeSync(fd);
+            let released = false;
+            return { acquired: true, release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        const value = JSON.parse(readFileSync(path, "utf8"));
+                        if (value.token === token)
+                            unlinkSync(path);
+                    }
+                    catch { /* already removed */ }
+                } };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let ownerPid;
+            try {
+                ownerPid = Number(JSON.parse(readFileSync(path, "utf8")).pid);
+            }
+            catch { /* stale malformed lock */ }
+            if (ownerPid !== undefined && active(ownerPid))
+                return { acquired: false, ownerPid, release: () => { } };
+            try {
+                unlinkSync(path);
+            }
+            catch { /* another process won the cleanup race */ }
+        }
+    }
+    return { acquired: false, release: () => { } };
+}

package/dist/seller-package.d.ts

@@ -0,0 +1,9 @@
+export declare function packageHostedSeller(input: {
+    home: string;
+    spec: string;
+    artifact: string;
+    metadata: string;
+    registration: string;
+    bundle: string;
+    contentType?: string;
+}): Promise<Record<string, unknown>>;

package/dist/seller-package.js

@@ -0,0 +1,50 @@
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { createCapabilityManifest, validateCapabilityPayload } from "./capability.js";
+import { fail } from "./errors.js";
+import { executeMandated, loadMandate } from "./mandate.js";
+import { Phase3App } from "./phase3.js";
+const ownerFile = (path) => {
+    const value = resolve(path);
+    if ((statSync(value).mode & 0o077) !== 0)
+        fail("SELLER_CONFIG_PERMISSIONS", `${value} must be owner-only`);
+    return value;
+};
+export async function packageHostedSeller(input) {
+    if (![input.home, input.spec, input.artifact, input.metadata, input.registration, input.bundle].every((value) => typeof value === "string" && value.length > 0))
+        fail("ARGUMENT_REQUIRED", "seller package requires --home, --spec, --artifact, --metadata, --registration, and --bundle");
+    const specPath = ownerFile(input.spec), artifactPath = ownerFile(input.artifact), metadataPath = ownerFile(input.metadata);
+    const artifact = readFileSync(artifactPath);
+    if (!artifact.length || artifact.length > 10 * 1024 * 1024)
+        fail("SELLER_ARTIFACT_INVALID", "hosted artifact must contain 1 byte to 10 MiB");
+    const spec = JSON.parse(readFileSync(specPath, "utf8"));
+    const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+    const home = resolve(input.home), app = new Phase3App(home);
+    try {
+        if (app.profile.role !== "seller" || app.profile.mock || app.profile.verifierVersion !== 2)
+            fail("SELLER_POOL_VERSION_MISMATCH", "hosted packaging requires a separate live v2 seller role home");
+        const encoded = app.store.getSecret("live:sui-private-key")?.toString() ?? fail("LIVE_CREDENTIAL_MISSING", "seller signer is missing");
+        const decoded = decodeSuiPrivateKey(encoded);
+        if (decoded.scheme !== "ED25519")
+            fail("SIGNER_UNSUPPORTED", "seller requires an ED25519 signer");
+        const signer = Ed25519Keypair.fromSecretKey(decoded.secretKey), manifest = createCapabilityManifest({ ...spec, sellerId: signer.toSuiAddress() });
+        validateCapabilityPayload(manifest, "output", metadata);
+        const published = await executeMandated(app, loadMandate(home), "capability.publish", { "operation-id": `publish-${manifest.manifestHash}`, manifest });
+        const manifestBlobId = String(published.blobId ?? "");
+        if (!manifestBlobId)
+            fail("WALRUS_PUBLISH_FAILED", "capability publication omitted a Walrus blob ID");
+        const transportPublicKey = app.store.getSecret("identity:x25519-public")?.toString("base64url") ?? fail("IDENTITY_MISSING", "seller transport key is missing");
+        const sellerSignature = (await signer.signPersonalMessage(Buffer.from(`${manifest.manifestHash}:${transportPublicKey}`))).signature;
+        const registration = { manifest, manifestBlobId, transportPublicKey, sellerSignature };
+        const registrationPath = resolve(input.registration), bundlePath = resolve(input.bundle);
+        writeFileSync(registrationPath, `${JSON.stringify(registration, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        const bundle = { sellers: [{ sellerId: manifest.sellerId, home, capabilities: [{ registrationFile: registrationPath, artifactFile: artifactPath, outputMetadata: metadata, contentType: input.contentType ?? "application/octet-stream" }] }] };
+        writeFileSync(bundlePath, `${JSON.stringify(bundle, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        return { sellerId: manifest.sellerId, capabilityId: manifest.capabilityId, manifestHash: manifest.manifestHash, manifestBlobId, registrationFile: registrationPath, provisioningBundle: bundlePath, nextCommand: `supercuts-seller-v2-provision ${JSON.stringify(bundlePath)}` };
+    }
+    finally {
+        app.close();
+    }
+}

package/dist/seller-service.js

@@ -182,7 +182,13 @@ export class SellerService {
         try {
             const url = new URL(request.url ?? "/", this.origin);
             if (request.method === "GET" && url.pathname === "/health")
-                return this.reply(response, this.#healthy ? 200 : 503, { ok: this.#healthy, service: "supercuts-sellers" });
+                return this.reply(response, this.#healthy ? 200 : 503, { ok: this.#healthy, service: "supercuts-sellers", buyerAccess: this.allowedBuyers.size ? "restricted" : "open" });
+            if (request.method === "GET" && url.pathname === "/v1/access") {
+                const buyerAddress = String(url.searchParams.get("buyerAddress") ?? "").toLowerCase();
+                if (!/^0x[0-9a-f]{64}$/.test(buyerAddress))
+                    fail("SELLER_REQUEST_INVALID", "buyerAddress is invalid");
+                return this.reply(response, 200, { buyerAddress, allowed: this.allowedBuyers.size === 0 || this.allowedBuyers.has(buyerAddress), mode: this.allowedBuyers.size ? "restricted" : "open" });
+            }
             if (request.method === "GET" && url.pathname === "/v2/directory/health") {
                 if (!this.directoryAggregator)
                     return this.reply(response, 503, { ok: false, service: "supercuts-directory", reason: "aggregator not configured" });
@@ -241,7 +247,7 @@ export class SellerService {
                     const sessionId = validId(input.sessionId, "sessionId"), runId = validId(input.runId, "runId"), buyerAddress = String(input.buyerAddress ?? ""), buyerPublicKey = String(input.buyerPublicKey ?? ""), ciphertext = String(input.ciphertext ?? ""), buyerSignature = String(input.buyerSignature ?? "");
                     if (!/^0x[0-9a-f]{64}$/.test(buyerAddress) || buyerPublicKey.length > 1024 || ciphertext.length > 16384 || !ciphertext || !buyerSignature)
                         fail("SELLER_REQUEST_INVALID", "buyer identity or encrypted offer is invalid");
-                    if (!this.allowedBuyers.has(buyerAddress))
+                    if (this.allowedBuyers.size > 0 && !this.allowedBuyers.has(buyerAddress))
                         fail("SELLER_BUYER_FORBIDDEN", "buyer is outside the seller service allowlist");
                     const signedBytes = Buffer.from(`${sessionId}:${capabilityId}:${buyerPublicKey}:${sha256(Buffer.from(ciphertext, "base64"))}`);
                     if (!(await isValidPersonalMessageSignature(signedBytes, buyerSignature, { address: buyerAddress })))
@@ -410,7 +416,7 @@ if (process.argv[1] && import.meta.url.endsWith(process.argv[1])) {
     const required = (key) => process.env[key] ?? fail("SELLER_CONFIG_MISSING", `${key} is required`);
     const port = Number(process.env.PORT ?? "3000");
     const origin = required("SELLER_ORIGIN");
-    SellerService.create({ db: new SellerDatabase(required("SUPABASE_URL"), required("SUPABASE_SERVICE_ROLE_KEY")), snapshotKey: required("SELLER_STATE_KEY"), origin, facilitatorUrl: required("FACILITATOR_URL"), facilitatorKey: required("FACILITATOR_SHARED_KEY"), allowedBuyers: new Set(required("SELLER_ALLOWED_BUYERS").split(",")), claudeKey: required("CLAUDE_API_KEY"), ...(process.env.DIRECTORY_WALRUS_AGGREGATOR ? { directoryAggregator: process.env.DIRECTORY_WALRUS_AGGREGATOR } : {}) })
+    SellerService.create({ db: new SellerDatabase(required("SUPABASE_URL"), required("SUPABASE_SERVICE_ROLE_KEY")), snapshotKey: required("SELLER_STATE_KEY"), origin, facilitatorUrl: required("FACILITATOR_URL"), facilitatorKey: required("FACILITATOR_SHARED_KEY"), allowedBuyers: new Set((process.env.SELLER_ALLOWED_BUYERS ?? "").split(",").map((item) => item.trim().toLowerCase()).filter(Boolean)), claudeKey: required("CLAUDE_API_KEY"), ...(process.env.DIRECTORY_WALRUS_AGGREGATOR ? { directoryAggregator: process.env.DIRECTORY_WALRUS_AGGREGATOR } : {}) })
         .then((service) => { const server = service.createServer(); server.listen(port, "0.0.0.0"); const close = () => server.close(() => { service.close(); process.exit(0); }); process.on("SIGINT", close); process.on("SIGTERM", close); })
         .catch((error) => { process.stderr.write(`${error instanceof Error ? error.message : "seller service failed"}\n`); process.exitCode = 1; });
 }

package/dist/x402-resource-service.d.ts

@@ -11,6 +11,8 @@ export interface X402ResourceServiceConfig {
     payTo: string;
     amount: string;
     maxTimeoutSeconds?: number;
+    /** Bounded retry schedule for transient facilitator cold starts. */
+    facilitatorRetryDelaysMs?: number[];
 }
 /** Seller-owned standard x402 v2 exact resource with additional request-binding replay protection. */
 export declare class X402ResourceService {