@muhaven/mcp 0.2.8 → 0.3.0

package/dist/index.js

@@ -10,7 +10,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { platform, homedir } from 'os';
 import { connect, createServer } from 'net';
 import { setTimeout as setTimeout$1 } from 'timers/promises';
-import { parseAbi, toFunctionSelector, encodeFunctionData, encodePacked, pad, concatHex, decodeAbiParameters } from 'viem';
+import { parseAbi, toFunctionSelector, encodeFunctionData, toEventSelector, decodeFunctionData, encodePacked, pad, concatHex, decodeAbiParameters, encodeAbiParameters, parseAbiParameters } from 'viem';
 import { createHash, randomBytes } from 'crypto';
 import { getUserOperationHash } from 'viem/account-abstraction';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -169,22 +169,45 @@ function loadBrokerConfig(env = process.env) {
     env.MUHAVEN_DASHBOARD_URL,
     DEFAULT_DASHBOARD_URL
   );
+  const chainRpcUrlRaw = readEnv("MUHAVEN_BROKER_RPC_URL", env) ?? readEnv("MUHAVEN_BUNDLER_URL", env);
+  const chainRpcUrl = chainRpcUrlRaw === void 0 ? void 0 : resolvePublicUrlEnv(
+    "MUHAVEN_BROKER_RPC_URL",
+    chainRpcUrlRaw,
+    chainRpcUrlRaw
+  );
+  const callbackServiceSecretRaw = readEnv("BROKER_CALLBACK_SERVICE_SECRET", env);
+  let callbackServiceSecret;
+  if (callbackServiceSecretRaw !== void 0) {
+    if (callbackServiceSecretRaw.length < 16) {
+      throw new Error(
+        "BROKER_CALLBACK_SERVICE_SECRET must be at least 16 characters (matches backend with-service-secret middleware floor)"
+      );
+    }
+    callbackServiceSecret = callbackServiceSecretRaw;
+  }
+  const outboundOriginHeader = readEnv("MUHAVEN_BROKER_ORIGIN", env) ?? dashboardBaseUrl;
   return {
     endpoint,
     sessionKeyHex,
     maxRequestBytes,
     requestTimeoutMs,
     backendBaseUrl,
-    dashboardBaseUrl
+    dashboardBaseUrl,
+    chainRpcUrl,
+    callbackServiceSecret,
+    outboundOriginHeader
   };
 }
 
 // src/broker/protocol.ts
-var BROKER_PROTOCOL_VERSION = "0.4.0";
+var BROKER_PROTOCOL_VERSION = "0.5.0";
 var HASH_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
 var ADDRESS_HEX_RE2 = /^0x[0-9a-fA-F]{40}$/;
 var SELECTOR_HEX_RE = /^0x[0-9a-fA-F]{8}$/;
 var HEX_PREFIXED_RE = /^0x[0-9a-fA-F]*$/;
+var ENABLE_DATA_HEX_RE = /^0x[0-9a-fA-F]{2,65536}$/;
+var ENABLE_SIG_HEX_RE = /^0x[0-9a-fA-F]{256,16384}$/;
+var UINT32_MAX = 4294967295;
 var JWT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
 var SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 var UINT256_DEC_RE = /^(0|[1-9][0-9]{0,77})$/;
@@ -304,6 +327,43 @@ function parsePolicySnapshot(raw) {
   if (!isOptionalPermissionId(obj.permissionId)) {
     return { error: "snapshot.permissionId must be a 0x-prefixed 4-byte hex when provided" };
   }
+  const enableData = obj.enableData;
+  const enableSig = obj.enableSig;
+  const validatorNonce = obj.validatorNonce;
+  const installPresent = [enableData, enableSig, validatorNonce].filter(
+    (v) => v !== void 0
+  ).length;
+  if (installPresent !== 0 && installPresent !== 3) {
+    return {
+      error: "snapshot.{enableData,enableSig,validatorNonce} must be all-present or all-absent (Option D Commit 3 install-material trio)"
+    };
+  }
+  if (enableData !== void 0) {
+    if (typeof enableData !== "string" || !ENABLE_DATA_HEX_RE.test(enableData)) {
+      return {
+        error: "snapshot.enableData must be a 0x-prefixed hex string of 2..65536 chars when provided"
+      };
+    }
+  }
+  if (enableSig !== void 0) {
+    if (typeof enableSig !== "string" || !ENABLE_SIG_HEX_RE.test(enableSig)) {
+      return {
+        error: "snapshot.enableSig must be a 0x-prefixed hex string of 256..16384 chars (WebAuthn envelope) when provided"
+      };
+    }
+  }
+  if (validatorNonce !== void 0) {
+    if (typeof validatorNonce !== "number" || !Number.isInteger(validatorNonce) || validatorNonce < 0 || validatorNonce > UINT32_MAX) {
+      return {
+        error: "snapshot.validatorNonce must be an integer in [0, 2^32-1] when provided"
+      };
+    }
+  }
+  if (installPresent === 3 && obj.permissionId === void 0) {
+    return {
+      error: "snapshot install material requires permissionId in the same snapshot"
+    };
+  }
   return {
     sessionId: obj.sessionId,
     mode: "scoped",
@@ -316,7 +376,10 @@ function parsePolicySnapshot(raw) {
     mintedAtSec: obj.mintedAtSec,
     ...obj.consentActionHash === void 0 ? {} : { consentActionHash: obj.consentActionHash.toLowerCase() },
     ...obj.consentTextSha256 === void 0 ? {} : { consentTextSha256: obj.consentTextSha256.toLowerCase() },
-    ...obj.permissionId === void 0 ? {} : { permissionId: obj.permissionId.toLowerCase() }
+    ...obj.permissionId === void 0 ? {} : { permissionId: obj.permissionId.toLowerCase() },
+    ...enableData === void 0 ? {} : { enableData: enableData.toLowerCase() },
+    ...enableSig === void 0 ? {} : { enableSig: enableSig.toLowerCase() },
+    ...validatorNonce === void 0 ? {} : { validatorNonce }
   };
 }
 function parseBrokerRequest(line) {
@@ -495,6 +558,72 @@ function parseBrokerRequest(line) {
     }
     case "get_active_session_id":
       return { type: "get_active_session_id" };
+    case "current_nonce": {
+      if (!isAddressHex(obj.accountAddress)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "current_nonce.accountAddress must be a 0x-prefixed 20-byte hex"
+        };
+      }
+      return {
+        type: "current_nonce",
+        accountAddress: obj.accountAddress.toLowerCase()
+      };
+    }
+    case "notify_userop_landed": {
+      if (!isSessionIdShape(obj.sessionId)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.sessionId must be 1-128 chars [A-Za-z0-9_-]"
+        };
+      }
+      if (!isAddressHex(obj.accountAddress)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.accountAddress must be a 0x-prefixed 20-byte hex"
+        };
+      }
+      if (!isSelectorHex(obj.permissionId)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.permissionId must be a 0x-prefixed 4-byte hex"
+        };
+      }
+      if (!isHashHex(obj.txHash)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.txHash must be a 0x-prefixed 32-byte hex"
+        };
+      }
+      if (typeof obj.blockNumber !== "number" || !Number.isFinite(obj.blockNumber) || !Number.isInteger(obj.blockNumber) || obj.blockNumber < 0) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.blockNumber must be a non-negative integer"
+        };
+      }
+      if (typeof obj.logIndex !== "number" || !Number.isFinite(obj.logIndex) || !Number.isInteger(obj.logIndex) || obj.logIndex < 0) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.logIndex must be a non-negative integer"
+        };
+      }
+      return {
+        type: "notify_userop_landed",
+        sessionId: obj.sessionId,
+        accountAddress: obj.accountAddress.toLowerCase(),
+        permissionId: obj.permissionId.toLowerCase(),
+        txHash: obj.txHash.toLowerCase(),
+        blockNumber: obj.blockNumber,
+        logIndex: obj.logIndex
+      };
+    }
     default:
       return {
         type: "error",
@@ -654,6 +783,33 @@ var BrokerClient = class {
     }
     return res;
   }
