@supercuts-walrus/backend 0.1.0 → 0.1.2

package/dist/live-runtime.js

@@ -10,6 +10,38 @@ import { buildDeposit, buildPrivateTransfer, buildWithdraw, writeClient } from "
 import { V2ExitQueue } from "./v2-exits.js";
 import { TatumLedger } from "./tatum.js";
 import { paymentBindingBytes, requirementsHash } from "./x402.js";
+export function x402ResourceFailure(status, response) {
+    const fallback = `paid resource returned ${status}`;
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(response).toString("utf8"));
+    }
+    catch {
+        return fallback;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return fallback;
+    const record = value, code = typeof record.error === "string" ? record.error.replace(/\s+/g, " ").slice(0, 128) : "", message = typeof record.message === "string" ? record.message.replace(/\s+/g, " ").slice(0, 512) : "";
+    return code || message ? `${fallback}: ${[code, message].filter(Boolean).join(": ")}` : fallback;
+}
+export function timestampExpirationUnsupported(value) {
+    const messages = [];
+    const visit = (item, depth = 0) => {
+        if (depth > 3 || item == null)
+            return;
+        if (typeof item === "string")
+            messages.push(item);
+        else if (item instanceof Error) {
+            messages.push(item.message);
+            visit(item.cause, depth + 1);
+        }
+        else if (typeof item === "object")
+            for (const nested of Object.values(item))
+                visit(nested, depth + 1);
+    };
+    visit(value);
+    return messages.some((message) => /timestamp-based transaction expiration is not yet supported|timestamp.*expiration.*not supported/i.test(message));
+}
 const hex = (value) => value.toString(16).padStart(64, "0");
 const bytes32 = (value) => Buffer.from(hex(value), "hex");
 const hash = (value) => createHash("sha256").update(value).digest("hex");
@@ -57,8 +89,8 @@ export class LiveRuntime {
         const engine = await ProtocolEngine.create({ deploymentDomain: profile.live.deploymentDomain, poolId: profile.poolId, coinTypeHash: profile.live.coinTypeHash, verifierVersion: profile.verifierVersion, initialRoot: profile.live.initialRoot });
         return new LiveRuntime(profile, store, new TatumLedger(profile.live.tatumGrpcEndpoint, tatumKey), Ed25519Keypair.fromSecretKey(decoded.secretKey), engine);
     }
