@bnbagent/studio-cli 0.0.6-alpha.9 → 0.0.7

package/dist/bag.js

@@ -44,7 +44,7 @@ import {
   x402SellerIsFree,
   x402SellerPricingState,
   x402SellerUsesB402
-} from "./chunk-JZAW6HMV.js";
+} from "./chunk-ODCZKKZJ.js";
 import {
   TWAK_CLI_MIN_VERSION,
   TWAK_CLI_VERSION,
@@ -69,35 +69,151 @@ import { ensureAltanaSessionLoaded } from "@bnbagent/studio-runtime/wallet";
 import * as fs from "fs";
 import {
   STUDIO_TOML,
-  envLocalPath,
+  envLocalPath as envLocalPath2,
   findProjectRoot,
   findWorkspaceRoot,
   loadEnv
 } from "@bnbagent/studio-runtime/config";
-function autoloadProjectEnv() {
+
+// src/cli/_erc8183Config.ts
+import { envLocalPath } from "@bnbagent/studio-runtime/config";
+var ERC8183_ADDRESS_OVERRIDE_KEYS = [
+  "ERC8183_COMMERCE_ADDRESS",
+  "ERC8183_ROUTER_ADDRESS",
+  "ERC8183_POLICY_ADDRESS"
+];
+var MAX_UINT256 = 2n ** 256n - 1n;
+function erc8183ContractEnvForProject(agentRoot2, fallback = process.env) {
+  const envPath = envLocalPath(agentRoot2);
+  const fromFile = {};
+  for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+    const raw = getEnvVar(envPath, key);
+    if (raw === null) continue;
+    const value = raw.trim().replace(/^"(.*)"$/u, "$1").replace(/^'(.*)'$/u, "$1");
+    if (value) fromFile[key] = value;
+  }
+  const fromFallback = {};
+  const fallbackOwnsStack = ERC8183_ADDRESS_OVERRIDE_KEYS.some(
+    (key) => fallback[key] !== void 0
+  );
+  for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+    const value = fallback[key]?.trim();
+    if (value) fromFallback[key] = value;
+  }
+  return fallbackOwnsStack ? fromFallback : fromFile;
+}
+function erc8183PricingState(pay) {
+  const priceRaw = pay.price;
+  const price = String(priceRaw ?? "").trim();
+  if (!price) return { kind: "unset" };
+  if (typeof priceRaw !== "string") {
+    return { kind: "invalid", field: "price", value: price };
+  }
+  const minRaw = pay.min_price;
+  const maxRaw = pay.max_price;
+  const minPrice = String(minRaw ?? "").trim() || "0";
+  const maxPrice = String(maxRaw ?? "").trim();
+  if (minRaw !== void 0 && typeof minRaw !== "string") {
+    return { kind: "invalid", field: "min_price", value: minPrice };
+  }
+  if (maxRaw !== void 0 && typeof maxRaw !== "string") {
+    return { kind: "invalid", field: "max_price", value: maxPrice };
+  }
+  for (const [field, value] of [
+    ["price", price],
+    ["min_price", minPrice],
+    ["max_price", maxPrice]
+  ]) {
+    if ((field !== "max_price" || value !== "") && !/^\d+$/.test(value)) {
+      return { kind: "invalid", field, value };
+    }
+  }
+  const list = BigInt(price);
+  const min = BigInt(minPrice);
+  const max = maxPrice ? BigInt(maxPrice) : MAX_UINT256;
+  if (list > MAX_UINT256 || min > MAX_UINT256 || max > MAX_UINT256) {
+    const [field, value] = list > MAX_UINT256 ? ["price", price] : min > MAX_UINT256 ? ["min_price", minPrice] : ["max_price", maxPrice];
+    return { kind: "invalid", field, value };
+  }
+  const clampedToMax = list < max ? list : max;
+  const effective = min > clampedToMax ? min : clampedToMax;
+  const base = {
+    listPrice: list,
+    minPrice: min,
+    maxPrice: max,
+    effectivePrice: effective
+  };
+  if (list > 0n && effective === 0n) {
+    return { kind: "clamped_to_zero", ...base };
+  }
+  return { kind: effective === 0n ? "free" : "paid", ...base };
+}
+function erc8183ContractOverrideState(env = process.env) {
+  const present = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => Boolean(env[key]?.trim())
+  );
+  const missing = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => !env[key]?.trim()
+  );
+  const invalid = present.filter(
+    (key) => !/^0x[0-9a-fA-F]{40}$/.test(env[key]?.trim() ?? "")
+  );
+  return {
+    mode: present.length === 0 ? "canonical" : invalid.length > 0 ? "invalid" : missing.length === 0 ? "custom" : "partial",
+    present: [...present],
+    missing: [...missing],
+    invalid
+  };
+}
+
+// src/cli/_env.ts
+var autoloadedValues = /* @__PURE__ */ new Map();
+function releaseAutoloadedValues() {
+  for (const [key, value] of autoloadedValues) {
+    if (process.env[key] === value) {
+      delete process.env[key];
+    }
+  }
+  autoloadedValues.clear();
+}
+function autoloadProjectEnv(start) {
   try {
-    const root = findProjectRoot();
+    releaseAutoloadedValues();
+    const root = findProjectRoot(start);
     if (root === null) {
-      return;
+      return releaseAutoloadedValues;
     }
-    const envPath = envLocalPath(root);
+    const envPath = envLocalPath2(root);
     if (!fs.statSync(envPath).isFile()) {
-      return;
+      return releaseAutoloadedValues;
     }
-    for (const [key, value] of Object.entries(loadEnv(envPath))) {
-      if (process.env[key] === void 0) {
-        process.env[key] = value;
+    const explicitContractKeys = new Set(
+      ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+        (key) => process.env[key] !== void 0
+      )
+    );
+    const loaded = loadEnv(envPath);
+    if (explicitContractKeys.size > 0) {
+      for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+        if (!explicitContractKeys.has(key) && key in loaded) {
+          delete process.env[key];
+          delete loaded[key];
+        }
       }
     }
+    for (const [key, value] of Object.entries(loaded)) {
+      autoloadedValues.set(key, value);
+    }
   } catch {
   }
+  return releaseAutoloadedValues;
 }
 
 // src/cli/_hosted/campaign.ts
 import * as fs2 from "fs";
 import * as path from "path";
 import {
-  envLocalPath as envLocalPath2,
+  envLocalPath as envLocalPath3,
   findSubProjectRoot,
   loadStudioToml
 } from "@bnbagent/studio-runtime/config";
@@ -106,7 +222,7 @@ import {
 var CAMPAIGN_DOC_URL = "https://www.bnbchain.org/en/blog/bnb-agent-studio-is-live-on-bnb-chain-ai-agents-from-one-prompt";
 var CAMPAIGN_CHECK_TIMEOUT_MS = 6e3;
 async function fetchCampaignActive() {
-  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-AJ25A4VK.js");
+  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-VM5TYKQX.js");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), CAMPAIGN_CHECK_TIMEOUT_MS);
   try {
@@ -158,7 +274,7 @@ var NUDGE_WINDOWS = [
 ];
 var NUDGE_ORDER = ["", "12h", "1h", "expired"];
 function trialStatePath(start) {
-  return path.join(path.dirname(envLocalPath2(start)), "platform-trial.json");
+  return path.join(path.dirname(envLocalPath3(start)), "platform-trial.json");
 }
 function loadTrialState(start) {
   try {
@@ -521,8 +637,8 @@ function tableOf(cfg, key) {
   const v = cfg[key];
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
-function registerProject(projectRootArg, opts = {}) {
-  const projectRoot = normalizePath(projectRootArg);
+function registerProject(projectRootArg2, opts = {}) {
+  const projectRoot = normalizePath(projectRootArg2);
   if (!isDir(projectRoot)) {
     throw new Error(`path is not a directory: ${projectRoot}`);
   }
@@ -1530,7 +1646,7 @@ function cmdDisable(projectRoot) {
 import * as fs8 from "fs";
 import * as path7 from "path";
 import {
-  envLocalPath as envLocalPath3,
+  envLocalPath as envLocalPath4,
   findSubProjectRoot as findSubProjectRoot2,
   findWorkspaceRoot as findWorkspaceRoot2,
   loadStudioToml as loadStudioToml2
@@ -1796,6 +1912,14 @@ var EXCLUDED_NAMES = /* @__PURE__ */ new Set([
   ".ruff_cache",
   ".mypy_cache"
 ]);
+var CREDENTIAL_FILE_NAMES = /* @__PURE__ */ new Set([
+  ".git-credentials",
+  ".netrc",
+  ".npmrc",
+  ".pypirc",
+  ".yarnrc",
+  ".yarnrc.yml"
+]);
 function registerBundle(program) {
   program.command("bundle").description(
     "Bundle a seller workspace + pinned SDK/runtime tarballs for handoff."
@@ -1846,6 +1970,11 @@ async function createBundle(opts = {}) {
   const archiveBase = `${safeName}-bundle-${stamp}`;
   const stagingRoot = path7.join(outputDir, `.${archiveBase}.staging`);
   const stagedWorkspace = path7.join(stagingRoot, safeName);
+  if (stagedWorkspace === stagingRoot || !inside(stagedWorkspace, stagingRoot)) {
+    throw new Error(
+      `unsafe project name ${JSON.stringify(projectName2)} escapes the bundle staging directory`
+    );
+  }
   const agentRel = path7.relative(workspaceRoot, agentRoot2);
   const stagedAgent = path7.join(stagedWorkspace, agentRel);
   const archivePath = path7.join(outputDir, `${archiveBase}.tar.gz`);
@@ -1917,7 +2046,8 @@ function readProjectName(agentRoot2) {
   return String(name);
 }
 function excludedName(name) {
-  return EXCLUDED_NAMES.has(name) || name.startsWith(".env") || name.endsWith(".egg-info") || name.startsWith(".venv-");
+  const lowerName = name.toLowerCase();
+  return EXCLUDED_NAMES.has(lowerName) || CREDENTIAL_FILE_NAMES.has(lowerName) || lowerName.startsWith(".env") || lowerName.endsWith(".egg-info") || lowerName.startsWith(".venv-");
 }
 function inside(child, parent) {
   const rel = path7.relative(parent, child);
@@ -1968,7 +2098,7 @@ function copyWorkspace(sourceRoot, destinationRoot, outputDir) {
   copy(source, destinationRoot);
 }
 function writeEnvExample(agentRoot2, stagedWorkspace) {
-  const sourceEnv = envLocalPath3(agentRoot2);
+  const sourceEnv = envLocalPath4(agentRoot2);
   const targetDir = path7.join(stagedWorkspace, ".studio");
   const target = path7.join(targetDir, ".env.local.example");
   fs8.mkdirSync(targetDir, { recursive: true, mode: 448 });
@@ -1989,8 +2119,13 @@ function writeEnvExample(agentRoot2, stagedWorkspace) {
     ];
   }
   const stripped = lines.map((line) => {
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(line);
-    return match ? `${match[1]}=` : line;
+    const trimmed = line.trim();
+    if (!trimmed) return line;
+    const commented = /^\s*(?:#\s*)+(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u.exec(line);
+    if (commented) return `# ${commented[1]}=`;
+    if (trimmed.startsWith("#")) return "# omitted source comment";
+    const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+    return match ? `${match[1]}=` : "# omitted unrecognized dotenv entry";
   });
   fs8.writeFileSync(target, `${[...header, ...stripped].join("\n")}
 `, {
@@ -2004,6 +2139,7 @@ function findStagedLeak(stagedWorkspace) {
       const full = path7.join(dir, name);
       const rel = path7.relative(root, full);
       const stat = fs8.lstatSync(full);
+      const lowerName = name.toLowerCase();
       if (stat.isSymbolicLink()) {
         const link = fs8.readlinkSync(full);
         const target = path7.resolve(path7.dirname(full), link);
@@ -2013,15 +2149,29 @@ function findStagedLeak(stagedWorkspace) {
         continue;
       }
       if (stat.isDirectory()) {
-        if (name === "wallets" && path7.basename(path7.dirname(full)) === ".studio") {
+        if (lowerName === "wallets" && path7.basename(path7.dirname(full)).toLowerCase() === ".studio") {
           return `wallet directory ${rel}`;
         }
         const nested = walk(full);
         if (nested !== null) return nested;
         continue;
       }
-      if (stat.isFile() && name.startsWith(".env") && name !== ".env.local.example") {
-        return `env file ${rel}`;
+      if (stat.isFile() && CREDENTIAL_FILE_NAMES.has(lowerName)) {
+        return `credential file ${rel}`;
+      }
+      if (stat.isFile() && lowerName.startsWith(".env")) {
+        if (lowerName !== ".env.local.example") return `env file ${rel}`;
+        const safeFixedLines = /* @__PURE__ */ new Set([
+          "# Copy to .studio/.env.local and fill in values.",
+          "# Generated by `bag bundle`; secret values were stripped.",
+          "# omitted source comment",
+          "# omitted unrecognized dotenv entry"
+        ]);
+        const unsafeExample = fs8.readFileSync(full, "utf-8").split(/\r?\n/u).some((line) => {
+          if (!line.trim() || safeFixedLines.has(line)) return false;
+          return !/^#?\s*[A-Za-z_][A-Za-z0-9_]*=$/u.test(line);
+        });
+        if (unsafeExample) return `non-empty env example ${rel}`;
       }
     }
     return null;
@@ -2064,6 +2214,7 @@ function writeInstallMd(stagedWorkspace, projectName2) {
     "",
     "- `.studio/.env.local`",
     "- `.studio/wallets/` and TWAK/Altana custody state",
+    "- project-level credential files such as `.npmrc`",
     "- `node_modules/`, build outputs, caches, and repository history",
     ""
   ];
@@ -2104,77 +2255,6 @@ function devPortInUse(port = 9e3, timeoutMs = 250) {
   });
 }
 
-// src/cli/_erc8183Config.ts
-var ERC8183_ADDRESS_OVERRIDE_KEYS = [
-  "ERC8183_COMMERCE_ADDRESS",
-  "ERC8183_ROUTER_ADDRESS",
-  "ERC8183_POLICY_ADDRESS"
-];
-var MAX_UINT256 = 2n ** 256n - 1n;
-function erc8183PricingState(pay) {
-  const priceRaw = pay.price;
-  const price = String(priceRaw ?? "").trim();
-  if (!price) return { kind: "unset" };
-  if (typeof priceRaw !== "string") {
-    return { kind: "invalid", field: "price", value: price };
-  }
-  const minRaw = pay.min_price;
-  const maxRaw = pay.max_price;
-  const minPrice = String(minRaw ?? "").trim() || "0";
-  const maxPrice = String(maxRaw ?? "").trim();
-  if (minRaw !== void 0 && typeof minRaw !== "string") {
-    return { kind: "invalid", field: "min_price", value: minPrice };
-  }
-  if (maxRaw !== void 0 && typeof maxRaw !== "string") {
-    return { kind: "invalid", field: "max_price", value: maxPrice };
-  }
-  for (const [field, value] of [
-    ["price", price],
-    ["min_price", minPrice],
-    ["max_price", maxPrice]
-  ]) {
-    if ((field !== "max_price" || value !== "") && !/^\d+$/.test(value)) {
-      return { kind: "invalid", field, value };
-    }
-  }
-  const list = BigInt(price);
-  const min = BigInt(minPrice);
-  const max = maxPrice ? BigInt(maxPrice) : MAX_UINT256;
-  if (list > MAX_UINT256 || min > MAX_UINT256 || max > MAX_UINT256) {
-    const [field, value] = list > MAX_UINT256 ? ["price", price] : min > MAX_UINT256 ? ["min_price", minPrice] : ["max_price", maxPrice];
-    return { kind: "invalid", field, value };
-  }
-  const clampedToMax = list < max ? list : max;
-  const effective = min > clampedToMax ? min : clampedToMax;
-  const base = {
-    listPrice: list,
-    minPrice: min,
-    maxPrice: max,
-    effectivePrice: effective
-  };
-  if (list > 0n && effective === 0n) {
-    return { kind: "clamped_to_zero", ...base };
-  }
-  return { kind: effective === 0n ? "free" : "paid", ...base };
-}
-function erc8183ContractOverrideState(env = process.env) {
-  const present = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
-    (key) => Boolean(env[key]?.trim())
-  );
-  const missing = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
-    (key) => !env[key]?.trim()
-  );
-  const invalid = present.filter(
-    (key) => !/^0x[0-9a-fA-F]{40}$/.test(env[key]?.trim() ?? "")
-  );
-  return {
-    mode: present.length === 0 ? "canonical" : invalid.length > 0 ? "invalid" : missing.length === 0 ? "custom" : "partial",
-    present: [...present],
-    missing: [...missing],
-    invalid
-  };
-}
-
 // src/cli/config.ts
 var MAX_QUOTE_TTL_SECONDS = NegotiationHandler.MAX_QUOTE_TTL_SECONDS;
 function registerConfig(program) {
@@ -2484,7 +2564,9 @@ async function cmdSet(key, rawValue, typeFlag, projectRoot) {
     }
     if (pricing.kind === "free") {
       printOut("pricing: FREE \u2014 buyers fund 0 token units; zero token escrow.");
-      const contracts = erc8183ContractOverrideState();
+      const contracts = erc8183ContractOverrideState(
+        erc8183ContractEnvForProject(root)
+      );
       if (contracts.mode === "custom") {
         printOut(
           "ERC-8183 contracts: custom contract stack selected with all three address overrides."
@@ -2498,8 +2580,8 @@ async function cmdSet(key, rawValue, typeFlag, projectRoot) {
           `warning: invalid ERC-8183 address override(s): ${contracts.invalid.join(", ")}.`
         );
       } else {
-        printErr(
-          "warning: FREE requires a zero-price-compatible contract stack; set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together before deploy."
+        printOut(
+          "ERC-8183 contracts: canonical contract stack selected; zero-price funding is supported."
         );
       }
     } else if (pricing.kind === "clamped_to_zero") {
@@ -2554,7 +2636,7 @@ function cmdListKeys(projectRoot) {
 import * as fs38 from "fs";
 import * as path38 from "path";
 import {
-  envLocalPath as envLocalPath16,
+  envLocalPath as envLocalPath17,
   findStudioWorkspaceRoot as findStudioWorkspaceRoot3,
   findSubProjectRoot as findSubProjectRoot16,
   loadStudioToml as loadStudioToml20
@@ -2566,7 +2648,7 @@ import { Option as Option4 } from "commander";
 import * as fs10 from "fs";
 import * as path9 from "path";
 import {
-  envLocalPath as envLocalPath4,
+  envLocalPath as envLocalPath5,
   findWorkspaceRoot as findWorkspaceRoot3,
   loadStudioToml as loadStudioToml3
 } from "@bnbagent/studio-runtime/config";
@@ -2649,10 +2731,10 @@ function oauthFacts(workspaceRoot, agentRoot2) {
   let tokenUrl = envValue(env, "OAUTH_TOKEN_URL");
   let scope = envValue(env, "OAUTH_SCOPE");
   if (!tokenUrl) {
-    tokenUrl = dotenvValue(envLocalPath4(agentRoot2), "OAUTH_TOKEN_URL");
+    tokenUrl = dotenvValue(envLocalPath5(agentRoot2), "OAUTH_TOKEN_URL");
   }
   if (!scope) {
-    scope = dotenvValue(envLocalPath4(agentRoot2), "OAUTH_SCOPE");
+    scope = dotenvValue(envLocalPath5(agentRoot2), "OAUTH_SCOPE");
   }
   return tokenUrl && scope ? [tokenUrl, scope] : null;
 }
@@ -2687,7 +2769,7 @@ function accessSummaryForAgentcore(agentRoot2, opts = {}) {
 
 // src/cli/_deploy/checks/storage.ts
 import {
-  envLocalPath as envLocalPath5,
+  envLocalPath as envLocalPath6,
   findSubProjectRoot as findSubProjectRoot4
 } from "@bnbagent/studio-runtime/config";
 
@@ -2945,7 +3027,7 @@ function agentStorageKind(root) {
 }
 function runtimeEnvResolvable(root, key) {
   const agentRoot2 = findSubProjectRoot4("agent", root) ?? root;
-  return Boolean(process.env[key] || getEnvVar(envLocalPath5(agentRoot2), key));
+  return Boolean(process.env[key] || getEnvVar(envLocalPath6(agentRoot2), key));
 }
 function storageLocalNotDeployableCheck(root) {
   if (agentStorageKind(root) !== "local") {
@@ -2996,13 +3078,13 @@ function hasIpfsEndpointFinding(result) {
 // src/cli/_deploy/cognitoCdk.ts
 import * as fs28 from "fs";
 import * as path27 from "path";
-import { envLocalPath as envLocalPath13 } from "@bnbagent/studio-runtime/config";
+import { envLocalPath as envLocalPath14 } from "@bnbagent/studio-runtime/config";
 
 // src/cli/_deploy/secrets.ts
 import * as fs27 from "fs";
 import * as path26 from "path";
 import {
-  envLocalPath as envLocalPath12,
+  envLocalPath as envLocalPath13,
   findSubProjectRoot as findSubProjectRoot8,
   loadStudioToml as loadStudioToml13
 } from "@bnbagent/studio-runtime/config";
@@ -3021,7 +3103,7 @@ import { Option as Option3 } from "commander";
 import * as fs12 from "fs";
 import * as path11 from "path";
 import {
-  envLocalPath as envLocalPath6,
+  envLocalPath as envLocalPath7,
   findSubProjectRoot as findSubProjectRoot5,
   loadStudioToml as loadStudioToml5
 } from "@bnbagent/studio-runtime/config";
@@ -3054,7 +3136,7 @@ function keystoreJsonFiles(dir) {
 }
 function migrateEnvLocal(start) {
   try {
-    const target = envLocalPath6(start);
+    const target = envLocalPath7(start);
     const ws = path11.dirname(path11.dirname(target));
     const agentRoot2 = findSubProjectRoot5("agent", start);
     const sources = [];
@@ -3120,7 +3202,7 @@ function migrateKeystoreOutOfCodelocation(start) {
   if (agentRoot2 === null) {
     return;
   }
-  const ws = path11.dirname(path11.dirname(envLocalPath6(start)));
+  const ws = path11.dirname(path11.dirname(envLocalPath7(start)));
   const target = path11.join(ws, ".studio", "wallets");
   const stash = path11.join(ws, ".bag-keystore-stash");
   if (isDir2(stash)) {
@@ -3469,6 +3551,26 @@ var EXPIRY_WARN_SECONDS = 7 * 24 * 60 * 60;
 function isAltana(data) {
   return tableOf2(data, "wallet").kind === "altana";
 }
+function checkAltanaCustomContractsUnsupported(root, _target) {
+  const data = loadAgentToml(root);
+  if (!isAltana(data)) return [];
+  if (Object.keys(tableOf2(tableOf2(data, "payments"), "erc8183")).length === 0) {
+    return [];
+  }
+  const agentRoot2 = agentRootOf(root);
+  const contracts = erc8183ContractOverrideState(
+    erc8183ContractEnvForProject(agentRoot2)
+  );
+  if (contracts.mode !== "custom") return [];
+  return [
+    {
+      level: Level.CRITICAL,
+      name: "altana_custom_contracts_unsupported",
+      message: "wallet.kind='altana' cannot use custom ERC-8183 targets: its bounded session permissions and quote-checker approval are tied to the canonical Commerce stack. Remove the ERC8183_*_ADDRESS overrides, or use wallet.kind='evm-local' for this custom stack.",
+      details: { override_keys: contracts.present }
+    }
+  ];
+}
 function isFile4(p) {
   try {
     return fs15.statSync(p).isFile();
@@ -3632,7 +3734,7 @@ function checkAltanaSessionNotInsideAgent(root, _target) {
 // src/cli/_deploy/checks/twak.ts
 import * as fs16 from "fs";
 import * as path15 from "path";
-import { envLocalPath as envLocalPath7 } from "@bnbagent/studio-runtime/config";
+import { envLocalPath as envLocalPath8 } from "@bnbagent/studio-runtime/config";
 import { resolveTwakHome } from "@bnbagent/studio-runtime/wallet";
 
 // src/cli/_twakContractTargets.ts
@@ -3784,7 +3886,10 @@ function checkTwakCustomContractsUnsupported(root, _target) {
     return [];
   }
   const networkName = String(tableOf2(data, "network").default ?? "bsc-testnet");
-  const overrides = twakUnsupportedContractOverrides(networkName);
+  const overrides = twakUnsupportedContractOverrides(
+    networkName,
+    erc8183ContractEnvForProject(agentRootOf(root))
+  );
   if (overrides.length === 0) {
     return [];
   }
@@ -3884,7 +3989,7 @@ async function checkTwakPasswordEnvSet(root, _target) {
     return [];
   }
   const agentRoot2 = agentRootOf(root);
-  if (process.env.TWAK_WALLET_PASSWORD || getEnvVar(envLocalPath7(agentRoot2), "TWAK_WALLET_PASSWORD")) {
+  if (process.env.TWAK_WALLET_PASSWORD || getEnvVar(envLocalPath8(agentRoot2), "TWAK_WALLET_PASSWORD")) {
     return [];
   }
   return [
@@ -3935,7 +4040,7 @@ async function checkTwakCredentialsAvailable(root, _target) {
     path15.dirname(twakWalletFile(walletCfg, agentRoot2)),
     "credentials.json"
   );
-  const envLocal = envLocalPath7(agentRoot2);
+  const envLocal = envLocalPath8(agentRoot2);
   const resolvable = (key) => Boolean(process.env[key] || getEnvVar(envLocal, key));
   if (isFile5(credentialsFile)) {
     return [];
@@ -3956,9 +4061,9 @@ async function checkTwakCredentialsAvailable(root, _target) {
 // src/cli/_deploy/fixes.ts
 import * as fs17 from "fs";
 import * as path16 from "path";
-import { envLocalPath as envLocalPath8 } from "@bnbagent/studio-runtime/config";
+import { envLocalPath as envLocalPath9 } from "@bnbagent/studio-runtime/config";
 function fixGitignore(root) {
-  const ws = path16.dirname(path16.dirname(envLocalPath8(root)));
+  const ws = path16.dirname(path16.dirname(envLocalPath9(root)));
   const gi = path16.join(ws, ".gitignore");
   const required = [".studio/"];
   let exists = false;
@@ -4432,8 +4537,10 @@ var azureFoundryChecks = [
   checkAccountEqualsSubdomain,
   checkEntrypointAndDockerfile,
   checkLlmExternalProviderReady,
+  checkTwakCustomContractsUnsupported,
   checkTwakPasswordEnvSet,
   checkTwakCredentialsAvailable,
+  checkAltanaCustomContractsUnsupported,
   checkAltanaSessionReady,
   checkAltanaSdkResolvable,
   checkAltanaSessionNotInsideAgent
@@ -4444,7 +4551,7 @@ import * as fs19 from "fs";
 import * as path18 from "path";
 import { query as auditQuery, auditedOp } from "@bnbagent/studio-runtime/audit";
 import {
-  envLocalPath as envLocalPath9,
+  envLocalPath as envLocalPath10,
   findProjectRoot as findProjectRoot2,
   loadStudioToml as loadStudioToml8
 } from "@bnbagent/studio-runtime/config";
@@ -4823,7 +4930,7 @@ async function cmdActivate(opts) {
   const pvCfg = loadPieverseConfig(cfg);
   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 envFileValue = replace ? null : getEnvVar(envLocalPath10(root), PIEVERSE_ENV_KEY);
   const existingEnv = replace ? null : envFileValue || process.env[PIEVERSE_ENV_KEY];
   if (replace) {
     printOut(
@@ -5026,7 +5133,7 @@ Retry: re-run \`bag llm activate\` \u2014 no state was persisted yet.`
   }
   const key = String(result.key);
   const keyHash = String(result.hash);
-  writeEnvLocal(PIEVERSE_ENV_KEY, key, envLocalPath9(root));
+  writeEnvLocal(PIEVERSE_ENV_KEY, key, envLocalPath10(root));
   updateStudioTomlSection(root, "llm.pieverse", {
     key_hash: keyHash,
     network: networkName
@@ -5557,7 +5664,7 @@ async function cmdRotate(opts) {
       `warning: could not auto-disable old key \u2014 manually disable ${oldHash} in the Pieverse dashboard.`
     );
   }
-  writeEnvLocal(PIEVERSE_ENV_KEY, newKey, envLocalPath9(root));
+  writeEnvLocal(PIEVERSE_ENV_KEY, newKey, envLocalPath10(root));
   updateStudioTomlSection(root, "llm.pieverse", {
     key_hash: newHash,
     network: networkName
@@ -6312,7 +6419,7 @@ import * as os3 from "os";
 import * as path22 from "path";
 import { EVMWalletProvider, SigningPolicy } from "@bnbagent/sdk";
 import {
-  envLocalPath as envLocalPath10,
+  envLocalPath as envLocalPath11,
   findProjectRoot as findProjectRoot3,
   loadStudioToml as loadStudioToml10
 } from "@bnbagent/studio-runtime/config";
@@ -6623,8 +6730,8 @@ async function cmdSessionGrant(opts) {
   printOut(granted.publicKey);
   return 0;
 }
-function cmdSessionStatus(projectRootArg) {
-  const projectRoot = resolveProjectRootArg(projectRootArg);
+function cmdSessionStatus(projectRootArg2) {
+  const projectRoot = resolveProjectRootArg(projectRootArg2);
   if (projectRoot === null) return 2;
   const ctx = loadContext(projectRoot);
   const { envelope } = readSession(ctx);
@@ -6857,7 +6964,7 @@ function requirePassword2() {
 }
 function requireDurablePassword(projectRoot) {
   const password = requirePassword2();
-  const envPath = envLocalPath10(projectRoot);
+  const envPath = envLocalPath11(projectRoot);
   const persisted = getEnvVar(envPath, PASSWORD_ENV2);
   if (!persisted) {
     throw new Error(
@@ -7230,8 +7337,8 @@ ${detail}` : `error: \`twak wallet create --no-keychain\` did not produce ${wall
   );
   return cmdNewTwak(projectRoot, walletCfg);
 }
-function cmdShow5(projectRootArg) {
-  const projectRoot = resolveWalletProjectRoot(projectRootArg);
+function cmdShow5(projectRootArg2) {
+  const projectRoot = resolveWalletProjectRoot(projectRootArg2);
   const walletCfg = loadWalletCfg(projectRoot);
   const kind = walletKind(walletCfg);
   if (kind === "twak") {
@@ -7292,8 +7399,8 @@ function cmdShow5(projectRootArg) {
   }
   return 0;
 }
-function cmdList2(projectRootArg) {
-  const projectRoot = resolveWalletProjectRoot(projectRootArg);
+function cmdList2(projectRootArg2) {
+  const projectRoot = resolveWalletProjectRoot(projectRootArg2);
   const walletCfg = loadWalletCfg(projectRoot);
   if (walletKind(walletCfg) === "twak") {
     printOut(twakProvider(projectRoot, walletCfg).address);
@@ -7334,8 +7441,8 @@ function cmdList2(projectRootArg) {
   }
   return 0;
 }
-async function cmdSign(msg, projectRootArg) {
-  const projectRoot = resolveWalletProjectRoot(projectRootArg);
+async function cmdSign(msg, projectRootArg2) {
+  const projectRoot = resolveWalletProjectRoot(projectRootArg2);
   const walletCfg = loadWalletCfg(projectRoot);
   const kind = walletKind(walletCfg);
   if (kind === "altana") {
@@ -7428,8 +7535,8 @@ async function cmdBalance(opts) {
   }
   return 0;
 }
-function cmdPolicyShow(asJson, projectRootArg) {
-  const projectRoot = resolveWalletProjectRoot(projectRootArg);
+function cmdPolicyShow(asJson, projectRootArg2) {
+  const projectRoot = resolveWalletProjectRoot(projectRootArg2);
   const walletCfg = loadWalletCfg(projectRoot);
   const kind = walletKind(walletCfg);
   if (kind === "twak") {
@@ -7752,7 +7859,7 @@ function registerInit(program) {
   ).addOption(
     new Option2(
       "--wallet-kind <kind>",
-      "Wallet backend for the Agent (default: evm-local = encrypted local keystore at the workspace root .studio/wallets/; CodeZip deploy). altana \u2014 encrypted local admin keystore plus a bounded runtime session (local dev; deployment deferred). twak \u2014 FULLY SUPPORTED, opt in: Trust Wallet Agent Kit CLI, self-custody encrypted mnemonic in a PROJECT-DEDICATED home (.studio/twak); deploys as a container image."
+      "Wallet backend for the Agent (default: evm-local = encrypted local keystore at the workspace root .studio/wallets/; CodeZip deploy). altana \u2014 encrypted local admin keystore plus a bounded runtime session; deploys ship ONLY the session (ALTANA_SESSION secret). twak \u2014 FULLY SUPPORTED, opt in: Trust Wallet Agent Kit CLI, self-custody encrypted mnemonic in a PROJECT-DEDICATED home (.studio/twak); deploys as a container image."
     ).choices(["twak", "evm-local", "altana"])
   ).option(
     "--twak-home <path>",
@@ -8128,7 +8235,7 @@ async function cmdInit(nameArg, opts) {
     });
   }
   if (destination === "platform") {
-    printPlatformWalletSuggestion();
+    printPlatformWalletSuggestion(walletKind2);
   }
   if (installFailed) {
     printErr(
@@ -8234,7 +8341,7 @@ function scaffold(target, name, o) {
   fs24.writeFileSync(path23.join(agentRoot2, ".gitignore"), renderAgentGitignore());
   fs24.writeFileSync(
     path23.join(agentRoot2, "README.md"),
-    renderAgentReadme(name, o.faces, o.destination)
+    renderAgentReadme(name, o.faces, o.destination, o.walletKind)
   );
   const packaging = derivePackaging(
     o.walletKind,
@@ -8620,8 +8727,7 @@ function renderAgentStudioToml(name, o) {
 [payments.erc8183]
 # Read by the Agent: it quotes the FIXED \`price\`, CLAMPS it to [min,max],
 # freezes a short-TTL offer, and EIP-191 signs it \u2014 pricing is rule-based, the
-# LLM never prices. price=0 is FREE and needs a zero-price-compatible
-# ERC-8183 stack selected with all three ERC8183_*_ADDRESS overrides.
+# LLM never prices. price=0 is FREE and is supported by the canonical stack.
 currency = "${currencyAddr}"   # $U token address \u2014 prefilled from [network].default
 price = "${o.erc8183Price}"                    # token base units; 0 = FREE (zero token escrow)
 min_price = "0"                                # wei \u2014 clamp floor
@@ -8748,7 +8854,6 @@ function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails, b402
       "",
       "# Optional ERC-8183 custom contract-stack override. Set all three",
       "# together; partial overrides can mix incompatible deployments.",
-      "# Required for price=0 while canonical contracts reject zero funding.",
       "# ERC8183_COMMERCE_ADDRESS=",
       "# ERC8183_ROUTER_ADDRESS=",
       "# ERC8183_POLICY_ADDRESS="
@@ -8757,7 +8862,7 @@ function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails, b402
   return `${lines.join("\n")}
 `;
 }
-function renderAgentReadme(name, faces, destination) {
+function renderAgentReadme(name, faces, destination, walletKind2) {
   const proto = faces.join(" + ");
   const mode = recipeModeOf(faces);
   const entry = `src/${entryStemOf(faces)}.ts`;
@@ -8796,8 +8901,7 @@ entrypoint code in \`src/signing.ts\` \u2014 never an LLM-callable tool.
 ${mode === "both" ? filesBoth : mode === "mcp" ? filesMcp : filesA2a}
 ${shared}
 - \`.env.local\` \u2014 Agent secrets; on deploy they are sent to the **operator's**
-  Secrets Manager (the scoped, consented commitment-#2 exception). Use a
-  THROWAWAY testnet wallet \u2014 \`(cd app/agent && bag wallet new)\`.
+  Secrets Manager (the scoped, consented commitment-#2 exception). ${walletKind2 === "altana" ? "Only the\n  bounded session ships (as `ALTANA_SESSION`); tighten it with\n  `bag wallet session grant --force` \u2014 do not create a new wallet." : "Use a\n  THROWAWAY testnet wallet \u2014 `(cd app/agent && bag wallet new)`."}
 
 ## Run locally
 
@@ -9189,8 +9293,8 @@ async function runOnboarding(o) {
     return false;
   }
   const agentRoot2 = path23.join(o.workspaceRoot, APP_DIR, AGENT_PKG);
-  const { envLocalPath: envLocalPath19 } = await import("@bnbagent/studio-runtime/config");
-  setEnvVar(envLocalPath19(agentRoot2), "WALLET_PASSWORD", password);
+  const { envLocalPath: envLocalPath20 } = await import("@bnbagent/studio-runtime/config");
+  setEnvVar(envLocalPath20(agentRoot2), "WALLET_PASSWORD", password);
   const savedCwd = process.cwd();
   const savedPw = process.env.WALLET_PASSWORD;
   let address = null;
@@ -9229,7 +9333,7 @@ async function runOnboarding(o) {
     }
   }
   if (o.storageProvider !== "local") {
-    await onboardIpfsKey(envLocalPath19(agentRoot2), o.ipfsKey);
+    await onboardIpfsKey(envLocalPath20(agentRoot2), o.ipfsKey);
   }
   if (address) {
     await printFaucetHint(o.network, address);
@@ -9363,8 +9467,8 @@ Guide: the bnbagent-studio-using-twak-wallet.md reference (installed by \`bag sk
     process.chdir(savedCwd);
   }
   if (o.storageProvider !== "local") {
-    const { envLocalPath: envLocalPath19 } = await import("@bnbagent/studio-runtime/config");
-    await onboardIpfsKey(envLocalPath19(agentRoot2), o.ipfsKey);
+    const { envLocalPath: envLocalPath20 } = await import("@bnbagent/studio-runtime/config");
+    await onboardIpfsKey(envLocalPath20(agentRoot2), o.ipfsKey);
   }
   if (address) {
     await printFaucetHint(o.network, address);
@@ -9545,7 +9649,22 @@ NOTE \u2014 wallet.kind = "altana" (bounded runtime session):
    \`bag wallet session grant --force\` and redeploy.`
   );
 }
-function printPlatformWalletSuggestion() {
+function printPlatformWalletSuggestion(walletKind2) {
+  if (walletKind2 === "altana") {
+    printOut(
+      `
+NOTE \u2014 destination = "platform" (48h TESTNET TRIAL on the BNB Chain managed platform):
+ \xB7 This is a sandbox, not a production seller \u2014 the runtime is auto-reclaimed at 48h.
+ \xB7 To sign, ONLY the bounded Altana session is transmitted to the operator's
+   Secrets Manager on deploy \u2014 the admin keystore and WALLET_PASSWORD never
+   ship. The session is budget-limited, expiring, and on-chain revocable.
+ \xB7 Want a smaller blast radius? Re-grant a tighter session before deploying \u2014
+       bag wallet session grant --force --budget-u <small> --expiry-days <short>
+   (do NOT run \`bag wallet new\`: a fresh admin keystore breaks the session's
+   [wallet].address anchor and deploy readiness fails).`
+    );
+    return;
+  }
   printOut(
     `
 NOTE \u2014 destination = "platform" (48h TESTNET TRIAL on the BNB Chain managed platform):
@@ -9901,7 +10020,9 @@ function printConfigSummary(agentRoot2) {
   const maxPrice = g(agent, "payments", "erc8183", "max_price");
   const pricingState = erc8183PricingState(erc8183);
   const isFreePrice = pricingState.kind === "free";
-  const contractOverrides = erc8183ContractOverrideState();
+  const contractOverrides = erc8183ContractOverrideState(
+    erc8183ContractEnvForProject(agentRoot2)
+  );
   const storageKind2 = shown(g(agent, "storage", "kind"), "?");
   const storageDesc = storageKind2 === "ipfs" ? "IPFS (durable, public)" : "local disk (offline dev only)";
   const walletKind2 = shown(g(agent, "wallet", "kind"), "evm-local");
@@ -10001,7 +10122,7 @@ function printConfigSummary(agentRoot2) {
         `  pricing   : FREE \u2014 ${weiToU(String(price))} per job; zero token escrow`
       );
       printOut(
-        contractOverrides.mode === "custom" ? "              contracts: custom stack selected (all three address overrides)" : "              contracts: configure all three ERC8183_*_ADDRESS overrides before deploy"
+        contractOverrides.mode === "custom" ? "              contracts: custom stack selected (all three address overrides)" : contractOverrides.mode === "canonical" ? "              contracts: canonical contract stack selected (zero-price supported)" : "              contracts: custom contract overrides are incomplete or invalid; run `bag doctor`"
       );
     } else {
       printOut(
@@ -10039,9 +10160,9 @@ function printConfigSummary(agentRoot2) {
   if (hasErc8183 && !maxPrice && !isFreePrice) {
     todo.push("[payments.erc8183].max_price \u2014 the price clamp ceiling");
   }
-  if (hasErc8183 && isFreePrice && contractOverrides.mode !== "custom") {
+  if (hasErc8183 && isFreePrice && (contractOverrides.mode === "partial" || contractOverrides.mode === "invalid")) {
     todo.push(
-      "ERC8183_COMMERCE_ADDRESS / ROUTER_ADDRESS / POLICY_ADDRESS \u2014 select one zero-price-compatible custom contract stack"
+      "ERC8183_COMMERCE_ADDRESS / ROUTER_ADDRESS / POLICY_ADDRESS \u2014 fix or remove the incomplete custom contract override"
     );
   }
   if (hasX402Seller && !isFreeX402) {
@@ -10307,6 +10428,17 @@ function loadEnvFileForDev(p) {
   if (!isFile10(p)) {
     return;
   }
+  const contractStackOwnedByShell = ERC8183_ADDRESS_OVERRIDE_KEYS.some(
+    (key) => process.env[key] !== void 0
+  );
+  const configuredContractKeys = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => Boolean(process.env[key]?.trim())
+  );
+  if (configuredContractKeys.length > 0 && configuredContractKeys.length < ERC8183_ADDRESS_OVERRIDE_KEYS.length) {
+    throw new Error(
+      `ERC-8183 contract override is incomplete; set all of ${ERC8183_ADDRESS_OVERRIDE_KEYS.join(", ")} or unset all three.`
+    );
+  }
   for (const line of fs25.readFileSync(p, "utf-8").split(/\r?\n/)) {
     if (!line || line.trimStart().startsWith("#")) {
       continue;
@@ -10314,6 +10446,11 @@ function loadEnvFileForDev(p) {
     const m = KEY_LINE_RE.exec(line);
     if (m) {
       const key = m[1];
+      if (contractStackOwnedByShell && ERC8183_ADDRESS_OVERRIDE_KEYS.includes(
+        key
+      )) {
+        continue;
+      }
       const eq = line.indexOf("=");
       const value = eq >= 0 ? line.slice(eq + 1) : "";
       if (value !== "") {
@@ -10552,8 +10689,8 @@ async function cmdDev(opts) {
   const agentDir = path24.join(workspaceRoot, "agent");
   migrateEnvLocal(agentDir);
   migrateKeystoreOutOfCodelocation(agentDir);
-  const { envLocalPath: envLocalPath19 } = await import("@bnbagent/studio-runtime/config");
-  loadEnvFileForDev(envLocalPath19(agentDir));
+  const { envLocalPath: envLocalPath20 } = await import("@bnbagent/studio-runtime/config");
+  loadEnvFileForDev(envLocalPath20(agentDir));
   ensureStoragePath(workspaceRoot);
   const ipfsErr = ipfsPreflight(agentDir);
   if (ipfsErr !== null) {
@@ -10798,7 +10935,7 @@ function networkBanner(agentDir) {
 import * as fs26 from "fs";
 import { createRequire } from "module";
 import * as path25 from "path";
-import { envLocalPath as envLocalPath11, loadStudioToml as loadStudioToml12 } from "@bnbagent/studio-runtime/config";
+import { envLocalPath as envLocalPath12, loadStudioToml as loadStudioToml12 } from "@bnbagent/studio-runtime/config";
 import { pieverseKeyHash as pieverseKeyHash2 } from "@bnbagent/studio-runtime/llm";
 var AGENTCORE_DESCRIPTOR2 = "agentcore/agentcore.json";
 function isFile11(p) {
@@ -10834,7 +10971,10 @@ function runtimeEnvKeys2(agentRoot2) {
   } catch {
     cfg = {};
   }
-  const resolvable = (key) => Boolean(process.env[key] || getEnvVar(envLocalPath11(agentRoot2), key));
+  const contractEnv = erc8183ContractEnvForProject(agentRoot2);
+  const resolvable = (key) => ERC8183_ADDRESS_OVERRIDE_KEYS.includes(
+    key
+  ) ? Boolean(contractEnv[key]) : Boolean(process.env[key] || getEnvVar(envLocalPath12(agentRoot2), key));
   return runtimeEnvKeysCore(cfg, resolvable);
 }
 var require2 = createRequire(import.meta.url);
@@ -11054,7 +11194,7 @@ function studioIgnored(lines) {
 }
 async function checkGitignoreExcludesSecrets(root, _target) {
   const out = [];
-  const ws = path25.dirname(path25.dirname(envLocalPath11(root)));
+  const ws = path25.dirname(path25.dirname(envLocalPath12(root)));
   const gi = path25.join(ws, ".gitignore");
   const lines = gitignoreLines(gi);
   if (lines === null) {
@@ -11160,7 +11300,7 @@ async function checkPieverseKeyHash(root, _target) {
     ];
   }
   const agentRoot2 = agentRootOf(root);
-  const apiKey = getEnvVar(envLocalPath11(agentRoot2), "PIEVERSE_LLM_API_KEY") || process.env.PIEVERSE_LLM_API_KEY;
+  const apiKey = getEnvVar(envLocalPath12(agentRoot2), "PIEVERSE_LLM_API_KEY") || process.env.PIEVERSE_LLM_API_KEY;
   if (!apiKey) return [];
   const configured = String(pvCfg.key_hash).trim().toLowerCase().replace(/^0x/u, "");
   const actual = pieverseKeyHash2(apiKey);
@@ -11177,10 +11317,10 @@ async function checkPieverseKeyHash(root, _target) {
     }
   ];
 }
-function erc8183RailChecks(cfg) {
+function erc8183RailChecks(cfg, env = process.env) {
   const c2 = tableOf2(tableOf2(cfg, "payments"), "erc8183");
   const out = [];
-  const contracts = erc8183ContractOverrideState();
+  const contracts = erc8183ContractOverrideState(env);
   if (contracts.mode === "partial") {
     out.push({
       level: Level.CRITICAL,
@@ -11232,19 +11372,13 @@ function erc8183RailChecks(cfg) {
       }
     });
   } else if (pricing.kind === "free") {
-    if (contracts.mode === "canonical") {
-      out.push({
-        level: Level.CRITICAL,
-        name: "commerce_zero_price_contract_unsupported",
-        message: "ERC-8183 pricing is FREE (zero token escrow), but the canonical contract stack rejects zero funding. Set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together to a zero-price-compatible custom stack.",
-        details: { effective_wei: "0", contract_profile: "canonical" }
-      });
-    } else if (contracts.mode === "custom") {
+    if (contracts.mode === "canonical" || contracts.mode === "custom") {
+      const contractProfile = contracts.mode;
       out.push({
         level: Level.INFO,
         name: "commerce_zero_price_enabled",
-        message: "ERC-8183 pricing is FREE \u2014 buyers fund 0 token units with zero token escrow; a complete custom contract stack is selected.",
-        details: { effective_wei: "0", contract_profile: "custom" }
+        message: `ERC-8183 pricing is FREE \u2014 buyers fund 0 token units with zero token escrow; the ${contractProfile} contract stack is selected.`,
+        details: { effective_wei: "0", contract_profile: contractProfile }
       });
     }
   }
@@ -11405,7 +11539,14 @@ async function checkCommerceReady(root, target) {
   const cfg = loadAgentToml(root);
   const rails = commerceRails(cfg);
   const out = [];
-  if (rails.erc8183) out.push(...erc8183RailChecks(cfg));
+  if (rails.erc8183) {
+    out.push(
+      ...erc8183RailChecks(
+        cfg,
+        erc8183ContractEnvForProject(agentRootOf(root))
+      )
+    );
+  }
   const x402Checks = x402SellerRailChecks(agentRootOf(root), cfg, target);
   if (!rails.erc8183 && rails.x402) {
     for (const check of x402Checks) {
@@ -11510,7 +11651,7 @@ async function checkRuntimeSecretsInjected(root, target) {
   }
   const missing = needed.filter((k) => !present[k]);
   if (missing.length > 0) {
-    const envLocal = envLocalPath11(root);
+    const envLocal = envLocalPath12(root);
     const recoverable = missing.filter(
       (k) => Boolean(process.env[k] || getEnvVar(envLocal, k))
     );
@@ -11688,6 +11829,7 @@ var allChecks = [
   checkTwakCredentialsAvailable,
   checkTwakDockerAvailable,
   // altana-kind checks (every one early-returns for other kinds).
+  checkAltanaCustomContractsUnsupported,
   checkAltanaSessionReady,
   checkAltanaSdkResolvable,
   checkAltanaSessionNotInsideAgent,
@@ -11770,7 +11912,7 @@ function readKeystoreJson(agentRoot2) {
 function readEnvLocal(agentRoot2) {
   const values = {};
   try {
-    const file = envLocalPath12(agentRoot2);
+    const file = envLocalPath13(agentRoot2);
     if (!isFile12(file)) {
       return values;
     }
@@ -11798,14 +11940,19 @@ function collectRuntimeSecretsDetailed(root) {
   const agentRoot2 = findSubProjectRoot8("agent", root) ?? root;
   const secretKeys = runtimeEnvKeys2(agentRoot2);
   const fileValues = readEnvLocal(agentRoot2);
+  const contractEnv = erc8183ContractEnvForProject(agentRoot2);
+  const contractSource = ERC8183_ADDRESS_OVERRIDE_KEYS.some((key) => process.env[key]?.trim()) ? "process.env" : ".studio/.env.local";
   const payload = {};
   const sources = {};
   for (const k of secretKeys) {
     const fromFile = fileValues[k];
-    const v = fromFile || process.env[k];
+    const isContractOverride = ERC8183_ADDRESS_OVERRIDE_KEYS.includes(
+      k
+    );
+    const v = isContractOverride ? contractEnv[k] : fromFile || process.env[k];
     if (v) {
       payload[k] = v;
-      sources[k] = fromFile ? ".studio/.env.local" : "process.env";
+      sources[k] = isContractOverride ? contractSource : fromFile ? ".studio/.env.local" : "process.env";
     }
   }
   const walletKind2 = deployWalletKind(agentRoot2);
@@ -12239,7 +12386,7 @@ function wireCognitoOutputs(workspaceRoot, outputsFile = null) {
   });
   fs28.writeFileSync(acj, `${JSON.stringify(cfg, null, 2)}
 `, "utf-8");
-  const envLocal = envLocalPath13(workspaceRoot);
+  const envLocal = envLocalPath14(workspaceRoot);
   upsertEnv(envLocal, { OAUTH_TOKEN_URL: tokenUrl, OAUTH_SCOPE: scope });
   return {
     discoveryUrl: discovery,
@@ -12833,7 +12980,7 @@ import { BSC_TESTNET_FAUCET_URLS } from "@bnbagent/studio-runtime/networks";
 import * as crypto4 from "crypto";
 import * as fs34 from "fs";
 import * as path33 from "path";
-import { envLocalPath as envLocalPath14 } from "@bnbagent/studio-runtime/config";
+import { envLocalPath as envLocalPath15 } from "@bnbagent/studio-runtime/config";
 import { show } from "@bnbagent/studio-runtime/erc8004";
 import { DEFAULT_RPC, getNetwork as getNetwork8 } from "@bnbagent/studio-runtime/networks";
 import * as walletRt3 from "@bnbagent/studio-runtime/wallet";
@@ -12978,7 +13125,7 @@ async function checkNetworkMatchesChainId(root, _target) {
   return [];
 }
 async function checkRpcUrlSetForRuntime(root, _target) {
-  const envLocal = envLocalPath14(root);
+  const envLocal = envLocalPath15(root);
   if (getEnvVar(envLocal, "RPC_URL")) {
     return [];
   }
@@ -13003,7 +13150,7 @@ async function checkRuntimeRpcReachable(root, _target) {
     return [];
   }
   const expected = getNetwork8(netName).chainId;
-  const configured = process.env.RPC_URL || getEnvVar(envLocalPath14(root), "RPC_URL") || "";
+  const configured = process.env.RPC_URL || getEnvVar(envLocalPath15(root), "RPC_URL") || "";
   const rpcUrl = configured || DEFAULT_RPC[netName] || "";
   if (!rpcUrl) {
     return [];
@@ -13312,6 +13459,8 @@ var criticalChecks = [
   checkPlatformLoggedIn,
   checkPlatformDockerAvailable,
   checkPlatformStorageEndpoint,
+  checkTwakCustomContractsUnsupported,
+  checkAltanaCustomContractsUnsupported,
   checkLocalKeystoreExists,
   checkWalletPasswordEnvSet,
   checkLlmProviderKeySet,
@@ -13753,7 +13902,7 @@ async function runVerify(opts) {
 import * as fs37 from "fs";
 import * as path37 from "path";
 import {
-  envLocalPath as envLocalPath15,
+  envLocalPath as envLocalPath16,
   findSubProjectRoot as findSubProjectRoot15,
   findWorkspaceRoot as findWorkspaceRoot6,
   loadStudioToml as loadStudioToml19
@@ -14508,7 +14657,7 @@ function persistDeploySummary(root, text2) {
       return null;
     }
     const p = path37.join(
-      path37.dirname(envLocalPath15(root)),
+      path37.dirname(envLocalPath16(root)),
       "last-deploy-summary.txt"
     );
     fs37.mkdirSync(path37.dirname(p), { recursive: true });
@@ -15143,10 +15292,10 @@ function writeAgentDeployState(workspaceRoot, arn, record = {}, destination = "s
       patchTomlKv(tomlPath, "deploy", "oauth_discovery_url", discoveryUrl);
     }
     if (tokenUrl) {
-      setEnvVar(envLocalPath16(agentRoot2), "OAUTH_TOKEN_URL", tokenUrl);
+      setEnvVar(envLocalPath17(agentRoot2), "OAUTH_TOKEN_URL", tokenUrl);
     }
     if (scope) {
-      setEnvVar(envLocalPath16(agentRoot2), "OAUTH_SCOPE", scope);
+      setEnvVar(envLocalPath17(agentRoot2), "OAUTH_SCOPE", scope);
     }
     syncDescriptorOauthFacts(workspaceRoot, {
       tokenUrl,
@@ -15883,7 +16032,7 @@ function persistDeploySummary2(root, text2) {
       return null;
     }
     const p = path38.join(
-      path38.dirname(envLocalPath16(root)),
+      path38.dirname(envLocalPath17(root)),
       "last-deploy-summary.txt"
     );
     fs38.mkdirSync(path38.dirname(p), { recursive: true });
@@ -16406,7 +16555,7 @@ import * as fs39 from "fs";
 import * as path39 from "path";
 import { EVMWalletProvider as EVMWalletProvider2 } from "@bnbagent/sdk";
 import {
-  envLocalPath as envLocalPath17,
+  envLocalPath as envLocalPath18,
   findProjectRoot as findProjectRoot4,
   findStudioWorkspaceRoot as findStudioWorkspaceRoot4,
   loadStudioToml as loadStudioToml21
@@ -16515,7 +16664,9 @@ async function cmdDoctor(opts) {
   checks.push(...await checkLlm(data, projectRoot));
   checks.push(...await checkNetwork(data, opts.network));
   checks.push(...checkCurrency(data));
-  checks.push(...checkErc8183Pricing(data));
+  checks.push(
+    ...checkErc8183Pricing(data, erc8183ContractEnvForProject(projectRoot))
+  );
   checks.push(...checkPriceBounds(data));
   checks.push(...checkX402Seller(data, projectRoot));
   checks.push(...checkStorage(data));
@@ -16546,7 +16697,7 @@ function resolveProjectRoot3(argRoot) {
 }
 function runCheckEnv(projectRoot) {
   const agentDir = workspaceLayers(projectRoot) ?? path39.join(projectRoot, "agent");
-  const envPath = envLocalPath17(agentDir);
+  const envPath = envLocalPath18(agentDir);
   printOut(`bag doctor --check-env: ${envPath}`);
   if (!isFile17(envPath)) {
     printOut(`  (no ${path39.basename(envPath)} found \u2014 nothing to report)`);
@@ -16589,8 +16740,8 @@ function workspaceLayers(projectRoot) {
   }
   return null;
 }
-function checkAppMain(projectRootArg) {
-  let projectRoot = projectRootArg;
+function checkAppMain(projectRootArg2) {
+  let projectRoot = projectRootArg2;
   const parent = path39.dirname(projectRoot);
   if (isFile17(path39.join(parent, "agent", "studio.toml"))) {
     projectRoot = parent;
@@ -16687,7 +16838,7 @@ async function checkWallet(projectRoot, data) {
     return checkWalletTwak(walletCfg, projectRoot, data);
   }
   if (walletCfg.kind === "altana") {
-    return checkWalletAltana(walletCfg, projectRoot);
+    return checkWalletAltana(walletCfg, projectRoot, data);
   }
   if (!isLocalEvmWallet(walletCfg)) {
     return [
@@ -16742,8 +16893,18 @@ async function checkWallet(projectRoot, data) {
   }
   return out;
 }
-function checkWalletAltana(walletCfg, projectRoot) {
+function checkWalletAltana(walletCfg, projectRoot, data) {
   const out = [];
+  const contracts = erc8183ContractOverrideState(
+    erc8183ContractEnvForProject(projectRoot)
+  );
+  if (Object.keys(tableOf14(tableOf14(data, "payments"), "erc8183")).length > 0 && contracts.mode === "custom") {
+    out.push({
+      name: "[wallet] Altana contract targets",
+      status: FAIL,
+      detail: "custom ERC-8183 targets are unsupported: this session's permissions and quote-checker approval are tied to the canonical Commerce stack. Remove the ERC8183_*_ADDRESS overrides, or use wallet.kind='evm-local'."
+    });
+  }
   const keystoreDir = anchoredKeystoreDir(projectRoot, walletCfg);
   const address = String(walletCfg.address ?? "").trim();
   if (!address) {
@@ -16960,7 +17121,7 @@ async function checkLlm(data, projectRoot) {
       }
     ];
   }
-  const keyValue = getEnvVar(envLocalPath17(projectRoot), keyEnv) || process.env[keyEnv];
+  const keyValue = getEnvVar(envLocalPath18(projectRoot), keyEnv) || process.env[keyEnv];
   const out = [];
   if (keyValue) {
     out.push({
@@ -17143,7 +17304,7 @@ function checkCurrency(data) {
   }
   return [];
 }
-function checkErc8183Pricing(data) {
+function checkErc8183Pricing(data, env = process.env) {
   const payValue = tableOf14(data, "payments").erc8183;
   if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
     return [];
@@ -17177,7 +17338,7 @@ function checkErc8183Pricing(data) {
       }
     ];
   }
-  const contracts = erc8183ContractOverrideState();
+  const contracts = erc8183ContractOverrideState(env);
   const priceMode = pricing.kind === "free" ? "FREE \u2014 zero token escrow" : `PAID \u2014 effective list price ${pricing.effectivePrice} token base units`;
   if (contracts.mode === "partial") {
     return [
@@ -17206,20 +17367,11 @@ function checkErc8183Pricing(data) {
       }
     ];
   }
-  if (contracts.mode === "custom") {
-    return [
-      {
-        name: "erc8183 pricing",
-        status: PASS,
-        detail: "FREE \u2014 zero token escrow; custom contract stack selected with all three ERC-8183 address overrides."
-      }
-    ];
-  }
   return [
     {
       name: "erc8183 pricing",
-      status: FAIL,
-      detail: "FREE \u2014 zero token escrow, but the canonical ERC-8183 contracts reject zero funding. Set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together to a zero-price-compatible custom stack."
+      status: PASS,
+      detail: contracts.mode === "custom" ? "FREE \u2014 zero token escrow; custom contract stack selected with all three ERC-8183 address overrides." : "FREE \u2014 zero token escrow; canonical contract stack selected with zero-price funding support."
     }
   ];
 }
@@ -17730,13 +17882,13 @@ function resolveEnvPath(fileArg, rootArg) {
     if (!fs40.existsSync(path40.join(root2, "studio.toml"))) {
       return [null, `error: no studio.toml under --project-root ${root2}`];
     }
-    return [envLocalPath(root2), null];
+    return [envLocalPath2(root2), null];
   }
   const root = findProjectRoot();
   if (root === null) {
     return [".env.local", null];
   }
-  const target = envLocalPath(root);
+  const target = envLocalPath2(root);
   let note = null;
   if (path40.dirname(path40.dirname(target)) !== path40.resolve(process.cwd())) {
     note = `\u2192 writing to ${target} (workspace .studio/, where \`bag dev\` reads)`;
@@ -19758,7 +19910,7 @@ import * as fs45 from "fs";
 import * as path47 from "path";
 import { auditedOp as auditedOp4 } from "@bnbagent/studio-runtime/audit";
 import {
-  envLocalPath as envLocalPath18,
+  envLocalPath as envLocalPath19,
   findProjectRoot as findProjectRoot6,
   loadStudioToml as loadStudioToml24
 } from "@bnbagent/studio-runtime/config";
@@ -20048,7 +20200,7 @@ async function cmdSellInit(priceFlag) {
       "utf8"
     );
   }
-  const envPath = envLocalPath18(root);
+  const envPath = envLocalPath19(root);
   for (const key of B402_ENV_KEYS) {
     const existing = getEnvVar(envPath, key);
     if (key === "B402_BASE_URL" && !free && resolveNetwork3(cfg).toLowerCase() === "bsc-testnet" && !process.env.B402_BASE_URL && !existing) {
@@ -20608,7 +20760,7 @@ function buildProgram() {
   return program;
 }
 function cliVersion() {
-  return "0.0.6-alpha.9";
+  return "0.0.6";
 }
 
 // src/cli/updateCheck.ts
@@ -20711,11 +20863,18 @@ async function main(argv) {
     printSetupNudge();
     return 0;
   }
-  autoloadProjectEnv();
+  const explicitProjectRoot = projectRootArg(args);
+  const releaseProjectEnv = autoloadProjectEnv(explicitProjectRoot);
   if (args[0] !== "wallet") {
+    const originalCwd = process.cwd();
     try {
+      if (explicitProjectRoot !== void 0) {
+        process.chdir(explicitProjectRoot);
+      }
       await ensureAltanaSessionLoaded();
     } catch {
+    } finally {
+      process.chdir(originalCwd);
     }
   }
   maybeSyncSkills(args.find((a) => !a.startsWith("-")));
@@ -20738,8 +20897,26 @@ async function main(argv) {
     process.stderr.write(`error: ${msg}
 `);
     return 1;
+  } finally {
+    releaseProjectEnv();
   }
 }
+function projectRootArg(args) {
+  let found;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") break;
+    if (arg === "--project-root") {
+      found = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--project-root=")) {
+      found = arg.slice("--project-root=".length);
+    }
+  }
+  return found;
+}
 function maybeSyncSkills(command) {
   try {
     if (process.env.BAG_NO_SKILL_SYNC) {