+  // ── Wave 5 Option D Commit 3 — install-mode pre-check + callback notify ──
+  async currentNonce(accountAddress) {
+    const res = await this.exchange({ type: "current_nonce", accountAddress });
+    if (res.type !== "current_nonce") {
+      throw new BrokerClientError(
+        "protocol_error",
+        `expected current_nonce response, got ${res.type}`
+      );
+    }
+    if (res.accountAddress.toLowerCase() !== accountAddress.toLowerCase()) {
+      throw new BrokerClientError(
+        "protocol_error",
+        `current_nonce echo mismatch (requested ${accountAddress}, got ${res.accountAddress})`
+      );
+    }
+    return res;
+  }
+  async notifyUseropLanded(args) {
+    const res = await this.exchange({ type: "notify_userop_landed", ...args });
+    if (res.type !== "notify_userop_landed") {
+      throw new BrokerClientError(
+        "protocol_error",
+        `expected notify_userop_landed response, got ${res.type}`
+      );
+    }
+    return res;
+  }
   /**
    * Detect whether the running daemon speaks Path D (protocol 0.4.0+).
    * Wraps `hello()` with a semver-gte comparison so the MCP tool layer
@@ -928,6 +1084,9 @@ var BackendClient = class {
       const jwt = await this.options.jwtSource.get();
       headers.authorization = `Bearer ${jwt}`;
     }
+    return this.runFetch(method, url, body, headers);
+  }
+  async runFetch(method, url, body, headers) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), this.options.timeoutMs);
     let res;
@@ -1137,12 +1296,12 @@ var BundlerClient = class _BundlerClient {
     }
     const obj = result;
     return {
-      callGasLimit: assertHex(obj.callGasLimit, "estimateUserOpGas.callGasLimit"),
-      verificationGasLimit: assertHex(
+      callGasLimit: assertHexQuantity(obj.callGasLimit, "estimateUserOpGas.callGasLimit"),
+      verificationGasLimit: assertHexQuantity(
         obj.verificationGasLimit,
         "estimateUserOpGas.verificationGasLimit"
       ),
-      preVerificationGas: assertHex(
+      preVerificationGas: assertHexQuantity(
         obj.preVerificationGas,
         "estimateUserOpGas.preVerificationGas"
       )
@@ -1512,8 +1671,19 @@ function assertHex(value, label) {
   }
   return value;
 }
+function assertHexQuantity(value, label) {
+  if (typeof value !== "string" || !/^0x[0-9a-fA-F]+$/.test(value)) {
+    const repr = value === void 0 ? "undefined" : JSON.stringify(value);
+    const safe = typeof repr === "string" ? repr.slice(0, 80) : "unknown";
+    throw new BundlerClientError(
+      "invalid_response",
+      `${label} must be a 0x-prefixed hex quantity (got ${safe})`
+    );
+  }
+  return value;
+}
 function assertHexNonZero(value, label, maxValue) {
-  const hex = assertHex(value, label);
+  const hex = assertHexQuantity(value, label);
   if (hex.length === 2 || BigInt(hex) === 0n) {
     throw new BundlerClientError(
       "invalid_response",
@@ -1964,6 +2134,26 @@ function encodeKernelExecuteSingleCall(input) {
     args: [KERNEL_V3_SINGLE_CALL_MODE_DEFAULT, executionCalldata]
   });
 }
+function decodeKernelExecuteSingleCall(data) {
+  let decoded;
+  try {
+    decoded = decodeFunctionData({ abi: KERNEL_EXECUTE_ABI, data });
+  } catch {
+    return null;
+  }
+  const [mode, executionCalldata] = decoded.args;
+  if (mode !== KERNEL_V3_SINGLE_CALL_MODE_DEFAULT) {
+    return null;
+  }
+  const ec = executionCalldata.slice(2);
+  if (ec.length < 20 * 2 + 32 * 2) {
+    return null;
+  }
+  const target = `0x${ec.slice(0, 40)}`;
+  const value = BigInt(`0x${ec.slice(40, 40 + 64)}`);
+  const innerCallData = `0x${ec.slice(40 + 64)}`;
+  return { mode, target, value, innerCallData };
+}
 var ECDSA_SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
 var PERMISSION_USE_PREFIX = "0xff";
 function buildKernelSessionKeySignature(input) {
@@ -1975,6 +2165,7 @@ function buildKernelSessionKeySignature(input) {
   return concatHex([PERMISSION_USE_PREFIX, input.ecdsaSignature]);
 }
 var VALIDATOR_MODE_DEFAULT = "0x00";
+var VALIDATOR_MODE_ENABLE = "0x01";
 var VALIDATOR_TYPE_PERMISSION = "0x02";
 var PERMISSION_ID_HEX_RE = /^0x[0-9a-fA-F]{8}$/;
 function composeKernelV3NonceKey(args) {
@@ -1991,9 +2182,10 @@ function composeKernelV3NonceKey(args) {
   }
   const paddedPermissionId = pad(args.permissionId, { size: 20, dir: "right" });
   const customKeyHex = pad(`0x${customKey.toString(16)}`, { size: 2 });
+  const modeByte = args.mode === "enable" ? VALIDATOR_MODE_ENABLE : VALIDATOR_MODE_DEFAULT;
   const composite = pad(
     concatHex([
-      VALIDATOR_MODE_DEFAULT,
+      modeByte,
       VALIDATOR_TYPE_PERMISSION,
       paddedPermissionId,
       customKeyHex
@@ -2002,6 +2194,38 @@ function composeKernelV3NonceKey(args) {
   );
   return BigInt(composite);
 }
+var CALL_TYPE_DELEGATE_CALL = "0xFF";
+var ZERO_ADDRESS_HEX = "0x0000000000000000000000000000000000000000";
+function wrapEnableModeSignature(input) {
+  const selectorData = concatHex([
+    input.action.selector,
+    input.action.address,
+    input.action.hookAddress ?? ZERO_ADDRESS_HEX,
+    encodeAbiParameters(
+      parseAbiParameters("bytes selectorInitData, bytes hookInitData"),
+      [CALL_TYPE_DELEGATE_CALL, "0x0000"]
+    )
+  ]);
+  const abiEncoded = encodeAbiParameters(
+    parseAbiParameters(
+      "bytes validatorData, bytes hookData, bytes selectorData, bytes enableSig, bytes userOpSig"
+    ),
+    [
+      input.enableData,
+      input.hookData ?? "0x",
+      selectorData,
+      input.enableSig,
+      input.userOpSignature
+    ]
+  );
+  return concatHex([input.hookAddress ?? ZERO_ADDRESS_HEX, abiEncoded]);
+}
+parseAbi([
+  "function currentNonce() view returns (uint32)"
+]);
+parseAbi([
+  "event SelectorSet(bytes4 selector, bytes21 vId, bool allowed)"
+]);
 
 // src/tools/auth-required.ts
 function authRequiredPayload() {
@@ -2353,6 +2577,79 @@ async function syncSnapshotFromMirror(deps, brokerSignerAddress) {
   }
   return { kind: "ok", sessionId: activeId };
 }
+var PURCHASE_SELECTOR_LOWER = SUBSCRIPTION_PURCHASE_SELECTOR.toLowerCase();
+function buildPathDDecodedCall(trace, deps) {
+  const sponsorEvent = trace.find((e) => e.method === "zd_sponsorUserOperation");
+  if (!sponsorEvent) return void 0;
+  let req;
+  try {
+    req = JSON.parse(sponsorEvent.requestBody);
+  } catch {
+    return void 0;
+  }
+  const userOp = req.params?.[0]?.userOp;
+  if (!userOp || typeof userOp.callData !== "string" || !userOp.callData.startsWith("0x")) {
+    return void 0;
+  }
+  const sender = userOp.sender ?? "<missing>";
+  const decoded = decodeKernelExecuteSingleCall(userOp.callData);
+  if (!decoded) {
+    return {
+      sender,
+      kernelExecuteMode: "<undecodable>",
+      kernelExecuteTarget: "<undecodable>",
+      kernelExecuteValue: "<undecodable>",
+      innerSelector: "<undecodable>",
+      interpretation: "kernel.execute callData could not be decoded as single-call default mode. The mode word is non-zero or the executionCalldata layout is unexpected. Manual decode required."
+    };
+  }
+  const innerSelector = decoded.innerCallData.slice(0, 10).toLowerCase();
+  let innerPurchaseTokenArg;
+  let innerPurchaseMaxSharesHint;
+  let innerPurchaseEphemeralEOA;
+  if (innerSelector === PURCHASE_SELECTOR_LOWER) {
+    try {
+      const inner = decodeFunctionData({
+        abi: SUBSCRIPTION_PURCHASE_ABI,
+        data: decoded.innerCallData
+      });
+      const [tokenArg, , maxSharesHint, ephemeralEOA] = inner.args;
+      innerPurchaseTokenArg = tokenArg;
+      innerPurchaseMaxSharesHint = maxSharesHint.toString();
+      innerPurchaseEphemeralEOA = ephemeralEOA;
+    } catch {
+    }
+  }
+  const expectedSubscriptionAddress = deps.subscriptionAddress?.toLowerCase();
+  const kernelTargetLower = decoded.target.toLowerCase();
+  let kernelExecuteTargetMatchesSubscription;
+  let interpretation;
+  if (expectedSubscriptionAddress === void 0) {
+    interpretation = `kernel.execute target=${decoded.target}; inner purchase token=${innerPurchaseTokenArg ?? "<unknown>"}; MUHAVEN_SUBSCRIPTION_ADDRESS not wired on this MCP server \u2014 cannot cross-check.`;
+  } else if (kernelTargetLower === expectedSubscriptionAddress) {
+    kernelExecuteTargetMatchesSubscription = true;
+    interpretation = `kernel.execute target matches MuHavenSubscription (${decoded.target}). Inner purchase token = ${innerPurchaseTokenArg ?? "<unknown>"}. The shape is correct; the AA23 revert is downstream of the validator's signature decode \u2014 likely either an on-chain signer-vs-installed-permission mismatch, a target/selector not in the on-chain policy, or a cap-arg breach. Check muhaven.policy.session_key_status for the installed permission state.`;
+  } else if (innerPurchaseTokenArg !== void 0 && kernelTargetLower === innerPurchaseTokenArg.toLowerCase()) {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} = the RWA MuHavenToken (purchase.token arg0). Expected MuHavenSubscription (${deps.subscriptionAddress}). The kernel is dispatching purchase() to the token contract instead of the subscription \u2014 token doesn't have a purchase() selector, so fallback returns empty revert data (= AA23 reverted 0x). This is a code-side bug in the kernel.execute target wiring.`;
+  } else {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} \u2014 NEITHER the expected MuHavenSubscription (${deps.subscriptionAddress}) NOR the inner purchase.token arg (${innerPurchaseTokenArg ?? "<none>"}). This is an unexpected third-address dispatch; inspect deps.subscriptionAddress env wiring.`;
+  }
+  return {
+    sender,
+    kernelExecuteMode: decoded.mode,
+    kernelExecuteTarget: decoded.target,
+    kernelExecuteValue: decoded.value.toString(),
+    innerSelector,
+    innerPurchaseTokenArg,
+    innerPurchaseMaxSharesHint,
+    innerPurchaseEphemeralEOA,
+    expectedSubscriptionAddress: deps.subscriptionAddress,
+    kernelExecuteTargetMatchesSubscription,
+    interpretation
+  };
+}
 async function attemptPathD(args, deps) {
   const { shares, tokenAddress, tokenSymbol } = args;
   if (!deps.broker || !deps.bundler) {
@@ -2475,6 +2772,9 @@ async function attemptPathD(args, deps) {
     };
   }
   let accountAddress;
+  let mirrorEnableStatus;
+  let mirrorValidatorNonce;
+  let mirrorSessionRow = null;
   try {
     const stateDto = await deps.backend.get("/api/v1/agent/policy/state", {
       surface: "mcp"
@@ -2494,6 +2794,18 @@ async function attemptPathD(args, deps) {
       message: `backend /agent/policy/state lookup failed: ${err2 instanceof Error ? err2.message : String(err2)}`
     };
   }
+  try {
+    const mirror = await deps.backend.get(
+      "/api/v1/agent/policy/scoped-session",
+      { surface: "mcp" }
+    );
+    if (mirror?.session) {
+      mirrorSessionRow = mirror.session;
+      mirrorEnableStatus = mirror.session.enableStatus ?? null;
+      mirrorValidatorNonce = mirror.session.validatorNonce ?? null;
+    }
+  } catch (err2) {
+  }
   if (!snapshot.permissionId) {
     return {
       kind: "fallback",
@@ -2502,6 +2814,115 @@ async function attemptPathD(args, deps) {
     };
   }
   const permissionId = snapshot.permissionId;
+  if (mirrorEnableStatus === "failed") {
+    return {
+      kind: "fallback",
+      reason: "validator_install_failed_re_walk_required",
+      message: "previous Scoped session validator install was flagged failed by the watchdog \u2014 re-walk /agent/policy/transition to mint a fresh session"
+    };
+  }
+  const needsEnable = mirrorEnableStatus === "pending";
+  if (needsEnable && mirrorSessionRow && mirrorSessionRow.signerAddress.toLowerCase() !== snapshot.signerAddress.toLowerCase()) {
+    return {
+      kind: "fallback",
+      reason: "signer_mismatch",
+      message: `mirror row signer ${mirrorSessionRow.signerAddress} disagrees with broker snapshot signer ${snapshot.signerAddress} \u2014 refusing install`
+    };
+  }
+  if (needsEnable && mirrorSessionRow?.permissionId && mirrorSessionRow.permissionId.toLowerCase() !== permissionId.toLowerCase()) {
+    return {
+      kind: "fallback",
+      reason: "install_material_malformed",
+      message: `mirror row permissionId ${mirrorSessionRow.permissionId} disagrees with broker snapshot permissionId ${permissionId} \u2014 refusing install`
+    };
+  }
+  let installMaterial = null;
+  if (needsEnable) {
+    if (!mirrorSessionRow?.sessionId) {
+      return {
+        kind: "fallback",
+        reason: "install_material_malformed",
+        message: "mirror reports enable_status=pending but no sessionId was carried back \u2014 backend response shape regressed"
+      };
+    }
+    let raw;
+    try {
+      raw = await deps.backend.get(
+        `/api/v1/agent/policy/scoped-session/${encodeURIComponent(
+          mirrorSessionRow.sessionId
+        )}/install-material`
+      );
+    } catch (err2) {
+      if (err2 instanceof BackendError && err2.status === 404) {
+        return {
+          kind: "fallback",
+          reason: "install_material_malformed",
+          message: "install-material subroute returned 404 \u2014 row vanished mid-flow OR not owned by the authenticated user; re-walk the ceremony"
+        };
+      }
+      if (err2 instanceof BackendError && err2.status === 401) {
+        return {
+          kind: "fallback",
+          reason: "install_material_unavailable",
+          message: "install-material fetch returned 401 \u2014 the broker device-flow JWT is missing/expired/invalid. Run `muhaven-broker login` to refresh it, then retry."
+        };
+      }
+      if (err2 instanceof BackendError && err2.status === 403) {
+        return {
+          kind: "fallback",
+          reason: "install_material_unavailable",
+          message: "install-material fetch returned 403 \u2014 the broker JWT lacks the `mcp.propose.*` scope. Re-authorize via `muhaven-broker login` (the device-flow must grant propose, not read-only). NOT a session problem \u2014 do not re-mint."
+        };
+      }
+      if (err2 instanceof BackendError && (err2.status === void 0 || err2.status >= 500)) {
+        return {
+          kind: "fallback",
+          reason: "install_material_unavailable",
+          message: `install-material fetch hit a transient backend error (${typedErrorCode(err2)}) \u2014 retry shortly. If it persists, the operator should check backend logs + that OPTION_D_C2_ENCRYPTION_KEY is set. NOT a session problem \u2014 do not re-mint.`
+        };
+      }
+      return {
+        kind: "fallback",
+        reason: "install_material_malformed",
+        message: `install-material lookup failed (${typedErrorCode(err2)})`
+      };
+    }
+    if (!raw?.installMaterial || !raw.installMaterial.enableData || !raw.installMaterial.enableSig || raw.installMaterial.validatorNonce == null || raw.installMaterial.permissionId == null) {
+      return {
+        kind: "fallback",
+        reason: "install_material_malformed",
+        message: "install-material subroute returned partial payload (enable_data / enable_sig / validator_nonce / permission_id) \u2014 re-walk the ceremony"
+      };
+    }
+    if (raw.installMaterial.permissionId.toLowerCase() !== permissionId.toLowerCase()) {
+      return {
+        kind: "fallback",
+        reason: "install_material_malformed",
+        message: `install-material permissionId ${raw.installMaterial.permissionId} disagrees with broker snapshot permissionId ${permissionId} \u2014 re-walk the ceremony`
+      };
+    }
+    installMaterial = raw.installMaterial;
+    try {
+      const liveNonce = await deps.broker.currentNonce(accountAddress);
+      const minted = installMaterial.validatorNonce ?? mirrorValidatorNonce ?? null;
+      if (minted !== null && liveNonce.nonce !== minted) {
+        return {
+          kind: "fallback",
+          reason: "enable_sig_stale",
+          message: `kernel.currentNonce() advanced ${minted} \u2192 ${liveNonce.nonce} since mint; the stored enableSig is over a stale typed-data digest. ` + (liveNonce.nonce === minted + 1 ? "This is most likely the benign post-install race (your own MODE.ENABLE just landed; the mirror flips to enabled within a few seconds) \u2014 WAIT a few seconds and retry; the repeat buy will use MODE.DEFAULT. Only re-mint if it persists." : "The validator nonce diverged by more than one \u2014 re-mint the Scoped session from the dashboard.")
+        };
+      }
+    } catch (err2) {
+      if (err2 instanceof BrokerClientError && err2.brokerCode === "chain_rpc_failed") {
+        return {
+          kind: "fallback",
+          reason: "broker_chain_rpc_failed",
+          message: "broker daemon currentNonce IPC returned chain_rpc_failed \u2014 set MUHAVEN_BROKER_RPC_URL on the broker (or MUHAVEN_BUNDLER_URL fallback) and restart"
+        };
+      }
+      return mapBrokerCallFailure(err2, "current_nonce", "broker_internal");
+    }
+  }
   let encShares;
   let ephemeralEOA;
   try {
@@ -2562,7 +2983,10 @@ async function attemptPathD(args, deps) {
   let nonce;
   let feeData;
   try {
-    const nonceKey = composeKernelV3NonceKey({ permissionId });
+    const nonceKey = composeKernelV3NonceKey({
+      permissionId,
+      mode: needsEnable ? "enable" : "default"
+    });
     nonce = await deps.bundler.getNonce(accountAddress, entryPointAddress, nonceKey);
     feeData = await deps.bundler.getFeeData();
   } catch (err2) {
@@ -2572,13 +2996,32 @@ async function attemptPathD(args, deps) {
       message: `bundler bootstrap failed: ${err2 instanceof BundlerClientError ? `${err2.code}: ${err2.message}` : String(err2)}`
     };
   }
+  let wrapForEnableMode = null;
+  if (needsEnable && installMaterial) {
+    const kernelExecuteSelector = toFunctionSelector(
+      KERNEL_EXECUTE_ABI[0]
+    ).toLowerCase();
+    const enableActionAddress = "0x0000000000000000000000000000000000000000";
+    const enableData = installMaterial.enableData;
+    const enableSig = installMaterial.enableSig;
+    wrapForEnableMode = (userOpSig) => wrapEnableModeSignature({
+      enableData,
+      enableSig,
+      userOpSignature: userOpSig,
+      action: {
+        selector: kernelExecuteSelector,
+        address: enableActionAddress
+      }
+    });
+  }
+  const sponsorshipSignature = wrapForEnableMode ? wrapForEnableMode(PLACEHOLDER_SIGNATURE) : PLACEHOLDER_SIGNATURE;
   const partial = {
     sender: accountAddress,
     nonce: `0x${nonce.toString(16)}`,
     callData: kernelCallData,
     maxFeePerGas: feeData.maxFeePerGas,
     maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
-    signature: PLACEHOLDER_SIGNATURE
+    signature: sponsorshipSignature
   };
   let sponsored;
   try {
@@ -2663,6 +3106,10 @@ async function attemptPathD(args, deps) {
     }
     return mapBrokerCallFailure(err2, "sign_userop", "broker_internal");
   }
+  const wrappedSessionKeySig = buildKernelSessionKeySignature({
+    ecdsaSignature: brokerSig
+  });
+  const finalSignature = wrapForEnableMode ? wrapForEnableMode(wrappedSessionKeySig) : wrappedSessionKeySig;
   const signedUserOpWire = {
     sender: accountAddress,
     nonce: partial.nonce,
@@ -2676,7 +3123,7 @@ async function attemptPathD(args, deps) {
     paymasterVerificationGasLimit: sponsored.paymasterVerificationGasLimit,
     paymasterPostOpGasLimit: sponsored.paymasterPostOpGasLimit,
     paymasterData: sponsored.paymasterData,
-    signature: buildKernelSessionKeySignature({ ecdsaSignature: brokerSig })
+    signature: finalSignature
   };
   let submittedHash;
   try {
@@ -2698,6 +3145,37 @@ async function attemptPathD(args, deps) {
   }
   try {
     const receipt = await deps.bundler.waitForReceipt(userOpHash, { timeoutMs: 12e3 });
+    if (needsEnable && activeId) {
+      try {
+        let permissionLogIndex = 0;
+        try {
+          const r = receipt.receipt;
+          if (Array.isArray(r.logs)) {
+            const SELECTOR_SET_TOPIC0 = toEventSelector(
+              "SelectorSet(bytes4,bytes21,bool)"
+            ).toLowerCase();
+            for (const l of r.logs) {
+              if (l.topics?.[0]?.toLowerCase() === SELECTOR_SET_TOPIC0 && l.address?.toLowerCase() === accountAddress.toLowerCase()) {
+                permissionLogIndex = l.logIndex ?? 0;
+                break;
+              }
+            }
+          }
+        } catch {
+        }
+        await deps.broker.notifyUseropLanded({
+          sessionId: activeId,
+          accountAddress,
+          permissionId,
+          txHash: receipt.receipt.transactionHash,
+          blockNumber: Number(
+            receipt.receipt.blockNumber ?? 0
+          ),
+          logIndex: permissionLogIndex
+        });
+      } catch {
+      }
+    }
     return {
       kind: "ok",
       data: {
@@ -2800,6 +3278,7 @@ async function positionBuy(input, deps) {
   let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
   let pathDBundlerTrace;
+  let pathDDecodedCall;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
     deps
@@ -2817,6 +3296,7 @@ async function positionBuy(input, deps) {
       const trace = deps.bundler.drainTrace();
       if (trace.length > 0) {
         pathDBundlerTrace = trace;
+        pathDDecodedCall = buildPathDDecodedCall(trace, deps);
       }
     }
   }
@@ -2843,7 +3323,8 @@ ${dashboardUrl}`,
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
       ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
       ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {},
-      ...pathDBundlerTrace ? { pathDBundlerTrace } : {}
+      ...pathDBundlerTrace ? { pathDBundlerTrace } : {},
+      ...pathDDecodedCall ? { pathDDecodedCall } : {}
     }
   });
 }
@@ -3194,7 +3675,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.8";
+    return "0.3.0";
   }
 }
 function toJsonInputSchema(schema) {
@@ -3994,11 +4475,285 @@ function checkPolicy(input) {
   }
   return { ok: true };
 }
+var KERNEL_V3_CURRENT_NONCE_ABI2 = parseAbi([
+  "function currentNonce() view returns (uint32)"
+]);
+var ChainRpcError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ChainRpcError";
+  }
+  cause;
+};
+var CallbackError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "CallbackError";
+  }
+  cause;
+};
+var CALLBACK_RETRY_SCHEDULE_MS = [
+  5e3,
+  15e3,
+  6e4,
+  5 * 6e4
+];
+var CALLBACK_MAX_ELAPSED_MS = 60 * 6e4;
+var DEFAULT_FETCH_TIMEOUT_MS = 15e3;
+var BrokerOutbound = class {
+  constructor(config, log = () => {
+  }) {
+    this.config = config;
+    this.log = log;
+    this.fetchImpl = config.fetchImpl ?? fetch;
+    this.fetchTimeoutMs = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    this.setTimeoutImpl = config.setTimeout ?? setTimeout;
+    this.clearTimeoutImpl = config.clearTimeout ?? clearTimeout;
+  }
+  config;
+  log;
+  fetchImpl;
+  fetchTimeoutMs;
+  setTimeoutImpl;
+  clearTimeoutImpl;
+  /**
+   * Wave 5 Option D Commit 3 (multi-agent review SecEng-MED-3) —
+   * in-process dedup of `notify_userop_landed` callbacks. Map of
+   * `<sessionId>:<txHash>` → the in-flight retry loop's Promise.
+   * Repeated IPC calls with the same key fold into the existing
+   * loop instead of spawning a parallel POST. Defends against a
+   * local-socket peer flooding the broker with replay attempts +
+   * caps the retry-budget waste at one loop per real install.
+   */
+  inflightCallbacks = /* @__PURE__ */ new Map();
+  /**
+   * Read the kernel's `currentNonce()` view via `eth_call` against the
+   * configured chain RPC. Returns a uint32. Throws `ChainRpcError` when
+   * unconfigured / network failed / RPC returned non-decodable bytes.
+   */
+  async currentNonce(accountAddress) {
+    if (!this.config.chainRpcUrl) {
+      throw new ChainRpcError(
+        "broker chain RPC unconfigured \u2014 set MUHAVEN_BROKER_RPC_URL or MUHAVEN_BUNDLER_URL"
+      );
+    }
+    const data = encodeFunctionData({
+      abi: KERNEL_V3_CURRENT_NONCE_ABI2,
+      functionName: "currentNonce"
+    });
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "eth_call",
+      params: [{ to: accountAddress, data }, "latest"]
+    });
+    let res;
+    const ac = new AbortController();
+    const timer = this.setTimeoutImpl(() => ac.abort(), this.fetchTimeoutMs);
+    try {
+      res = await this.fetchImpl(this.config.chainRpcUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          Origin: this.config.outboundOriginHeader
+        },
+        body,
+        signal: ac.signal
+      });
+    } catch (err2) {
+      throw new ChainRpcError(
+        `chain RPC fetch failed: ${err2 instanceof Error ? err2.message : String(err2)}`,
+        err2
+      );
+    } finally {
+      this.clearTimeoutImpl(timer);
+    }
+    if (!res.ok) {
+      throw new ChainRpcError(
+        `chain RPC returned HTTP ${res.status}`
+      );
+    }
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch (err2) {
+      throw new ChainRpcError(
+        `chain RPC returned non-JSON: ${err2 instanceof Error ? err2.message : String(err2)}`
+      );
+    }
+    if (parsed.error) {
+      throw new ChainRpcError(
+        `chain RPC error: ${parsed.error.message ?? "unknown"}`
+      );
+    }
+    if (typeof parsed.result !== "string" || !/^0x[0-9a-fA-F]*$/.test(parsed.result)) {
+      throw new ChainRpcError(
+        `chain RPC returned non-hex result: ${JSON.stringify(parsed.result).slice(0, 80)}`
+      );
+    }
+    let nonce;
+    try {
+      const decoded = decodeAbiParameters(
+        [{ type: "uint32" }],
+        parsed.result
+      );
+      nonce = Number(decoded[0]);
+    } catch (err2) {
+      throw new ChainRpcError(
+        `failed to decode currentNonce result: ${err2 instanceof Error ? err2.message : String(err2)}`
+      );
+    }
+    if (!Number.isFinite(nonce) || nonce < 0 || nonce > 4294967295) {
+      throw new ChainRpcError(`currentNonce out of uint32 range: ${nonce}`);
+    }
+    return nonce;
+  }
+  /**
+   * Whether the callback path is wired (both secret + backend URL set).
+   * The `notify_userop_landed` daemon handler checks this and returns
+   * `callback_unconfigured` when false so the operator sees the gap.
+   */
+  isCallbackConfigured() {
+    return Boolean(this.config.callbackServiceSecret) && Boolean(this.config.backendBaseUrl);
+  }
+  /**
+   * Queue a `validator-enabled` callback POST to the backend. Returns
+   * immediately; the retry loop runs in the background (5s / 15s / 60s
+   * / 5m, max 1h elapsed). Failures are logged but do NOT propagate to
+   * the IPC caller — the chain indexer is the authoritative safety
+   * net.
+   *
+   * Idempotency: every POST carries an `Idempotency-Key` header
+   * `<sessionId>:validator-enabled`. The backend route is no-op if the
+   * mirror row's `enable_status` is already `'enabled'` (because the
+   * chain indexer raced ahead).
+   *
+   * Returns a Promise resolved when the loop terminates (success or
+   * max-elapsed). Callers don't need to await; tests use it for
+   * deterministic assertions.
+   */
+  enqueueValidatorEnabledCallback(args) {
+    if (!this.isCallbackConfigured()) {
+      return Promise.resolve({
+        ok: false,
+        attempts: 0,
+        lastError: "callback_unconfigured"
+      });
+    }
+    const dedupKey = `${args.sessionId}:${args.txHash.toLowerCase()}:${args.accountAddress.toLowerCase()}`;
+    const existing = this.inflightCallbacks.get(dedupKey);
+    if (existing) {
+      this.log("info", "validator-enabled callback already in flight \u2014 folded", {
+        sessionId: args.sessionId
+      });
+      return existing;
+    }
+    const promise = this.runCallbackLoop(args).finally(() => {
+      this.inflightCallbacks.delete(dedupKey);
+    });
+    this.inflightCallbacks.set(dedupKey, promise);
+    return promise;
+  }
+  async runCallbackLoop(args) {
+    const url = `${this.config.backendBaseUrl.replace(/\/+$/, "")}/api/v1/agent/policy/scoped-session/${encodeURIComponent(args.sessionId)}/validator-enabled`;
+    const body = JSON.stringify({
+      userId: args.userId,
+      accountAddress: args.accountAddress,
+      permissionId: args.permissionId,
+      txHash: args.txHash,
+      blockNumber: args.blockNumber,
+      logIndex: args.logIndex
+    });
+    const startedAt = Date.now();
+    let attempts = 0;
+    let lastError;
+    for (let i = 0; i <= CALLBACK_RETRY_SCHEDULE_MS.length; i++) {
+      if (i > 0) {
+        const delay2 = CALLBACK_RETRY_SCHEDULE_MS[i - 1] ?? 0;
+        const elapsed = Date.now() - startedAt;
+        if (elapsed + delay2 > CALLBACK_MAX_ELAPSED_MS) {
+          lastError = `retry budget exhausted after ${attempts} attempts (last error: ${lastError ?? "unknown"})`;
+          this.log("error", "validator-enabled callback abandoned", {
+            sessionId: args.sessionId,
+            attempts,
+            lastError
+          });
+          return { ok: false, attempts, lastError };
+        }
+        await this.sleep(delay2);
+      }
+      attempts++;
+      try {
+        const ok2 = await this.postCallback(url, body, args.sessionId);
+        if (ok2) {
+          this.log("info", "validator-enabled callback succeeded", {
+            sessionId: args.sessionId,
+            attempts
+          });
+          return { ok: true, attempts };
+        }
+        lastError = "non-2xx response";
+      } catch (err2) {
+        lastError = err2 instanceof Error ? err2.message : String(err2);
+        this.log("warn", "validator-enabled callback attempt failed", {
+          sessionId: args.sessionId,
+          attempt: attempts,
+          err: lastError
+        });
+      }
+    }
+    this.log("error", "validator-enabled callback retry budget exhausted", {
+      sessionId: args.sessionId,
+      attempts,
+      lastError
+    });
+    return { ok: false, attempts, lastError };
+  }
+  async postCallback(url, body, sessionId) {
+    const ac = new AbortController();
+    const timer = this.setTimeoutImpl(() => ac.abort(), this.fetchTimeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          Authorization: `Bearer ${this.config.callbackServiceSecret}`,
+          "Idempotency-Key": `${sessionId}:validator-enabled`,
+          Origin: this.config.outboundOriginHeader
+        },
+        body,
+        signal: ac.signal
+      });
+    } finally {
+      this.clearTimeoutImpl(timer);
+    }
+    if (res.status === 409) {
+      this.log("info", "callback returned 409 (row already enabled \u2014 idempotent)", {
+        sessionId
+      });
+      return true;
+    }
+    if (res.ok) return true;
+    throw new CallbackError(
+      `backend callback returned HTTP ${res.status}`
+    );
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      this.setTimeoutImpl(() => resolve(), ms);
+    });
+  }
+};
 
 // src/broker/daemon.ts
 var noopLogger = (_e) => {
 };