-    async doctor() {
-        const artifacts = this.prover.doctor();
+    async doctor(proofsRequired = true) {
+        const artifacts = proofsRequired ? this.prover.doctor() : { rapidSnark: false, artifacts: {} };
         const [service, suiObject] = await Promise.all([this.tatum.getServiceInfo(), this.client.getObject({ objectId: this.profile.poolId, include: { json: true } })]);
         if (!suiObject.object)
             fail("POOL_OBJECT_MISSING", "pinned Testnet pool object is unavailable; check the Sui write RPC and deployment config");
@@ -67,7 +99,7 @@ export class LiveRuntime {
         const babySeed = this.store.getSecret("identity:babyjub-seed") ?? fail("IDENTITY_MISSING", "BabyJub identity is missing");
         const identity = this.engine.identity(babySeed);
         const fixes = [];
-        if (!artifacts.rapidSnark)
+        if (proofsRequired && !artifacts.rapidSnark)
             fixes.push("Set an executable RapidSnark path in the role profile for v2 proofs.");
         if (!this.profile.live.walrusPublisherUrl)
             fixes.push("Configure the Walrus publisher URL for capability and transcript writes.");
@@ -85,9 +117,7 @@ export class LiveRuntime {
                 fixes.push(`Walrus ${name} is unreachable; check the configured URL and network access.`);
             }
         }
-        if (this.profile.role === "buyer" && !this.store.getSecret("live:memory-config"))
-            fixes.push("Configure an owner-only Walrus Memory file using the local 1536-dimensional embedding adapter.");
-        return { healthy: true, readyForDemo: fixes.length === 0, fixes, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
+        return { role: this.profile.role, network: "testnet", packageId: this.profile.packageId, poolId: this.profile.poolId, asset: this.profile.coinType, verifierVersion: this.profile.verifierVersion, keyPermissions: "owner-only", rpc: this.profile.live.writeGrpcEndpoint, healthy: true, readyForDemo: fixes.length === 0, fixes, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), memoryConfigured: Boolean(this.store.getSecret("live:memory-config")), proofsRequired, rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
     }
     async balance() {
         const state = await this.index.sync();
@@ -165,6 +195,29 @@ export class LiveRuntime {
     async confirmTatum(digest, checkpoint) {
         assertTatumFinality(await this.tatum.getTransaction(digest), digest, checkpoint);
     }
+    async paymentStatus(operationId, reconcile = false) {
+        const row = this.store.db.prepare("SELECT digest,status,updated_at AS updatedAt FROM live_signed_transactions WHERE operation_id=?").get(operationId);
+        if (!row)
+            fail("OPERATION_NOT_FOUND", "payment operation was not found in the live transaction journal");
+        const payment = row;
+        const context = this.store.db.prepare("SELECT kind FROM live_operation_context WHERE operation_id=?").get(operationId);
+        const delivered = Boolean(this.store.db.prepare("SELECT 1 FROM live_x402_deliveries WHERE operation_id=?").get(operationId));
+        if (payment.status === "finalized")
+            return { operationId, status: "finalized", transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "not-applicable-or-pending", finalized: true, safeToResumeSameOperationId: true };
+        if (!reconcile)
+            return { operationId, status: payment.status, transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "pending", finalized: false, chainStatus: "unchecked", safeToResumeSameOperationId: true };
+        let transaction;
+        try {
+            transaction = await this.client.waitForTransaction({ digest: payment.digest, timeout: 5_000, include: { effects: true } });
+        }
+        catch {
+            return { operationId, status: payment.status, transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "pending", finalized: false, chainStatus: "not-found-or-pending", safeToResumeSameOperationId: true };
+        }
+        const checkpoint = assertSuiFinality(transaction, payment.digest);
+        await this.confirmTatum(payment.digest, checkpoint);
+        this.store.db.prepare("UPDATE live_signed_transactions SET status='finalized',updated_at=? WHERE operation_id=?").run(Date.now(), operationId);
+        return { operationId, status: "finalized", transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "pending", finalized: true, checkpoint, tatumVerified: true, safeToResumeSameOperationId: true };
+    }
     prepareOpening(opening, role, operationId, leaves) {
         const commitment = hex(opening.commitment), key = `note:${commitment}`;
         this.store.db.exec("BEGIN IMMEDIATE");
@@ -534,21 +587,40 @@ export class LiveRuntime {
             fail("POLICY_ASSET_FORBIDDEN", "challenged asset is not allowed");
         if (!this.profile.policy.allowedCounterparties.includes(payTo))
             fail("POLICY_COUNTERPARTY_FORBIDDEN", "challenged payee is not allowed");
-        const extra = requirements.extra, requestId = String(extra?.requestId ?? operationId), challengeOperationId = String(extra?.operationId ?? operationId), nonce = String(extra?.nonce ?? "");
-        if (challengeOperationId !== operationId || !nonce || String(extra?.requirementsHash ?? "") !== requirementsHash({ ...requirements, extra: { requestId, operationId: challengeOperationId, nonce } }))
-            fail("X402_CHALLENGE_INVALID", "challenge does not bind this operation and request");
+        const extra = requirements.extra, requestId = String(extra?.requestId ?? operationId), challengeOperationId = String(extra?.operationId ?? operationId), nonce = String(extra?.nonce ?? ""), expiresAt = Number(extra?.expiresAt);
+        const unsignedRequirements = { ...requirements, extra: { requestId, operationId: challengeOperationId, nonce, expiresAt } };
+        if (challengeOperationId !== operationId || !nonce || !Number.isSafeInteger(expiresAt) || expiresAt <= Date.now() || String(extra?.requirementsHash ?? "") !== requirementsHash(unsignedRequirements))
+            fail("X402_CHALLENGE_INVALID", "challenge does not bind this operation, request, and expiry");
         bind?.({ amount: amount.toString(), counterparty: payTo, asset, endpoint: resourceUrl, requestId, requirementsHash: String(extra?.requirementsHash) });
         const tx = new (await import("@mysten/sui/transactions")).Transaction();
         tx.transferObjects([tx.coin({ balance: amount, type: asset })], payTo);
+        tx.setSender(this.signer.toSuiAddress());
+        await tx.build({ client: this.client });
+        const resolvedExpiration = tx.getData().expiration;
+        const validity = resolvedExpiration?.$kind === "ValidDuring" ? resolvedExpiration.ValidDuring : fail("X402_TRANSACTION_EXPIRY_INVALID", "Sui did not resolve a bounded transaction validity window");
+        if (validity.minEpoch == null || validity.maxEpoch == null || !validity.chain || validity.nonce == null)
+            fail("X402_TRANSACTION_EXPIRY_INVALID", "Sui resolved an incomplete transaction validity window");
+        tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: expiresAt, chain: validity.chain, nonce: validity.nonce } });
+        try {
+            const probe = await this.client.simulateTransaction({ transaction: tx, include: { effects: true } });
+            const simulated = probe.Transaction ?? probe.FailedTransaction;
+            if (!simulated?.status.success && timestampExpirationUnsupported(simulated?.status?.error))
+                tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: null, chain: validity.chain, nonce: validity.nonce } });
+        }
+        catch (error) {
+            if (!timestampExpirationUnsupported(error))
+                throw error;
+            tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: null, chain: validity.chain, nonce: validity.nonce } });
+        }
         const legacyIntentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString() }));
         const intentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString(), requestId, requirementsHash: String(extra?.requirementsHash) })), signed = await this.signed(operationId, intentHash, tx, legacyIntentHash);
