@projectsolo/solo-mission-mcp 0.21.13 → 0.22.0

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   apiPatch,
   apiPost,
   publicApiPost
-} from "./chunk-TKRT2V2W.js";
+} from "./chunk-OP4QYTL4.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -19,7 +19,7 @@ import {
 var RESPONSE_SCHEMA_PROPERTY = {
   type: "array",
   maxItems: 20,
-  description: 'Structured completion questions a human answers to complete the mission. Question ids must be unique within one schema \u2014 a duplicate id is rejected at creation/update, not merged or silently overwritten. When set, finalize_qualification auto-derives qualified UIDs from completion instead of requiring an explicit qualified_human_uids list \u2014 same mechanism media_review has always used for track ratings, generalized to any mission type. media_review defaults to a canonical two-question schema when this is omitted at creation \u2014 literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", required: false } \u2014 so read/append against those exact ids if you rely on the default rather than supplying your own schema. Every other type has no default (stays fully manual/chat-based unless you set this).',
+  description: 'Structured completion questions a human answers to complete the mission. Question ids must be unique within one schema \u2014 a duplicate id is rejected at creation/update, not merged or silently overwritten. When set, finalize_qualification auto-derives qualified UIDs from completion instead of requiring an explicit qualified_human_uids list \u2014 same mechanism media_review has always used for track ratings, generalized to any mission type. media_review defaults to a canonical two-question schema when this is omitted at creation \u2014 literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", required: true } \u2014 so read/append against those exact ids if you rely on the default rather than supplying your own schema. Every other type has no default (stays fully manual/chat-based unless you set this).',
   items: {
     type: "object",
     properties: {
@@ -43,7 +43,10 @@ var RESPONSE_SCHEMA_PROPERTY = {
       },
       label: { type: "string", description: "Question text shown to the human (max 200 chars). For the checkbox kind this is the checkbox's own clickable text, not a separate heading." },
       help: { type: "string", description: "Optional helper text shown under the label (max 500 chars)." },
-      required: { type: "boolean", description: "Whether this question must be answered to complete the mission." },
+      required: {
+        type: "boolean",
+        description: "Whether this question must be answered to complete the mission. A required: false question does NOT block mission completion or finalize_qualification's auto-qualification \u2014 both derive purely from the required questions, so an optional question left blank (or still being typed into) will not stop either from firing the instant the required ones are answered. If every question in the schema should actually be answered, mark them all required: true; reserve required: false for a genuinely optional/skippable field."
+      },
       options: {
         type: "array",
         items: { type: "string" },
@@ -58,7 +61,7 @@ var RESPONSE_SCHEMA_PROPERTY = {
 var missionTools = [
   {
     name: "create_mission",
-    description: "Create a new mission. Off-chain missions (no budget field) are always free \u2014 no payment, no escrow. For paid missions, include the budget field AND chain: 'solana' \u2014 the response will contain funding_params for fund_solana_mission. Base (EscrowVault) on-chain missions are closed to new creation during the Solana private beta migration: any budget-bearing request that resolves to chain 'base' (including the pre-Solana default of omitting chain) now returns 503, not a created mission \u2014 always pass chain: 'solana' explicitly for a paid mission.",
+    description: "Create a new mission. Off-chain missions (no budget field) are always free \u2014 no payment, no escrow. Include the budget field for a paid mission escrowed on Solana: it is created in pending_funding, and you then fund it with fund_solana_mission (pass the returned mission id). Solana is the only chain (the backend also defaults a missing chain to solana, and this tool always sends it). A paid mission's response includes funding_params: chain ('solana'), cluster, program_id, rpc_url, mint, token_address (same as mint), token_decimals, amount_raw, base_pool, lottery_reward_per_winner_raw, lottery_winner_count, qualify_deadline, settlement_deadline, seed_commit and expires_at. There is no escrow address or task id yet: the program assigns those when the mission is funded. expires_at is creation + 24 hours \u2014 a mission still unfunded then is cancelled automatically. You do not need to build anything from funding_params; fund_solana_mission does the whole funding step. The response's mission.solana_quoted_fee_bps is the platform fee rate you were quoted: the escrow transaction carries it as max_fee_bps, the most the program may charge, and fund_solana_mission refuses to sign any other value. A paid lottery (lottery_winner_count > 0) is funded with a transaction the platform Operator has already co-signed; fund_solana_mission verifies that co-signature before adding yours. Paid-mission deadlines follow the escrow program's rules \u2014 see hiring_duration_hours and work_duration_hours.",
     inputSchema: {
       type: "object",
       properties: {
@@ -69,8 +72,8 @@ var missionTools = [
         },
         chain: {
           type: "string",
-          enum: ["base", "solana"],
-          description: "Which chain escrows a paid (budget-bearing) mission. 'base' is currently closed to new creation and returns 503 \u2014 pass 'solana' for any on-chain mission. Ignored for off-chain missions (no budget field)."
+          enum: ["solana"],
+          description: "Optional. Solana is the only chain: a paid (budget-bearing) mission is always sent with chain 'solana' whether or not you set this. Ignored for off-chain missions (no budget field)."
         },
         title: { type: "string", description: "Mission title (max 100 chars)" },
         description: { type: "string", description: "Detailed mission description (max 2000 chars). Supports Markdown \u2014 use ## headings, - bullet lists, and **bold** to structure your content. The platform renders it as formatted text." },
@@ -87,14 +90,14 @@ var missionTools = [
         reward_usdt: { type: "number", minimum: 0, description: "Deprecated \u2014 ignored for off-chain missions (which are always free). Has no effect. Omit this field." },
         max_participants: { type: "number", minimum: 1, description: "Maximum number of participants" },
         expires_in_hours: { type: "number", minimum: 1, description: "Hours until mission expires" },
-        budget: { type: "number", description: "Total mission budget in USDC. Enables on-chain escrow \u2014 pair with chain: 'solana' (Base is closed to new creation, see chain). Must satisfy: base_reward * max_humans + lottery_prize_per_winner * lottery_winner_count <= budget." },
+        budget: { type: "number", description: "Total mission budget in USDC. Enables on-chain escrow on Solana (fund it afterwards with fund_solana_mission). Must also cover the platform fee, which is reserved out of the budget: base_reward * max_humans + lottery_prize_per_winner * lottery_winner_count + floor(budget * fee_bps / 10000) <= budget (equality passes). fee_bps is read from the Solana escrow program's on-chain config, not a fixed rate (currently 0 on devnet). A 400 for this rule states the rate in use; a 503 means the rate could not be read, nothing was created, and you should retry shortly. Both the backend and the Solana escrow program enforce this." },
         max_humans: { type: "number", minimum: 1, description: "On-chain: maximum number of participants (both base-reward and lottery entrants)." },
         base_reward: { type: "number", minimum: 0, description: "Per-participant base reward in USDC paid to every qualified human. Defaults to 0. Set to 0 for pure-lottery missions." },
         reward_per_human: { type: "number", minimum: 0, description: "Deprecated \u2014 use base_reward instead." },
-        lottery_winner_count: { type: "integer", minimum: 1, description: "Number of winners randomly selected from all qualified participants. Must be <= max_humans. Must be paired with lottery_prize_per_winner. Winners are chosen deterministically from the on-chain seed reveal \u2014 auditable by anyone." },
+        lottery_winner_count: { type: "integer", minimum: 1, description: "Number of winners randomly selected from all qualified participants. Must be <= max_humans. Must be paired with lottery_prize_per_winner. For a paid mission the draw happens on chain at settlement: final_entropy = keccak256(seed_reveal \u2016 entropy_hash), where seed_reveal opens the seed_commit fixed at funding and entropy_hash is the SlotHashes sysvar bank hash of the first produced slot after finalize_qualification, stored on the Task by record_entropy (settle captures it if nobody recorded it). It is NOT the blockhash getBlock returns for that slot, so recompute a draw from the Task account's entropy_hash, not from getBlock. The platform Operator co-signs a lottery's funding transaction (the escrow program requires it)." },
         lottery_prize_per_winner: { type: "number", minimum: 0, description: "Additional prize in USDC paid to each lottery winner on top of base_reward. Must be paired with lottery_winner_count." },
-        hiring_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) the mission accepts applications and the agent hires/rejects. The hiring window closes at now + hiring_duration_hours. Finalize-qualification cannot be called before this. Backend floor is 60s (0.0166h), same for every chain \u2014 see work_duration_hours for the reasoning." },
-        work_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) hired participants have to complete the work. Agent must call settle_mission before this period ends. Backend floor is 60s (0.0166h) for every chain \u2014 this is a flat sanity check against a near-zero window, not a guarantee of a legal settlement window on every chain: Base's own EscrowVault contract separately enforces its own fixed 1-hour minimum regardless of what this floor allows through, so a too-short Base mission still fails downstream (at finalize_qualification, or on-chain) instead of being caught at creation." },
+        hiring_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) the mission accepts applications and the agent hires/rejects. The hiring window closes at now + hiring_duration_hours. Finalize-qualification cannot be called before this. Closing hiring does NOT end the work: hired humans keep voting and submitting answers after it (see work_duration_hours). Backend floor is 60s (0.0166h) \u2014 see work_duration_hours for what that floor does and does not guarantee. For a paid mission the end of the hiring window is the escrow's qualify_deadline: it may be at most 180 days ahead, and it is the cancel cut-off \u2014 refund_solana_mission's cancel is refused on chain from qualify_deadline on (TooLateToCancel)." },
+        work_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) hired participants have to complete the work: settlement_deadline = end of the hiring window + work_duration_hours. Agent must call settle_mission before this period ends. Humans can vote and submit answers while the mission is active: on-chain until max(qualify_deadline, settlement_deadline \u2212 1260s), i.e. about 21 minutes before settlement_deadline; off-chain until finalize. Either way, finalize_qualification closes submissions. Backend floor is 60s (0.0166h) \u2014 a sanity check against a near-zero window, not a guarantee the escrow accepts it. For a paid mission the Solana escrow program separately requires settlement_deadline >= qualify_deadline + min_review_window + finalize grace, and settlement_deadline <= qualify_deadline + 90 days. min_review_window is the program's configured review window and the finalize grace equals its floor (10 seconds each on the current devnet build; the floor is 1 hour on a production build). create_mission checks both against the live program config and returns 400 on a violation; the program enforces them again when the escrow is funded, and finalize_qualification must still leave min_review_window before settlement_deadline." },
         auto_accept_applicants: { type: "boolean", description: "Defaults to true \u2014 applicants are automatically hired when they apply, no manual hire_participant call needed, first-come first-served up to max_humans, face verification still required. Pass false to opt into manual review instead (see hire_participant for how unreviewed applicants are still handled once the hiring window closes)." },
         response_schema: RESPONSE_SCHEMA_PROPERTY
       },
@@ -140,21 +143,9 @@ var missionTools = [
       required: ["mission_id"]
     }
   },
-  {
-    name: "confirm_funding",
-    description: `Base (EscrowVault) only \u2014 Solana missions use fund_solana_mission instead, which confirms as part of the same call. Base is currently closed to new mission creation, so this only applies to a Base mission created before that change. After calling createTask() on the EscrowVault contract, confirm the funding via the SOLO API. The backend verifies the transaction on-chain. Mission transitions from pending_funding \u2192 active. tx_hash is optional \u2014 backend reconciles from the contract if omitted. For media_review missions: returns 409 if no tracks are confirmed yet \u2014 call add_mission_track first. Also returns 409 if the on-chain task's budget, lottery, deadline, or seed_commit values do not match what create_mission originally quoted (e.g. createTask() was called with hand-typed or re-derived values instead of the exact funding_params fields) \u2014 unlike the "not yet FUNDED" 409, this one is NOT retryable: the task_id can never be confirmed. Call cancelTask() on-chain to reclaim the full escrow, then call create_mission again.`,
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" },
-        tx_hash: { type: "string", description: "Transaction hash of createTask() call (optional)" }
-      },
-      required: ["mission_id"]
-    }
-  },
   {
     name: "hire_participant",
-    description: "Accept a human applicant for a mission. Only applied humans can be hired. Hired humans can start work via conversations. Only valid while mission is active. IMPORTANT: silence is not neutral \u2014 an applicant you never call this (or reject_participant) on is automatically hired once the hiring window closes (up to max_humans, oldest applied_at first). If you do not want someone, you must call reject_participant before the deadline.",
+    description: "Accept a human applicant for a mission. Only applied humans can be hired. Hired humans can start work via conversations. Only valid while mission is active. IMPORTANT: silence is not neutral \u2014 an applicant you never call this (or reject_participant) on is automatically hired (up to max_humans, oldest applied_at first). That does NOT happen when the hiring window closes. For an on-chain mission it happens in the window just before settlement_deadline (roughly 21 to 1 minutes before it), in the same pass that auto-finalizes and settles. For an off-chain mission it happens at expires_at. If you do not want someone, call reject_participant before then.",
     inputSchema: {
       type: "object",
       properties: {
@@ -166,7 +157,7 @@ var missionTools = [
   },
   {
     name: "reject_participant",
-    description: "Reject a human applicant or hired participant. Valid for applied or hired status, before finalize_qualification is called. This is the ONLY way to exclude someone \u2014 the platform auto-hires overdue applicants and auto-qualifies overdue hired participants by default (silence = go), so if you do not explicitly reject someone before their deadline, they end up hired/qualified/paid.",
+    description: "Reject a human applicant or hired participant. Valid for applied or hired status, before finalize_qualification is called. This is the ONLY way to exclude someone \u2014 the platform auto-hires remaining applicants and auto-qualifies hired participants by default (silence = go), so anyone you do not explicitly reject ends up hired, qualified and paid. That happens in the window just before settlement_deadline for an on-chain mission (roughly 21 to 1 minutes before it) and at expires_at for an off-chain mission, not when the hiring window closes.",
     inputSchema: {
       type: "object",
       properties: {
@@ -178,7 +169,7 @@ var missionTools = [
   },
   {
     name: "finalize_qualification",
-    description: "Lock in the qualified participants after reviewing their work. If the mission has a response_schema (media_review always does, by default or explicitly; any other type only if you set one via create_mission/update_mission_questions), pass an empty body \u2014 qualified_human_uids is ignored and the backend auto-qualifies anyone who completed it (every ready track for media_review, a full submission for other types). Otherwise provide an explicit list of UIDs whose work was accepted. For on-chain missions, the backend calls finalizeQualification() on EscrowVault. Mission transitions to qualifying. If you never call this, the platform does it for you shortly after the hiring window closes, qualifying every hired participant you did not explicitly reject_participant (silence = go) \u2014 call reject_participant first for anyone whose work should NOT be paid.",
+    description: "Lock in the qualified participants after reviewing their work. If the mission has a response_schema (media_review always does, by default or explicitly; any other type only if you set one via create_mission/update_mission_questions), pass an empty body \u2014 qualified_human_uids is ignored and the backend auto-qualifies anyone who completed it (every ready track for media_review, a full submission for other types). Otherwise provide an explicit list of UIDs whose work was accepted. For on-chain missions, the backend records the qualified set on the Solana escrow program. Mission transitions to qualifying. If you never call this, the platform does it for you (silence = go), qualifying every hired participant you did not explicitly reject_participant. It does NOT happen when the hiring window closes. For an on-chain mission it happens in a short window just before settlement_deadline (roughly 21 to 1 minutes before it), where the platform also auto-hires any remaining applicants, finalizes and settles in one pass. For an off-chain mission it happens at expires_at. Call reject_participant first for anyone whose work should NOT be paid.",
     inputSchema: {
       type: "object",
       properties: {
@@ -194,7 +185,7 @@ var missionTools = [
   },
   {
     name: "settle_mission",
-    description: "Settle the mission after finalize_qualification. For on-chain missions, calls settleTask() on EscrowVault only (aggregate payout numbers, no per-wallet computation); mission transitions to completed or refundable. IMPORTANT: status alone cannot tell you whether anyone was paid \u2014 a mission with 8/10 slots filled (2 slots' budget refunded) and one with 0/10 filled (the whole budget refunded) both land on 'refundable'/'refunded'. Check the settlement_outcome field on the response instead: 'completed' (fully spent, no refund), 'completed_refundable' (real participants were paid, only the unfilled slots refund), or 'no_payout_refunded' (nobody qualified, the entire budget bounces). Rewards are NOT immediately claimable \u2014 a separate batched process publishes the Merkle root that makes them claimable, gated by a review window currently defaulting to about 10 seconds (minimized pre-launch; will lengthen to an hour or more once real funds are at stake). Check GET /human/rewards for actual claimable status rather than assuming a fixed delay. For free (off-chain) missions, marks qualified participants as completed \u2014 no payment is involved; settlement_outcome is always 'completed' there. If you never call this, the platform settles on your behalf shortly after finalize_qualification (auto or manual) \u2014 you do not get a second chance to change who is qualified at that point, so reject anyone unwanted before finalize, not after.",
+    description: "Settle the mission after finalize_qualification. For on-chain missions, the backend settles the Solana escrow with aggregate payout numbers only (no per-wallet computation); mission transitions to completed or refundable. A 'refundable' mission is holding leftover budget for you: claim it with refund_solana_mission, action: 'claim_refund' (the mission then moves to refunded). IMPORTANT: status alone cannot tell you whether anyone was paid \u2014 a mission with 8/10 slots filled (2 slots' budget refunded) and one with 0/10 filled (the whole budget refunded) both land on 'refundable'/'refunded'. Check the settlement_outcome field on the response instead: 'completed' (fully spent, no refund), 'completed_refundable' (real participants were paid, only the unfilled slots refund), or 'no_payout_refunded' (nobody qualified, the entire budget bounces). Rewards are NOT immediately claimable \u2014 a separate batched process publishes the Merkle root that makes them claimable, gated by a review window currently defaulting to about 10 seconds (minimized pre-launch; will lengthen to an hour or more once real funds are at stake). Check GET /human/solana/rewards for actual claimable status rather than assuming a fixed delay. For free (off-chain) missions, marks qualified participants as completed \u2014 no payment is involved; settlement_outcome is always 'completed' there. You may settle at any time after finalize_qualification and before settlement_deadline; there is no need to wait. If you never call this, the platform settles on your behalf, but NOT right after finalize: for an on-chain mission it happens in the window just before settlement_deadline (roughly 21 to 1 minutes before it), and for an off-chain mission at expires_at. Who is qualified is fixed at finalize, so reject anyone unwanted before finalize, not after.",
     inputSchema: {
       type: "object",
       properties: {
@@ -205,7 +196,7 @@ var missionTools = [
   },
   {
     name: "cancel_mission",
-    description: "Cancel an off-chain mission directly. Valid when status is active or qualifying. For on-chain missions, use get_cancel_params instead.",
+    description: "Cancel a mission that holds no escrowed funds: an off-chain mission (status active or qualifying), or an unfunded Solana mission still in pending_funding. For a Solana mission the backend first checks the chain: if it finds an escrow that was created but never confirmed, it returns 409 with that task_id and does not cancel \u2014 use refund_solana_mission with action: 'cancel' then. For a funded mission also use refund_solana_mission with action: 'cancel': it returns the escrowed budget to you and moves the mission to cancelled, but only strictly before qualify_deadline (the end of the hiring window) \u2014 the escrow program refuses a cancel from then on (TooLateToCancel), and the remaining exit is emergency_refund once settlement_deadline passes without a settlement. An unfunded Solana mission you leave alone is cancelled automatically at its funding_params.expires_at (creation + 24 hours).",
     inputSchema: {
       type: "object",
       properties: {
@@ -214,78 +205,9 @@ var missionTools = [
       required: ["mission_id"]
     }
   },
-  {
-    name: "get_cancel_params",
-    description: "Get on-chain transaction parameters to cancel a funded mission via cancelTask() on EscrowVault. Only valid before qualify_deadline. After qualify_deadline, use get_emergency_refund_params instead.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" }
-      },
-      required: ["mission_id"]
-    }
-  },
-  {
-    name: "confirm_cancel",
-    description: "After executing cancelTask() on EscrowVault, confirm the cancellation on the SOLO platform. Mission transitions to cancelled.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" },
-        tx_hash: { type: "string", description: "Transaction hash of cancelTask() (optional)" }
-      },
-      required: ["mission_id"]
-    }
-  },
-  {
-    name: "get_emergency_refund_params",
-    description: "Get on-chain transaction parameters to force-refund a mission after the settlement_deadline has passed without settlement. Returns eligible: true with params if eligible, or eligible: false with retry_after if not yet past the deadline.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" }
-      },
-      required: ["mission_id"]
-    }
-  },
-  {
-    name: "confirm_emergency_refund",
-    description: "After executing emergencyRefund() on EscrowVault, confirm on the SOLO platform. Mission transitions to cancelled.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" },
-        tx_hash: { type: "string", description: "Transaction hash of emergencyRefund() (optional)" }
-      },
-      required: ["mission_id"]
-    }
-  },
-  {
-    name: "get_refund_params",
-    description: "Get on-chain transaction parameters to claim unused budget via claimRefund() on EscrowVault. Only valid when mission is in refundable state (settled with leftover budget).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" }
-      },
-      required: ["mission_id"]
-    }
-  },
-  {
-    name: "confirm_refund",
-    description: "After executing claimRefund() on EscrowVault, confirm the refund on the SOLO platform. Mission transitions to refunded.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mission_id: { type: "string" },
-        tx_hash: { type: "string", description: "Transaction hash of claimRefund() (optional)" }
-      },
-      required: ["mission_id"]
-    }
-  },
   {
     name: "rate_participant",
-    description: "Leave a rating and optional comment for a mission participant. Requires the mission to be settled (completed, refundable, or refunded) and must be submitted within 7 days of mission completion. Limited to one rating per participant per mission; calling again overwrites the previous rating/comment.",
+    description: "Leave a rating and optional comment for a mission participant. Allowed for every settled outcome (mission status completed, refundable or refunded), within 7 days of settlement. Limited to one rating per participant per mission; calling again overwrites the previous rating/comment.",
     inputSchema: {
       type: "object",
       properties: {
@@ -300,8 +222,10 @@ var missionTools = [
 ];
 async function handleMissionTool(name, args) {
   switch (name) {
-    case "create_mission":
-      return apiPost("/agent/missions", args);
+    case "create_mission": {
+      const { chain: _chain, ...body } = args;
+      return apiPost("/agent/missions", body.budget !== void 0 ? { ...body, chain: "solana" } : body);
+    }
     case "list_missions": {
       const params = {};
       if (args.status) params.status = args.status;
@@ -313,8 +237,6 @@ async function handleMissionTool(name, args) {
       return apiGet(`/agent/missions/${args.mission_id}`);
     case "update_mission_questions":
       return apiPatch(`/agent/missions/${args.mission_id}/questions`, { response_schema: args.response_schema });
-    case "confirm_funding":
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-funding`, { tx_hash: args.tx_hash });
     case "hire_participant":
       return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/hire`);
     case "reject_participant":
@@ -327,18 +249,6 @@ async function handleMissionTool(name, args) {
       return apiPost(`/agent/missions/${args.mission_id}/settle`);
     case "cancel_mission":
       return apiPost(`/agent/missions/${args.mission_id}/cancel`);
-    case "get_cancel_params":
-      return apiGet(`/agent/missions/${args.mission_id}/cancel-params`);
-    case "confirm_cancel":
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-cancel`, { tx_hash: args.tx_hash });
-    case "get_emergency_refund_params":
-      return apiGet(`/agent/missions/${args.mission_id}/emergency-refund-params`);
-    case "confirm_emergency_refund":
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-emergency-refund`, { tx_hash: args.tx_hash });
-    case "get_refund_params":
-      return apiGet(`/agent/missions/${args.mission_id}/refund-params`);
-    case "confirm_refund":
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-refund`, { tx_hash: args.tx_hash });
     case "rate_participant":
       return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/comment`, {
         rating: args.rating,
@@ -879,7 +789,7 @@ import { readFile } from "fs/promises";
 var trackTools = [
   {
     name: "add_mission_track",
-    description: "Upload a media item (audio, image, or video) to a media_review mission. Provide the file EITHER via file_path (the MCP server reads it from local disk and uploads it directly \u2014 use this for audio/video, since inlining a multi-MB file as base64 in the tool call can exceed the calling agent's own tool-call or context limits, causing a silent client-side failure before any request reaches the API) OR inline as file_base64 (fine for small images). Exactly one of the two is required. For on-chain missions, call this BEFORE confirm_funding \u2014 uploads are blocked once the mission is active. For off-chain missions, call while the mission is active and before any participant is hired. The item becomes visible to hired participants once confirmed.",
+    description: "Upload a media item (audio, image, or video) to a media_review mission. Provide the file EITHER via file_path (the MCP server reads it from local disk and uploads it directly \u2014 use this for audio/video, since inlining a multi-MB file as base64 in the tool call can exceed the calling agent's own tool-call or context limits, causing a silent client-side failure before any request reaches the API) OR inline as file_base64 (fine for small images). Exactly one of the two is required. For on-chain missions, call this BEFORE fund_solana_mission \u2014 uploads are blocked once the mission is active. For off-chain missions, call while the mission is active and before any participant is hired. The item becomes visible to hired participants once confirmed.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1002,12 +912,12 @@ async function handleTrackTool(name, args) {
 var solanaTools = [
   {
     name: "get_solana_config",
-    description: "Read the Solana escrow deployment: program id, cluster, RPC endpoint, accepted mints and their decimals, and the minimum first payout. Call this before funding so you use a whitelisted mint \u2014 a mint that is not whitelisted is rejected on chain, not by the API. Requires no wallet.",
+    description: "Read the Solana escrow deployment: program id, cluster, RPC endpoint, accepted mints and their decimals, the minimum first payout, and escrow_interface \u2014 the program interface funding transactions use. This server verifies only escrow_interface 'v2' and refuses to fund against anything else. Call this before funding so you use a whitelisted mint \u2014 a mint that is not whitelisted is rejected on chain, not by the API. Requires no wallet.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "get_solana_wallet",
-    description: "Show your Solana wallet address and its balances. Reports SOL (needed for transaction fees and for account rent) and the token balance for a given mint (the mission budget). Use this before funding: an agent needs BOTH, and the rent line has no equivalent on Base. Rent is a refundable deposit, not a fee \u2014 most of it returns when the task is closed. If no wallet is configured this explains how to set one up.",
+    description: "Show your Solana wallet address and its balances. Reports SOL (needed for transaction fees and for account rent) and the token balance for a given mint (the mission budget). Use this before funding: an agent needs BOTH, and the rent line is easy to miss. Rent is a refundable deposit, not a fee \u2014 most of it returns when the task is closed. If no wallet is configured this explains how to set one up.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1020,18 +930,23 @@ var solanaTools = [
   },
   {
     name: "fund_solana_mission",
-    description: "Fund a Solana mission end to end: the backend builds the escrow transaction, this tool DECODES AND VERIFIES it against the parameters you expect, signs it locally with your wallet, and submits it. Your key never leaves this process.\n\nVerification is not optional and cannot be skipped. On Solana the backend builds the transaction rather than publishing a parameter set for you to rebuild, so without a decode you would be signing bytes you cannot read. This tool refuses to sign if anything differs from what you expect \u2014 a substituted mint, an altered budget, an extra instruction, a vault that is not a program-derived address \u2014 and returns the discrepancies instead.\n\nCall create_mission with chain='solana' first; pass that mission's id here.",
+    description: "Fund a Solana mission end to end: the backend builds the escrow transaction, this tool DECODES AND VERIFIES it against the parameters you expect, signs it locally with your wallet, and submits it. Your key never leaves this process.\n\nVerification is not optional and cannot be skipped. On Solana the backend builds the transaction rather than publishing a parameter set for you to rebuild, so without a decode you would be signing bytes you cannot read. This tool refuses to sign if anything differs from what you expect \u2014 a substituted mint, an altered budget or deadline, an extra instruction, an account that is not the program-derived address, a raised fee ceiling, a lottery co-signer that is not the program's Operator \u2014 and returns the discrepancies instead.\n\nThe escrow program id is pinned in this package per cluster (SOLO_SOLANA_PROGRAM_ID can pin another) and the API's program_id must match it; the mint's decimals, which scale expected_budget, are read from chain.\n\nEscrow interface v2 (the only one this server verifies; get_solana_config reports it):\n- max_fee_bps: create_task carries the highest platform fee the escrow may take. It must equal the fee rate create_mission quoted you (mission.solana_quoted_fee_bps). If the program's fee has risen above it by the time the transaction lands, create_task fails with FeeAboveSponsorMax instead of charging you more; cancel the mission and create a new one for a fresh quote.\n- Lottery co-signature: a mission with lottery_winner_count > 0 must be co-signed by the platform Operator, so the transaction arrives already signed by it. This tool checks that the co-signer is the Operator in the program's on-chain Config (read directly from the cluster, not from the API), that its ed25519 signature is valid over the exact message, and that you, not the Operator, pay the fee. It then adds ONLY your signature and leaves the Operator's untouched; any change to the bytes would invalidate it. A non-lottery transaction must carry no co-signer.\n\nCall create_mission with a budget first and pass that mission's id here. Fund it within 24 hours: an unfunded mission is cancelled automatically at funding_params.expires_at. A media_review mission needs at least one ready track (add_mission_track) before funding, or this returns 409 before anything is signed.",
     inputSchema: {
       type: "object",
       properties: {
-        mission_id: { type: "string", description: 'Mission created with chain="solana".' },
+        mission_id: { type: "string", description: "A paid (budget-bearing) mission from create_mission, still in pending_funding." },
         expected_budget: {
           type: "number",
           description: "The total budget in whole tokens (e.g. 10 for 10 USDC) you expect to escrow. Verified against the transaction before signing. Pass what you intended, NOT what the API told you \u2014 comparing the API to itself proves nothing."
         },
         expected_mint: {
           type: "string",
-          description: "The mint you expect the budget to be taken in. Verified before signing. Defaults to the deployment payout mint."
+          description: "The mint you expect the budget to be taken in. Verified before signing. Defaults to the mint create_mission recorded for this mission (its funding_params.mint)."
+        },
+        expected_max_fee_bps: {
+          type: "integer",
+          minimum: 0,
+          description: "The platform fee rate, in basis points, that create_mission quoted you: its response's mission.solana_quoted_fee_bps. Verified against the transaction's max_fee_bps before signing. Defaults to the quote recorded on the mission."
         },
         dry_run: {
           type: "boolean",
@@ -1043,7 +958,7 @@ var solanaTools = [
   },
   {
     name: "refund_solana_mission",
-    description: "Get a Solana mission's escrowed funds back to the sponsor. Covers all three routes: cancel (while funded, before hiring closes), emergency_refund (once the settlement deadline passes and the platform has not settled), and claim_refund (leftover budget after a partial settle).\n\nSame flow as funding: the backend builds the transaction, this tool VERIFIES it, signs locally, and submits. Your key never leaves this process.\n\nCall with no action to ask what is currently available \u2014 the response lists the legal actions for the mission's state rather than guessing. Without this tool a funded Solana mission's money was unreachable except by hand-assembling an Anchor instruction, for which Solana has no `cast send` equivalent.",
+    description: "Get a Solana mission's escrowed funds back to the sponsor. Covers all three routes:\n- cancel: while the task is funded and strictly before qualify_deadline (the end of the hiring window). The escrow program refuses a cancel from qualify_deadline on (TooLateToCancel), even one built earlier, because by then the participants' work is done.\n- emergency_refund: once settlement_deadline has passed and the platform has not settled. It stays available after the cancel cut-off, and a pause does not block it.\n- claim_refund: leftover budget after a settle (mission status refundable).\n\nSame flow as funding: the backend builds the transaction, this tool VERIFIES it, signs locally, and submits. Your key never leaves this process.\n\nCall with no action to ask what is currently available \u2014 the response lists the legal actions for the mission's state rather than guessing. If the backend or the chain rejects an action, the response says which one did, names the program error, and lists the actions that remain.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1076,19 +991,25 @@ function toRawAmount(amount, decimals) {
   return (whole + frac.padEnd(decimals, "0")).replace(/^0+(?=\d)/, "");
 }
 var SOLANA_TOOL_NAMES = new Set(solanaTools.map((t) => t.name));
+function apiErrorBody(e) {
+  return e?.data ?? e?.response?.data ?? e?.body ?? {};
+}
+var CANCEL_CUTOFF_RULE = "cancel is refused on chain from qualify_deadline on (TooLateToCancel, error 6125); emergency_refund opens once settlement_deadline has passed without a settlement.";
 async function handleSolanaTool(name, args) {
-  const { apiGet: apiGet2, apiPost: apiPost2 } = await import("./client-LDWK5HLP.js");
+  const { apiGet: apiGet2, apiPost: apiPost2 } = await import("./client-NS6J6IO2.js");
+  const { resolvePinnedProgram, resolveTrustedRpc, solanaRpcUrl } = await import("./deployment-UCUWVIPJ.js");
   switch (name) {
     case "get_solana_config":
       return apiGet2("/agent/solana/config");
     case "get_solana_wallet": {
-      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress } = await import("./wallet-V4T4NTCM.js");
+      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress, KEY_STORAGE_GUIDANCE } = await import("./wallet-LX7SI5RE.js");
       if (!hasSolanaWallet()) {
         return {
           configured: false,
           how_to_configure: {
-            option_1: "SOLO_SOLANA_KEYPAIR \u2014 JSON byte array, as `solana-keygen new` writes it",
-            option_2: "SOLO_SOLANA_KEYPAIR_PATH \u2014 path to that file, e.g. ~/.config/solana/id.json"
+            recommended: "SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE \u2014 a keyfile encrypted with `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256`, plus a separate passphrase file (chmod 600 both)",
+            alternative: "SOLO_SOLANA_KEYPAIR_PATH \u2014 path to a plaintext `solana-keygen` keyfile, e.g. ~/.config/solana/id.json (chmod 600)",
+            key_storage: KEY_STORAGE_GUIDANCE
           },
           what_you_need: "SOL for transaction fees and account rent, plus the payout token for the budget. Rent is a refundable deposit, not a fee \u2014 most of it returns on close_task. Roughly $0.58 is locked per mission and about $0.24 is permanent, which buys the on-chain record that makes the escrow verifiable by anyone."
         };
@@ -1099,7 +1020,7 @@ async function handleSolanaTool(name, args) {
       const mint = args.mint ?? cfg.mints[symbol];
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
       const rpc = async (method, params) => {
-        const res = await fetch(cfg.rpc_url, {
+        const res = await fetch(solanaRpcUrl(cfg), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
@@ -1128,23 +1049,87 @@ async function handleSolanaTool(name, args) {
       };
     }
     case "fund_solana_mission": {
-      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-V4T4NTCM.js");
-      const { verifyFundingTransaction } = await import("./verify-KAETIGV5.js");
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-LX7SI5RE.js");
+      const { verifyFundingTransaction, readEscrowConfig, readMintDecimals, SUPPORTED_ESCROW_INTERFACE } = await import("./verify-7EUVRUAS.js");
       const wallet = await loadSolanaWallet();
       const cfg = await apiGet2("/agent/solana/config");
-      const symbol = Object.keys(cfg.mints)[0];
-      const mint = args.expected_mint ?? cfg.mints[symbol];
-      const decimals = cfg.decimals[symbol] ?? 6;
+      if (cfg.escrow_interface !== SUPPORTED_ESCROW_INTERFACE) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            `the deployment reports escrow_interface ${JSON.stringify(cfg.escrow_interface)}; this version of @projectsolo/solo-mission-mcp verifies only '${SUPPORTED_ESCROW_INTERFACE}' funding transactions`
+          ],
+          what_this_means: "Nothing was built, signed or escrowed. This server cannot decode the funding transaction the deployment would build, so it will not sign one. Use a version of this package that supports the reported escrow interface."
+        };
+      }
+      const pin = resolvePinnedProgram(cfg);
+      const rpc = resolveTrustedRpc(cfg);
+      if ("problem" in pin || "problem" in rpc) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            ..."problem" in pin ? [pin.problem] : [],
+            ..."problem" in rpc ? [rpc.problem] : []
+          ],
+          what_this_means: "Nothing was built, signed or escrowed."
+        };
+      }
+      const rpcUrl = rpc.rpc_url;
+      const { mission } = await apiGet2(`/agent/missions/${args.mission_id}`);
+      if (!mission) {
+        return {
+          funded: false,
+          error: `Could not read mission ${args.mission_id} \u2014 call get_mission to check it exists.`
+        };
+      }
+      const mint = args.expected_mint ?? mission.token_address ?? cfg.mints[Object.keys(cfg.mints)[0]];
+      let decimals;
+      try {
+        decimals = await readMintDecimals(rpcUrl, mint);
+      } catch (e) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            `cannot read mint ${mint}'s decimals from chain, which expected_budget is scaled by: ` + e.message
+          ],
+          what_this_means: "Nothing was built, signed or escrowed."
+        };
+      }
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
       const built = await apiPost2(
         `/agent/solana/missions/${args.mission_id}/funding-transaction`,
         { sponsor_wallet: wallet.publicKey, sponsor_token_account: tokenAccount }
       );
+      let onchainConfig = null;
+      let onchainConfigError;
+      try {
+        onchainConfig = await readEscrowConfig(rpcUrl, pin.program_id);
+      } catch (e) {
+        onchainConfigError = e.message;
+      }
+      let quotedFeeBps;
+      let feeQuoteSource;
+      if (args.expected_max_fee_bps !== void 0) {
+        quotedFeeBps = Number(args.expected_max_fee_bps);
+        feeQuoteSource = "expected_max_fee_bps argument";
+      } else if (typeof mission.solana_quoted_fee_bps === "number") {
+        quotedFeeBps = mission.solana_quoted_fee_bps;
+        feeQuoteSource = "mission.solana_quoted_fee_bps (the create_mission quote)";
+      } else {
+        quotedFeeBps = onchainConfig?.fee_bps;
+        feeQuoteSource = "on-chain Config.fee_bps (the mission has no recorded quote)";
+      }
       const expectedBudgetRaw = toRawAmount(args.expected_budget, decimals);
       const verdict = await verifyFundingTransaction({
         transaction_base64: built.transaction_base64,
+        escrow_interface: built.escrow_interface,
+        task_id: String(built.task_id),
         declared: built.declared,
         accounts: built.accounts,
+        message_sha256: built.message_sha256,
         expected: {
           budget_raw: expectedBudgetRaw,
           // base_pool is derived by the backend from reward × max_humans. The agent's check on it
@@ -1152,21 +1137,30 @@ async function handleSolanaTool(name, args) {
           // asserting a locally recomputed figure would require duplicating that arithmetic here
           // and would fail on a legitimately rounded reward.
           base_pool_raw: String(built.declared.base_pool),
-          lottery_winner_count: Number(built.declared.lottery_winner_count),
-          lottery_prize_per_winner_raw: String(built.declared.lottery_prize_per_winner),
-          qualify_deadline: Number(built.declared.qualify_deadline),
-          settlement_deadline: Number(built.declared.settlement_deadline),
+          // The rest is what create_mission recorded, not what the funding response says: whether
+          // this is a lottery decides whether a co-signer is required at all.
+          lottery_winner_count: Number(mission.lottery_winner_count ?? 0),
+          lottery_prize_per_winner_raw: String(mission.lottery_prize_per_winner_raw ?? "0"),
+          qualify_deadline: Number(mission.qualify_deadline),
+          settlement_deadline: Number(mission.settlement_deadline),
+          seed_commit: mission.seed_commit,
+          max_fee_bps: quotedFeeBps,
           mint,
-          sponsor: wallet.publicKey
+          sponsor: wallet.publicKey,
+          sponsor_token_account: tokenAccount
         },
-        expected_program_id: cfg.program_id
+        expected_program_id: pin.program_id,
+        onchain_config: onchainConfig,
+        onchain_config_error: onchainConfigError
       });
       if (!verdict.ok) {
         return {
           funded: false,
           refused_to_sign: true,
           problems: verdict.problems,
+          warnings: verdict.warnings,
           summary: verdict.summary,
+          fee_quote_source: feeQuoteSource,
           what_this_means: "The transaction does not match what you asked for, so it was NOT signed and nothing was escrowed. This is the verifier doing its job. Do not retry blindly \u2014 the discrepancy above is either a bug or an attempt to have you authorise something else."
         };
       }
@@ -1177,22 +1171,49 @@ async function handleSolanaTool(name, args) {
           verified: true,
           task_id: built.task_id,
           summary: verdict.summary,
+          warnings: verdict.warnings,
+          fee_quote_source: feeQuoteSource,
           would_escrow: `${args.expected_budget} (${expectedBudgetRaw} raw) of ${mint}`
         };
       }
       const signed = await signTransaction(built.transaction_base64, wallet);
-      const confirmed = await apiPost2(
-        `/agent/solana/missions/${args.mission_id}/confirm-funding`,
-        { signed_transaction: signed, task_id: built.task_id }
-      );
-      return { funded: true, verified: true, ...confirmed };
+      let confirmed;
+      try {
+        confirmed = await apiPost2(`/agent/solana/missions/${args.mission_id}/confirm-funding`, {
+          signed_transaction: signed,
+          task_id: built.task_id
+        });
+      } catch (e) {
+        const { escrowErrorFromMessage } = await import("./escrowErrors-4XSAYLGT.js");
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        return {
+          funded: false,
+          verified: true,
+          signed: true,
+          status: e?.status,
+          message,
+          program_error: escrowErrorFromMessage(message) ?? void 0,
+          ...body.funding_mismatch ? { funding_mismatch: body.funding_mismatch } : {},
+          ...body.task_id ? { task_id: body.task_id } : {}
+        };
+      }
+      return {
+        funded: true,
+        verified: true,
+        lottery: verdict.summary.lottery,
+        operator_cosigned: verdict.summary.operator_signature === "valid",
+        max_fee_bps: verdict.summary.max_fee_bps,
+        ...confirmed
+      };
     }
     case "refund_solana_mission": {
-      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-V4T4NTCM.js");
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-LX7SI5RE.js");
+      const { escrowErrorFromMessage } = await import("./escrowErrors-4XSAYLGT.js");
       const wallet = await loadSolanaWallet();
       const cfg = await apiGet2("/agent/solana/config");
-      const mission = await apiGet2(`/agent/missions/${args.mission_id}`);
-      const mint = mission.mission?.token_address;
+      const { mission } = await apiGet2(`/agent/missions/${args.mission_id}`);
+      const mint = mission?.token_address;
       if (!mint) {
         return {
           refunded: false,
@@ -1200,6 +1221,11 @@ async function handleSolanaTool(name, args) {
         };
       }
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      const deadlines = {
+        qualify_deadline: mission?.qualify_deadline,
+        settlement_deadline: mission?.settlement_deadline,
+        ...mission?.qualify_deadline !== void 0 ? { cancel_cutoff: new Date(mission.qualify_deadline * 1e3).toISOString() } : {}
+      };
       if (!args.action) {
         try {
           await apiPost2(`/agent/solana/missions/${args.mission_id}/refund-transaction`, {
@@ -1209,31 +1235,69 @@ async function handleSolanaTool(name, args) {
           });
           return { available_actions: ["claim_refund"], note: "claim_refund is available now" };
         } catch (e) {
-          const body = e?.data ?? e?.response?.data ?? e?.body ?? {};
+          const body = apiErrorBody(e);
           return {
             available_actions: body.available_actions ?? [],
             why_not_claim_refund: body.message,
-            note: (body.available_actions?.length ?? 0) === 0 ? "Nothing is refundable right now. cancel needs the hiring window still open; emergency_refund needs the settlement deadline to have passed." : "Re-run with one of available_actions."
+            ...deadlines,
+            note: (body.available_actions?.length ?? 0) === 0 ? `Nothing is refundable right now. ${CANCEL_CUTOFF_RULE}` : `Re-run with one of available_actions. ${CANCEL_CUTOFF_RULE}`
           };
         }
       }
-      const built = await apiPost2(
-        `/agent/solana/missions/${args.mission_id}/refund-transaction`,
-        {
+      const nowSec = Math.floor(Date.now() / 1e3);
+      if (args.action === "cancel" && typeof mission?.qualify_deadline === "number" && nowSec >= mission.qualify_deadline) {
+        return {
+          refunded: false,
+          rejected_by: "client",
+          action: "cancel",
+          message: `qualify_deadline (${deadlines.cancel_cutoff}) has passed by this machine's clock, so the escrow program would refuse this cancel (TooLateToCancel). Nothing was built or signed.`,
+          ...deadlines,
+          what_to_do: CANCEL_CUTOFF_RULE
+        };
+      }
+      const pin = resolvePinnedProgram(cfg);
+      if ("problem" in pin) {
+        return {
+          refunded: false,
+          refused_to_sign: true,
+          problems: [pin.problem],
+          what_this_means: "Nothing was built, signed or moved."
+        };
+      }
+      let built;
+      try {
+        built = await apiPost2(
+          `/agent/solana/missions/${args.mission_id}/refund-transaction`,
+          {
+            action: args.action,
+            sponsor_wallet: wallet.publicKey,
+            sponsor_token_account: tokenAccount
+          }
+        );
+      } catch (e) {
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        return {
+          refunded: false,
+          rejected_by: "backend",
           action: args.action,
-          sponsor_wallet: wallet.publicKey,
-          sponsor_token_account: tokenAccount
-        }
-      );
-      const { Transaction, PublicKey } = await import("@solana/web3.js");
+          status: e?.status,
+          message,
+          available_actions: body.available_actions ?? [],
+          program_error: escrowErrorFromMessage(message) ?? void 0,
+          ...deadlines,
+          what_to_do: CANCEL_CUTOFF_RULE
+        };
+      }
+      const { Transaction } = await import("@solana/web3.js");
       const tx = Transaction.from(Buffer.from(built.transaction_base64, "base64"));
       const problems = [];
       if (tx.instructions.length !== 1) {
         problems.push(`expected 1 instruction, found ${tx.instructions.length}`);
       }
       const ix = tx.instructions[0];
-      if (ix?.programId?.toBase58() !== cfg.program_id) {
-        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${cfg.program_id}`);
+      if (ix?.programId?.toBase58() !== pin.program_id) {
+        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${pin.program_id}`);
       }
       const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
       if (signers.length !== 1 || signers[0] !== wallet.publicKey) {
@@ -1248,7 +1312,6 @@ async function handleSolanaTool(name, args) {
       if ((ix?.data?.length ?? 0) !== 8) {
         problems.push(`instruction data is ${ix?.data?.length} bytes, expected 8`);
       }
-      void PublicKey;
       if (problems.length > 0) {
         return {
           refunded: false,
@@ -1264,14 +1327,33 @@ async function handleSolanaTool(name, args) {
           verified: true,
           action: args.action,
           task_id: built.task_id,
-          destination: tokenAccount
+          destination: tokenAccount,
+          ...built.cancel_deadline ? { cancel_deadline: built.cancel_deadline } : {}
         };
       }
       const signed = await signTransaction(built.transaction_base64, wallet);
-      const confirmed = await apiPost2(
-        `/agent/solana/missions/${args.mission_id}/confirm-refund`,
-        { signed_transaction: signed, action: args.action }
-      );
+      let confirmed;
+      try {
+        confirmed = await apiPost2(`/agent/solana/missions/${args.mission_id}/confirm-refund`, {
+          signed_transaction: signed,
+          action: args.action
+        });
+      } catch (e) {
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        const programError = escrowErrorFromMessage(message);
+        return {
+          refunded: false,
+          rejected_by: programError || /transaction failed/i.test(message) ? "chain" : "backend",
+          action: args.action,
+          status: e?.status,
+          message,
+          program_error: programError ?? void 0,
+          available_actions: body.available_actions,
+          ...deadlines,
+          what_to_do: programError?.what_to_do ?? CANCEL_CUTOFF_RULE
+        };
+      }
       return { refunded: true, verified: true, ...confirmed };
     }
     default: