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

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";
@@ -4277,6 +4284,7 @@ import {
 import { getNetwork as getNetwork4 } from "@bnbagent/studio-runtime/networks";
 import * as pieverseRt from "@bnbagent/studio-runtime/pieverse";
 import {
+  PieverseKeyNotFoundError,
   PieversePolicy,
   RetryPolicy,
   allocateWithSettleRetry,
@@ -4410,7 +4418,10 @@ function registerLlm(program) {
   ).option(
     "--network <name>",
     "Override [llm.pieverse].network (e.g. bsc-mainnet, bsc-testnet)."
-  ).option("--name <name>", "Key name (default: bnbagent-studio-default).").action(
+  ).option("--name <name>", "Key name (default: bnbagent-studio-default).").option(
+    "--replace",
+    "Ignore any existing key and mint a fresh one, overwriting PIEVERSE_LLM_API_KEY in .studio/.env.local. Use when the key you inherited (e.g. from a shared env file) no longer exists in Pieverse. The old key is left untouched on the Pieverse side."
+  ).action(
     act(
       (opts) => cmdActivate(opts)
     )
@@ -4619,9 +4630,20 @@ async function cmdActivate(opts) {
     return 2;
   }
   const pvCfg = loadPieverseConfig(cfg);
-  let existingHash = pvCfg.key_hash ? String(pvCfg.key_hash) : null;
-  const envFileValue = getEnvVar(envLocalPath9(root), PIEVERSE_ENV_KEY);
-  const existingEnv = envFileValue || process.env[PIEVERSE_ENV_KEY];
+  const replace = opts.replace === true;
+  let existingHash = !replace && pvCfg.key_hash ? String(pvCfg.key_hash) : null;
+  const envFileValue = replace ? null : getEnvVar(envLocalPath9(root), PIEVERSE_ENV_KEY);
+  const existingEnv = replace ? null : envFileValue || process.env[PIEVERSE_ENV_KEY];
+  if (replace) {
+    printOut(
+      `\u2192 --replace: ignoring any existing ${PIEVERSE_ENV_KEY} and minting a fresh key\u2026`
+    );
+    if (process.env[PIEVERSE_ENV_KEY]) {
+      printErr(
+        `warning: ${PIEVERSE_ENV_KEY} is also exported in this shell. The new key goes to .studio/.env.local, which \`bag\` prefers, but \`unset ${PIEVERSE_ENV_KEY}\` to keep the two from diverging.`
+      );
+    }
+  }
   if (!existingHash && existingEnv) {
     const derivedHash = pieverseKeyHash(existingEnv);
     printOut(
@@ -4630,15 +4652,24 @@ async function cmdActivate(opts) {
     try {
       await withSiweRetry(wallet, (token) => inspectKey(token, derivedHash));
     } catch (exc) {
+      if (!(exc instanceof PieverseKeyNotFoundError)) {
+        printErr(
+          `error: could not verify the existing ${PIEVERSE_ENV_KEY} against Pieverse: ${errMessage(
+            exc
+          )}
+The existing key was kept and no new key was created. This looks like a transport or login failure rather than a missing key \u2014 retry \`bag llm activate\` once Pieverse is reachable.`
+        );
+        return 2;
+      }
       const sources = [
         envFileValue ? `.studio/.env.local (a ${PIEVERSE_ENV_KEY}= line)` : "",
         process.env[PIEVERSE_ENV_KEY] ? "the shell environment" : ""
       ].filter(Boolean).join(" and ");
       printErr(
-        `error: ${PIEVERSE_ENV_KEY} already exists but its derived key_hash could not be verified: ${errMessage(
+        `error: ${PIEVERSE_ENV_KEY} already exists but Pieverse does not know its key_hash: ${errMessage(
           exc
         )}
-The existing key was kept and no new key was created. The key comes from ${sources}; \`bag\` reads both, so clear every source \u2014 remove the ${PIEVERSE_ENV_KEY}= line from .studio/.env.local AND \`unset ${PIEVERSE_ENV_KEY}\` in the shell \u2014 then re-run \`bag llm activate\` to mint a fresh key. (\`bag llm rotate\` replaces a key that is still valid in Pieverse; it cannot recover this one.)`
+The existing key was kept and no new key was created. The key comes from ${sources}. Re-run \`bag llm activate --replace\` to mint a fresh key and overwrite .studio/.env.local (then \`unset ${PIEVERSE_ENV_KEY}\` if you also exported it in this shell). (\`bag llm rotate\` replaces a key that is still valid in Pieverse; it cannot recover this one.)`
       );
       return 2;
     }
@@ -9858,6 +9889,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 +10026,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 +10051,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 +10061,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 +10071,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 +10171,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 +10183,7 @@ function compactJson(text2) {
 function readTwakFiles(agentDir) {
   let walletCfg = {};
   try {
-    walletCfg = tableOf8(
+    walletCfg = tableOf9(
       loadStudioToml11(path23.join(agentDir, "studio.toml")),
       "wallet"
     );
@@ -10552,7 +10593,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 +10646,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) {
@@ -11391,6 +11390,84 @@ async function checkAwsTargetsPopulated(root, target) {
     }
   ];
 }
+var AGENTCORE_AGENT_QUOTA_CODE = "L-F4575653";
+function awsJson(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function checkAgentcoreQuotaHeadroom(root, target) {
+  if (target !== "agentcore") {
+    return [];
+  }
+  const [, region] = readAwsTarget(root);
+  if (!region || !await whichBin("aws")) {
+    return [];
+  }
+  const quotaRes = await runCapture("aws", [
+    "service-quotas",
+    "get-service-quota",
+    "--service-code",
+    "bedrock-agentcore",
+    "--quota-code",
+    AGENTCORE_AGENT_QUOTA_CODE,
+    "--region",
+    region,
+    "--output",
+    "json"
+  ]);
+  if (quotaRes.code !== 0) {
+    return [];
+  }
+  const quota = awsJson(quotaRes.stdout)?.Quota;
+  const limit = typeof quota?.Value === "number" ? quota.Value : null;
+  if (limit === null) {
+    return [];
+  }
+  const listRes = await runCapture("aws", [
+    "bedrock-agentcore-control",
+    "list-agent-runtimes",
+    "--region",
+    region,
+    "--output",
+    "json"
+  ]);
+  if (listRes.code !== 0) {
+    return [];
+  }
+  const runtimes = awsJson(listRes.stdout)?.agentRuntimes;
+  if (!Array.isArray(runtimes)) {
+    return [];
+  }
+  const used = runtimes.length;
+  const details = {
+    used,
+    limit,
+    region,
+    quota_code: AGENTCORE_AGENT_QUOTA_CODE
+  };
+  if (used < limit) {
+    return [
+      {
+        level: Level.INFO,
+        name: "agentcore_quota_headroom",
+        message: `AgentCore runtimes: ${used}/${limit} used in ${region}.`,
+        details
+      }
+    ];
+  }
+  return [
+    {
+      level: Level.CRITICAL,
+      name: "agentcore_quota_headroom",
+      message: `AgentCore runtimes: ${used}/${limit} used in ${region} \u2014 no slots left, so the deploy would fail with \`maxAgents limit exceeded\` AFTER pushing the image and creating the secret, M2M client, and execution role (all orphans). Delete a runtime you no longer need (\`bag deploy destroy\` in its workspace) or request a quota increase for ${AGENTCORE_AGENT_QUOTA_CODE} ("Total Agents per Account") in the Service Quotas console.`,
+      details
+    }
+  ];
+}
 var allChecks = [
   checkAgentcoreJsonPresent,
   checkAgentcoreAuthorizerKeyLegacy,
@@ -11415,7 +11492,8 @@ var allChecks = [
   checkCommerceReady,
   checkDeployCliRunnable,
   checkRuntimeSecretsInjected,
-  checkAwsTargetsPopulated
+  checkAwsTargetsPopulated,
+  checkAgentcoreQuotaHeadroom
 ];
 
 // src/cli/_deploy/secrets.ts
@@ -11436,17 +11514,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 +11539,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) {
@@ -11699,6 +11777,12 @@ function cognitoPackageJson() {
 function readme() {
   return `# Cognito M2M client for the AgentCore A2A inbound OAuth2 authorizer
 
+> **DEPRECATED.** \`bag deploy --provider aws\` now provisions its own user pool
+> and M2M client, and overwrites the values wired from this stack. Deploying
+> this app leaves a second, unused pool behind that you have to clean up
+> yourself. Keep it only if you need to own the pool out of band; otherwise run
+> \`bag deploy --provider aws\` and hand buyers the credentials it prints.
+
 AgentCore A2A endpoints REQUIRE inbound auth (there is no anonymous mode). This
 seller uses **OAuth2 via Cognito** \u2014 NOT SigV4, because external buyers cannot
 obtain your AWS IAM credentials. Cognito has no public machine-to-machine
@@ -11739,12 +11823,11 @@ This reads the local \`cdk-outputs.json\` and patches:
 | \`Scope\`        | \`agentcore.json\` \u2192 \`envVars[] OAUTH_SCOPE\` (+ \`.studio/.env.local\` for local dev) |
 
 \`OAUTH_TOKEN_URL\` / \`OAUTH_SCOPE\` are read by the emitted agent card from
-the environment, so the published A2A agent card advertises the OAuth2 security
-scheme buyers must use. They go into \`agentcore.json\` \`envVars[]\` (non-secret)
-because \`.studio/.env.local\` lives outside the deploy CodeZip \u2014 so envVars[]
-is the channel that actually reaches the runtime; the \`.env.local\` copy only
-serves local \`bag dev\`. (\`bag deploy provision-cognito --wire <file>\` accepts a
-custom outputs path.)
+the environment, so the agent card advertises the OAuth2 security scheme buyers
+must use. **A \`bag deploy\` run replaces both values (and the authorizer) with
+the pool it provisions itself**, so this wiring only takes effect for local
+\`bag dev\`. (\`bag deploy provision-cognito --wire <file>\` accepts a custom
+outputs path.)
 
 ## Issue buyer credentials
 
@@ -11795,7 +11878,8 @@ function wireSummary(r) {
       allowedClients = [${r.clientId}]
   - ${path26.basename(r.agentcoreJson)}: envVars[] OAUTH_TOKEN_URL + OAUTH_SCOPE (reach the runtime so the agent card advertises oauth2)
   - ${r.envLocal}: same pair, for local \`bag dev\`
-  \u2192 \`bag deploy prepare\` W9 will now pass; deploy when ready.`;
+  \u2192 NOTE: a \`bag deploy\` run provisions its own pool and overwrites these
+    values with the ones it issued. This wiring only feeds local \`bag dev\`.`;
 }
 function flattenCdkOutputs(raw) {
   const flat = {};
@@ -11823,6 +11907,49 @@ function upsertDescriptorEnvvars(cfg, values) {
     }
   }
 }
+function syncDescriptorOauthFacts(workspaceRoot, facts) {
+  const acj = path26.join(workspaceRoot, "agentcore", "agentcore.json");
+  let cfg;
+  try {
+    cfg = JSON.parse(fs27.readFileSync(acj, "utf-8"));
+  } catch {
+    return;
+  }
+  const envValues = {};
+  if (facts.tokenUrl) {
+    envValues.OAUTH_TOKEN_URL = facts.tokenUrl;
+  }
+  if (facts.scope) {
+    envValues.OAUTH_SCOPE = facts.scope;
+  }
+  const authorizer = facts.discoveryUrl && facts.clientId ? {
+    customJwtAuthorizer: {
+      discoveryUrl: facts.discoveryUrl,
+      allowedClients: [facts.clientId]
+    }
+  } : null;
+  if (Object.keys(envValues).length === 0 && authorizer === null) {
+    return;
+  }
+  if (Object.keys(envValues).length > 0) {
+    upsertDescriptorEnvvars(cfg, envValues);
+  }
+  if (authorizer !== null && Array.isArray(cfg.runtimes)) {
+    for (const rt of cfg.runtimes) {
+      if (rt !== null && typeof rt === "object") {
+        const r = rt;
+        r.authorizerType = "CUSTOM_JWT";
+        r.authorizerConfiguration = authorizer;
+      }
+    }
+  }
+  try {
+    fs27.writeFileSync(acj, `${JSON.stringify(cfg, null, 2)}
+`, "utf-8");
+  } catch {
+    return;
+  }
+}
 function upsertEnv(envLocal, values) {
   let lines = [];
   try {
@@ -12503,7 +12630,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 +12792,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;
@@ -12705,59 +12877,6 @@ async function checkInstalledRecipesUnchanged(root, _target) {
   }
   return [];
 }
-function agentcoreAuthorizer(root) {
-  const descriptor = path32.join(root, "agentcore", "agentcore.json");
-  let data;
-  try {
-    data = JSON.parse(fs33.readFileSync(descriptor, "utf-8"));
-  } catch {
-    return null;
-  }
-  if (data === null || typeof data !== "object" || Array.isArray(data)) {
-    return null;
-  }
-  const runtimes = data.runtimes;
-  if (!Array.isArray(runtimes)) {
-    return null;
-  }
-  for (const rt of runtimes) {
-    if (rt === null || typeof rt !== "object") {
-      continue;
-    }
-    const auth = rt.authorizerConfiguration;
-    if (auth !== null && typeof auth === "object" && !Array.isArray(auth)) {
-      const jwt = auth.customJwtAuthorizer ?? auth.customJWTAuthorizer;
-      if (jwt !== null && typeof jwt === "object" && !Array.isArray(jwt)) {
-        return jwt;
-      }
-    }
-  }
-  return null;
-}
-async function checkCognitoAuthorizerConfigured(root, target) {
-  if (target !== "agentcore") {
-    return [];
-  }
-  const jwt = agentcoreAuthorizer(root);
-  const discovery = jwt?.discoveryUrl;
-  const clients = jwt?.allowedClients;
-  const configured = Boolean(discovery) && Array.isArray(clients) && clients.length > 0;
-  if (configured) {
-    return [];
-  }
-  return [
-    {
-      level: Level.WARNING,
-      name: "cognito_authorizer_configured",
-      message: "no Cognito authorizer configured in agentcore.json (authorizerConfiguration.customJwtAuthorizer.discoveryUrl/allowedClients) \u2192 the A2A endpoint will require SigV4/AWS creds; external buyers can't reach it. Run `bag deploy provision-cognito`, then paste the CDK outputs into the authorizer.",
-      fixCmd: "bag deploy provision-cognito",
-      details: {
-        discovery_url_set: Boolean(discovery),
-        allowed_clients: Array.isArray(clients) ? clients : []
-      }
-    }
-  ];
-}
 async function checkStorageLocalNotDeployable(root, _target) {
   const storage = loadAgentToml(root).storage;
   if (storage === null || typeof storage !== "object" || Array.isArray(storage) || String(storage.kind ?? "").toLowerCase() !== "local") {
@@ -12780,14 +12899,14 @@ var allChecks4 = [
   checkAgentUriDataUriOrHttps,
   checkNetworkMatchesChainId,
   checkRpcUrlSetForRuntime,
+  checkRuntimeRpcReachable,
   checkInstalledRecipesUnchanged,
-  checkCognitoAuthorizerConfigured,
   checkStorageLocalNotDeployable
 ];
 
 // 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 +12921,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 +12950,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 +12974,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 +12987,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 +13045,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 +13058,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 +13120,8 @@ var warningChecks = [
   checkPlatformX402MerchantsMainnet,
   checkWalletBalancesAllZero,
   checkWalletTbnbBalanceSufficient,
-  checkWalletUBalanceNonzero
+  checkWalletUBalanceNonzero,
+  checkRuntimeRpcReachable
 ];
 var infoChecks = [
   checkPlatformTrialStatus,
@@ -13234,6 +13354,7 @@ function baseResult(endpoint, runtime, overrides) {
     studioTomlUpdated: false,
     runtime,
     note: null,
+    warning: null,
     error: null,
     exitCode: 0,
     ...overrides
@@ -13273,15 +13394,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;
@@ -13289,6 +13410,7 @@ async function runVerify(opts) {
   let action = "none";
   let registerError = null;
   let postWriteError = null;
+  let postWriteWarning = null;
   let registerNote = null;
   let identityPendingReason = null;
   let registerExitCode = 0;
@@ -13321,9 +13443,8 @@ async function runVerify(opts) {
             const cause = e.cause !== null && typeof e.cause === "object" ? e.cause : null;
             const relayTxHash = typeof cause?.txHash === "string" ? cause.txHash : e.txHash;
             action = "register_partial";
-            postWriteError = relayTxHash ? `ERC-8004 register created agent_id=${e.agentId}, but setAgentURI relay tx_hash=${relayTxHash} was not observed by the chain RPC. Run \`bag erc8004 clear-pending\` to reconcile, then retry \`bag erc8004 update-endpoint\`.` : `ERC-8004 register created agent_id=${e.agentId}, but the setAgentURI relay submission was not observed by the chain RPC. Run \`bag erc8004 clear-pending\` to reconcile, then retry \`bag erc8004 update-endpoint\`.`;
+            postWriteWarning = relayTxHash ? `ERC-8004 register created agent_id=${e.agentId}, but setAgentURI relay tx_hash=${relayTxHash} was not observed by the chain RPC. Run \`bag erc8004 clear-pending\` to reconcile, then retry \`bag erc8004 update-endpoint\`.` : `ERC-8004 register created agent_id=${e.agentId}, but the setAgentURI relay submission was not observed by the chain RPC. Run \`bag erc8004 clear-pending\` to reconcile, then retry \`bag erc8004 update-endpoint\`.`;
             identityPendingReason = "setAgentURI relay submission unverified; run bag erc8004 clear-pending before retrying";
-            registerExitCode = 1;
           } else if (e.txHash) {
             action = "register_pending";
             registerNote = `ERC-8004 register created agent_id=${e.agentId}; setAgentURI tx pending (${e.txHash}). Check the tx before retrying \`bag erc8004 update-endpoint\`.`;
@@ -13417,6 +13538,7 @@ async function runVerify(opts) {
     action,
     studioTomlUpdated,
     note: notes.length > 0 ? notes.join(" | ") : null,
+    warning: postWriteWarning,
     error: postWriteError,
     exitCode: registerExitCode
   });
@@ -13436,10 +13558,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 +13602,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 +13622,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 +13658,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 +13715,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 +13726,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 +13738,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 +13756,7 @@ function recordExposedAddress(root, address) {
   if (tomlPath === null) {
     return;
   }
-  const existing = tableOf11(
+  const existing = tableOf12(
     loadAgentCfg(root),
     WALLET_SECTION
   ).platform_exposed_addresses;
@@ -13589,7 +13776,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 +13820,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 +13900,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 +13915,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 +13935,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 +14049,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 +14064,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 +14110,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 +14142,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 +14193,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 +14205,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 +14413,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 +14425,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 +14476,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 : {};
 }
@@ -14439,8 +14648,8 @@ function registerDeploy(program) {
   p.command("fix-gitignore").description(
     "Ensure the workspace .gitignore excludes .studio/ (the agent's .env.local + keystore)."
   ).option("--project-root <path>", "Override project root.").action(act((opts) => cmdFixGitignore(opts)));
-  p.command("provision-cognito").description(
-    "Emit an AWS CDK app under agentcore/cognito/ that provisions a Cognito M2M client for the AgentCore A2A inbound OAuth2 authorizer (studio writes IaC + prints steps; you run `cdk deploy`)."
+  p.command("provision-cognito", { hidden: true }).description(
+    "DEPRECATED \u2014 `bag deploy` provisions inbound OAuth by itself. Emit an AWS CDK app under agentcore/cognito/ that provisions a Cognito M2M client for the AgentCore inbound OAuth2 authorizer (studio writes IaC + prints steps; you run `cdk deploy`)."
   ).option("--project-root <path>", "Override project root.").option(
     "--wire [outputsFile]",
     "After you `cdk deploy --outputs-file <file>`, wire those outputs into agentcore.json + .studio/.env.local (default file: agentcore/cognito/cdk-outputs.json). Pure local file I/O \u2014 studio never calls AWS."
@@ -14479,7 +14688,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,24 +14696,29 @@ 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)) {
   const explicit = opts.runtime ?? opts.target;
-  if (explicit) {
-    return explicit;
-  }
   if (destination === "platform") {
+    if (explicit && explicit !== "platform") {
+      printErr(
+        `warning: --runtime=${explicit} ignored \u2014 studio.toml has [deploy].destination = 'platform', which selects the managed deploy path and its own checks. Use --provider bnb|aws to pick where this agent deploys.`
+      );
+    }
     return "platform";
   }
+  if (explicit) {
+    return explicit;
+  }
   return readStackRuntime(root) ?? "agentcore";
 }
 function validateRuntimeAgainstStack(target, force, root) {
@@ -14711,6 +14925,12 @@ function writeAgentDeployState(workspaceRoot, arn, record = {}, destination = "s
     if (scope) {
       setEnvVar(envLocalPath16(agentRoot2), "OAUTH_SCOPE", scope);
     }
+    syncDescriptorOauthFacts(workspaceRoot, {
+      tokenUrl,
+      scope,
+      discoveryUrl,
+      clientId
+    });
     if (persistedPackaging(agentRoot2) === null) {
       patchTomlKv(
         tomlPath,
@@ -14976,6 +15196,17 @@ async function refreshLocalDeployDependencies(root) {
     return 1;
   }
 }
+function partialDeployCleanupNote(workspaceRoot) {
+  const project = projectName(workspaceRoot);
+  return [
+    "note: a deploy that fails partway can leave these behind (they are reused by a successful retry, so clean up only if you are giving up):",
+    `  - ECR image            bnbagent/${project}`,
+    `  - Secrets Manager      bnbagent/${project}/runtime`,
+    `  - Cognito M2M client   bnbagent-${project}`,
+    `  - IAM role             bnbagent-${project}-runtime`,
+    "  `bag deploy destroy --provider aws --execute` removes the runtime, secret, and M2M client; add --purge for the ECR repository and log groups. The IAM role is deleted with the runtime it was created for."
+  ].join("\n");
+}
 async function cmdAgent(opts, agentcoreArgs) {
   let rc = applyProjectRoot(opts.projectRoot);
   if (rc !== null) {
@@ -15187,6 +15418,7 @@ async function cmdAgent(opts, agentcoreArgs) {
     printErr(
       "note: the pinned bnbagent-deploy adapter automatically restores an owned runtime secret that is inside its recovery window. If AWS denies that operation, update the deployer policy to include secretsmanager:RestoreSecret."
     );
+    printErr(partialDeployCleanupNote(workspaceRoot));
     return code;
   }
   const record = recordOf2(data);
@@ -15246,13 +15478,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 +15493,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 +15502,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 +15511,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 +15604,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,
@@ -15526,6 +15761,7 @@ function verifyToJson(r) {
     studio_toml_updated: r.studioTomlUpdated,
     runtime: r.runtime,
     note: r.note,
+    warning: r.warning,
     error: r.error,
     exit_code: r.exitCode
   };
@@ -15567,12 +15803,15 @@ function renderVerifyHuman(r, deployment, liveStatus) {
   if (r.note) {
     printOut(`note: ${r.note}`);
   }
+  if (r.warning) {
+    printOut(`warning: ${r.warning}`);
+  }
   if (r.error) {
     printOut(`error: ${r.error}`);
   }
 }
 function deployCliError(data) {
-  const error = tableOf12(data, "error");
+  const error = tableOf13(data, "error");
   const message = String(error.message ?? "").trim();
   return message || null;
 }
@@ -15914,6 +16153,7 @@ async function cmdFixGitignore(opts) {
   printOut(`${marker} ${result.name}: ${result.message}`);
   return 0;
 }
+var PROVISION_COGNITO_DEPRECATION = "warning: `bag deploy provision-cognito` is deprecated and will be removed.\n  `bag deploy` provisions the inbound OAuth user pool and M2M client on its\n  own; the pool this CDK app stands up is never used by a deploy, and both\n  the stack and its client are billable orphans you have to clean up.\n  Run `bag deploy --provider aws` directly instead.";
 async function cmdProvisionCognito(opts) {
   const rc = applyProjectRoot(opts.projectRoot, false);
   if (rc !== null) {
@@ -15921,6 +16161,7 @@ async function cmdProvisionCognito(opts) {
   }
   const root = resolveProjectRoot2(opts.projectRoot);
   const workspaceRoot = deployWorkspaceRoot2(root);
+  printOut(PROVISION_COGNITO_DEPRECATION);
   if (opts.wire !== void 0 && opts.wire !== false) {
     const outputsFile = typeof opts.wire === "string" && opts.wire ? opts.wire : null;
     try {
@@ -15987,7 +16228,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 +16305,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 +16388,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 +16465,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 +16637,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 +16683,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 +16719,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 +16764,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 +16835,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 +16856,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 +16901,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 +16919,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 +16999,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 +17017,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 +17034,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 +17069,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 +17095,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 +17141,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 +17163,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 +17240,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 +17257,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 +17267,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 +17312,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 +17321,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 +17354,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 +17394,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 +17678,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 +17701,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 +17712,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 +17722,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 +17768,7 @@ function syncAgentRegistry(agentId, op) {
 function loadIdentityBlock(agentRoot2) {
   try {
     return {
-      ...tableOf14(
+      ...tableOf15(
         loadStudioToml22(path40.join(agentRoot2, "studio.toml")),
         "identity"
       )
@@ -17630,7 +17871,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 +18175,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 +18307,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 +18345,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 +18361,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 +19613,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 +19631,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 +19685,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 +19709,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 +19748,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 +19774,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 +19795,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 +19955,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 +19968,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 +20002,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 +20018,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 +20080,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 +20094,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 +20210,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 +20302,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 +20383,7 @@ function buildProgram() {
   return program;
 }
 function cliVersion() {
-  return "0.0.6-alpha.5";
+  return "0.0.6-alpha.7";
 }
 
 // src/cli/updateCheck.ts