-        const unsignedBinding = { requestId, nonce, requirementsHash: requirementsHash({ ...requirements, extra: { requestId, operationId: challengeOperationId, nonce } }), transactionDigest: signed.digest, payer: this.signer.toSuiAddress() };
+        const unsignedBinding = { requestId, nonce, requirementsHash: requirementsHash(unsignedRequirements), transactionDigest: signed.digest, payer: this.signer.toSuiAddress() };
         const payerSignature = (await this.signer.signPersonalMessage(paymentBindingBytes(unsignedBinding))).signature;
         const paymentPayload = { x402Version: 2, resource, accepted: requirements, payload: { signature: signed.signature, transaction: Buffer.from(signed.transaction).toString("base64") } };
         const paid = await fetch(paymentUrl, { redirect: "error", headers: { "payment-signature": Buffer.from(JSON.stringify(paymentPayload)).toString("base64"), "x-supercuts-binding": Buffer.from(JSON.stringify({ ...unsignedBinding, payerSignature })).toString("base64") }, signal: AbortSignal.timeout(60_000) });
         const response = Buffer.from(await paid.arrayBuffer());
         if (!paid.ok)
-            fail("X402_DELIVERY_FAILED", `paid resource returned ${paid.status}`);
+            fail("X402_DELIVERY_FAILED", x402ResourceFailure(paid.status, response));
         const settlementHeader = paid.headers.get("payment-response") ?? fail("X402_SETTLEMENT_INVALID", "payment-response header is missing");
         let settlement;
         try {

package/dist/live-seller-transport.js

@@ -97,6 +97,8 @@ export class LiveSellerTransport {
     async handle(request, response) {
         try {
             const url = new URL(request.url ?? "/", this.config.origin);
+            if (request.method === "GET" && url.pathname === "/health")
+                return this.respond(response, 200, { ok: true, service: "supercuts-seller", capabilities: this.runtime.catalog().length });
             if (request.method === "GET" && url.pathname === "/v2/catalog")
                 return this.respond(response, 200, { capabilities: this.runtime.catalog() });
             if (request.method === "POST" && url.pathname === "/v2/prepare")
@@ -108,7 +110,9 @@ export class LiveSellerTransport {
                     if (url.pathname.startsWith(`${(resource.config.pathPrefix ?? "/capability").replace(/\/$/, "")}/`))
                         return resource.handle(request, response);
             }
-            return this.respond(response, 404, { error: "NOT_FOUND" });
+            if (request.method === "GET" && [...this.#registrations.values()].some((item) => url.pathname === new URL(item.manifest.endpoint).pathname))
+                return this.respond(response, 404, { error: "NEGOTIATION_REQUIRED", message: "Protected resource URLs are issued for a negotiated session." });
+            return this.respond(response, 404, { error: "NOT_FOUND", message: "Seller route was not found." });
         }
         catch (error) {
             const known = error instanceof SupercutsError ? error : new SupercutsError("SELLER_REQUEST_FAILED", "seller request failed");

package/dist/mandate.js

@@ -14,8 +14,8 @@ const definitions = {
     "wallet.balance": object({}, [], false, "Read event-derived private-note balance."),
     "wallet.recover": object({ commitment: string("Optional payment-note commitment."), amount: string("Optional matching amount.", { pattern: "^[1-9][0-9]*$" }) }, [], true, "Recover notes from pinned finalized pool events."),
     "wallet.withdraw": object({ commitment: string("Note commitment to spend."), recipient: string("Sui recipient address.") }, ["commitment"], true, "Withdraw one owned shielded note."),
-    "wallet.exit.queue": object({ commitment: string("Recovered note commitment."), amount: string("Public exit amount in MIST.", { pattern: "^[1-9][0-9]*$" }), "exact-exit": boolean("Approve a nonstandard amount that is publicly visible."), "window-start": string("Exit window start as Unix milliseconds."), "window-end": string("Exit window end as Unix milliseconds.") }, ["commitment", "amount", "window-start", "window-end"], true, "Queue a v2 exit with a fresh payout address and owner-selected delayed window."),
-    "wallet.exit.status": object({ "operation-id": string("Queued exit operation ID.") }, ["operation-id"], false, "Read a queued v2 exit without exposing its proof or note opening."),
+    "wallet.exit.queue": object({ commitment: string("Recovered note commitment."), amount: string("Public exit amount in MIST.", { pattern: "^[1-9][0-9]*$" }), "exact-exit": boolean("Approve a nonstandard amount that is publicly visible."), "window-start": string("Exit window start as Unix milliseconds."), "window-end": string("Exit window end as Unix milliseconds.") }, ["commitment", "amount", "window-start", "window-end"], true, "Queue a delayed pool exit to a fresh payout address."),
+    "wallet.exit.status": object({ "operation-id": string("Queued exit operation ID.") }, ["operation-id"], false, "Read a queued pool exit without exposing its proof or note opening."),
     "wallet.exit.finalize": object({ "exit-id": string("Queued exit operation ID."), digest: string("Finalized relayer transaction digest.") }, ["exit-id", "digest"], true, "Verify Sui and Tatum exit evidence and reconcile the owner note journal."),
     "offer.open": object({ session: string("Optional stable negotiation session ID.") }, [], true, "Open a durable negotiation session."),
     "offer.propose": object({ session: string("Negotiation session ID."), revision: string("Positive revision.", { pattern: "^[1-9][0-9]*$" }), terms: string("Plain-language or canonical JSON terms.") }, ["session", "revision", "terms"], true, "Submit an offer revision."),
@@ -24,7 +24,7 @@ const definitions = {
     "offer.show": object({ session: string("Negotiation session ID.") }, ["session"], false, "Read the latest durable offer revision."),
     "pay.quote": object({ rail: string("Requested settlement rail.", { enum: ["x402", "shielded"] }), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved payee."), asset: string("Sui coin type.") }, ["rail", "amount", "counterparty"], false, "Evaluate payment policy without signing."),
     "pay.shielded": object({ session: string("Accepted agreement session."), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved seller."), asset: string("Sui coin type."), "request-id": string("Bound delivery request ID."), "broadcast-only": boolean("Stop after broadcast for recovery testing."), "plan-hash": string("Approved settlement plan hash.", { pattern: "^[0-9a-f]{64}$" }) }, [], true, "Settle one accepted agreement through the experimental shielded pool."),
-    "pay.x402": object({ "resource-url": string("Seller-owned protected resource URL."), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved public payee."), asset: string("Sui coin type."), "request-id": string("Bound delivery request ID."), "broadcast-only": boolean("Stop after broadcast for recovery testing."), "plan-hash": string("Approved settlement plan hash.", { pattern: "^[0-9a-f]{64}$" }) }, [], true, "Complete a standard x402 v2 exact Sui payment challenge."),
+    "pay.x402": object({ "resource-url": string("Seller-owned protected resource URL."), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved public payee."), asset: string("Sui coin type."), "request-id": string("Bound delivery request ID."), "broadcast-only": boolean("Stop after broadcast for recovery testing."), "plan-hash": string("Approved settlement plan hash.", { pattern: "^[0-9a-f]{64}$" }) }, [], true, "Make a public Sui payment through an x402 exact payment challenge."),
     "pay.status": object({ "operation-id": string("Payment operation identity."), reconcile: boolean("Reconcile an ambiguous broadcast.") }, ["operation-id"], false, "Read or reconcile a previously journaled payment."),
     "resource.serve": object({ "request-id": string("Unique request identity."), body: string("Base64-encoded artifact bytes.") }, ["request-id", "body"], true, "Bind one generated artifact to one request."),
     "resource.fetch": object({ "request-id": string("Bound request identity."), "operation-id": string("Finalized payment operation."), response: string("Base64-encoded paid response.") }, ["request-id", "operation-id", "response"], false, "Record delivery separately from payment evidence."),
@@ -43,13 +43,14 @@ const definitions = {
     "deal.delivery": object({ dealId: string("Existing delivered deal ID.") }, ["dealId"], false, "Read a verified paid artifact from the buyer's encrypted journal."),
     "remote.catalog": object({}, [], false, "Discover the signed remote seller catalog through Walrus."),
     "remote.rank-briefs": object({ budget: string("Total budget in MIST.", { pattern: "^[1-9][0-9]*$" }), topic: string("Sui research topic.", { maxLength: 256 }) }, ["budget", "topic"], false, "Compare eligible market briefs with a visible quality and price rubric."),
-    "remote.negotiate": object({ capabilityId: string("Selected capability ID."), sessionId: string("Stable negotiation session ID."), runId: string("Demo run ID."), task: string("Private task summary.", { maxLength: 512 }), opening: string("Opening amount in MIST.", { pattern: "^[1-9][0-9]*$" }), maximum: string("Maximum amount in MIST.", { pattern: "^[1-9][0-9]*$" }), briefHash: string("Purchased brief SHA-256 if analyzing it.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "sessionId", "runId", "task", "opening", "maximum"], false, "Exchange an encrypted buyer offer and seller response through Walrus."),
-    "remote.quote": object({ capabilityId: string("Selected capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Demo run ID."), task: string("Brief task summary.", { maxLength: 512 }), briefHash: string("Purchased brief SHA-256 for an analysis variant.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task"], false, "Ask a remote seller for its exact x402 quote and protected resource URL."),
-    "remote.purchase-brief": object({ capabilityId: string("Selected market brief capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Demo run ID."), task: string("Brief task summary.", { maxLength: 512 }), budget: string("Maximum brief spend in MIST.", { pattern: "^[1-9][0-9]*$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task", "budget"], false, "Plan, buy, verify, and deliver the selected market brief through x402."),
-    "remote.agreement": object({ capabilityId: string("Analysis capability ID."), operationId: string("Stable shielded payment operation ID."), sessionId: string("Stable negotiation session ID."), runId: string("Demo run ID."), briefHash: string("Delivered brief SHA-256.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "sessionId", "runId", "briefHash"], false, "Request and accept a seller-signed analysis agreement bound to the purchased brief and saved privacy rule."),
+    "remote.negotiate": object({ capabilityId: string("Selected capability ID."), sessionId: string("Stable negotiation session ID."), runId: string("Run ID."), task: string("Private task summary.", { maxLength: 512 }), opening: string("Opening amount in MIST.", { pattern: "^[1-9][0-9]*$" }), maximum: string("Maximum amount in MIST.", { pattern: "^[1-9][0-9]*$" }), briefHash: string("Purchased brief SHA-256 if analyzing it.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "sessionId", "runId", "task", "opening", "maximum"], false, "Exchange an encrypted buyer offer and seller response through Walrus."),
+    "remote.quote": object({ capabilityId: string("Selected capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Run ID."), task: string("Brief task summary.", { maxLength: 512 }), briefHash: string("Purchased brief SHA-256 for an analysis variant.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task"], false, "Ask a remote seller for its exact x402 quote and protected resource URL."),
+    "remote.purchase-brief": object({ capabilityId: string("Selected market brief capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Run ID."), task: string("Brief task summary.", { maxLength: 512 }), budget: string("Maximum brief spend in MIST.", { pattern: "^[1-9][0-9]*$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task", "budget"], false, "Plan, buy, verify, and deliver the selected market brief through x402."),
+    "remote.agreement": object({ capabilityId: string("Analysis capability ID."), operationId: string("Stable shielded payment operation ID."), sessionId: string("Stable negotiation session ID."), runId: string("Run ID."), briefHash: string("Delivered brief SHA-256.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "sessionId", "runId", "briefHash"], false, "Request and accept a seller-signed analysis agreement bound to the purchased brief and saved privacy rule."),
     "remote.settle-analysis": object({ sessionId: string("Accepted analysis session ID."), operationId: string("Stable shielded payment operation ID.") }, ["sessionId", "operationId"], false, "Settle the accepted analysis agreement through the approved shielded pool plan."),
     "remote.delivery": object({ sessionId: string("Accepted analysis session ID."), operationId: string("Finalized shielded payment operation ID.") }, ["sessionId", "operationId"], false, "Recover the seller payment and decrypt the delivered analysis."),
-    "remote.events": object({ runId: string("Demo run ID.") }, ["runId"], false, "Read safe remote seller activity for the demo."),
+    "remote.events": object({ runId: string("Run ID.") }, ["runId"], false, "Read redacted remote seller activity for the run."),
+    "remote.research": object({ topic: string("Sui research topic.", { maxLength: 256 }), budget: string("Total workflow budget in MIST.", { pattern: "^[1-9][0-9]*$" }), runId: string("Optional active run ID; normally supplied by the MCP session.") }, ["topic", "budget"], true, "Rank, purchase, and deliver a public Sui brief plus its matching privacy-aware analysis using one resumable operation."),
     disclose: object({ "deal-id": string("Deal scope."), auditor: string("Designated auditor identity."), "payment-digest": string("Finalized payment digest."), "transcript-root": string("Authenticated agreement transcript root.") }, ["deal-id", "auditor", "payment-digest", "transcript-root"], true, "Create a deal- and auditor-scoped disclosure package."),
     "audit.verify": object({ package: string("Seal ciphertext or mock disclosure package."), auditor: string("This auditor identity."), "deal-id": string("Exact deal scope.") }, ["package", "auditor", "deal-id"], false, "Verify agreement and payment only; delivery remains a separate observation."),
 };
@@ -124,7 +125,7 @@ export async function executeMandated(app, mandate, command, raw) {
         fail("MANDATE_COMMAND_FORBIDDEN", `mandate does not allow ${command}`);
     const args = {};
     for (const [key, value] of Object.entries(raw))
-        args[key] = typeof value === "boolean" ? value : typeof value === "string" ? value : Buffer.from(JSON.stringify(value)).toString("base64url");
+        args[key] = typeof value === "boolean" ? value : typeof value === "string" ? value : Buffer.from(canonical(value)).toString("base64url");
     if (!spec.mutating)
         return (await app.execute(command, args)).data;
     const operationId = String(raw["operation-id"]), journalOperationId = command === "settlement.plan" ? `settlement.plan:${operationId}` : operationId;

package/dist/mcp-bootstrap.js

@@ -12,6 +12,13 @@ if (existsSync(join(home, "profile.json"))) {
 else {
     const send = (value) => process.stdout.write(`${JSON.stringify(value)}\n`);
     const rl = createInterface({ input: process.stdin });
+    let promoting = false;
+    const promote = () => {
+        if (promoting)
+            return;
+        promoting = true;
+        setImmediate(() => { rl.close(); void import("./mcp.js"); });
+    };
     rl.on("line", (line) => {
         if (Buffer.byteLength(line) > 1024 * 1024)
             return send({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Request exceeds 1 MiB" } });
@@ -29,11 +36,26 @@ else {
         if (request.method === "notifications/initialized")
             return;
         if (request.method === "tools/list")
-            return send({ jsonrpc: "2.0", id: request.id, result: { tools: [{ name: "setup.status", description: "Explain how the owner completes one-time buyer setup locally. Do not request secrets in chat.", inputSchema: { type: "object", properties: {}, additionalProperties: false } }] } });
+            return send({ jsonrpc: "2.0", id: request.id, result: { tools: [
+                        { name: "setup.status", description: "Explain how the owner completes one-time buyer or seller setup locally. Do not request secrets in chat.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+                        { name: "setup.refresh", description: "Reload this MCP connection after the owner completes local setup.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+                    ] } });
         if (request.method === "tools/call" && request.params?.name === "setup.status") {
-            const result = { schemaVersion: "supercuts.setup.v1", ok: true, configured: false, home, nextStep: `Run supercuts setup buyer --home ${JSON.stringify(home)} in a terminal, then restart this MCP connection. The command asks for policy limits, seller origins and local credential file paths. Do not paste keys or tokens into Codex.` };
+            const configured = existsSync(join(home, "profile.json"));
+            const result = { schemaVersion: "supercuts.setup.v1", ok: true, configured, home, nextStep: configured ? "Call setup.refresh to load the configured role tools without restarting the connector." : `Run supercuts onboard buyer --home ${JSON.stringify(home)} or supercuts onboard seller --home ${JSON.stringify(home)} in a terminal, then call setup.refresh. Use a separate owner-only home for every role and identity. Do not paste keys or tokens into Codex.` };
             return send({ jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
         }
+        if (request.method === "tools/call" && request.params?.name === "setup.refresh") {
+            if (!existsSync(join(home, "profile.json"))) {
+                const result = { schemaVersion: "supercuts.setup.v1", ok: false, error: { code: "SETUP_REQUIRED", message: "role setup is not complete", recovery: `Run supercuts onboard buyer --home ${JSON.stringify(home)} or supercuts onboard seller --home ${JSON.stringify(home)} locally, then retry setup.refresh.` } };
+                return send({ jsonrpc: "2.0", id: request.id, result: { isError: true, content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
+            }
+            const result = { schemaVersion: "supercuts.setup.v1", ok: true, configured: true, reloading: true };
+            send({ jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
+            send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+            promote();
+            return;
+        }
         return send({ jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "Method not found" } });
     });
 }

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

@@ -19,10 +19,10 @@ export async function onboardingDoctor(home, sellerConfig) {
     try {
         if (app.profile.mock)
             fail("LIVE_PROFILE_REQUIRED", "onboarding doctor requires a live Testnet role home");
-        const runtime = await app.execute("doctor", {});
-        if (runtime.data.readyForDemo === false)
-            fail("ONBOARDING_RUNTIME_NOT_READY", "live runtime doctor reports missing prerequisites");
         if (app.profile.role === "buyer") {
+            const runtime = await app.execute("doctor", {});
+            if (runtime.data.readyForDemo === false)
+                fail("ONBOARDING_RUNTIME_NOT_READY", "live runtime doctor reports missing prerequisites");
             const mandate = loadMandate(home);
             if (mandate.version !== "supercuts.mandate.v2")
                 fail("DEAL_MANDATE_VERSION", "buyer needs a v2 standing mandate");
@@ -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)
@@ -57,15 +68,20 @@ export async function onboardingDoctor(home, sellerConfig) {
             const served = await json(new URL("/v2/catalog", config.origin));
             if (!Array.isArray(served.capabilities))
                 fail("SELLER_CATALOG_INVALID", "seller endpoint has no valid catalog");
+            let proofsRequired = false;
             for (const item of config.capabilities) {
                 const registrationPath = resolve(item.registrationFile);
                 if ((statSync(registrationPath).mode & 0o077) !== 0)
                     fail("SELLER_CONFIG_PERMISSIONS", "registration file must be owner-only");
                 const registration = JSON.parse(readFileSync(registrationPath, "utf8"));
+                proofsRequired ||= registration.manifest.supportedRails.includes("shielded");
                 await verifySignedCapability(registration);
                 if (!served.capabilities.some((entry) => JSON.stringify(entry) === JSON.stringify(registration)))
                     fail("SELLER_CATALOG_INVALID", "seller endpoint does not serve its configured registration");
             }
+            const runtime = await app.execute("doctor", { "proofs-required": proofsRequired });
+            if (runtime.data.readyForDemo === false)
+                fail("ONBOARDING_RUNTIME_NOT_READY", "live runtime doctor reports missing prerequisites");
             return { role: "seller", healthy: true, runtime: runtime.data, capabilities: config.capabilities.length, origin: config.origin };
         }
         return fail("ROLE_FORBIDDEN", "onboarding doctor supports buyer and seller homes");

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);
@@ -748,7 +760,7 @@ export class Phase3App {
             return output(command, await this.liveMemory(command, args));
         const runtime = await LiveRuntime.create(this.profile, this.store);
         if (command === "doctor")
-            return output(command, await runtime.doctor());
+            return output(command, await runtime.doctor(args["proofs-required"] !== false));
         if (command === "status")
             return output(command, { role: this.profile.role, network: this.profile.network, mock: false, runtime: "testnet-live" });
         if (command === "capability.publish")
@@ -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", "DEAL_SELLER_UNAVAILABLE", "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,21 @@ 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 === "DEAL_SELLER_UNAVAILABLE")
+        return "check the seller /health endpoint, then resume the same root operation ID";
+    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";
 }