-async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.floor(Date.now() / 1e3), options = {}, policyStore) {
+async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.floor(Date.now() / 1e3), options = {}, policyStore, outbound) {
   switch (req.type) {
     case "hello": {
       let hasJwt = false;
@@ -4206,6 +4961,57 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
         );
       }
     }
+    case "current_nonce": {
+      if (!outbound) {
+        return errorResponse(
+          "chain_rpc_failed",
+          "broker daemon was not configured with a chain RPC URL"
+        );
+      }
+      try {
+        const nonce = await outbound.currentNonce(req.accountAddress);
+        return {
+          type: "current_nonce",
+          nonce,
+          accountAddress: req.accountAddress
+        };
+      } catch (err2) {
+        if (err2 instanceof ChainRpcError) {
+          return errorResponse("chain_rpc_failed", err2.message);
+        }
+        return errorResponse(
+          "chain_rpc_failed",
+          err2 instanceof Error ? err2.message : "chain RPC eth_call failed"
+        );
+      }
+    }
+    case "notify_userop_landed": {
+      if (!outbound) {
+        return errorResponse(
+          "callback_unconfigured",
+          "broker daemon was not configured with the callback service secret"
+        );
+      }
+      if (!outbound.isCallbackConfigured()) {
+        return errorResponse(
+          "callback_unconfigured",
+          "BROKER_CALLBACK_SERVICE_SECRET or backend URL is unset \u2014 validator-enabled callback skipped (chain indexer is the safety net)"
+        );
+      }
+      void outbound.enqueueValidatorEnabledCallback({
+        sessionId: req.sessionId,
+        accountAddress: req.accountAddress,
+        permissionId: req.permissionId,
+        txHash: req.txHash,
+        blockNumber: req.blockNumber,
+        logIndex: req.logIndex
+      });
+      return {
+        type: "notify_userop_landed",
+        queued: true,
+        sessionId: req.sessionId
+      };
+    }
   }
 }
 function errorResponse(code, message) {
@@ -4236,6 +5042,7 @@ var BrokerDaemon = class {
   config;
   keystore;
   policyStore;
+  outbound;
   /**
    * Whether a session-key private half is actually loaded. `false` =
    * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`
@@ -4256,6 +5063,15 @@ var BrokerDaemon = class {
     }
     this.keystore = options.keystore ?? null;
     this.policyStore = options.policyStore ?? new FilePolicyStore(FilePolicyStore.defaultDir());
+    this.outbound = options.outbound ?? new BrokerOutbound(
+      {
+        chainRpcUrl: options.config.chainRpcUrl,
+        backendBaseUrl: options.config.backendBaseUrl,
+        callbackServiceSecret: options.config.callbackServiceSecret,
+        outboundOriginHeader: options.config.outboundOriginHeader ?? options.config.dashboardBaseUrl
+      },
+      (level, msg, meta) => (options.logger ?? noopLogger)({ level, msg, meta })
+    );
     this.log = options.logger ?? noopLogger;
     this.server = createServer((socket) => this.onConnection(socket));
   }
@@ -4388,7 +5204,8 @@ var BrokerDaemon = class {
           },
           pid: process.pid
         },
-        this.policyStore
+        this.policyStore,
+        this.outbound
       );
       socket.end(serializeResponse(res));
     } catch (err2) {