@dvmkit/sdk 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/{chunk-EDU6COY2.js → chunk-7AKBC4PW.js}

@@ -1,40 +1,279 @@
+import {
+  connectedTempoAccount,
+  tempoBalanceCheckHint,
+  tempoTokenReference
+} from "./chunk-ANFX5HEG.js";
 import {
   fundingReachableAt,
-  isValidEvmPrivateKey,
   listCredits,
-  loadConfig,
   maxAdvertisedMicro,
   normalizeCreditEndpoint,
   withinAdvertisedTolerance
-} from "./chunk-2K6UXDAN.js";
+} from "./chunk-KSQEFVFJ.js";
+import {
+  costAnchor,
+  formatUsd,
+  formatUsdcMicrounits
+} from "./chunk-5URG56JJ.js";
 import {
   DvmError,
   IDENTITIES_FILE,
   TEMPO_CHANNELS_FILE,
-  costAnchor,
   ensureConfigDir,
-  formatUsd,
   resolveRpcHttpTransportOptions,
   resolveRpcOverride
-} from "./chunk-F2L6KIMD.js";
+} from "./chunk-MKI6OVW4.js";
 import {
   redactUrl,
   redactUrlsInText
 } from "./chunk-FUJ36YDV.js";
 
+// src/lib/cli-identity-store.ts
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import lockfile from "proper-lockfile";
+var DEFAULT_LOCK_STALE_MS = 3e4;
+var DEFAULT_LOCK_RETRIES = 30;
+var DEFAULT_LOCK_RETRY_INTERVAL_MS = 1e3;
+var IDENTITIES_VERSION = 1;
+function identitiesFileExists() {
+  return existsSync(IDENTITIES_FILE);
+}
+function loadIdentities() {
+  if (!existsSync(IDENTITIES_FILE)) return null;
+  const raw = readFileSync(IDENTITIES_FILE, "utf-8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new DvmError(
+      "identities_corrupt",
+      `Identities file at ${IDENTITIES_FILE} is not valid JSON.`,
+      `Restore a backup or delete the file and run 'dvm init'. Underlying error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || !("version" in parsed)) {
+    throw new DvmError(
+      "identities_corrupt",
+      `Identities file at ${IDENTITIES_FILE} is missing a version field.`,
+      "Restore a backup or delete the file and run 'dvm init'."
+    );
+  }
+  const version = parsed.version;
+  if (version !== IDENTITIES_VERSION) {
+    throw new DvmError(
+      "identities_unknown_version",
+      `Unknown identities file version ${String(version)} (this CLI understands version ${String(IDENTITIES_VERSION)}).`,
+      "Upgrade dvm CLI: a newer version wrote this file."
+    );
+  }
+  const identities = parsed.identities;
+  if (typeof identities !== "object" || identities === null || Array.isArray(identities)) {
+    throw new DvmError(
+      "identities_corrupt",
+      `Identities file at ${IDENTITIES_FILE} has a malformed identities map.`,
+      "Restore a backup or delete the file and run 'dvm init'."
+    );
+  }
+  return {
+    version: IDENTITIES_VERSION,
+    identities
+  };
+}
+function saveIdentities(file) {
+  ensureConfigDir();
+  const tmp = `${IDENTITIES_FILE}.tmp`;
+  const data = JSON.stringify(file, null, 2) + "\n";
+  writeFileSync(tmp, data, { mode: 384 });
+  try {
+    renameSync(tmp, IDENTITIES_FILE);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+async function withIdentitiesLock(fn, opts = {}) {
+  ensureConfigDir();
+  const lockPath = `${IDENTITIES_FILE}.lock`;
+  const stale = opts.stale ?? DEFAULT_LOCK_STALE_MS;
+  const retries = opts.retries ?? DEFAULT_LOCK_RETRIES;
+  const interval = opts.retryIntervalMs ?? DEFAULT_LOCK_RETRY_INTERVAL_MS;
+  let release;
+  try {
+    release = await lockfile.lock(IDENTITIES_FILE, {
+      lockfilePath: lockPath,
+      stale,
+      realpath: false,
+      retries: { retries, factor: 1, minTimeout: interval, maxTimeout: interval }
+    });
+  } catch (err) {
+    throw new DvmError(
+      "identities_locked",
+      `Could not acquire the identities lock at ${lockPath} within the retry budget.`,
+      `Another dvm CLI may be writing to ${IDENTITIES_FILE}. Wait a moment and retry. If no other dvm CLI is running, remove ${lockPath} and try again.`,
+      { lock_file: lockPath, underlying: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  try {
+    return await fn();
+  } finally {
+    try {
+      await release();
+    } catch {
+    }
+  }
+}
+function generateIdentity(now = Date.now()) {
+  const { secretKey, publicKey } = schnorr.keygen();
+  return {
+    privkey: bytesToHex(secretKey),
+    pubkey: bytesToHex(publicKey),
+    createdAt: now
+  };
+}
+function deriveIdentityFromPrivkey(privkeyHex, now = Date.now()) {
+  if (!/^[0-9a-f]{64}$/.test(privkeyHex)) {
+    throw new DvmError(
+      "invalid_privkey",
+      "Private key must be 64 lowercase hex characters (32 bytes).",
+      "Generate a fresh one with 'dvm identity create <name>'."
+    );
+  }
+  const privkeyBytes = hexToBytes(privkeyHex);
+  const pubkeyBytes = schnorr.getPublicKey(privkeyBytes);
+  return {
+    privkey: privkeyHex,
+    pubkey: bytesToHex(pubkeyBytes),
+    createdAt: now
+  };
+}
+function bytesToHex(bytes) {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+function hexToBytes(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+// src/lib/cli-identity-resolve.ts
+function resolveSigningIdentity(opts) {
+  if (opts.as !== void 0) {
+    const file2 = loadIdentities();
+    const entry = file2?.identities[opts.as];
+    if (!entry) {
+      throw new DvmError(
+        "auth_required",
+        `No identity named '${opts.as}' is configured.`,
+        availableHint(file2?.identities, "create one with 'dvm identity create <name>'.")
+      );
+    }
+    return {
+      privkey: entry.privkey,
+      pubkey: entry.pubkey,
+      source: { kind: "flag", name: opts.as }
+    };
+  }
+  const envKey = process.env.DVM_IDENTITY_KEY;
+  if (envKey) {
+    const derived = deriveIdentityFromPrivkey(envKey.toLowerCase());
+    return { privkey: derived.privkey, pubkey: derived.pubkey, source: { kind: "env" } };
+  }
+  const file = loadIdentities();
+  const identities = file?.identities ?? {};
+  const names = Object.keys(identities);
+  const configuredDefault = opts.config?.defaultIdentity;
+  if (configuredDefault !== void 0) {
+    if (!Object.hasOwn(identities, configuredDefault)) {
+      throw new DvmError(
+        "auth_required",
+        `Configured default identity '${configuredDefault}' no longer exists.`,
+        availableHint(identities, "set a new default with 'dvm identity use <name>'.")
+      );
+    }
+    const entry = identities[configuredDefault];
+    return {
+      privkey: entry.privkey,
+      pubkey: entry.pubkey,
+      source: { kind: "default", name: configuredDefault }
+    };
+  }
+  if (names.length === 1) {
+    const onlyName = names[0];
+    const entry = identities[onlyName];
+    return {
+      privkey: entry.privkey,
+      pubkey: entry.pubkey,
+      source: { kind: "sole", name: onlyName }
+    };
+  }
+  if (names.length === 0) {
+    throw new DvmError(
+      "auth_required",
+      "This DVM requires a signed request but no caller identity is configured.",
+      "Run 'dvm identity create <name>' (or 'dvm init') to generate one, or pass DVM_IDENTITY_KEY=<hex>."
+    );
+  }
+  throw new DvmError(
+    "auth_required",
+    "Multiple identities are configured but none is selected.",
+    `Pass --as <name>, set a default with 'dvm identity use <name>', or export DVM_IDENTITY_KEY=<hex>. Available: ${names.join(", ")}.`
+  );
+}
+function findSigningIdentityByPubkey(pubkey) {
+  const wanted = pubkey.toLowerCase();
+  const envKey = process.env.DVM_IDENTITY_KEY;
+  if (envKey) {
+    try {
+      const derived = deriveIdentityFromPrivkey(envKey.toLowerCase());
+      if (derived.pubkey === wanted) {
+        return { privkey: derived.privkey, pubkey: derived.pubkey, source: { kind: "env" } };
+      }
+    } catch {
+    }
+  }
+  const identities = loadIdentities()?.identities ?? {};
+  for (const [name, entry] of Object.entries(identities)) {
+    if (entry.pubkey.toLowerCase() === wanted) {
+      return { privkey: entry.privkey, pubkey: entry.pubkey, source: { kind: "pubkey", name } };
+    }
+  }
+  return null;
+}
+function availableHint(identities, suffix) {
+  const names = identities ? Object.keys(identities) : [];
+  if (names.length === 0) return `No identities are configured \u2014 ${suffix}`;
+  return `Available identities: ${names.join(", ")}. ${suffix}`;
+}
+
+// src/lib/shell-quote.ts
+function shellQuoteArg(value) {
+  if (value === "") return "''";
+  if (SAFE_VALUE_RE.test(value)) return value;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+var SAFE_VALUE_RE = /^[a-zA-Z0-9_\-./@:=,+%]+$/;
+
 // src/lib/payment-rails/tempo-channel-store.ts
 import { AsyncLocalStorage } from "async_hooks";
 import { randomUUID } from "crypto";
-import { existsSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "fs";
 import { Session as TempoSession } from "mppx/tempo";
-import lockfile from "proper-lockfile";
+import lockfile2 from "proper-lockfile";
 import { isAddress, zeroAddress } from "viem";
 var TEMPO_CHARGE_PENDING_STALE_MS = 24 * 60 * 60 * 1e3;
 var tempoLockOwner = new AsyncLocalStorage();
 async function withTempoChannelLock(operation) {
   if (tempoLockOwner.getStore()?.active) return operation();
   ensureTempoChannelFile();
-  const release = await lockfile.lock(TEMPO_CHANNELS_FILE, {
+  const release = await lockfile2.lock(TEMPO_CHANNELS_FILE, {
     realpath: false,
     retries: { retries: 20, minTimeout: 25, maxTimeout: 250 }
   });
@@ -191,6 +430,14 @@ function tempoChannelControlledBy(controller, address) {
   const candidate = address.toLowerCase();
   return controller.payer.toLowerCase() === candidate || controller.authorizedSigner.toLowerCase() === candidate;
 }
+async function retireTempoChannel(association) {
+  await createTempoChannelStore({
+    callerPubkey: association.callerPubkey,
+    endpoint: association.endpoint,
+    creditId: association.creditId,
+    operator: association.operator
+  }).delete(association.channelKey);
+}
 async function retireTempoChannelScope(association) {
   await createTempoChannelStore({
     callerPubkey: association.callerPubkey,
@@ -280,7 +527,7 @@ function tryWithTempoChannelLockSync(operation) {
   ensureTempoChannelFile();
   let release;
   try {
-    release = lockfile.lockSync(TEMPO_CHANNELS_FILE, { realpath: false });
+    release = lockfile2.lockSync(TEMPO_CHANNELS_FILE, { realpath: false });
   } catch (error) {
     if (error.code === "ELOCKED") return void 0;
     throw error;
@@ -295,9 +542,9 @@ function tryWithTempoChannelLockSync(operation) {
 }
 function ensureTempoChannelFile() {
   ensureConfigDir();
-  if (existsSync(TEMPO_CHANNELS_FILE)) return;
+  if (existsSync2(TEMPO_CHANNELS_FILE)) return;
   try {
-    writeFileSync(TEMPO_CHANNELS_FILE, `${JSON.stringify(emptyFile(), null, 2)}
+    writeFileSync2(TEMPO_CHANNELS_FILE, `${JSON.stringify(emptyFile(), null, 2)}
 `, {
       mode: 384,
       flag: "wx"
@@ -306,9 +553,9 @@ function ensureTempoChannelFile() {
   }
 }
 function loadFile() {
-  if (!existsSync(TEMPO_CHANNELS_FILE)) return emptyFile();
+  if (!existsSync2(TEMPO_CHANNELS_FILE)) return emptyFile();
   try {
-    const parsed = JSON.parse(readFileSync(TEMPO_CHANNELS_FILE, "utf8"));
+    const parsed = JSON.parse(readFileSync2(TEMPO_CHANNELS_FILE, "utf8"));
     if (parsed.version === 1) return migrateLegacyFile(parsed);
     if (parsed.version !== 2 || !isStringRecord(parsed.values) || !Array.isArray(parsed.associations) || !parsed.associations.every(isTempoChannelAssociation)) {
       throw new Error("unsupported Tempo channel store shape");
@@ -334,8 +581,8 @@ function loadFile() {
 function saveFile(file) {
   ensureConfigDir();
   const tmp = `${TEMPO_CHANNELS_FILE}.${randomUUID()}.tmp`;
-  writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n", { mode: 384 });
-  renameSync(tmp, TEMPO_CHANNELS_FILE);
+  writeFileSync2(tmp, JSON.stringify(file, null, 2) + "\n", { mode: 384 });
+  renameSync2(tmp, TEMPO_CHANNELS_FILE);
 }
 function emptyFile() {
   return { version: 2, values: {}, associations: [], charges: [] };
@@ -397,15 +644,19 @@ function isLegacyTempoChannelAssociation(value) {
   return typeof association.endpoint === "string" && typeof association.callerPubkey === "string" && typeof association.creditId === "string" && typeof association.channelKey === "string" && typeof association.channelId === "string" && typeof association.cumulativeAmount === "string" && typeof association.deposit === "string" && typeof association.chainId === "number" && typeof association.opened === "boolean" && typeof association.updatedAt === "number";
 }
 
-// src/lib/shell-quote.ts
-function shellQuoteArg(value) {
-  if (value === "") return "''";
-  if (SAFE_VALUE_RE.test(value)) return value;
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-var SAFE_VALUE_RE = /^[a-zA-Z0-9_\-./@:=,+%]+$/;
+// src/lib/payment-rails/tempo-session.ts
+import { Credential } from "mppx";
+import { Mppx } from "mppx/client";
+import { Session as TempoSession2 } from "mppx/tempo";
+import { decodeFunctionData, formatUnits, isAddress as isAddress2, zeroAddress as zeroAddress2 } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { Transaction } from "viem/tempo";
 
 // src/lib/rail-labels.ts
+var PAYMENT_RAIL_KEYS = ["cashu", "cashu_p2pk", "x402", "tempo"];
+function isPaymentRailKey(value) {
+  return typeof value === "string" && PAYMENT_RAIL_KEYS.includes(value);
+}
 function fundingRailLabel(rail) {
   switch (rail) {
     case "cashu":
@@ -418,145 +669,80 @@ function fundingRailLabel(rail) {
       return "Tempo stablecoin";
   }
 }
-
-// src/lib/cli-identity-store.ts
-import { schnorr } from "@noble/curves/secp256k1.js";
-import { existsSync as existsSync2, readFileSync as readFileSync2, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
-import lockfile2 from "proper-lockfile";
-var IDENTITIES_VERSION = 1;
-function loadIdentities() {
-  if (!existsSync2(IDENTITIES_FILE)) return null;
-  const raw = readFileSync2(IDENTITIES_FILE, "utf-8");
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new DvmError(
-      "identities_corrupt",
-      `Identities file at ${IDENTITIES_FILE} is not valid JSON.`,
-      `Restore a backup or delete the file and run 'dvm init'. Underlying error: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-  if (typeof parsed !== "object" || parsed === null || !("version" in parsed)) {
-    throw new DvmError(
-      "identities_corrupt",
-      `Identities file at ${IDENTITIES_FILE} is missing a version field.`,
-      "Restore a backup or delete the file and run 'dvm init'."
-    );
-  }
-  const version = parsed.version;
-  if (version !== IDENTITIES_VERSION) {
-    throw new DvmError(
-      "identities_unknown_version",
-      `Unknown identities file version ${String(version)} (this CLI understands version ${String(IDENTITIES_VERSION)}).`,
-      "Upgrade dvm CLI: a newer version wrote this file."
-    );
-  }
-  const identities = parsed.identities;
-  if (typeof identities !== "object" || identities === null || Array.isArray(identities)) {
-    throw new DvmError(
-      "identities_corrupt",
-      `Identities file at ${IDENTITIES_FILE} has a malformed identities map.`,
-      "Restore a backup or delete the file and run 'dvm init'."
-    );
-  }
-  return {
-    version: IDENTITIES_VERSION,
-    identities
-  };
-}
-function deriveIdentityFromPrivkey(privkeyHex, now = Date.now()) {
-  if (!/^[0-9a-f]{64}$/.test(privkeyHex)) {
-    throw new DvmError(
-      "invalid_privkey",
-      "Private key must be 64 lowercase hex characters (32 bytes).",
-      "Generate a fresh one with 'dvm identity create <name>'."
-    );
+function paymentRailLabel(rail) {
+  switch (rail) {
+    case "cashu":
+    case "cashu_p2pk":
+      return "ecash";
+    case "x402":
+      return "x402 stablecoin";
+    case "tempo":
+      return "Tempo stablecoin";
   }
-  const privkeyBytes = hexToBytes(privkeyHex);
-  const pubkeyBytes = schnorr.getPublicKey(privkeyBytes);
-  return {
-    privkey: privkeyHex,
-    pubkey: bytesToHex(pubkeyBytes),
-    createdAt: now
-  };
 }
-function bytesToHex(bytes) {
-  let s = "";
-  for (const b of bytes) s += b.toString(16).padStart(2, "0");
-  return s;
+function probeRailLabel(rail) {
+  return rail === "lightning" ? "Lightning float" : fundingRailLabel(rail);
 }
-function hexToBytes(hex) {
-  const out = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < out.length; i++) {
-    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  return out;
+function railLabelAtSentenceStart(label) {
+  return label === "ecash" ? "Ecash" : label;
 }
 
-// src/lib/cli-identity-resolve.ts
-function findSigningIdentityByPubkey(pubkey) {
-  const wanted = pubkey.toLowerCase();
-  const envKey = process.env.DVM_IDENTITY_KEY;
-  if (envKey) {
-    try {
-      const derived = deriveIdentityFromPrivkey(envKey.toLowerCase());
-      if (derived.pubkey === wanted) {
-        return { privkey: derived.privkey, pubkey: derived.pubkey, source: { kind: "env" } };
-      }
-    } catch {
-    }
+// src/lib/wallet-rail-copy.ts
+function rpcEndpointSuffix(rail) {
+  const url = rail.details?.rpc_url;
+  return typeof url === "string" && url.length > 0 ? ` via ${url}` : "";
+}
+function rpcEndpointLine(rail) {
+  const url = rail.details?.rpc_url;
+  if (typeof url !== "string" || url.length === 0) return null;
+  const source = rail.details?.rpc_source === "override" ? rpcOverrideEnvVar(rail.rail) : null;
+  return `read from ${url} (${source ?? "bundled default"})`;
+}
+function unreachableRailDisplay(rail) {
+  if (rail.error?.code === "x402_unsupported_network") {
+    const network = rail.details?.network;
+    return typeof network === "string" ? `x402 rail is configured for ${network}, a chain it can't settle on.` : "x402 rail is configured for a chain it can't settle on.";
   }
-  const identities = loadIdentities()?.identities ?? {};
-  for (const [name, entry] of Object.entries(identities)) {
-    if (entry.pubkey.toLowerCase() === wanted) {
-      return { privkey: entry.privkey, pubkey: entry.pubkey, source: { kind: "pubkey", name } };
-    }
+  return nwcRejectionDisplay(rail) ?? `${railLabelAtSentenceStart(probeRailLabel(rail.rail))} rail is configured but not reachable.`;
+}
+function nwcRejectionDisplay(rail) {
+  switch (rail.error?.code) {
+    case "float_unauthorized":
+      return "The Lightning wallet no longer recognises this connection \u2014 it looks revoked or expired.";
+    case "float_connection_restricted":
+      return "The Lightning wallet recognises this connection but won't let it do what the agent needs.";
+    default:
+      return null;
   }
-  return null;
 }
-
-// src/lib/payment-rails/tempo-wallet.ts
-var TEMPO_CHAIN_ID = 4217;
-async function connectedTempoAccount() {
-  const config = loadConfig();
-  return tempoAccountFromConfig(config);
-}
-async function deriveTempoAddress(privateKey) {
-  if (!isValidEvmPrivateKey(privateKey)) throw invalidTempoPrivateKey();
-  const { privateKeyToAccount: privateKeyToAccount2 } = await import("viem/accounts");
-  return privateKeyToAccount2(privateKey).address.toLowerCase();
-}
-async function tempoAccountFromConfig(config) {
-  if (config?.tempo?.method !== "tempo") return null;
-  const apiKey = config.tempo.apiKey;
-  if (!apiKey || !isValidEvmPrivateKey(apiKey)) return null;
-  const privateKey = apiKey;
-  const address = await deriveTempoAddress(privateKey);
-  return { privateKey, address };
-}
-function invalidTempoPrivateKey() {
-  return new DvmError(
-    "invalid_api_key",
-    "A Tempo private key must be a valid 0x-prefixed 32-byte hex secp256k1 private key.",
-    "Generate one with `cast wallet new` or `openssl rand -hex 32` (and prepend 0x)."
-  );
+function unreachableRailHint(rail) {
+  if (rail.error?.hint) return rail.error.hint;
+  switch (rail.rail) {
+    case "lightning":
+      return "Re-run 'dvm wallet connect' with the connection string piped in.";
+    case "cashu":
+      return "Check mint health with 'dvm wallet mint-health'.";
+    case "x402":
+      return "Check DVM_X402_RPC_URL, or ensure viem is installed.";
+    case "tempo":
+      return "Check DVM_TEMPO_RPC_URL, or ensure viem is installed.";
+  }
 }
-
-// src/lib/payment-rails/tempo-session.ts
-import { Credential } from "mppx";
-import { Mppx } from "mppx/client";
-import { Session as TempoSession2 } from "mppx/tempo";
-import { decodeFunctionData, formatUnits, isAddress as isAddress2, zeroAddress as zeroAddress2 } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { Transaction } from "viem/tempo";
-
-// src/lib/wallet-rail-copy.ts
 function tempoKeyImportRoutes(opts) {
   const force = opts.replacingConnectedKey ? " --force" : "";
   return `'dvm wallet tempo-connect --key-file <path>${force}', or DVM_TEMPO_KEY=<key> dvm wallet tempo-connect${force}`;
 }
 var TEMPO_EXIT_KEY_MISSING_HINT = `Reconnect that exact key (${tempoKeyImportRoutes({ replacingConnectedKey: false })}) before attempting an on-chain exit.`;
+function rpcOverrideEnvVar(rail) {
+  switch (rail) {
+    case "x402":
+      return "DVM_X402_RPC_URL";
+    case "tempo":
+      return "DVM_TEMPO_RPC_URL";
+    default:
+      return null;
+  }
+}
 
 // src/lib/payment-rails/tempo-session.ts
 function offersTempoCreditSession(menu) {
@@ -810,6 +996,53 @@ function tempoSessionChallengeMicro(challenge) {
   }
   return Number(micro);
 }
+async function createTempoCloseCredential(args) {
+  const entry = await loadTempoChannelEntry(args.association);
+  if (!entry) {
+    throw new DvmError(
+      "tempo_channel_not_found",
+      `The Tempo channel for credit ${args.association.creditId} is missing locally.`,
+      "Use 'dvm wallet tempo-exit <dvm>' only when the channel record is present; otherwise contact the DVM operator with the credit id."
+    );
+  }
+  if (BigInt(args.cumulativeAmountMicro) > entry.cumulativeAmount) {
+    throw new DvmError(
+      "tempo_close_amount_unauthorized",
+      `The DVM asked to close this Tempo channel at $${formatUsdcMicrounits(BigInt(args.cumulativeAmountMicro))}, above the $${formatUsdcMicrounits(entry.cumulativeAmount)} this wallet has authorized on it.`,
+      `No credential was signed and nothing is stranded: run 'dvm wallet tempo-exit <dvm>' to recover the channel's unsettled balance on-chain, and tell the DVM's operator that its close request exceeded the caller's authorization.`
+    );
+  }
+  const durableStore = createTempoChannelStore({
+    endpoint: args.association.endpoint,
+    callerPubkey: args.association.callerPubkey,
+    creditId: args.association.creditId,
+    operator: args.association.operator
+  });
+  const method = TempoSession2.Client.session({
+    account: privateKeyToAccount(args.account.privateKey),
+    // mppx normally deletes a channel as soon as it signs a manual close.
+    // The credential has not reached the DVM at that point, so keep the
+    // unilateral-exit record until wallet tempo-exit independently confirms the
+    // cooperative close on-chain and retires it.
+    channelStore: {
+      get: (key) => durableStore.get(key),
+      set: (next) => durableStore.set(next),
+      delete: () => void 0
+    },
+    ...args.getClient ? { getClient: args.getClient } : {}
+  });
+  return method.createCredential({
+    challenge: args.challenge,
+    context: {
+      action: "close",
+      descriptor: entry.descriptor,
+      cumulativeAmountRaw: String(args.cumulativeAmountMicro)
+    }
+  });
+}
+async function advanceTempoChannelExit(args) {
+  return withTempoChannelLock(() => advanceTempoChannelExitLocked(args));
+}
 async function reconcileTempoChannelOnChain(args) {
   const { association } = args;
   const unread = {
@@ -850,6 +1083,168 @@ async function reconcileTempoChannelOnChain(args) {
     return { ...read, retired: false, error: asTempoReadError(err) };
   }
 }
+async function advanceTempoChannelExitLocked(args) {
+  const association = loadTempoChannelAssociation(
+    args.association.endpoint,
+    args.association.callerPubkey,
+    args.association.creditId
+  );
+  if (association?.channelId.toLowerCase() !== args.association.channelId.toLowerCase()) {
+    throw new DvmError(
+      "tempo_channel_not_found",
+      `No local Tempo channel entry remains for credit ${args.association.creditId}.`
+    );
+  }
+  const entry = await loadTempoChannelEntry(association);
+  if (!entry) {
+    if (args.abandon) {
+      await retireTempoChannel(association);
+      return {
+        status: "abandoned",
+        descriptorMissing: true,
+        channelId: association.channelId
+      };
+    }
+    throw new DvmError(
+      "tempo_channel_not_found",
+      `The Tempo channel record for credit ${association.creditId} has no stored descriptor.`,
+      `Run 'dvm wallet tempo-exit ${association.endpoint} --abandon' to retire this unusable local record. Nothing will be broadcast, because there is no descriptor from which to address the escrow.`
+    );
+  }
+  const identity = { channelId: entry.channelId, channelToken: entry.descriptor.token };
+  const account = args.account;
+  const controller = tempoDescriptorController(entry.descriptor);
+  if (account && controller && !tempoChannelControlledBy(controller, account.address)) {
+    if (!args.abandon) throw foreignChannelExitError(association, controller, account);
+    await retireTempoChannelScope(association);
+    return {
+      status: "abandoned",
+      foreignPayer: controller.payer,
+      channelId: association.channelId
+    };
+  }
+  const rpc = await resolveTempoExitRpc(entry.chainId);
+  const client = args.client ?? (account ? await tempoWalletClient(account, rpc) : await tempoPublicClient(rpc));
+  const chain = redactingExitChain(
+    args.chain ?? TempoSession2.Precompile.Chain,
+    rpc,
+    entry.descriptor.token
+  );
+  let state = await chain.getChannelState(client, entry.channelId, entry.escrow);
+  const amounts = () => {
+    const authorized = entry.cumulativeAmount > state.settled ? entry.cumulativeAmount : state.settled;
+    return {
+      depositMicro: Number(state.deposit),
+      settledMicro: Number(state.settled),
+      guaranteedMicro: Number(state.deposit > authorized ? state.deposit - authorized : 0n),
+      // Clamped because the escrow zeroes a withdrawn channel's deposit while
+      // keeping its settled total, so a closed channel reads deposit 0 against
+      // a positive settled and the raw subtraction goes negative.
+      likelyMicro: Number(state.deposit > state.settled ? state.deposit - state.settled : 0n)
+    };
+  };
+  if (state.deposit === 0n) {
+    if (classifyTempoChannelState(entry, state) === "closed") {
+      await retireTempoChannelScope(association);
+      return { status: "already_closed", ...identity, ...amounts() };
+    }
+    if (args.abandon) {
+      await retireTempoChannel(association);
+      return { status: "abandoned", ...identity, ...amounts() };
+    }
+    return { status: "unconfirmed", ...identity, ...amounts() };
+  }
+  if (args.abandon) {
+    throw new DvmError(
+      "tempo_channel_on_chain",
+      `The Tempo channel for credit ${association.creditId} holds $${formatUsdcMicrounits(state.deposit)} on-chain, so its record cannot be abandoned.`,
+      account ? `Run 'dvm wallet tempo-exit' without --abandon to close it and recover the collateral.` : `No Tempo key is connected, so this record could not be checked against one. Reconnect the key that opened this channel (${tempoKeyImportRoutes({ replacingConnectedKey: false })}) and run 'dvm wallet tempo-exit' without --abandon to recover the collateral. Retiring the record is offered only once a connected key shows the channel is not this wallet's.`
+    );
+  }
+  if (!account) throw tempoExitKeyMissingError();
+  const exitAccount = privateKeyToAccount(account.privateKey);
+  const transactionOptions = {
+    account: exitAccount,
+    feePayer: exitAccount,
+    candidateFeeTokens: [entry.descriptor.token]
+  };
+  if (state.closeRequestedAt === 0) {
+    const hash2 = await chain.requestCloseOnChain(
+      client,
+      entry.descriptor,
+      entry.escrow,
+      transactionOptions
+    );
+    await chain.waitForSuccessfulReceipt(client, hash2);
+    state = await chain.getChannelState(client, entry.channelId, entry.escrow);
+    return {
+      status: "close_requested",
+      ...identity,
+      transactionHash: hash2,
+      withdrawAvailableAt: (state.closeRequestedAt + 900) * 1e3,
+      ...amounts()
+    };
+  }
+  const withdrawAvailableAt = state.closeRequestedAt + 900;
+  const now = args.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (now < withdrawAvailableAt) {
+    return {
+      status: "waiting",
+      ...identity,
+      withdrawAvailableAt: withdrawAvailableAt * 1e3,
+      ...amounts()
+    };
+  }
+  const withdrawnAmounts = amounts();
+  const hash = await chain.withdrawOnChain(
+    client,
+    entry.descriptor,
+    entry.escrow,
+    transactionOptions
+  );
+  await chain.waitForSuccessfulReceipt(client, hash);
+  state = await chain.getChannelState(client, entry.channelId, entry.escrow);
+  await retireTempoChannelScope(association);
+  return {
+    status: "withdrawn",
+    ...identity,
+    transactionHash: hash,
+    ...withdrawnAmounts
+  };
+}
+function foreignChannelExitError(association, controller, account) {
+  const abandon = [
+    "dvm wallet tempo-exit",
+    shellQuoteArg(association.endpoint),
+    "--credit-id",
+    shellQuoteArg(association.creditId),
+    "--abandon"
+  ].join(" ");
+  return new DvmError(
+    "tempo_wallet_mismatch",
+    `The connected Tempo key ${account.address} is not the wallet recorded for the channel with ${association.endpoint} \u2014 that channel was opened by ${controller.payer}.`,
+    // `--force` is live here and only here among the exit refusals: reaching
+    // this error took a connected `account`, so the reconnect is a replacement
+    // the import refuses without it (internal-review).
+    `Nothing was signed or broadcast, and the channel's collateral is untouched \u2014 only ${controller.payer} can move it. Reconnect that exact key (${tempoKeyImportRoutes({ replacingConnectedKey: true })}) and retry, or run '${abandon}' to retire the local record. Retiring it discards this machine's only descriptor for that channel, so restoring the key afterwards would no longer recover the collateral; the record blocks nothing while it stands.`,
+    {
+      anchor: "tempo_channel_payer_mismatch",
+      endpoint: association.endpoint,
+      credit_id: association.creditId,
+      channel_id: association.channelId,
+      recorded_payer: controller.payer,
+      recorded_authorized_signer: controller.authorizedSigner,
+      connected_payer: account.address
+    }
+  );
+}
+function tempoExitKeyMissingError() {
+  return new DvmError(
+    "tempo_wallet_missing",
+    "The Tempo key that controls this channel is not connected.",
+    TEMPO_EXIT_KEY_MISSING_HINT
+  );
+}
 async function readTempoChannelState(args) {
   const entry = await loadTempoChannelEntry(args.association);
   if (!entry) {
@@ -927,6 +1322,18 @@ async function tempoPublicClient(rpc) {
     transport: transportOptions ? http(rpc.url, transportOptions) : http(rpc.url)
   });
 }
+async function tempoWalletClient(account, rpc) {
+  const { createWalletClient, http } = await import("viem");
+  const transportOptions = resolveRpcHttpTransportOptions(
+    rpc.source,
+    process.env.DVM_TEMPO_RPC_HEADERS_JSON
+  );
+  return createWalletClient({
+    account: privateKeyToAccount(account.privateKey),
+    chain: rpc.chain,
+    transport: transportOptions ? http(rpc.url, transportOptions) : http(rpc.url)
+  });
+}
 function readSessionDeposit(credential) {
   let payload;
   try {
@@ -1017,6 +1424,182 @@ function isTransportFailure(err) {
   }
   return transport;
 }
+function redactingExitChain(chain, rpc, token) {
+  const guard = async (run) => {
+    try {
+      return await run();
+    } catch (err) {
+      if (err instanceof DvmError) throw err;
+      const cause = redactUrlsInText(err instanceof Error ? err.message : String(err));
+      if (!isTransportFailure(err)) {
+        throw new DvmError(
+          "tempo_exit_failed",
+          `Tempo channel exit failed: ${cause}`,
+          `This failed on-chain rather than in transit, so changing DVM_TEMPO_RPC_URL will not help \u2014 a transaction the escrow rejected reads like this, and so does one this wallet cannot pay for. The exit is caller-paid and Tempo charges its fees in a stablecoin rather than a separate gas token, so check that the wallet holds a spendable balance of ${tempoTokenReference(token)} outside the channel. ${tempoBalanceCheckHint(token)} Then re-run 'dvm wallet tempo-exit' \u2014 it re-reads the chain and resumes from wherever the channel actually is. If it fails the same way with the wallet funded, the escrow is refusing the exit and the channel needs a closer look.`
+        );
+      }
+      throw new DvmError(
+        "tempo_rpc_error",
+        `Tempo channel exit failed: ${cause}`,
+        // Which knob is the caller's to turn depends on whose endpoint this was.
+        rpc.source === "override" ? `DVM_TEMPO_RPC_URL sent this exit to ${redactUrl(rpc.url)}. Correct it, or unset it to fall back to Tempo's bundled endpoint, then re-run 'dvm wallet tempo-exit' \u2014 it re-reads the chain and resumes from wherever the channel actually is.` : `Verify connectivity to Tempo's bundled endpoint (${redactUrl(rpc.url)}), or send the exit somewhere else with DVM_TEMPO_RPC_URL, then re-run 'dvm wallet tempo-exit' \u2014 it re-reads the chain and resumes from wherever the channel actually is.`
+      );
+    }
+  };
+  return {
+    getChannelState: (...args) => guard(() => chain.getChannelState(...args)),
+    requestCloseOnChain: (...args) => guard(() => chain.requestCloseOnChain(...args)),
+    waitForSuccessfulReceipt: (...args) => guard(() => chain.waitForSuccessfulReceipt(...args)),
+    withdrawOnChain: (...args) => guard(() => chain.withdrawOnChain(...args))
+  };
+}
+
+// src/lib/payment-rails/tempo-lifecycle.ts
+async function assertTempoWalletIdle(intent) {
+  const connected = await connectedTempoAccount();
+  if (!connected) return;
+  const records = await ownedTempoChannelRecords(connected.address);
+  const verdicts = await Promise.all(
+    records.map(async (association) => ({
+      association,
+      chain: await reconcileTempoChannelOnChain({ association })
+    }))
+  );
+  let blocker;
+  for (const status of BLOCKING_ORDER) {
+    blocker = verdicts.find((verdict) => verdict.chain.status === status);
+    if (blocker) break;
+  }
+  if (!blocker) return;
+  const blocking = verdicts.filter((verdict) => verdict.chain.status !== "closed").length;
+  throw blocker.chain.status === "unreadable" ? blocker.chain.error?.code === "tempo_channel_not_found" ? descriptorlessChannelError(blocker.association, blocker.chain, intent, blocking) : unreadableChainError(blocker.association, blocker.chain, intent, blocking) : liveChannelError(blocker.association, blocker.chain, intent, blocking);
+}
+async function ownedTempoChannelRecords(address) {
+  const records = listTempoChannelAssociations();
+  const controlled = await Promise.all(
+    records.map(
+      async (association) => tempoChannelControlledBy(
+        await loadTempoChannelController(association).catch(() => void 0),
+        address
+      )
+    )
+  );
+  return records.filter((_, index) => controlled[index]);
+}
+var BLOCKING_ORDER = ["open", "closing", "unconfirmed", "unreadable"];
+function liveChannelError(association, chain, intent, blocking) {
+  const depositMicro = chain.status === "unconfirmed" ? Number(association.deposit) : chain.depositMicro;
+  const amount = `$${formatUsdcMicrounits(BigInt(depositMicro))}`;
+  const message = chain.status === "open" ? `The connected Tempo key still holds ${amount} of collateral in an open channel with ${association.endpoint}.` : chain.status === "closing" ? `The connected Tempo key has ${amount} still escrowed on its channel with ${association.endpoint}, where a close has been requested on-chain and is in its 15-minute grace period.` : `The connected Tempo key signed an open committing ${amount} to a channel with ${association.endpoint} that the escrow has no record of, so that collateral may or may not be locked.`;
+  const caller = findSigningIdentityByPubkey(association.callerPubkey);
+  if (!caller) {
+    return new DvmError(
+      "tempo_channels_active",
+      message,
+      `Only this key can close that channel, but its caller identity (${association.callerPubkey}) is no longer configured. Restore that identity first, then retry the wallet ${intent === "replace" ? "replacement" : "disconnect"}; the key and channel record were left untouched.${remainingClause(blocking)}`,
+      channelData(association, chain, depositMicro, blocking)
+    );
+  }
+  const identityName = caller.source.kind === "env" ? void 0 : caller.source.name;
+  const selectors = { creditId: association.creditId, identityName };
+  const exit = tempoExitCommand(association.endpoint, selectors);
+  const abandon = tempoExitCommand(association.endpoint, selectors, true);
+  const fund = creditCommand("fund", association.endpoint, selectors);
+  const remedy = chain.status === "open" ? (
+    // The endpoint can hold several credits and caller identities. Both
+    // selectors keep every remedy pointed at the channel just named.
+    `Empty the channel first \u2014 '${creditCommand("drain", association.endpoint, selectors)}' for the cooperative exit, or '${exit}' if the DVM is unavailable`
+  ) : chain.status === "closing" ? `'${exit}' withdraws what remains once the grace period ends` : `'${exit}' reads the chain and says which it is, and '${fund}' resumes a funding still pending for it. Once that open is known never to have landed, '${abandon}' retires the record`;
+  return new DvmError(
+    "tempo_channels_active",
+    message,
+    `Only this key can close that channel. ${remedy} \u2014 and ${intentClause(intent)}.${remainingClause(blocking)}`,
+    channelData(association, chain, depositMicro, blocking)
+  );
+}
+function tempoExitCommand(endpoint, selectors, abandon = false) {
+  const parts = [
+    "dvm wallet tempo-exit",
+    shellQuoteArg(endpoint),
+    "--credit-id",
+    shellQuoteArg(selectors.creditId)
+  ];
+  if (selectors.identityName !== void 0) {
+    parts.push("--as", shellQuoteArg(selectors.identityName));
+  }
+  if (abandon) parts.push("--abandon");
+  return parts.join(" ");
+}
+function creditCommand(verb, endpoint, selectors) {
+  const parts = [
+    `dvm credit ${verb}`,
+    shellQuoteArg(endpoint),
+    "--credit-id",
+    shellQuoteArg(selectors.creditId)
+  ];
+  if (selectors.identityName !== void 0) {
+    parts.push("--as", shellQuoteArg(selectors.identityName));
+  }
+  return parts.join(" ");
+}
+function unreadableChainError(association, chain, intent, blocking) {
+  const cause = chain.error;
+  return new DvmError(
+    cause?.code ?? "tempo_chain_read_failed",
+    `The Tempo channel with ${association.endpoint} could not be read, so there is no way to show it is empty: ${cause?.message ?? "the chain read failed"}`,
+    `The Tempo key is untouched, and the local channel record was kept \u2014 it is the only route back to any collateral the escrow does hold. ${cause?.hint ? `${cause.hint} Then ${intentClause(intent)}.` : `Restore the chain read, then ${intentClause(intent)}.`}${remainingClause(blocking)}`,
+    channelData(association, chain, Number(association.deposit), blocking)
+  );
+}
+function descriptorlessChannelError(association, chain, intent, blocking) {
+  const message = `The saved Tempo channel with ${association.endpoint} has no stored descriptor, so its escrow state cannot be read or closed from this machine.`;
+  const data = {
+    ...channelData(association, chain, Number(association.deposit), blocking),
+    anchor: "tempo_channel_descriptor_missing"
+  };
+  const caller = findSigningIdentityByPubkey(association.callerPubkey);
+  if (!caller) {
+    return new DvmError(
+      "tempo_channel_not_found",
+      message,
+      `The caller identity that owns this record (${association.callerPubkey}) is no longer configured. Restore that identity first, then retire the descriptor-less record; the Tempo key and record were left untouched.${remainingClause(blocking)}`,
+      data
+    );
+  }
+  const identityName = caller.source.kind === "env" ? void 0 : caller.source.name;
+  const abandon = tempoExitCommand(
+    association.endpoint,
+    { creditId: association.creditId, identityName },
+    true
+  );
+  return new DvmError(
+    "tempo_channel_not_found",
+    message,
+    `Run '${abandon}' to retire this unusable local record without broadcasting anything, then ${intentClause(intent)}.${remainingClause(blocking)}`,
+    data
+  );
+}
+function channelData(association, chain, depositMicro, blocking) {
+  return {
+    anchor: "tempo_channel_live",
+    endpoint: association.endpoint,
+    credit_id: association.creditId,
+    channel_id: association.channelId,
+    chain_id: association.chainId,
+    chain_status: chain.status,
+    deposit_micro: depositMicro,
+    ...chain.status === "unreadable" ? {} : { settled_micro: chain.settledMicro },
+    // How many records are still in the way, so an agent knows whether clearing
+    // the one named above is the whole job.
+    blocking_channels: blocking
+  };
+}
+function remainingClause(blocking) {
+  return blocking > 1 ? ` ${blocking - 1} other recorded channel${blocking > 2 ? "s" : ""} still ${blocking > 2 ? "block" : "blocks"} this too \u2014 'dvm wallet balance' lists them all with what the escrow says about each.` : "";
+}
+function intentClause(intent) {
+  return intent === "replace" ? "retry the replacement" : "retry 'dvm wallet tempo-disconnect'";
+}
 
 export {
   TEMPO_CHARGE_PENDING_STALE_MS,
@@ -1032,10 +1615,28 @@ export {
   listResumableTempoChargeFundings,
   clearPendingTempoChargeFunding,
   shellQuoteArg,
+  isPaymentRailKey,
   fundingRailLabel,
+  paymentRailLabel,
+  probeRailLabel,
+  railLabelAtSentenceStart,
+  rpcEndpointSuffix,
+  rpcEndpointLine,
+  unreachableRailDisplay,
+  nwcRejectionDisplay,
+  unreachableRailHint,
+  tempoKeyImportRoutes,
+  TEMPO_EXIT_KEY_MISSING_HINT,
+  IDENTITIES_VERSION,
+  identitiesFileExists,
+  loadIdentities,
+  saveIdentities,
+  withIdentitiesLock,
+  generateIdentity,
+  deriveIdentityFromPrivkey,
+  resolveSigningIdentity,
   findSigningIdentityByPubkey,
-  TEMPO_CHAIN_ID,
-  connectedTempoAccount,
+  assertTempoWalletIdle,
   offersTempoCreditSession,
   offersTempoCreditCharge,
   withholdsTempoCreditSession,
@@ -1053,5 +1654,8 @@ export {
   assertTempoSessionVoucherWithinAsk,
   persistTempoOpenCredential,
   tempoSessionChallenge,
+  tempoSessionChallengeMicro,
+  createTempoCloseCredential,
+  advanceTempoChannelExit,
   reconcileTempoChannelOnChain
 };