@bnbagent/studio-cli 0.0.6-alpha.5 → 0.0.6-alpha.6

package/dist/bag.js

@@ -2722,6 +2722,11 @@ function client(networkName) {
   const net2 = getNetwork(networkName);
   return createPublicClient({ transport: http(net2.rpcUrl) });
 }
+async function readChainIdAt(rpcUrl) {
+  return createPublicClient({
+    transport: http(rpcUrl, { retryCount: 0, timeout: 5e3 })
+  }).getChainId();
+}
 async function readNativeBalanceRaw(address, networkName) {
   return client(networkName).getBalance({
     address: getAddress(address)
@@ -3192,44 +3197,6 @@ function relocateKeys(src, target, label) {
   return true;
 }
 
-// src/cli/_twakContractTargets.ts
-import { resolveNetwork } from "@bnbagent/sdk";
-var CONTRACT_OVERRIDES = [
-  ["ERC8004_REGISTRY_ADDRESS", "registryContract"],
-  ["ERC8183_COMMERCE_ADDRESS", "commerceContract"],
-  ["ERC8183_ROUTER_ADDRESS", "routerContract"],
-  ["ERC8183_POLICY_ADDRESS", "policyContract"]
-];
-function twakCustomContractOverrides(networkName, env = process.env) {
-  let network;
-  try {
-    network = resolveNetwork(networkName);
-  } catch {
-    return [];
-  }
-  const erc8183 = erc8183ContractOverrideState(env);
-  const out = [];
-  for (const [envKey, field] of CONTRACT_OVERRIDES) {
-    if (envKey.startsWith("ERC8183_") && erc8183.mode !== "custom") {
-      continue;
-    }
-    const configured = env[envKey]?.trim() ?? "";
-    if (!/^0x[0-9a-fA-F]{40}$/u.test(configured)) {
-      continue;
-    }
-    const canonical = network[field];
-    if (configured.toLowerCase() !== canonical.toLowerCase()) {
-      out.push({ envKey, configured, canonical });
-    }
-  }
-  return out;
-}
-function twakUnsupportedContractOverrides(networkName, env = process.env) {
-  return twakCustomContractOverrides(networkName, env).filter(
-    (item) => item.envKey.startsWith("ERC8183_")
-  );
-}
-
 // src/cli/init.ts
 import * as fs23 from "fs";
 import * as os4 from "os";
@@ -3498,6 +3465,46 @@ import * as fs15 from "fs";
 import * as path14 from "path";
 import { envLocalPath as envLocalPath7 } from "@bnbagent/studio-runtime/config";
 import { resolveTwakHome } from "@bnbagent/studio-runtime/wallet";
+
+// src/cli/_twakContractTargets.ts
+import { resolveNetwork } from "@bnbagent/sdk";
+var CONTRACT_OVERRIDES = [
+  ["ERC8004_REGISTRY_ADDRESS", "registryContract"],
+  ["ERC8183_COMMERCE_ADDRESS", "commerceContract"],
+  ["ERC8183_ROUTER_ADDRESS", "routerContract"],
+  ["ERC8183_POLICY_ADDRESS", "policyContract"]
+];
+function twakCustomContractOverrides(networkName, env = process.env) {
+  let network;
+  try {
+    network = resolveNetwork(networkName);
+  } catch {
+    return [];
+  }
+  const erc8183 = erc8183ContractOverrideState(env);
+  const out = [];
+  for (const [envKey, field] of CONTRACT_OVERRIDES) {
+    if (envKey.startsWith("ERC8183_") && erc8183.mode !== "custom") {
+      continue;
+    }
+    const configured = env[envKey]?.trim() ?? "";
+    if (!/^0x[0-9a-fA-F]{40}$/u.test(configured)) {
+      continue;
+    }
+    const canonical = network[field];
+    if (configured.toLowerCase() !== canonical.toLowerCase()) {
+      out.push({ envKey, configured, canonical });
+    }
+  }
+  return out;
+}
+function twakUnsupportedContractOverrides(networkName, env = process.env) {
+  return twakCustomContractOverrides(networkName, env).filter(
+    (item) => item.envKey.startsWith("ERC8183_")
+  );
+}
+
+// src/cli/_deploy/checks/twak.ts
 var AGENTCORE_DESCRIPTOR = path14.join("agentcore", "agentcore.json");
 function isTwak(data) {
   return tableOf2(data, "wallet").kind === "twak";
@@ -9858,6 +9865,57 @@ function isDir4(p) {
   }
 }
 
+// src/cli/_runtimeEnvKeys.ts
+function tableOf8(cfg, key) {
+  const v = cfg[key];
+  return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+function runtimeEnvKeysCore(cfg, resolvable) {
+  const walletKind2 = tableOf8(cfg, "wallet").kind ?? "evm-local";
+  let keys;
+  if (walletKind2 === "twak") {
+    keys = ["TWAK_WALLET_PASSWORD"];
+    for (const k of ["TWAK_ACCESS_ID", "TWAK_HMAC_SECRET"]) {
+      if (resolvable(k)) {
+        keys.push(k);
+      }
+    }
+  } else if (walletKind2 === "altana") {
+    keys = [];
+  } else {
+    keys = ["WALLET_PASSWORD"];
+  }
+  const provider = tableOf8(cfg, "llm").provider;
+  const providerKey = typeof provider === "string" ? PROVIDER_KEY_ENV[provider] : null;
+  if (providerKey) {
+    keys.push(providerKey);
+  }
+  const storageKind2 = String(
+    tableOf8(cfg, "storage").kind ?? "local"
+  ).toLowerCase();
+  if (storageKind2 === "ipfs") {
+    keys.push("STORAGE_API_URL");
+    if (resolvable("STORAGE_API_KEY")) {
+      keys.push("STORAGE_API_KEY");
+    }
+  }
+  if (resolvable("RPC_URL")) {
+    keys.push("RPC_URL");
+  }
+  if (commerceRails(cfg).erc8183) {
+    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+      if (resolvable(key)) keys.push(key);
+    }
+  }
+  const runtime = String(tableOf8(cfg, "stack").runtime ?? "agentcore");
+  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
+    for (const key of B402_RUNTIME_KEYS) {
+      if (resolvable(key)) keys.push(key);
+    }
+  }
+  return keys;
+}
+
 // src/cli/dev.ts
 var DEFAULT_AGENT_HOST = "127.0.0.1";
 var AGENTCORE_BIN = "agentcore";
@@ -9944,17 +10002,17 @@ function loadAgentToml2(workspaceRoot) {
     return {};
   }
 }
-function tableOf8(data, key) {
+function tableOf9(data, key) {
   const v = data[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
 function agentRuntime(workspaceRoot) {
-  const runtime = tableOf8(loadAgentToml2(workspaceRoot), "stack").runtime;
+  const runtime = tableOf9(loadAgentToml2(workspaceRoot), "stack").runtime;
   return typeof runtime === "string" && runtime.trim() ? runtime.trim() : RUNTIME_AGENTCORE;
 }
 function agentFaces(workspaceRoot) {
   const cfg = loadAgentToml2(workspaceRoot);
-  return stackFaces(tableOf8(cfg, "stack"), tableOf8(cfg, "payments"));
+  return stackFaces(tableOf9(cfg, "stack"), tableOf9(cfg, "payments"));
 }
 function localEntryFile(faces) {
   return `src/${entryStemOf(faces)}.ts`;
@@ -9969,7 +10027,7 @@ function storageKind(agentDir) {
   } catch {
     return "local";
   }
-  const kind = tableOf8(data, "storage").kind;
+  const kind = tableOf9(data, "storage").kind;
   return typeof kind === "string" && kind.trim() ? kind.trim() : "local";
 }
 function networkNameOf(agentDir) {
@@ -9979,7 +10037,7 @@ function networkNameOf(agentDir) {
   } catch {
     return "bsc-testnet";
   }
-  const name = tableOf8(data, "network").default;
+  const name = tableOf9(data, "network").default;
   return typeof name === "string" && name.trim() ? name.trim() : "bsc-testnet";
 }
 function walletKindOf(agentDir) {
@@ -9989,12 +10047,12 @@ function walletKindOf(agentDir) {
   } catch {
     return "evm-local";
   }
-  const kind = tableOf8(data, "wallet").kind;
+  const kind = tableOf9(data, "wallet").kind;
   return typeof kind === "string" && kind.trim() ? kind.trim() : "evm-local";
 }
 function altanaSessionForRuntime(agentDir) {
   const cfg = loadStudioToml11(path23.join(agentDir, "studio.toml"));
-  const wallet = tableOf8(cfg, "wallet");
+  const wallet = tableOf9(cfg, "wallet");
   const configured = String(
     wallet.session_file ?? ".studio/wallets/altana-session.json"
   );
@@ -10089,48 +10147,7 @@ function runtimeEnvKeys(agentDir) {
   } catch {
     cfg = {};
   }
-  const resolvable = (key) => Boolean(process.env[key]);
-  const kind = tableOf8(cfg, "wallet").kind;
-  let keys;
-  if (kind === "twak") {
-    keys = ["TWAK_WALLET_PASSWORD"];
-    for (const k of ["TWAK_ACCESS_ID", "TWAK_HMAC_SECRET"]) {
-      if (resolvable(k)) {
-        keys.push(k);
-      }
-    }
-  } else if (kind === "altana") {
-    keys = [];
-  } else {
-    keys = ["WALLET_PASSWORD"];
-  }
-  const provider = tableOf8(cfg, "llm").provider;
-  const providerKey = typeof provider === "string" ? PROVIDER_KEY_ENV[provider] : null;
-  if (providerKey) {
-    keys.push(providerKey);
-  }
-  const sk = String(tableOf8(cfg, "storage").kind ?? "local").toLowerCase();
-  if (sk === "ipfs") {
-    keys.push("STORAGE_API_URL");
-    if (resolvable("STORAGE_API_KEY")) {
-      keys.push("STORAGE_API_KEY");
-    }
-  }
-  if (resolvable("RPC_URL")) {
-    keys.push("RPC_URL");
-  }
-  if (commerceRails(cfg).erc8183) {
-    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
-      if (resolvable(key)) keys.push(key);
-    }
-  }
-  const runtime = String(tableOf8(cfg, "stack").runtime ?? "agentcore");
-  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
-    for (const key of B402_RUNTIME_KEYS) {
-      if (resolvable(key)) keys.push(key);
-    }
-  }
-  return keys;
+  return runtimeEnvKeysCore(cfg, (key) => Boolean(process.env[key]));
 }
 function compactJson(text2) {
   try {
@@ -10142,7 +10159,7 @@ function compactJson(text2) {
 function readTwakFiles(agentDir) {
   let walletCfg = {};
   try {
-    walletCfg = tableOf8(
+    walletCfg = tableOf9(
       loadStudioToml11(path23.join(agentDir, "studio.toml")),
       "wallet"
     );
@@ -10552,7 +10569,7 @@ function networkBanner(agentDir) {
   } catch {
     return null;
   }
-  const name = tableOf8(data, "network").default;
+  const name = tableOf9(data, "network").default;
   if (typeof name !== "string" || !name.trim()) {
     return null;
   }
@@ -10605,49 +10622,7 @@ function runtimeEnvKeys2(agentRoot2) {
     cfg = {};
   }
   const resolvable = (key) => Boolean(process.env[key] || getEnvVar(envLocalPath11(agentRoot2), key));
-  const walletKind2 = tableOf2(cfg, "wallet").kind ?? "evm-local";
-  let keys;
-  if (walletKind2 === "twak") {
-    keys = ["TWAK_WALLET_PASSWORD"];
-    for (const k of ["TWAK_ACCESS_ID", "TWAK_HMAC_SECRET"]) {
-      if (resolvable(k)) {
-        keys.push(k);
-      }
-    }
-  } else if (walletKind2 === "altana") {
-    keys = [];
-  } else {
-    keys = ["WALLET_PASSWORD"];
-  }
-  const provider = tableOf2(cfg, "llm").provider;
-  const providerKey = typeof provider === "string" ? PROVIDER_KEY_ENV[provider] : null;
-  if (providerKey) {
-    keys.push(providerKey);
-  }
-  const storageKind2 = String(
-    tableOf2(cfg, "storage").kind ?? "local"
-  ).toLowerCase();
-  if (storageKind2 === "ipfs") {
-    keys.push("STORAGE_API_URL");
-    if (resolvable("STORAGE_API_KEY")) {
-      keys.push("STORAGE_API_KEY");
-    }
-  }
-  if (resolvable("RPC_URL")) {
-    keys.push("RPC_URL");
-  }
-  if (commerceRails(cfg).erc8183) {
-    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
-      if (resolvable(key)) keys.push(key);
-    }
-  }
-  const runtime = String(tableOf2(cfg, "stack").runtime ?? "agentcore");
-  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
-    for (const key of B402_RUNTIME_KEYS) {
-      if (resolvable(key)) keys.push(key);
-    }
-  }
-  return keys;
+  return runtimeEnvKeysCore(cfg, resolvable);
 }
 var require2 = createRequire(import.meta.url);
 async function checkAgentcoreJsonPresent(root, target) {
@@ -11436,17 +11411,17 @@ function loadTomlOr(agentRoot2) {
     return {};
   }
 }
-function tableOf9(cfg, key) {
+function tableOf10(cfg, key) {
   const v = cfg[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
 function deployWalletKind(agentRoot2) {
-  const kind = tableOf9(loadTomlOr(agentRoot2), "wallet").kind;
+  const kind = tableOf10(loadTomlOr(agentRoot2), "wallet").kind;
   return kind ? String(kind) : "evm-local";
 }
 function resolveKeystoreDir3(agentRoot2) {
   const rel = String(
-    tableOf9(loadTomlOr(agentRoot2), "wallet").keystore_dir ?? ".studio/wallets"
+    tableOf10(loadTomlOr(agentRoot2), "wallet").keystore_dir ?? ".studio/wallets"
   );
   return path25.resolve(path25.isAbsolute(rel) ? rel : path25.join(agentRoot2, rel));
 }
@@ -11461,7 +11436,7 @@ function readKeystoreJson(agentRoot2) {
   if (names.length === 0) {
     return null;
   }
-  const address = tableOf9(loadTomlOr(agentRoot2), "wallet").address;
+  const address = tableOf10(loadTomlOr(agentRoot2), "wallet").address;
   let chosen = null;
   if (typeof address === "string" && address) {
     for (const n of names) {
@@ -12503,7 +12478,7 @@ import * as fs33 from "fs";
 import * as path32 from "path";
 import { envLocalPath as envLocalPath14 } from "@bnbagent/studio-runtime/config";
 import { show } from "@bnbagent/studio-runtime/erc8004";
-import { getNetwork as getNetwork8 } from "@bnbagent/studio-runtime/networks";
+import { DEFAULT_RPC, getNetwork as getNetwork8 } from "@bnbagent/studio-runtime/networks";
 import * as walletRt3 from "@bnbagent/studio-runtime/wallet";
 var TBNB_MIN_WEI = 7n * 10n ** 15n;
 function isFile13(p) {
@@ -12665,6 +12640,51 @@ async function checkRpcUrlSetForRuntime(root, _target) {
     }
   ];
 }
+async function checkRuntimeRpcReachable(root, _target) {
+  const netName = tableOf2(loadAgentToml(root), "network").default;
+  if (!netName || typeof netName !== "string") {
+    return [];
+  }
+  const expected = getNetwork8(netName).chainId;
+  const configured = process.env.RPC_URL || getEnvVar(envLocalPath14(root), "RPC_URL") || "";
+  const rpcUrl = configured || DEFAULT_RPC[netName] || "";
+  if (!rpcUrl) {
+    return [];
+  }
+  const source = configured ? "RPC_URL" : "the runtime default";
+  let actual;
+  try {
+    actual = await readChainIdAt(rpcUrl);
+  } catch (exc) {
+    return [
+      {
+        level: Level.WARNING,
+        name: "runtime_rpc_reachable",
+        message: `the RPC endpoint the deployed runtime will use (${rpcUrl}, from ${source}) did not answer eth_chainId (${exc instanceof Error ? exc.message.split("\n")[0] : String(exc)}). The seller's first chain read (e.g. notify_funded verification) will fail in the cloud until a working endpoint is set.`,
+        fixCmd: "bag env set RPC_URL <working-endpoint>",
+        details: { rpc_url: rpcUrl, source, network: netName }
+      }
+    ];
+  }
+  if (actual !== expected) {
+    return [
+      {
+        level: Level.WARNING,
+        name: "runtime_rpc_reachable",
+        message: `the RPC endpoint the deployed runtime will use (${rpcUrl}, from ${source}) answered chain_id=${actual}; expected ${expected} for ${netName}.`,
+        fixCmd: "bag env set RPC_URL <endpoint-on-the-right-chain>",
+        details: {
+          rpc_url: rpcUrl,
+          source,
+          network: netName,
+          expected,
+          actual
+        }
+      }
+    ];
+  }
+  return [];
+}
 async function checkInstalledRecipesUnchanged(root, _target) {
   const manifest = path32.join(root, ".studio", "recipes", "manifest.json");
   let data;
@@ -12780,6 +12800,7 @@ var allChecks4 = [
   checkAgentUriDataUriOrHttps,
   checkNetworkMatchesChainId,
   checkRpcUrlSetForRuntime,
+  checkRuntimeRpcReachable,
   checkInstalledRecipesUnchanged,
   checkCognitoAuthorizerConfigured,
   checkStorageLocalNotDeployable
@@ -12787,7 +12808,7 @@ var allChecks4 = [
 
 // src/cli/_deploy/checks/platform.ts
 var SLUG_RE = /^[a-z][a-z0-9-]{1,40}$/;
-function tableOf10(data, key) {
+function tableOf11(data, key) {
   const value = data[key];
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -12802,16 +12823,16 @@ function loadAgent(root) {
   }
 }
 function platformArtifact(data) {
-  const walletKind2 = String(tableOf10(data, "wallet").kind ?? "evm-local").trim().toLowerCase();
+  const walletKind2 = String(tableOf11(data, "wallet").kind ?? "evm-local").trim().toLowerCase();
   if (walletKind2 === "twak") return "container";
-  const deploy = tableOf10(data, "deploy");
+  const deploy = tableOf11(data, "deploy");
   const explicit = String(deploy.platform_artifact ?? "").toLowerCase();
   if (explicit) return explicit;
   return String(deploy.packaging ?? "").toLowerCase() === "container" ? "container" : "zip";
 }
 var checkPlatformEntrypointPresent = async (root, _target) => {
   const data = loadAgent(root);
-  const faces = stackFaces(tableOf10(data, "stack"), tableOf10(data, "payments"));
+  const faces = stackFaces(tableOf11(data, "stack"), tableOf11(data, "payments"));
   const stem2 = entryStemOf(faces);
   const filenames = [`${stem2}.ts`];
   if (stem2 === "dualMain") filenames.push("mcpMain.ts");
@@ -12831,7 +12852,7 @@ var checkPlatformEntrypointPresent = async (root, _target) => {
 };
 var checkPlatformKeystoreNotInArtifact = async (root, _target) => {
   const data = loadAgent(root);
-  const wallet = tableOf10(data, "wallet");
+  const wallet = tableOf11(data, "wallet");
   if (String(wallet.kind ?? "evm-local") === "twak") return [];
   const agent = path33.resolve(agentRoot(root));
   const configured = String(wallet.keystore_dir ?? ".studio/wallets");
@@ -12855,7 +12876,7 @@ var checkPlatformKeystoreNotInArtifact = async (root, _target) => {
   ];
 };
 var checkPlatformTestnetOnly = async (root, _target) => {
-  const network = String(tableOf10(loadAgent(root), "network").default ?? "").trim().toLowerCase();
+  const network = String(tableOf11(loadAgent(root), "network").default ?? "").trim().toLowerCase();
   if (!network || network === "bsc-testnet") return [];
   return [
     {
@@ -12868,7 +12889,7 @@ var checkPlatformTestnetOnly = async (root, _target) => {
   ];
 };
 var checkPlatformSlugValid = async (root, _target) => {
-  const platform = tableOf10(tableOf10(loadAgent(root), "deploy"), "platform");
+  const platform = tableOf11(tableOf11(loadAgent(root), "deploy"), "platform");
   const slug = String(platform.slug ?? "").trim();
   if (!slug || SLUG_RE.test(slug)) return [];
   return [
@@ -12926,7 +12947,7 @@ var checkPlatformStorageEndpoint = async (root, _target) => {
 };
 var checkPlatformMcpSyncTimeout = async (root, _target) => {
   const data = loadAgent(root);
-  const faces = stackFaces(tableOf10(data, "stack"), tableOf10(data, "payments"));
+  const faces = stackFaces(tableOf11(data, "stack"), tableOf11(data, "payments"));
   if (!hasMcpFace(faces)) return [];
   const dual = hasA2aFace(faces);
   return [
@@ -12939,8 +12960,8 @@ var checkPlatformMcpSyncTimeout = async (root, _target) => {
   ];
 };
 var checkPlatformX402MerchantsMainnet = async (root, _target) => {
-  const merchants = tableOf10(
-    tableOf10(tableOf10(loadAgent(root), "payments"), "x402"),
+  const merchants = tableOf11(
+    tableOf11(tableOf11(loadAgent(root), "payments"), "x402"),
     "merchants"
   );
   const names = Object.keys(merchants).sort();
@@ -13001,7 +13022,8 @@ var warningChecks = [
   checkPlatformX402MerchantsMainnet,
   checkWalletBalancesAllZero,
   checkWalletTbnbBalanceSufficient,
-  checkWalletUBalanceNonzero
+  checkWalletUBalanceNonzero,
+  checkRuntimeRpcReachable
 ];
 var infoChecks = [
   checkPlatformTrialStatus,
@@ -13273,15 +13295,15 @@ async function runVerify(opts) {
       exitCode: 1
     });
   }
-  const tableOf16 = (key) => {
+  const tableOf17 = (key) => {
     const v = data[key];
     return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
   };
-  const network = opts.network || String(tableOf16("network").default ?? "bsc-testnet");
+  const network = opts.network || String(tableOf17("network").default ?? "bsc-testnet");
   const protocol = nativeProtocolOf(
-    stackFaces(tableOf16("stack"), tableOf16("payments"))
+    stackFaces(tableOf17("stack"), tableOf17("payments"))
   );
-  const identity = tableOf16("identity");
+  const identity = tableOf17("identity");
   const existingAgentId = identity.agent_id;
   const accessDescription = accessSummaryForAgentcore(root, { protocol });
   let agentId = null;
@@ -13436,10 +13458,16 @@ var WALLET_SECTION = "wallet";
 var KEYSTORE_JSON_ENV2 = "WALLET_KEYSTORE_JSON";
 var TWAK_WALLET_JSON_ENV2 = "TWAK_WALLET_JSON";
 var WALLET_MATERIAL_KEYS = [KEYSTORE_JSON_ENV2, TWAK_WALLET_JSON_ENV2];
+var RETIRED_AGENT_STATES = /* @__PURE__ */ new Set([
+  "deleted",
+  "retired",
+  "removed",
+  "reclaiming"
+]);
 function isJsonObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function tableOf11(cfg, key) {
+function tableOf12(cfg, key) {
   const value = cfg[key];
   return isJsonObject(value) ? value : {};
 }
@@ -13474,7 +13502,7 @@ function loadAgentCfg(root) {
   }
 }
 function platformCfg(root) {
-  return tableOf11(tableOf11(loadAgentCfg(root), "deploy"), "platform");
+  return tableOf12(tableOf12(loadAgentCfg(root), "deploy"), "platform");
 }
 function patchTomlKv2(tomlPath, section, key, value) {
   let text2 = fs36.readFileSync(tomlPath, "utf-8");
@@ -13494,6 +13522,32 @@ function recordPlatformKv(root, key, value) {
   } catch {
   }
 }
+function retiredAgentReason(agent) {
+  const candidates = [agent];
+  for (const key of ["agent", "data"]) {
+    const nested = agent[key];
+    if (isJsonObject(nested)) {
+      candidates.push(nested);
+    }
+  }
+  for (const item of candidates) {
+    for (const key of [
+      "state",
+      "status",
+      "lifecycle_state",
+      "lifecycleState"
+    ]) {
+      const value = item[key];
+      if (typeof value === "string" && RETIRED_AGENT_STATES.has(value.toLowerCase())) {
+        return value.toLowerCase();
+      }
+    }
+    if (item.deleted_at || item.deletedAt) {
+      return "deleted";
+    }
+  }
+  return null;
+}
 function suggestNextSlug(slug) {
   const m = /(\d+)$/.exec(slug);
   let next;
@@ -13504,12 +13558,45 @@ function suggestNextSlug(slug) {
   }
   return next.slice(0, 41);
 }
+async function retiredSlugPreflight(slug, platformCmd) {
+  let res;
+  try {
+    res = await platformCmd(["list"], {
+      slug: "studio-platform",
+      json: true,
+      quiet: true
+    });
+  } catch {
+    return null;
+  }
+  if (res.code !== 0 || !isJsonObject(res.data)) {
+    return null;
+  }
+  const candidates = [res.data];
+  for (const key of ["agents", "data", "items", "records"]) {
+    const nested = res.data[key];
+    if (Array.isArray(nested)) {
+      candidates.push(...nested);
+    }
+  }
+  for (const entry of candidates) {
+    if (!isJsonObject(entry)) {
+      continue;
+    }
+    const entrySlug = String(entry.slug ?? entry.name ?? "").toLowerCase();
+    if (entrySlug !== slug.toLowerCase()) {
+      continue;
+    }
+    return retiredAgentReason(entry);
+  }
+  return null;
+}
 function clearIdentityEndpointIfMatches(root, oldUrl) {
   if (!oldUrl) {
     return;
   }
   const cfg = loadAgentCfg(root);
-  if (String(tableOf11(cfg, "identity").endpoint ?? "") !== String(oldUrl)) {
+  if (String(tableOf12(cfg, "identity").endpoint ?? "") !== String(oldUrl)) {
     return;
   }
   const tomlPath = agentTomlPath2(root);
@@ -13528,7 +13615,7 @@ function persistedPackaging2(agentRoot2) {
   }
   try {
     const cfg = loadStudioToml19(tomlPath);
-    const value = tableOf11(cfg, "deploy").packaging;
+    const value = tableOf12(cfg, "deploy").packaging;
     return value ? String(value) : null;
   } catch {
     return null;
@@ -13539,7 +13626,7 @@ function resolvePlatformArtifact2(agentRoot2) {
   if (isFile14(tomlPath)) {
     try {
       const cfg = loadStudioToml19(tomlPath);
-      const explicit = tableOf11(cfg, "deploy").platform_artifact;
+      const explicit = tableOf12(cfg, "deploy").platform_artifact;
       if (explicit) {
         return String(explicit);
       }
@@ -13551,7 +13638,7 @@ function resolvePlatformArtifact2(agentRoot2) {
 function platformPackaging(root) {
   const agentRoot2 = findSubProjectRoot15("agent", root);
   const platformArtifact2 = agentRoot2 !== null ? resolvePlatformArtifact2(agentRoot2) : "zip";
-  const walletKind2 = agentRoot2 !== null ? String(tableOf11(loadCfgAt(agentRoot2), "wallet").kind ?? "evm-local") : "evm-local";
+  const walletKind2 = agentRoot2 !== null ? String(tableOf12(loadCfgAt(agentRoot2), "wallet").kind ?? "evm-local") : "evm-local";
   if (walletKind2 === "twak") {
     return "container";
   }
@@ -13569,7 +13656,7 @@ function recordExposedAddress(root, address) {
   if (tomlPath === null) {
     return;
   }
-  const existing = tableOf11(
+  const existing = tableOf12(
     loadAgentCfg(root),
     WALLET_SECTION
   ).platform_exposed_addresses;
@@ -13589,7 +13676,7 @@ function utcStamp() {
 function buyerAccess(root) {
   const base = bnbPlatformApiUrl();
   const cfg = loadAgentCfg(root);
-  const faces = stackFaces(tableOf11(cfg, "stack"), tableOf11(cfg, "payments"));
+  const faces = stackFaces(tableOf12(cfg, "stack"), tableOf12(cfg, "payments"));
   const protocol = nativeProtocolOf(faces);
   const rawAgentId = platformCfg(root).agent_id;
   const agentId = typeof rawAgentId === "string" && rawAgentId ? rawAgentId : null;
@@ -13633,7 +13720,7 @@ function resolveSlug(root) {
   if (typeof recorded === "string" && recorded) {
     return recorded;
   }
-  let name = String(tableOf11(loadAgentCfg(root), "project").name ?? "");
+  let name = String(tableOf12(loadAgentCfg(root), "project").name ?? "");
   name = name.replace(/-(agent|service)$/, "");
   if (!name) {
     name = path36.basename(findWorkspaceRoot6(root) ?? root);
@@ -13713,6 +13800,11 @@ async function platformAgent(opts) {
   }
   const secrets = await (opts.collectRuntimeSecrets ?? collectRuntimeSecrets)(root);
   walletWarning(root, secrets);
+  if (Object.keys(secrets).length > 0) {
+    warn(
+      `note: runtime secret keys handed to the platform: ${Object.keys(secrets).sort().join(", ")} (names only \u2014 values not printed).`
+    );
+  }
   if (!opts.skipPrepare && opts.runPrepareGate) {
     const rc = await opts.runPrepareGate(root, opts.force ?? false);
     if (rc !== null && rc !== 0) {
@@ -13723,6 +13815,18 @@ async function platformAgent(opts) {
     }
   }
   const slug = resolveSlug(root);
+  {
+    const reason = await retiredSlugPreflight(slug, platformCmd);
+    if (reason !== null) {
+      const next = suggestNextSlug(slug);
+      warn(
+        `error: the slug '${slug}' is ${reason} on the platform \u2014 deploys to it always fail (destroyed slugs are permanently retired). Pick a new slug:
+  bag config set deploy.platform.slug ${next}
+then re-run the deploy.`
+      );
+      return 1;
+    }
+  }
   const agentDir = findSubProjectRoot15("agent", root);
   if (agentDir === null) {
     warn(
@@ -13731,7 +13835,7 @@ async function platformAgent(opts) {
     return 1;
   }
   const cfg = loadAgentCfg(root);
-  const faces = stackFaces(tableOf11(cfg, "stack"), tableOf11(cfg, "payments"));
+  const faces = stackFaces(tableOf12(cfg, "stack"), tableOf12(cfg, "payments"));
   const protocol = nativeProtocolOf(faces);
   const runDeploy = opts.runDelegatedDeploy ?? (async (o) => withDeployFiles(
     o.root,
@@ -13845,8 +13949,8 @@ async function confirmPackagingDefault(root, packaging, deps) {
     return null;
   }
   const cfg = loadAgentCfg(root);
-  const walletKind2 = String(tableOf11(cfg, "wallet").kind ?? "evm-local");
-  const destination = String(tableOf11(cfg, "deploy").destination ?? "platform");
+  const walletKind2 = String(tableOf12(cfg, "wallet").kind ?? "evm-local");
+  const destination = String(tableOf12(cfg, "deploy").destination ?? "platform");
   const answer = await deps.promptUser(
     `This project will deploy as a ${packaging} package (wallet.kind=${walletKind2}, destination=${destination}). Continue? [Y/n] `
   );
@@ -13860,7 +13964,7 @@ function walletWarning(root, secrets) {
   if (!WALLET_MATERIAL_KEYS.some((k) => k in secrets)) {
     return;
   }
-  const address = tableOf11(loadAgentCfg(root), "wallet").address;
+  const address = tableOf12(loadAgentCfg(root), "wallet").address;
   const who = typeof address === "string" && address ? `key (address ${address})` : "signing key";
   warn(
     `
@@ -13906,7 +14010,7 @@ function recordShippedWallet(root, secrets) {
   if (!WALLET_MATERIAL_KEYS.some((k) => k in secrets)) {
     return;
   }
-  const address = tableOf11(loadAgentCfg(root), "wallet").address;
+  const address = tableOf12(loadAgentCfg(root), "wallet").address;
   if (typeof address === "string" && address) {
     recordExposedAddress(root, address);
   }
@@ -13938,7 +14042,7 @@ function printAccessNextSteps(root, _invokeUrl) {
     }
     if (!x402Only) {
       emit(
-        "  mint buyer creds: bag platform invoke-client new  (prints client_id + client_secret to POST to the client_credentials token endpoint above)"
+        "  mint buyer creds: bag platform invoke-client new  (prints client_id + client_secret to POST to the client_credentials token endpoint above \u2014 credentials go in the form BODY; HTTP Basic auth is not accepted)"
       );
     } else {
       emit("  protocol discovery is suppressed for this X402-only deployment.");
@@ -13989,6 +14093,8 @@ function printAgentClientPrompt(root, invokeUrl, status) {
   const agentIdNote = agentId ?? "<not registered yet \u2014 run `bag platform invoke-client new` to get one>";
   const tokenSteps = `  1) run \`bag platform invoke-client new\` -> client_id + client_secret (secret shown ONCE).
   2) POST client_credentials to ${tokenUrl} with scope \`${scope}\` -> access_token.
+     Send client_id + client_secret in the application/x-www-form-urlencoded BODY \u2014
+     this endpoint does NOT accept HTTP Basic auth (\`curl -u\` fails with oauth.invalid_request).
   3) send \`Authorization: Bearer <token>\`.`;
   const agentCfg = loadAgentCfg(agentRoot2);
   const rails = commerceRails(agentCfg);
@@ -13999,7 +14105,10 @@ function printAgentClientPrompt(root, invokeUrl, status) {
   if (hasA2aFace(faces)) {
     endpoints.push(
       `  [A2A] Agent card: ${cardUrl}
-        Invoke (JSON-RPC message/send): ${a2aInvokeUrl}`
+        Invoke (JSON-RPC message/send): ${a2aInvokeUrl}
+        When composing agent-card URLs in code, build them with \`new URL(base)\` +
+        \`url.pathname = ... \` (keeps any querystring intact) \u2014 never string-concatenate
+        \`\${base}/.well-known/agent-card.json\`; that breaks on URLs that carry a querystring.`
     );
   }
   if (hasMcpFace(faces)) {
@@ -14204,7 +14313,8 @@ async function platformDestroy(opts) {
     return 1;
   }
   const oldInvokeUrl = recorded.invoke_url;
-  recordPlatformKv(root, "slug", "");
+  const nextSlug = suggestNextSlug(slug);
+  recordPlatformKv(root, "slug", nextSlug);
   recordPlatformKv(root, "deployment_id", "");
   recordPlatformKv(root, "invoke_url", "");
   recordPlatformKv(root, "agent_id", "");
@@ -14215,11 +14325,10 @@ async function platformDestroy(opts) {
   );
   emit(`\u2713 deleted platform agent ${slug} (deployment + transmitted secret).`);
   emit(
-    "note: the on-chain ERC-8004 identity is unchanged; its endpoint will go stale. The platform slug was cleared locally because destroyed slugs are permanently retired. Your local keystore (.studio/wallets/) was left untouched."
+    `note: the on-chain ERC-8004 identity is unchanged; its endpoint will go stale. Destroyed slugs are permanently retired, so the local slug was advanced to '${nextSlug}' \u2014 the next deploy uses it automatically. Your local keystore (.studio/wallets/) was left untouched.`
   );
   emit(
-    `  Redeploying THIS project needs a fresh slug (the old one is retired):
-      bag config set deploy.platform.slug ${suggestNextSlug(slug)}
+    `  Redeploy THIS project (uses '${nextSlug}', or pick your own with \`bag config set deploy.platform.slug <name>\`):
       bag deploy --provider bnb`
   );
   return 0;
@@ -14267,7 +14376,7 @@ function isDir7(p) {
 function errMsg2(exc) {
   return exc instanceof Error ? exc.message : String(exc);
 }
-function tableOf12(cfg, key) {
+function tableOf13(cfg, key) {
   const v = cfg[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
@@ -14479,7 +14588,7 @@ function readStackRuntime(root) {
   if (cfg === null) {
     return null;
   }
-  const runtime = tableOf12(cfg, "stack").runtime;
+  const runtime = tableOf13(cfg, "stack").runtime;
   return runtime ? String(runtime) : null;
 }
 function agentNetworkDefault(root) {
@@ -14487,14 +14596,14 @@ function agentNetworkDefault(root) {
   if (cfg === null) {
     return "";
   }
-  return String(tableOf12(cfg, "network").default ?? "").toLowerCase();
+  return String(tableOf13(cfg, "network").default ?? "").toLowerCase();
 }
 function agentDeployDestination(root) {
   const cfg = loadAgentCfg2(root);
   if (cfg === null) {
     return "self";
   }
-  const dest = String(tableOf12(cfg, "deploy").destination ?? "").trim().toLowerCase();
+  const dest = String(tableOf13(cfg, "deploy").destination ?? "").trim().toLowerCase();
   return dest || "self";
 }
 function resolveTarget(opts, root, destination = agentDeployDestination(root)) {
@@ -15246,13 +15355,13 @@ function recordedEndpoint(root) {
   if (cfg === null) {
     return null;
   }
-  const url = tableOf12(cfg, "identity").endpoint;
+  const url = tableOf13(cfg, "identity").endpoint;
   return url ? String(url) : null;
 }
 function recordedAgentId(agentRoot2) {
   try {
     const cfg = loadStudioToml20(path37.join(agentRoot2, "studio.toml"));
-    const val = tableOf12(cfg, "identity").agent_id;
+    const val = tableOf13(cfg, "identity").agent_id;
     return val !== void 0 && val !== null && val !== "" ? String(val) : null;
   } catch {
     return null;
@@ -15261,7 +15370,7 @@ function recordedAgentId(agentRoot2) {
 function recordedRuntimeArn(agentRoot2) {
   try {
     const cfg = loadStudioToml20(path37.join(agentRoot2, "studio.toml"));
-    const val = tableOf12(cfg, "deploy").runtime_arn;
+    const val = tableOf13(cfg, "deploy").runtime_arn;
     return val ? String(val) : null;
   } catch {
     return null;
@@ -15270,7 +15379,7 @@ function recordedRuntimeArn(agentRoot2) {
 function recordedOauthClientId(agentRoot2) {
   try {
     const cfg = loadStudioToml20(path37.join(agentRoot2, "studio.toml"));
-    const val = tableOf12(cfg, "deploy").oauth_client_id;
+    const val = tableOf13(cfg, "deploy").oauth_client_id;
     return val ? String(val) : null;
   } catch {
     return null;
@@ -15279,7 +15388,7 @@ function recordedOauthClientId(agentRoot2) {
 function agentFacesOf(agentRoot2) {
   try {
     const cfg = loadStudioToml20(path37.join(agentRoot2, "studio.toml"));
-    return stackFaces(tableOf12(cfg, "stack"), tableOf12(cfg, "payments"));
+    return stackFaces(tableOf13(cfg, "stack"), tableOf13(cfg, "payments"));
   } catch {
     return ["A2A"];
   }
@@ -15372,7 +15481,10 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
         and POST it to the invoke URL above.` : `  [A2A] Invoke (JSON-RPC message/send, POST-only): ${a2aInvokeUrl}
         NOTE: this AgentCore endpoint is POST-only and serves NO
         GET-able agent card. Skip A2A discovery (do NOT fetch
-        /.well-known/agent-card.json) \u2014 ${a2aPayloadPhrase} straight to the invoke URL above.`;
+        /.well-known/agent-card.json) \u2014 ${a2aPayloadPhrase} straight to the invoke URL above.
+        The invoke URL carries a querystring (?qualifier=...): never
+        string-concatenate extra path segments onto it \u2014 that produces
+        an invalid URL and an HTTP 405.`;
   const lines = [
     "",
     CLIENT_PROMPT_RULE2,
@@ -15572,7 +15684,7 @@ function renderVerifyHuman(r, deployment, liveStatus) {
   }
 }
 function deployCliError(data) {
-  const error = tableOf12(data, "error");
+  const error = tableOf13(data, "error");
   const message = String(error.message ?? "").trim();
   return message || null;
 }
@@ -15987,7 +16099,7 @@ var SECRET_ENV_KEYS = [
   "TWAK_ACCESS_ID",
   "TWAK_HMAC_SECRET"
 ];
-function tableOf13(cfg, key) {
+function tableOf14(cfg, key) {
   const v = cfg[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
@@ -16064,7 +16176,7 @@ async function cmdDoctor(opts) {
   checks.push(...await checkBalances(projectRoot, data, opts.network));
   checks.push(...await checkPieverseMainnetU(projectRoot, data));
   checks.push(...await check8004(projectRoot, data, opts.network));
-  const destination = String(tableOf13(data, "deploy").destination ?? "self").trim().toLowerCase();
+  const destination = String(tableOf14(data, "deploy").destination ?? "self").trim().toLowerCase();
   checks.push(...await checkDeployTools(data, destination));
   checks.push(...checkAgentsMdSkillTrigger(projectRoot));
   printChecks(checks);
@@ -16147,13 +16259,13 @@ function checkAppMain(projectRootArg) {
       config = {};
     }
   }
-  const stack = tableOf13(config, "stack");
+  const stack = tableOf14(config, "stack");
   const runtime = String(stack.runtime ?? "").toLowerCase();
   let entrypoint;
   if (runtime === "azure-foundry") {
     entrypoint = "src/foundryMain.ts";
   } else if (runtime === "agentcore") {
-    const faces = stackFaces(stack, tableOf13(config, "payments"));
+    const faces = stackFaces(stack, tableOf14(config, "payments"));
     entrypoint = `src/${entryStemOf(faces)}.ts`;
   } else {
     entrypoint = "src/main.ts";
@@ -16224,7 +16336,7 @@ function anchoredKeystoreDir(projectRoot, walletCfg) {
   return path38.isAbsolute(rel) ? rel : path38.join(projectRoot, rel);
 }
 async function checkWallet(projectRoot, data) {
-  const walletCfg = tableOf13(data, "wallet");
+  const walletCfg = tableOf14(data, "wallet");
   if (walletCfg.kind === "twak") {
     return checkWalletTwak(walletCfg, projectRoot, data);
   }
@@ -16396,7 +16508,7 @@ async function checkWalletTwak(walletCfg, projectRoot, data = {}) {
       detail: `not on PATH \u2014 npm install -g @trustwallet/cli@${TWAK_CLI_VERSION}`
     });
   }
-  const networkName = String(tableOf13(data, "network").default ?? "bsc-testnet");
+  const networkName = String(tableOf14(data, "network").default ?? "bsc-testnet");
   const unsupportedTargets = twakUnsupportedContractOverrides(networkName);
   if (unsupportedTargets.length > 0) {
     out.push({
@@ -16442,7 +16554,7 @@ async function checkWalletTwak(walletCfg, projectRoot, data = {}) {
   return out;
 }
 function checkPassword(data) {
-  const walletKind2 = String(tableOf13(data, "wallet").kind ?? "evm-local");
+  const walletKind2 = String(tableOf14(data, "wallet").kind ?? "evm-local");
   if (walletKind2 === "twak") {
     if (process.env.TWAK_WALLET_PASSWORD) {
       return [
@@ -16478,7 +16590,7 @@ function checkPassword(data) {
   ];
 }
 async function checkLlm(data, projectRoot) {
-  const llmCfg = tableOf13(data, "llm");
+  const llmCfg = tableOf14(data, "llm");
   const provider = llmCfg.provider ? String(llmCfg.provider) : null;
   if (!provider) {
     return [{ name: "[llm] provider", status: WARN, detail: "not configured" }];
@@ -16523,8 +16635,8 @@ async function checkLlm(data, projectRoot) {
   return out;
 }
 async function checkPieverse(data, apiKey) {
-  const llmCfg = tableOf13(data, "llm");
-  const pvCfg = tableOf13(llmCfg, "pieverse");
+  const llmCfg = tableOf14(data, "llm");
+  const pvCfg = tableOf14(llmCfg, "pieverse");
   const keyHash = pvCfg.key_hash ? String(pvCfg.key_hash) : null;
   const hasEnv = Boolean(apiKey);
   const out = [];
@@ -16594,8 +16706,8 @@ async function checkPieverse(data, apiKey) {
     });
   }
   try {
-    const policy = pieversePolicyFromToml(tableOf13(llmCfg, "auto_renew"));
-    const budget = policyFromToml(tableOf13(data, "budget"));
+    const policy = pieversePolicyFromToml(tableOf14(llmCfg, "auto_renew"));
+    const budget = policyFromToml(tableOf14(data, "budget"));
     let detail;
     if (policy.enabled) {
       const allocateDetail = `enabled: allocates $${policy.topupChunkUsd.toFixed(2)} from Account Balance when key < $${policy.minBalanceUsd.toFixed(2)}.`;
@@ -16615,7 +16727,7 @@ async function checkPieverse(data, apiKey) {
   return out;
 }
 async function checkNetwork(data, networkOverride) {
-  const netName = networkOverride || tableOf13(data, "network").default;
+  const netName = networkOverride || tableOf14(data, "network").default;
   if (!netName) {
     return [
       {
@@ -16660,7 +16772,7 @@ async function checkNetwork(data, networkOverride) {
   }
 }
 function checkCurrency(data) {
-  const payments = tableOf13(data, "payments");
+  const payments = tableOf14(data, "payments");
   const pay = payments.erc8183;
   if (pay === null || typeof pay !== "object" || Array.isArray(pay)) {
     return [];
@@ -16678,7 +16790,7 @@ function checkCurrency(data) {
   return [];
 }
 function checkErc8183Pricing(data) {
-  const payValue = tableOf13(data, "payments").erc8183;
+  const payValue = tableOf14(data, "payments").erc8183;
   if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
     return [];
   }
@@ -16758,7 +16870,7 @@ function checkErc8183Pricing(data) {
   ];
 }
 function checkPriceBounds(data) {
-  const payValue = tableOf13(data, "payments").erc8183;
+  const payValue = tableOf14(data, "payments").erc8183;
   if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
     return [];
   }
@@ -16776,7 +16888,7 @@ function checkPriceBounds(data) {
   return [];
 }
 function checkX402Seller(data, agentRoot2) {
-  const payments = tableOf13(data, "payments");
+  const payments = tableOf14(data, "payments");
   const sellerValue = payments.x402_seller;
   if (sellerValue === null || typeof sellerValue !== "object" || Array.isArray(sellerValue)) {
     return [];
@@ -16793,7 +16905,7 @@ function checkX402Seller(data, agentRoot2) {
       }
     ];
   }
-  const runtime = String(tableOf13(data, "stack").runtime ?? "agentcore");
+  const runtime = String(tableOf14(data, "stack").runtime ?? "agentcore");
   const hasErc8183 = payments.erc8183 !== null && typeof payments.erc8183 === "object" && !Array.isArray(payments.erc8183);
   const fallbackStatus = hasErc8183 ? WARN : FAIL;
   if (pricing.kind === "free") {
@@ -16828,7 +16940,7 @@ function checkX402Seller(data, agentRoot2) {
       detail: `PAID \u2014 $${pricing.priceUsd} per request through B402.`
     }
   ];
-  const walletKind2 = String(tableOf13(data, "wallet").kind ?? "evm-local");
+  const walletKind2 = String(tableOf14(data, "wallet").kind ?? "evm-local");
   if (!["evm-local", "twak"].includes(walletKind2)) {
     out.push({
       name: "x402 payout wallet",
@@ -16854,7 +16966,7 @@ function checkX402Seller(data, agentRoot2) {
   return out;
 }
 function checkStorage(data) {
-  const kind = String(tableOf13(data, "storage").kind ?? "local").toLowerCase();
+  const kind = String(tableOf14(data, "storage").kind ?? "local").toLowerCase();
   if (kind === "ipfs") {
     if (!process.env.STORAGE_API_URL) {
       return [
@@ -16900,7 +17012,7 @@ function checkStorage(data) {
   ];
 }
 function balanceAddress(projectRoot, data) {
-  const walletCfg = tableOf13(data, "wallet");
+  const walletCfg = tableOf14(data, "wallet");
   if (walletCfg.kind === "twak" || walletCfg.kind === "altana") {
     const addr = String(walletCfg.address ?? "").trim();
     return addr || null;
@@ -16922,7 +17034,7 @@ function balanceAddress(projectRoot, data) {
   return provider.address;
 }
 async function checkBalances(projectRoot, data, networkOverride) {
-  const netName = networkOverride || tableOf13(data, "network").default;
+  const netName = networkOverride || tableOf14(data, "network").default;
   if (!netName) {
     return [];
   }
@@ -16999,11 +17111,11 @@ async function checkBalances(projectRoot, data, networkOverride) {
   }
 }
 async function checkPieverseMainnetU(projectRoot, data) {
-  const llmCfg = tableOf13(data, "llm");
+  const llmCfg = tableOf14(data, "llm");
   if (llmCfg.provider !== "pieverse-llm") {
     return [];
   }
-  const pvCfg = tableOf13(llmCfg, "pieverse");
+  const pvCfg = tableOf14(llmCfg, "pieverse");
   const pvNetwork = String(pvCfg.network ?? "bsc-mainnet");
   if (pvNetwork === "bsc-testnet") {
     return [
@@ -17016,7 +17128,7 @@ async function checkPieverseMainnetU(projectRoot, data) {
   }
   const modelName = String(llmCfg.model ?? "");
   const isFreeModel2 = modelName.includes("auto/free");
-  const budgetEnabled = tableOf13(data, "budget").enabled === true;
+  const budgetEnabled = tableOf14(data, "budget").enabled === true;
   if (isFreeModel2 && !budgetEnabled) {
     return [
       {
@@ -17026,7 +17138,7 @@ async function checkPieverseMainnetU(projectRoot, data) {
       }
     ];
   }
-  const autoRenew = tableOf13(llmCfg, "auto_renew");
+  const autoRenew = tableOf14(llmCfg, "auto_renew");
   const chunk = typeof autoRenew.topup_chunk_usd === "number" ? autoRenew.topup_chunk_usd : 1;
   const threshold = chunk * 2;
   try {
@@ -17071,7 +17183,7 @@ async function check8004(projectRoot, data, networkOverride) {
   if (!process.env.WALLET_PASSWORD) {
     return [];
   }
-  const walletCfg = tableOf13(data, "wallet");
+  const walletCfg = tableOf14(data, "wallet");
   if (!isLocalEvmWallet(walletCfg)) {
     return [];
   }
@@ -17080,7 +17192,7 @@ async function check8004(projectRoot, data, networkOverride) {
     return [];
   }
   const network = String(
-    networkOverride || tableOf13(data, "network").default || "bsc-testnet"
+    networkOverride || tableOf14(data, "network").default || "bsc-testnet"
   );
   try {
     const wallet = walletRt5.getWallet();
@@ -17113,11 +17225,11 @@ async function check8004(projectRoot, data, networkOverride) {
   }
 }
 function platformPackagingRequiresContainer(data) {
-  const walletKind2 = String(tableOf13(data, "wallet").kind ?? "evm-local").trim().toLowerCase();
+  const walletKind2 = String(tableOf14(data, "wallet").kind ?? "evm-local").trim().toLowerCase();
   if (walletKind2 === "twak") {
     return true;
   }
-  const deployCfg = tableOf13(data, "deploy");
+  const deployCfg = tableOf14(data, "deploy");
   let platformArtifact2 = String(deployCfg.platform_artifact ?? "").trim().toLowerCase();
   if (!platformArtifact2) {
     const packaging = String(deployCfg.packaging ?? "").trim().toLowerCase();
@@ -17153,7 +17265,7 @@ async function checkDeployTools(data, destination) {
         detail: "[deploy].platform_artifact='zip' uses the managed platform's ZIP runtime; local Docker is not required."
       });
     }
-    const walletKind2 = String(tableOf13(data, "wallet").kind ?? "").trim().toLowerCase();
+    const walletKind2 = String(tableOf14(data, "wallet").kind ?? "").trim().toLowerCase();
     if (walletKind2 === "twak") {
       out.push(emit2(await checkTwak()));
     } else {
@@ -17437,7 +17549,7 @@ function registerErc8004(program) {
     )
   );
 }
-function tableOf14(cfg, key) {
+function tableOf15(cfg, key) {
   const v = cfg[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
@@ -17460,7 +17572,7 @@ function resolveNetwork2(override) {
     return override;
   }
   const cfg = loadAgentCfg3();
-  const net2 = cfg === null ? void 0 : tableOf14(cfg, "network").default;
+  const net2 = cfg === null ? void 0 : tableOf15(cfg, "network").default;
   return net2 ? String(net2) : "bsc-testnet";
 }
 function resolveProtocol(override) {
@@ -17471,7 +17583,7 @@ function resolveProtocol(override) {
   if (cfg === null) {
     return "A2A";
   }
-  const faces = stackFaces(tableOf14(cfg, "stack"), tableOf14(cfg, "payments"));
+  const faces = stackFaces(tableOf15(cfg, "stack"), tableOf15(cfg, "payments"));
   if (faces.length === 1 && hasX402Face(faces)) {
     printErr(
       "warning: this X402-only project has no public ERC-8004 protocol face; A2A is only the internal AgentCore protocol declaration."
@@ -17481,13 +17593,13 @@ function resolveProtocol(override) {
 }
 function recordedEndpoint2() {
   const cfg = loadAgentCfg3();
-  const endpoint = cfg === null ? void 0 : tableOf14(cfg, "identity").endpoint;
+  const endpoint = cfg === null ? void 0 : tableOf15(cfg, "identity").endpoint;
   return endpoint ? String(endpoint) : null;
 }
 var REGISTER_MIN_BNB = 2e-3;
 function walletSelfPaysGas() {
   const cfg = loadAgentCfg3();
-  if (cfg !== null && tableOf14(cfg, "wallet").gasless) {
+  if (cfg !== null && tableOf15(cfg, "wallet").gasless) {
     return false;
   }
   return true;
@@ -17527,7 +17639,7 @@ function syncAgentRegistry(agentId, op) {
 function loadIdentityBlock(agentRoot2) {
   try {
     return {
-      ...tableOf14(
+      ...tableOf15(
         loadStudioToml22(path40.join(agentRoot2, "studio.toml")),
         "identity"
       )
@@ -17630,7 +17742,7 @@ function printPartialRegister(exc) {
 }
 async function cmdRegister2(opts) {
   const cfg = loadAgentCfg3();
-  const destination = cfg === null ? "" : String(tableOf14(cfg, "deploy").destination ?? "").trim().toLowerCase();
+  const destination = cfg === null ? "" : String(tableOf15(cfg, "deploy").destination ?? "").trim().toLowerCase();
   if (destination === "platform") {
     printErr(
       "error: this is a platform-destination project \u2014 ERC-8004 registration is relayed GASLESSLY by the BNB Chain operator, not broadcast from your local wallet.\n  Use:  bag deploy verify --endpoint <your-invoke-url>\n(`bag erc8004 register` always self-pays gas from the local wallet, which fails on the zero-balance throwaway wallet the trial uses.)"
@@ -17934,7 +18046,12 @@ function registerErc8183(program) {
     "--agent-id <id>",
     "ERC-8004 agent_id (resolves provider + negotiates).",
     (v) => Number.parseInt(v, 10)
-  ).argument("[task]", "Task description (or use --task).").option("--task <text>", "Task description (alternative to positional).").option(
+  ).argument("[task]", "Task description (or use --task).").option("--task <text>", "Task description (alternative to positional).").addOption(
+    new Option6(
+      "--quote-json <json|path>",
+      "A seller's signed quote envelope (the negotiate response JSON, inline or a file path) to anchor on-chain. Use with --provider for sellers whose negotiate step ran out-of-band (e.g. an OAuth-gated AgentCore seller)."
+    ).conflicts("agentId")
+  ).option(
     "--budget-u <amount>",
     "Max U to spend (default: negotiated or policy)."
   ).option(
@@ -18061,6 +18178,35 @@ async function cmdList3(opts) {
   }
   return 0;
 }
+function parseQuoteEnvelope(raw) {
+  const trimmed = raw.trim();
+  let text2 = trimmed;
+  if (!trimmed.startsWith("{")) {
+    try {
+      text2 = fs40.readFileSync(trimmed, "utf-8");
+    } catch (exc) {
+      throw new Error(
+        `--quote-json is neither inline JSON nor a readable file: ${errMsg5(exc)}`
+      );
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text2);
+  } catch (exc) {
+    throw new Error(`--quote-json is not valid JSON: ${errMsg5(exc)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--quote-json must decode to a JSON object.");
+  }
+  const envelope = parsed;
+  if (!envelope.negotiation_hash || !envelope.provider_sig) {
+    throw new Error(
+      "--quote-json is not a signed quote envelope: it must carry `negotiation_hash` and `provider_sig` (the seller's negotiate response). Re-run the negotiate step and pass its full response body."
+    );
+  }
+  return envelope;
+}
 async function cmdBuy(taskPositional, opts) {
   const rc = applyProjectRoot2(opts.projectRoot);
   if (rc !== null) {
@@ -18070,6 +18216,15 @@ async function cmdBuy(taskPositional, opts) {
     printErr("error: one of --provider / --agent-id is required");
     return 2;
   }
+  let negotiationEnvelope = null;
+  if (opts.quoteJson !== void 0) {
+    try {
+      negotiationEnvelope = parseQuoteEnvelope(opts.quoteJson);
+    } catch (exc) {
+      printErr(`error: ${errMsg5(exc)}`);
+      return 2;
+    }
+  }
   if (taskPositional !== void 0 && opts.task !== void 0) {
     printErr(
       "error: pass the task once (either positional or --task, not both)"
@@ -18077,19 +18232,20 @@ async function cmdBuy(taskPositional, opts) {
     return 2;
   }
   const task = taskPositional ?? opts.task;
-  if (task === void 0) {
-    printErr("error: task is required");
+  if (task === void 0 && negotiationEnvelope === null) {
+    printErr("error: task is required (or pass --quote-json)");
     return 2;
   }
   let r;
   try {
-    r = await buyWorkflow(opts.provider ?? null, task, {
+    r = await buyWorkflow(opts.provider ?? null, task ?? "", {
       agentId: opts.agentId ?? null,
       budgetU: opts.budgetU ?? null,
       deadlineMinutes: opts.deadlineMin,
       network: opts.network ?? null,
       negotiate: opts.negotiate,
-      protocol: opts.protocol
+      protocol: opts.protocol,
+      negotiationEnvelope
     });
   } catch (exc) {
     printErr(`error: ${errMsg5(exc)}`);
@@ -19328,6 +19484,9 @@ function registerX402(program) {
   ).option("--method <verb>", "HTTP verb to send (default: GET).", "GET").option(
     "--json <body>",
     "JSON body to send with the request (a string parsed as JSON)."
+  ).option(
+    "--local-dev",
+    "DEV ONLY: skip the host allowlist for a localhost/127.0.0.1 target."
   ).action(
     act(
       (url, opts) => cmdQuote(url, opts)
@@ -19343,6 +19502,9 @@ function registerX402(program) {
   ).option("--method <verb>", "HTTP verb to send (default: GET).", "GET").option(
     "--json <body>",
     "JSON body to send with the request (a string parsed as JSON)."
+  ).option(
+    "--local-dev",
+    "DEV ONLY: for a localhost/127.0.0.1 target, skip the host allowlist and accept the challenge's payTo as the recipient (printed loudly)."
   ).action(
     act(
       (url, opts) => cmdBuy2(url, opts)
@@ -19394,6 +19556,23 @@ function hostOf(url) {
     return "";
   }
 }
+function isLoopbackHost(host) {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+  return h === "localhost" || h === "127.0.0.1" || h === "::1";
+}
+function printLocalDevHint(url) {
+  printErr("hint: local dev seller detected. One command sets up everything:");
+  printErr(`  bag x402 trust ${url.split("?")[0]}`);
+  printErr(
+    "  (adds the host to the allowlist AND pins the seller's payTo as the trusted recipient)"
+  );
+  printErr(
+    "Or configure both by hand in studio.toml [payments.x402]: add the host to allowed_hosts and set expected_recipient."
+  );
+  printErr(
+    "For a throwaway check you can also pass --local-dev to `bag x402 buy`/`quote` (loopback targets only)."
+  );
+}
 function checkHostAllowed(url, allowedHosts) {
   const host = hostOf(url);
   const allowedLower = new Set(
@@ -19401,7 +19580,7 @@ function checkHostAllowed(url, allowedHosts) {
   );
   return allowedLower.has(host);
 }
-function tableOf15(cfg, key) {
+function tableOf16(cfg, key) {
   const v = cfg[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
@@ -19440,7 +19619,7 @@ function resolveNetwork3(cfg, override) {
   if (override) {
     return override;
   }
-  const net2 = tableOf15(cfg, "network").default;
+  const net2 = tableOf16(cfg, "network").default;
   return net2 ? String(net2) : "bsc-mainnet";
 }
 function parseJsonBody(raw) {
@@ -19466,8 +19645,11 @@ function resolveWallet2() {
     return null;
   }
 }
-function printScopeError(host) {
+function printScopeError(host, url) {
   printErr(`error: ${SCOPE_NOTE.replace("{host}", host)}`);
+  if (url !== void 0 && isLoopbackHost(host)) {
+    printLocalDevHint(url);
+  }
 }
 async function cmdSellInit(priceFlag) {
   const loaded = loadSellerConfig();
@@ -19484,7 +19666,7 @@ async function cmdSellInit(priceFlag) {
     return 2;
   }
   const free = x402SellerPricingState({ price_usd: priceUsd }).kind === "free";
-  const walletKind2 = String(tableOf15(cfg, "wallet").kind ?? "evm-local");
+  const walletKind2 = String(tableOf16(cfg, "wallet").kind ?? "evm-local");
   if (!free && !["evm-local", "twak"].includes(walletKind2)) {
     printErr(
       `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet.`
@@ -19644,8 +19826,12 @@ async function cmdQuote(url, opts) {
     printErr(`error: ${errMsg6(exc)}`);
     return 2;
   }
-  if (!checkHostAllowed(url, hosts)) {
-    printScopeError(hostOf(url) || url);
+  if (opts.localDev && !isLoopbackHost(hostOf(url))) {
+    printErr("error: --local-dev applies to localhost/127.0.0.1 targets only.");
+    return 2;
+  }
+  if (!opts.localDev && !checkHostAllowed(url, hosts)) {
+    printScopeError(hostOf(url) || url, url);
     return 1;
   }
   let body;
@@ -19653,7 +19839,7 @@ async function cmdQuote(url, opts) {
     body = await quoteUrl(url, {
       method: opts.method,
       jsonBody,
-      allowedHosts: hosts
+      allowedHosts: opts.localDev ? null : hosts
     });
   } catch (exc) {
     printX402Error(exc);
@@ -19687,8 +19873,12 @@ async function cmdBuy2(url, opts) {
     return 1;
   }
   const [, cfg, hosts] = loaded;
-  if (!checkHostAllowed(url, hosts)) {
-    printScopeError(hostOf(url) || url);
+  if (opts.localDev && !isLoopbackHost(hostOf(url))) {
+    printErr("error: --local-dev applies to localhost/127.0.0.1 targets only.");
+    return 2;
+  }
+  if (!opts.localDev && !checkHostAllowed(url, hosts)) {
+    printScopeError(hostOf(url) || url, url);
     return 1;
   }
   let jsonBody;
@@ -19699,6 +19889,24 @@ async function cmdBuy2(url, opts) {
     return 2;
   }
   const networkName = resolveNetwork3(cfg, opts.network);
+  let localDevExpectedTo = null;
+  if (opts.localDev) {
+    let challenge;
+    try {
+      challenge = await quoteUrl(url, { method: opts.method, jsonBody });
+    } catch (exc) {
+      printX402Error(exc);
+      return 1;
+    }
+    const selected2 = selectPayable(challenge, networkName);
+    if (selected2 === null) {
+      return 1;
+    }
+    localDevExpectedTo = String(selected2[0].payTo);
+    printOut(
+      `\u26A0 DEV-ONLY --local-dev: accepting the challenge's payTo ${localDevExpectedTo} as the recipient without a configured pin. Never use this outside your own machine.`
+    );
+  }
   const wallet = resolveWallet2();
   if (wallet === null) {
     return 1;
@@ -19743,7 +19951,8 @@ async function cmdBuy2(url, opts) {
           networkName,
           method: opts.method,
           jsonBody,
-          allowedHosts: hosts
+          allowedHosts: opts.localDev ? null : hosts,
+          expectedTo: localDevExpectedTo
         });
         if (r.paidUsd !== null) {
           h.extraContext.paid_usd = r.paidUsd;
@@ -19756,6 +19965,9 @@ async function cmdBuy2(url, opts) {
     );
   } catch (exc) {
     printX402Error(exc);
+    if (errName4(exc) === "X402RecipientRequiredError" && isLoopbackHost(hostOf(url))) {
+      printLocalDevHint(url);
+    }
     return 1;
   }
   const paidUsd = result.paidUsd ?? 0;
@@ -19869,10 +20081,19 @@ async function cmdTrust(merchant, opts) {
   if (merchant.includes("://")) {
     probeUrl = merchant;
     host = hostOf(probeUrl);
-    if (!probeUrl.toLowerCase().startsWith("https://") || !host) {
-      printErr("error: trust-by-URL needs an absolute https:// URL.");
+    const plainHttp = probeUrl.toLowerCase().startsWith("http://");
+    const localDevHttp = plainHttp && isLoopbackHost(host);
+    if (!probeUrl.toLowerCase().startsWith("https://") && !localDevHttp || !host) {
+      printErr(
+        "error: trust-by-URL needs an absolute https:// URL (plain http:// is allowed only for localhost/127.0.0.1 dev sellers)."
+      );
       return 1;
     }
+    if (localDevHttp) {
+      printOut(
+        "\u26A0 DEV-ONLY: trusting a plain-http loopback seller. http:// carries no transport integrity \u2014 never trust it beyond your own machine."
+      );
+    }
     methodHint = null;
   } else {
     rec = RECOMMENDED_MERCHANTS[merchant.toLowerCase()] ?? null;
@@ -19952,7 +20173,7 @@ The merchant may have rotated its address (or the response was tampered with). U
       "  \u26A0 MAINNET: calls spend real $U from the agent wallet. The cap above and [budget].max_per_day_usd bound the exposure."
     );
   }
-  const projectDefault = tableOf15(cfg, "network").default;
+  const projectDefault = tableOf16(cfg, "network").default;
   if (projectDefault && String(projectDefault) !== networkName) {
     printOut(
       `  note: your project default is ${projectDefault}; this paid capability settles on ${networkName} independently of it.`
@@ -20033,7 +20254,7 @@ function buildProgram() {
   return program;
 }
 function cliVersion() {
-  return "0.0.6-alpha.5";
+  return "0.0.6-alpha.6";
 }
 
 // src/cli/updateCheck.ts