@fibscope/agent 0.1.0

package/index.mjs

@@ -0,0 +1,3244 @@
+#!/usr/bin/env node
+
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  addressToScript,
+  blake160,
+  blake2b,
+  bytesToHex,
+  calculateTransactionFee,
+  ECPair,
+  EMPTY_SECP_SIG,
+  getTransactionSize,
+  hexToBytes,
+  PERSONAL,
+  privateKeyToAddress,
+  privateKeyToPublicKey,
+  rawTransactionToHash,
+  serializeWitnessArgs,
+  scriptToAddress,
+  systemScripts,
+  toUint64Le,
+} from "@nervosnetwork/ckb-sdk-utils";
+import { collectFiberStateReport } from "./lib/pulse/engine.mjs";
+import { createTelemetryCollector } from "./lib/observe/collector.mjs";
+import { recommend } from "./lib/bridge/recommendation.mjs";
+import { virtualizePayment } from "./lib/route/route.mjs";
+import { chooseFnnInstance, describeFnnInstance, discoverFnnInstances, rpcResponds } from "./lib/fnn-discovery.mjs";
+
+const AGENT_VERSION = "0.1.0";
+const DEFAULT_CONFIG_PATH = ".fiber/agent.json";
+const DEFAULT_STATUS_PATH = ".fiber/agent-status.json";
+const DEFAULT_PUSH_INTERVAL_MS = 15_000;
+const MAX_BACKOFF_MS = 300_000;
+const DEFAULT_PULSE_MODULE = new URL("./lib/pulse/index.mjs", import.meta.url).href;
+const DEFAULT_FNN_PREFLIGHT_TIMEOUT_MS = 2_500;
+const DEFAULT_REPORT_URL = "https://ejchwtvdxpyojxsursmh.supabase.co/functions/v1/fibscope-gateway/agent/v1/report";
+const AGENT_ENV_PATHS = [resolve("agent/.env"), resolve(".env")];
+const ENV_REPORT_URL = "FIBGATE";
+const ENV_REPORT_URL_ALIAS = "FIBSCOPE_AGENT_REPORT_URL";
+const ENV_AGENT_TOKEN = "FIBKEY";
+const ENV_AGENT_TOKEN_ALIAS = "FIBSCOPE_AGENT_TOKEN";
+const ENV_CKB_RPC_URL = "FIBCKB";
+const ENV_WALLET_PATH = "FIBWALLET";
+const DEFAULT_COMMAND_POLL_MS = 5_000;
+const DEFAULT_KNOWN_PEER_RECONNECT_MS = 60_000;
+const DEFAULT_CHANNEL_FUNDING_CKB = "499";
+const DEFAULT_CHANNEL_FUNDING_RESERVE_SHANNONS = 100_000n;
+const DEFAULT_CHANNEL_OPEN_TIMEOUT_MS = 60_000;
+const DEFAULT_CHANNEL_OPEN_RETRY_MS = 2_000;
+const DEFAULT_CHANNEL_FAILURE_WATCH_MS = 45_000;
+const DEFAULT_CHANNEL_FAILURE_POLL_MS = 3_000;
+const MIN_SECP_CELL_CAPACITY = 61n * 100_000_000n;
+const DEFAULT_PAYOUT_FEE_RATE = 1_000n;
+const SECP256K1_ORDER = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
+const SIGHASH_CODE_HASH = "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8";
+const inferredPeerAddressCache = new Map();
+
+loadAgentEnv();
+
+export async function init(options = {}) {
+  const configPath = resolve(options.config ?? DEFAULT_CONFIG_PATH);
+  const existing = existsSync(configPath) ? await readJson(configPath) : {};
+  const terminal = createInterface({ input, output });
+  try {
+    const discoveredRpcUrl = await discoverAgentRpcUrl(existing.fiberRpcUrl ?? process.env.FIBSCOPE_AGENT_FIBER_RPC_URL, {
+      prompt: (label) => terminal.question(label),
+    });
+    const reportUrl = resolveReportUrl(existing);
+    const reportUrlOverride = configuredReportUrl(existing);
+    const agentToken = await prompt(terminal, "Agent token", existing.agentToken ?? envValue(ENV_AGENT_TOKEN, ENV_AGENT_TOKEN_ALIAS) ?? "");
+    const chain = await prompt(terminal, "Chain", existing.chain ?? process.env.FIBSCOPE_AGENT_CHAIN ?? "testnet");
+    const fiberRpcUrl = await prompt(terminal, "Local Fiber RPC URL", discoveredRpcUrl ?? existing.fiberRpcUrl ?? process.env.FIBSCOPE_AGENT_FIBER_RPC_URL ?? "http://127.0.0.1:8227");
+    const pushIntervalMs = Number(await prompt(terminal, "Push interval ms", String(existing.pushIntervalMs ?? process.env.FIBSCOPE_AGENT_PUSH_INTERVAL_MS ?? DEFAULT_PUSH_INTERVAL_MS)));
+    const commandPollMs = Number(await prompt(terminal, "Command poll ms", String(existing.commandPollMs ?? process.env.FIBSCOPE_AGENT_COMMAND_POLL_MS ?? DEFAULT_COMMAND_POLL_MS)));
+    const publicProfileDefault = (existing.publicProfileEnabled ?? yes(process.env.FIBSCOPE_AGENT_PUBLIC_PROFILE)) ? "y" : "n";
+    const publicProfileEnabled = yes(await prompt(terminal, "Enable public profile? (y/n)", publicProfileDefault));
+    const overwriteNodeDefault = (existing.overwriteNodeRegistration ?? yes(process.env.FIBSCOPE_AGENT_OVERWRITE_NODE_REGISTRATION)) ? "y" : "n";
+    const overwriteNodeRegistration = yes(await prompt(terminal, "Allow this API key to replace a previously registered node? (y/n)", overwriteNodeDefault));
+    const config = {
+      ...(reportUrlOverride ? { reportUrl } : {}),
+      agentToken,
+      chain,
+      fiberRpcUrl,
+      pushIntervalMs: Number.isFinite(pushIntervalMs) && pushIntervalMs > 0 ? pushIntervalMs : DEFAULT_PUSH_INTERVAL_MS,
+      commandPollMs: Number.isFinite(commandPollMs) && commandPollMs > 0 ? commandPollMs : DEFAULT_COMMAND_POLL_MS,
+      publicProfileEnabled,
+      overwriteNodeRegistration,
+      publicFields: existing.publicFields ?? {
+        node: true,
+        peers: true,
+        channels: true,
+        liquidity: true,
+        diagnostics: true,
+        health: true,
+        metrics: true,
+        alerts: true,
+      },
+    };
+    await writeJson(configPath, await enrichConfigFromMatchingFnn(config));
+    console.log(`Agent config written to ${configPath}`);
+    console.log(`Fibscope endpoint: ${reportUrlOverride ? reportUrl : "built in"}`);
+    return config;
+  } finally {
+    terminal.close();
+  }
+}
+
+export async function once(options = {}) {
+  const runtime = await createRuntime(options);
+  await runtime.rehydrateKnownPeers({ force: true }).catch(() => undefined);
+  const report = await runtime.collect();
+  let registration;
+  try {
+    registration = await runtime.register(report);
+  } catch (error) {
+    await runtime.writeStatus({
+      running: false,
+      remoteConfig: runtime.remoteConfig,
+      lastCollectionAt: report.collectedAt,
+      lastRegistrationStatus: "failed",
+      lastRegistrationError: message(error),
+      retainedReport: true,
+    });
+    throw error;
+  }
+  const result = await pushWithRegistrationRetry(runtime, report);
+  await runtime.writeStatus({
+    running: false,
+    remoteConfig: runtime.remoteConfig,
+    lastCollectionAt: report.collectedAt,
+    lastRegistrationAt: registration?.node?.lastRegisteredAt ?? Date.now(),
+    lastRegistrationStatus: "ok",
+    lastRegistrationError: undefined,
+    lastRegisteredNodeId: registration?.node?.nodeId,
+    lastPushAt: result.ok ? Date.now() : undefined,
+    lastPushStatus: result.ok ? "ok" : result.code === "NODE_REGISTRATION_REQUIRED" ? "registration_required" : "failed",
+    lastPushError: result.ok ? undefined : result.error,
+    retainedReport: result.ok ? false : true,
+  });
+  if (!result.ok) {
+    throw new Error(`Agent push failed: ${result.error}`);
+  }
+  console.log(JSON.stringify({ ok: true, collectedAt: report.collectedAt, status: result.status }, null, 2));
+  return result;
+}
+
+export async function start(options = {}) {
+  const runtime = await createRuntime(options);
+  let retainedReport = undefined;
+  let collectionInFlight = false;
+  let transmissionInFlight = false;
+  let commandInFlight = false;
+  let knownPeerInFlight = false;
+  let lastKnownPeerHydrationAt = 0;
+  let backoffMs = 1_000;
+  let stopped = false;
+  let lastCommandPollError;
+
+  const collectTick = async () => {
+    if (collectionInFlight) return;
+    collectionInFlight = true;
+    try {
+      const report = await runtime.collect();
+      retainedReport = undefined;
+      let registration;
+      try {
+        registration = await runtime.register(report);
+      } catch (error) {
+        await runtime.writeStatus({
+          running: true,
+          remoteConfig: runtime.remoteConfig,
+          lastCollectionAt: report.collectedAt,
+          lastRegistrationStatus: "failed",
+          lastRegistrationError: message(error),
+          retainedReport: false,
+        });
+        return;
+      }
+      retainedReport = report;
+      await runtime.writeStatus({
+        running: true,
+        remoteConfig: runtime.remoteConfig,
+        lastCollectionAt: retainedReport.collectedAt,
+        lastRegistrationAt: registration?.node?.lastRegisteredAt ?? Date.now(),
+        lastRegistrationStatus: "ok",
+        lastRegistrationError: undefined,
+        lastRegisteredNodeId: registration?.node?.nodeId,
+        retainedReport: true,
+      });
+    } catch (error) {
+      await runtime.writeStatus({
+        running: true,
+        lastCollectionError: message(error),
+      });
+    } finally {
+      collectionInFlight = false;
+    }
+  };
+
+  const transmitTick = async () => {
+    if (transmissionInFlight || !retainedReport) return;
+    transmissionInFlight = true;
+    const report = retainedReport;
+    try {
+      const result = await pushWithRegistrationRetry(runtime, report);
+      if (result.ok) {
+        if (retainedReport === report) retainedReport = undefined;
+        backoffMs = 1_000;
+        await runtime.writeStatus({
+          running: true,
+          lastPushAt: Date.now(),
+          lastPushStatus: "ok",
+          lastPushError: undefined,
+          retainedReport: Boolean(retainedReport),
+        });
+      } else {
+        backoffMs = nextBackoff(backoffMs);
+        await runtime.writeStatus({
+          running: true,
+          lastPushStatus: result.code === "NODE_REGISTRATION_REQUIRED" ? "registration_required" : result.status === 409 ? "stale" : "failed",
+          lastPushError: result.error,
+          nextRetryMs: backoffMs,
+          retainedReport: true,
+        });
+      }
+    } finally {
+      transmissionInFlight = false;
+    }
+  };
+
+  const commandTick = async () => {
+    if (commandInFlight) return;
+    commandInFlight = true;
+    try {
+      const batch = await fetchAgentCommands(runtime.config);
+      const results = [];
+      for (const command of batch.commands ?? []) {
+        results.push(await executeAndReportCommand(runtime, command));
+      }
+      if (lastCommandPollError) {
+        console.log(formatCliBlock({
+          title: "Agent commands",
+          status: "polling restored",
+          tone: "success",
+          rows: [
+            ["Fibscope", runtime.config.reportUrl.replace(/\/report\/?$/, "/commands")],
+          ],
+        }));
+        lastCommandPollError = undefined;
+      }
+      const failed = results.find((result) => result.status === "failed");
+      await runtime.writeStatus({
+        running: true,
+        lastCommandPollAt: Date.now(),
+        lastCommandStatus: failed ? "failed" : "ok",
+        lastCommandError: failed?.error,
+        lastCommandResults: results.length ? results.slice(-10) : undefined,
+      });
+    } catch (error) {
+      const detail = message(error);
+      if (detail !== lastCommandPollError) {
+        console.warn(formatCliBlock({
+          title: "Agent commands",
+          status: "poll failed",
+          tone: "error",
+          rows: [
+            ["Fibscope", runtime.config.reportUrl.replace(/\/report\/?$/, "/commands")],
+            ["Result", detail],
+          ],
+        }));
+        lastCommandPollError = detail;
+      }
+      await runtime.writeStatus({
+        running: true,
+        lastCommandPollAt: Date.now(),
+        lastCommandStatus: "failed",
+        lastCommandError: detail,
+      });
+    } finally {
+      commandInFlight = false;
+    }
+  };
+
+  const knownPeerTick = async (force = false) => {
+    if (knownPeerInFlight) return;
+    if (!force && Date.now() - lastKnownPeerHydrationAt < runtime.config.knownPeerReconnectMs) return;
+    knownPeerInFlight = true;
+    try {
+      const result = await runtime.rehydrateKnownPeers({ force });
+      lastKnownPeerHydrationAt = Date.now();
+      await runtime.writeStatus({
+        running: true,
+        lastKnownPeerHydrationAt,
+        lastKnownPeerHydrationResult: result,
+        lastKnownPeerHydrationError: undefined,
+      });
+    } catch (error) {
+      lastKnownPeerHydrationAt = Date.now();
+      await runtime.writeStatus({
+        running: true,
+        lastKnownPeerHydrationAt,
+        lastKnownPeerHydrationError: message(error),
+      });
+    } finally {
+      knownPeerInFlight = false;
+    }
+  };
+
+  const collectionTimer = setInterval(() => void collectTick(), runtime.config.pushIntervalMs);
+  const transmissionLoop = async () => {
+    while (!stopped) {
+      await transmitTick();
+      await sleep(retainedReport ? backoffMs : 1_000);
+    }
+  };
+  const commandLoop = async () => {
+    while (!stopped) {
+      await commandTick();
+      await sleep(runtime.config.commandPollMs);
+    }
+  };
+  const knownPeerLoop = async () => {
+    while (!stopped) {
+      await knownPeerTick();
+      await sleep(Math.max(5_000, runtime.config.knownPeerReconnectMs));
+    }
+  };
+
+  await runtime.writeStatus({ running: true, startedAt: Date.now(), retainedReport: false, remoteConfig: runtime.remoteConfig });
+  await knownPeerTick(true);
+  await collectTick();
+  await knownPeerTick(true);
+  void transmissionLoop();
+  void commandLoop();
+  void knownPeerLoop();
+  const remoteNode = runtime.remoteConfig?.node?.displayName ?? runtime.remoteConfig?.node?.nodeId;
+  console.log(formatAgentStarted(runtime, remoteNode));
+
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(collectionTimer);
+    await runtime.writeStatus({ running: false, stoppedAt: Date.now(), retainedReport: Boolean(retainedReport) });
+  };
+  process.once("SIGINT", () => void stop().then(() => process.exit(0)));
+  process.once("SIGTERM", () => void stop().then(() => process.exit(0)));
+}
+
+export async function status(options = {}) {
+  const statusPath = resolve(options.status ?? DEFAULT_STATUS_PATH);
+  const value = existsSync(statusPath)
+    ? await readJson(statusPath)
+    : { running: false, message: "No agent status file found." };
+  console.log(JSON.stringify(value, null, 2));
+  return value;
+}
+
+export async function createRuntime(options = {}) {
+  const configPath = resolve(options.config ?? DEFAULT_CONFIG_PATH);
+  const statusPath = resolve(options.status ?? DEFAULT_STATUS_PATH);
+  const config = await loadConfig(configPath, options);
+  await ensureFnnPreflight(config, statusPath, options);
+  const remoteConfig = await fetchAgentConfig(config).catch(() => undefined);
+  if (!config.nodeDisplayName && remoteConfig?.node?.displayName) {
+    config.nodeDisplayName = remoteConfig.node.displayName;
+  }
+  let lastRegisteredFiberNodeId;
+  let previousReport;
+  const runtime = {
+    config,
+    remoteConfig,
+    configPath,
+    statusPath,
+    collect: async () => {
+      const report = await collectReport(config, previousReport);
+      previousReport = report;
+      return report;
+    },
+    register: async (report, options = {}) => {
+      const localNodeId = readNodeId(report.node) ?? runtime.remoteConfig?.node?.nodeId;
+      const remoteFiberNodeId = runtime.remoteConfig?.node?.fiberNodeId;
+      if (!options.force && lastRegisteredFiberNodeId && localNodeId === lastRegisteredFiberNodeId) return runtime.remoteConfig;
+      if (!options.force && remoteFiberNodeId && localNodeId === remoteFiberNodeId) return runtime.remoteConfig;
+      const registration = await registerAgentNode(config, report, runtime.remoteConfig);
+      runtime.remoteConfig = mergeAgentRemoteConfig(runtime.remoteConfig, registration);
+      lastRegisteredFiberNodeId = registration?.node?.fiberNodeId ?? localNodeId;
+      return registration;
+    },
+    push: (report, options = {}) => pushReport(config, report, options),
+    writeStatus: (patch) => writeStatus(statusPath, patch),
+    rehydrateKnownPeers: (options = {}) => reconnectKnownPeersFromGateway(config, runtime.remoteConfig, options),
+  };
+  return runtime;
+}
+
+async function ensureFnnPreflight(config, statusPath, options = {}) {
+  if (options.skipFnnPreflight) return;
+  const probedAt = Date.now();
+  const timeoutMs = positiveNumber(config.fnnPreflightTimeoutMs ?? config.timeoutMs, DEFAULT_FNN_PREFLIGHT_TIMEOUT_MS);
+  try {
+    const info = await rpcCall(config.fiberRpcUrl, "node_info", [], timeoutMs);
+    const nodeId = readNodeId(info);
+    const version = textValue(info?.version ?? info?.commit ?? info?.buildVersion ?? info?.build_version);
+    if (!nodeId && !version) throw new Error("node_info returned an unexpected Fiber RPC response.");
+    await writeStatus(statusPath, {
+      running: false,
+      fiberRpcUrl: config.fiberRpcUrl,
+      fnnStatus: "ready",
+      lastFnnProbeAt: probedAt,
+      lastFnnProbeError: undefined,
+      lastFnnNodeId: nodeId,
+      lastFnnVersion: version,
+    });
+  } catch (error) {
+    const detail = message(error);
+    await writeStatus(statusPath, {
+      running: false,
+      fiberRpcUrl: config.fiberRpcUrl,
+      fnnStatus: "unreachable",
+      lastFnnProbeAt: probedAt,
+      lastFnnProbeError: detail,
+    });
+    throw new Error(formatFnnPreflightError(config.fiberRpcUrl, detail));
+  }
+}
+
+export async function collectReport(config, previousReport = undefined) {
+  const engineOptions = {
+    rpcUrl: config.fiberRpcUrl,
+    timeoutMs: config.timeoutMs ?? 8_000,
+  };
+  const state = await collectFiberStateReport(engineOptions);
+  state.node = await enrichReportNode(state.node, config);
+  const funding = await collectFundingState(config);
+  const fundingWallet = await collectFundingWalletState(config, funding);
+  const collector = createTelemetryCollector({
+    ...engineOptions,
+    pulseModule: DEFAULT_PULSE_MODULE,
+    maxSnapshots: 1,
+    maxEvents: config.maxEvents ?? 100,
+    maxAlerts: config.maxAlerts ?? 50,
+  });
+  collector.record({
+    timestamp: state.timestamp ?? Date.now(),
+    node: state.node,
+    peers: state.peers ?? [],
+    channels: state.channels ?? [],
+    payments: state.payments ?? [],
+  });
+  const observability = {
+    health: collector.health(),
+    metrics: collector.reliability(),
+    alerts: collector.alertLog(),
+  };
+  const recommendations = recommend({ component1: state, component3: observability });
+  const collectedAt = Date.now();
+  const progress = buildProgress({
+    chain: config.chain ?? "testnet",
+    collectedAt,
+    state,
+    funding,
+    observability,
+    recommendations,
+  });
+  const events = deriveProgressEvents(previousReport, {
+    collectedAt,
+    chain: config.chain ?? "testnet",
+    node: state.node,
+    progress,
+  });
+  return {
+    agentVersion: AGENT_VERSION,
+    chain: config.chain ?? "testnet",
+    collectedAt,
+    node: state.node,
+    peers: state.peers ?? [],
+    channels: state.channels ?? [],
+    liquidity: state.liquidity ?? {},
+    funding,
+    fundingWallet,
+    diagnostics: state.diagnostics ?? [],
+    health: observability.health ?? state.health ?? {},
+    metrics: observability.metrics ?? {},
+    alerts: observability.alerts ?? [],
+    recommendations,
+    progress,
+    events,
+    publicProfileEnabled: Boolean(config.publicProfileEnabled),
+    publicFields: config.publicFields ?? {},
+  };
+}
+
+async function enrichReportNode(node, config) {
+  if (!node || typeof node !== "object") return node;
+  const displayName = textValue(config.nodeDisplayName);
+  const addresses = uniqueStrings([
+    ...readAddressList(node.addresses),
+    ...readAddressList(node.address),
+    ...configuredPeerAddresses(config),
+    ...await inferPeerAddressesFromLocalFnn(config),
+  ]);
+  if (!addresses.length && !displayName) return node;
+  return {
+    ...node,
+    ...(displayName ? { displayName } : {}),
+    address: node.address ?? addresses[0],
+    addresses,
+  };
+}
+
+function configuredPeerAddresses(config) {
+  return uniqueStrings([
+    ...readAddressList(config.peerAddresses),
+    ...readAddressList(config.publicPeerAddresses),
+    ...readAddressList(config.announcedAddresses),
+    ...readAddressList(config.peerAddress),
+    ...readAddressList(config.publicPeerAddress),
+    ...readAddressList(config.announcedAddress),
+  ]);
+}
+
+async function inferPeerAddressesFromLocalFnn(config) {
+  if (!config.fiberRpcUrl) return [];
+  const cached = inferredPeerAddressCache.get(config.fiberRpcUrl);
+  if (cached && Date.now() - cached.checkedAt < 60_000) return cached.addresses;
+  let addresses = [];
+  try {
+    const instances = await discoverFnnInstances({ timeoutMs: 800 });
+    const instance = instances.find((item) => sameRpcUrl(item.rpcUrl, config.fiberRpcUrl));
+    addresses = uniqueStrings([
+      ...readAddressList(instance?.p2pListenAddr).map(normalizeLocalListenAddress),
+    ]);
+    if (instance?.baseDir) {
+      addresses = uniqueStrings([
+        ...addresses,
+        ...await readPeerAddressesFromFnnLog(join(instance.baseDir, "logs", "fnn.log")),
+      ]);
+    }
+  } catch {
+    addresses = [];
+  }
+  inferredPeerAddressCache.set(config.fiberRpcUrl, { checkedAt: Date.now(), addresses });
+  return addresses;
+}
+
+async function readPeerAddressesFromFnnLog(logPath) {
+  if (!existsSync(logPath)) return [];
+  const text = stripAnsi(await readFile(logPath, "utf8"));
+  const matches = [...text.matchAll(/"([^"]+\/tcp\/\d+\/p2p\/[^"]+)"/g)];
+  const addresses = matches
+    .map((match) => match[1])
+    .filter((address) => !address.includes("/ws/"))
+    .map(normalizeLocalListenAddress);
+  return uniqueStrings(addresses).slice(-3);
+}
+
+function normalizeLocalListenAddress(address) {
+  return String(address ?? "")
+    .trim()
+    .replace("/ip4/0.0.0.0/", "/ip4/127.0.0.1/")
+    .replace("/ip6/::/", "/ip6/::1/");
+}
+
+function sameRpcUrl(left, right) {
+  try {
+    const a = new URL(left);
+    const b = new URL(right);
+    return a.protocol === b.protocol && a.hostname === b.hostname && (a.port || defaultPort(a)) === (b.port || defaultPort(b));
+  } catch {
+    return left === right;
+  }
+}
+
+function defaultPort(url) {
+  return url.protocol === "https:" ? "443" : "80";
+}
+
+async function collectFundingState(config) {
+  const checkedAt = Date.now();
+  const indexerUrl = resolveCkbIndexerUrl(config);
+  let lockScript;
+  let policy;
+  try {
+    const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs ?? 8_000);
+    lockScript = normalizeCkbScript(info?.default_funding_lock_script ?? info?.defaultFundingLockScript);
+    policy = fundingPolicyFromNodeInfo(info);
+  } catch (error) {
+    return unavailableFundingState({
+      checkedAt,
+      indexerUrl,
+      error: `FNN funding lock unavailable: ${message(error)}`,
+    });
+  }
+
+  if (!lockScript) {
+    return unavailableFundingState({
+      checkedAt,
+      indexerUrl,
+      error: "FNN node_info did not include a default funding lock script.",
+      policy,
+    });
+  }
+  if (!indexerUrl) {
+    return unavailableFundingState({
+      checkedAt,
+      lockScript,
+      error: "No CKB indexer RPC URL is configured. Set FIBCKB or FIBSCOPE_AGENT_CKB_RPC_URL.",
+      policy,
+    });
+  }
+
+  try {
+    const summary = await collectCkbCellsCapacity(indexerUrl, lockScript, config);
+    return {
+      status: "ready",
+      assetType: "CKB",
+      source: "ckb-indexer",
+      checkedAt,
+      ckbRpcUrl: indexerUrl,
+      lockScript,
+      ...summary,
+      policy,
+    };
+  } catch (error) {
+    return unavailableFundingState({
+      checkedAt,
+      indexerUrl,
+      lockScript,
+      error: `CKB funding balance unavailable: ${message(error)}`,
+      policy,
+    });
+  }
+}
+
+function unavailableFundingState({ checkedAt, indexerUrl, lockScript, error, policy }) {
+  return {
+    status: "unavailable",
+    assetType: "CKB",
+    source: indexerUrl ? "ckb-indexer" : "configuration",
+    checkedAt,
+    ckbRpcUrl: indexerUrl,
+    lockScript,
+    totalCapacity: "0",
+    availableCapacity: "0",
+    occupiedCapacity: "0",
+    cellCount: 0,
+    availableCellCount: 0,
+    occupiedCellCount: 0,
+    policy,
+    error,
+  };
+}
+
+async function collectFundingWalletState(config, funding = undefined) {
+  const checkedAt = Date.now();
+  const walletPath = resolveFundingWalletPath(config);
+  const keyPath = resolveFundingKeyPath(config, walletPath);
+  const indexerUrl = resolveCkbIndexerUrl(config);
+  if (!walletPath) {
+    return {
+      status: "unavailable",
+      checkedAt,
+      error: "No FNN data directory is known yet. Start or bind the agent to a Fiber node.",
+    };
+  }
+  if (!existsSync(walletPath)) {
+    return {
+      status: "missing",
+      checkedAt,
+      path: walletPath,
+      keyPath,
+      restartRequired: false,
+      message: "No local funding wallet is linked to this Fiber node.",
+    };
+  }
+
+  try {
+    const wallet = await readFundingWallet(walletPath, config.chain ?? "testnet");
+    const fundingLock = normalizeCkbScript(funding?.lockScript);
+    const matchesFnnFundingLock = scriptsEqual(wallet.lockScript, fundingLock);
+    let balance = {};
+    if (matchesFnnFundingLock && funding?.status === "ready") {
+      balance = pickFundingBalance(funding);
+    } else if (indexerUrl) {
+      balance = await collectCkbCellsCapacity(indexerUrl, wallet.lockScript, config);
+    }
+    const safe = safeFundingWallet(wallet);
+    const totalCapacity = amountString(balance.totalCapacity);
+    const availableCapacity = amountString(balance.availableCapacity);
+    return {
+      status: matchesFnnFundingLock ? "linked" : "pending_restart",
+      checkedAt,
+      path: walletPath,
+      keyPath,
+      ...safe,
+      matchesFnnFundingLock,
+      restartRequired: !matchesFnnFundingLock,
+      balance: {
+        ...balance,
+        totalCapacity,
+        availableCapacity,
+        occupiedCapacity: amountString(balance.occupiedCapacity),
+      },
+      replaceRequiresConfirmation: amountBigInt(totalCapacity) > 0n || amountBigInt(availableCapacity) > 0n,
+      message: matchesFnnFundingLock
+        ? "Funding wallet is linked to this Fiber node."
+        : "Wallet file exists, but the running Fiber node is still using another key. Restart FNN to activate it.",
+    };
+  } catch (error) {
+    return {
+      status: "invalid",
+      checkedAt,
+      path: walletPath,
+      keyPath,
+      error: message(error),
+    };
+  }
+}
+
+function resolveFundingWalletPath(config) {
+  const explicit = textValue(config.walletPath ?? process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH));
+  if (explicit) return resolve(explicit);
+  const baseDir = textValue(config.fnnBaseDir);
+  return baseDir ? resolve(baseDir, "ckb", "wallet.json") : "";
+}
+
+function resolveFundingKeyPath(config, walletPath) {
+  const explicit = textValue(config.fiberKeyPath ?? config.keyPath);
+  if (explicit) return resolve(explicit);
+  return walletPath ? resolve(dirname(walletPath), "key") : "";
+}
+
+async function readFundingWallet(walletPath, fallbackNetwork) {
+  const existing = await readJson(walletPath);
+  const privateKey = normalizePrivateKey(existing.privateKeyHex ?? existing.private_key ?? existing.fiber?.keyFileValue ?? "");
+  const network = normalizeNetwork(existing.network ?? fallbackNetwork);
+  return buildFundingWallet(privateKey, network);
+}
+
+function buildFundingWallet(privateKey, networkValue) {
+  const network = normalizeNetwork(networkValue);
+  const privateKeyHex = `0x${normalizePrivateKey(privateKey)}`;
+  const publicKey = privateKeyToPublicKey(privateKeyHex);
+  const lockArg = `0x${blake160(publicKey, "hex")}`;
+  const sdkLockScript = {
+    codeHash: SIGHASH_CODE_HASH,
+    hashType: "type",
+    args: lockArg,
+  };
+  const lockScript = {
+    code_hash: sdkLockScript.codeHash,
+    hash_type: sdkLockScript.hashType,
+    args: sdkLockScript.args,
+  };
+  const addressPrefix = network === "mainnet" ? "ckb" : "ckt";
+  return {
+    schema: "fiber.wallet.v1",
+    network,
+    createdAt: new Date().toISOString(),
+    privateKeyHex,
+    publicKey,
+    lockArg,
+    address: privateKeyToAddress(privateKeyHex, { prefix: addressPrefix }),
+    lockScript,
+    sdkLockScript,
+    lockScriptAddress: scriptToAddress(sdkLockScript, network === "mainnet"),
+    fiber: {
+      keyFileFormat: "plain-private-key-hex-without-0x",
+      keyFileValue: privateKeyHex.slice(2),
+      defaultKeyPath: network === "testnet"
+        ? ".fiber/testnet-node/ckb/key"
+        : ".fiber/mainnet-node/ckb/key",
+    },
+    faucet: network === "testnet"
+      ? {
+          ckb: "https://faucet.nervos.org",
+          note: "Fund this address before opening testnet Fiber channels.",
+        }
+      : undefined,
+  };
+}
+
+function safeFundingWallet(wallet) {
+  return {
+    schema: wallet.schema,
+    network: wallet.network,
+    address: wallet.address,
+    publicKey: wallet.publicKey,
+    lockArg: wallet.lockArg,
+    lockScript: wallet.lockScript,
+    lockScriptAddress: wallet.lockScriptAddress,
+    faucet: wallet.faucet,
+  };
+}
+
+function pickFundingBalance(funding) {
+  return {
+    totalCapacity: amountString(funding?.totalCapacity),
+    availableCapacity: amountString(funding?.availableCapacity),
+    occupiedCapacity: amountString(funding?.occupiedCapacity),
+    cellCount: numeric(funding?.cellCount, 0),
+    availableCellCount: numeric(funding?.availableCellCount, 0),
+    occupiedCellCount: numeric(funding?.occupiedCellCount, 0),
+  };
+}
+
+function scriptsEqual(left, right) {
+  const a = normalizeCkbScript(left);
+  const b = normalizeCkbScript(right);
+  if (!a || !b) return false;
+  return a.code_hash?.toLowerCase() === b.code_hash?.toLowerCase()
+    && a.hash_type === b.hash_type
+    && a.args?.toLowerCase() === b.args?.toLowerCase();
+}
+
+function normalizeNetwork(value) {
+  const network = String(value ?? "testnet").trim().toLowerCase();
+  if (network !== "testnet" && network !== "mainnet") throw new Error("Funding wallet network must be testnet or mainnet.");
+  return network;
+}
+
+function normalizePrivateKey(value) {
+  const key = String(value ?? "").trim().replace(/^0x/i, "");
+  if (!/^[0-9a-fA-F]{64}$/.test(key)) {
+    throw new Error("Funding wallet private key must be 64 hex characters.");
+  }
+  const bigint = BigInt(`0x${key}`);
+  if (bigint <= 0n || bigint >= SECP256K1_ORDER) {
+    throw new Error("Funding wallet private key is outside the secp256k1 private key range.");
+  }
+  return key.toLowerCase();
+}
+
+function generatePrivateKeyHex() {
+  while (true) {
+    const key = randomBytes(32).toString("hex");
+    const bigint = BigInt(`0x${key}`);
+    if (bigint > 0n && bigint < SECP256K1_ORDER) return key;
+  }
+}
+
+async function writeFundingWallet(config, wallet, options = {}) {
+  const walletPath = resolveFundingWalletPath(config);
+  const keyPath = resolveFundingKeyPath(config, walletPath);
+  if (!walletPath || !keyPath) throw new Error("Funding wallet path is unavailable. Start or bind the agent to a Fiber node first.");
+  const current = await collectFundingWalletState(config, await collectFundingState(config));
+  assertFundingWalletReplaceAllowed(current, options);
+  await mkdir(dirname(walletPath), { recursive: true });
+  await writeFile(walletPath, `${JSON.stringify(wallet, null, 2)}\n`, { mode: 0o600 });
+  await chmod(walletPath, 0o600).catch(() => undefined);
+  await mkdir(dirname(keyPath), { recursive: true });
+  await writeFile(keyPath, `${wallet.privateKeyHex.slice(2)}\n`, { mode: 0o600 });
+  await chmod(keyPath, 0o600).catch(() => undefined);
+  return {
+    ok: true,
+    path: walletPath,
+    keyPath,
+    previous: summarizeFundingWalletState(current),
+    wallet: safeFundingWallet(wallet),
+    restartRequired: true,
+    message: "Funding wallet saved. Restart FNN so the node uses this key.",
+  };
+}
+
+function assertFundingWalletReplaceAllowed(current, options) {
+  const exists = !["missing", "unavailable"].includes(String(current?.status ?? ""));
+  if (exists && !boolValue(options.replace, false)) {
+    throw new Error("A funding wallet is already linked. Choose replace to overwrite it.");
+  }
+  if (walletStateHasBalance(current) && !boolValue(options.confirmReplaceWithBalance, false)) {
+    throw new Error(`The existing funding wallet still has ${ckbText(current?.balance?.totalCapacity ?? current?.balance?.availableCapacity)}. Confirm replacement before continuing.`);
+  }
+}
+
+function walletStateHasBalance(state) {
+  const balance = state?.balance && typeof state.balance === "object" ? state.balance : {};
+  return amountBigInt(balance.totalCapacity) > 0n || amountBigInt(balance.availableCapacity) > 0n;
+}
+
+function summarizeFundingWalletState(state) {
+  if (!state || typeof state !== "object") return undefined;
+  return omitUndefined({
+    status: state.status,
+    address: state.address,
+    path: state.path,
+    totalCapacity: state.balance?.totalCapacity,
+    availableCapacity: state.balance?.availableCapacity,
+  });
+}
+
+async function createFundingWallet(config, params) {
+  const network = normalizeNetwork(params.network ?? config.chain ?? "testnet");
+  if (network === "mainnet" && !boolValue(params.allowMainnetGeneration, false)) {
+    throw new Error("Creating a new mainnet funding wallet is disabled. Link an existing mainnet wallet instead.");
+  }
+  const wallet = buildFundingWallet(generatePrivateKeyHex(), network);
+  return writeFundingWallet(config, wallet, params);
+}
+
+async function linkFundingWallet(config, params) {
+  const sourcePath = textValue(params.sourcePath ?? params.path ?? params.walletPath);
+  if (!sourcePath) throw new Error("Choose a local wallet.json path for the agent to link.");
+  const wallet = await readFundingWallet(resolve(sourcePath), config.chain ?? "testnet");
+  return writeFundingWallet(config, wallet, params);
+}
+
+async function collectCkbCellsCapacity(indexerUrl, lockScript, config) {
+  let totalCapacity = 0n;
+  let availableCapacity = 0n;
+  let cellCount = 0;
+  let availableCellCount = 0;
+  let cursor;
+  const limit = hexQuantity(positiveNumber(config.ckbCellPageSize, 100));
+  const maxPages = Math.max(1, Math.min(50, Math.trunc(positiveNumber(config.ckbCellMaxPages, 20))));
+
+  for (let page = 0; page < maxPages; page += 1) {
+    const params = [
+      {
+        script: lockScript,
+        script_type: "lock",
+      },
+      "asc",
+      limit,
+    ];
+    if (cursor) params.push(cursor);
+    const result = await rpcCall(indexerUrl, "get_cells", params, config.ckbRpcTimeoutMs ?? config.timeoutMs ?? 10_000);
+    const objects = Array.isArray(result?.objects) ? result.objects : [];
+    for (const cell of objects) {
+      const output = cell?.output ?? cell?.cell_output ?? {};
+      const capacity = amountBigInt(output.capacity);
+      totalCapacity += capacity;
+      cellCount += 1;
+      if (!output.type) {
+        availableCapacity += capacity;
+        availableCellCount += 1;
+      }
+    }
+    const nextCursor = typeof result?.last_cursor === "string" && result.last_cursor !== cursor ? result.last_cursor : undefined;
+    if (!objects.length || !nextCursor || nextCursor === "0x") break;
+    cursor = nextCursor;
+  }
+
+  const occupiedCapacity = totalCapacity >= availableCapacity ? totalCapacity - availableCapacity : 0n;
+  return {
+    totalCapacity: totalCapacity.toString(),
+    availableCapacity: availableCapacity.toString(),
+    occupiedCapacity: occupiedCapacity.toString(),
+    cellCount,
+    availableCellCount,
+    occupiedCellCount: Math.max(0, cellCount - availableCellCount),
+  };
+}
+
+function resolveCkbIndexerUrl(config) {
+  const explicit = textValue(config.ckbIndexerUrl ?? config.ckbRpcUrl);
+  if (explicit) return explicit;
+  if (config.chain === "testnet") return "https://testnet.ckbapp.dev/";
+  if (config.chain === "mainnet") return "http://127.0.0.1:8114/";
+  return "";
+}
+
+function normalizeCkbScript(value) {
+  if (!value || typeof value !== "object") return undefined;
+  const codeHash = textValue(value.code_hash ?? value.codeHash);
+  const hashType = textValue(value.hash_type ?? value.hashType);
+  const args = textValue(value.args);
+  if (!codeHash || !hashType || !args) return undefined;
+  return {
+    code_hash: codeHash,
+    hash_type: hashType,
+    args,
+  };
+}
+
+function fundingPolicyFromNodeInfo(info) {
+  if (!info || typeof info !== "object") return undefined;
+  return omitUndefined({
+    openChannelAutoAcceptMinCkbFundingAmount: amountStringOrUndefined(info.open_channel_auto_accept_min_ckb_funding_amount),
+    autoAcceptChannelCkbFundingAmount: amountStringOrUndefined(info.auto_accept_channel_ckb_funding_amount),
+  });
+}
+
+function amountStringOrUndefined(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  return amountString(value);
+}
+
+function amountBigInt(value) {
+  if (typeof value === "bigint") return value > 0n ? value : 0n;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value)) return BigInt(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return BigInt(value);
+  return 0n;
+}
+
+function channelFundingReserve(config) {
+  const explicitShannons = amountBigInt(config.channelFundingReserveShannons ?? config.channelFundingFeeReserveShannons);
+  if (explicitShannons > 0n) return explicitShannons;
+  const explicitCkb = textValue(config.channelFundingReserveCkb ?? config.channelFundingFeeReserveCkb);
+  if (explicitCkb) return ckbToShannons(explicitCkb);
+  return DEFAULT_CHANNEL_FUNDING_RESERVE_SHANNONS;
+}
+
+function hexQuantity(value) {
+  return `0x${BigInt(Math.max(0, Math.trunc(value))).toString(16)}`;
+}
+
+async function pushWithRegistrationRetry(runtime, report, options = {}) {
+  let result = await pushWithRateLimitRetry(runtime, report, options);
+  if (result.ok || result.code !== "NODE_REGISTRATION_REQUIRED") return result;
+  try {
+    const registration = await runtime.register(report, { force: true });
+    await runtime.writeStatus({
+      running: true,
+      remoteConfig: runtime.remoteConfig,
+      lastRegistrationAt: registration?.node?.lastRegisteredAt ?? Date.now(),
+      lastRegistrationStatus: "ok",
+      lastRegistrationError: undefined,
+      lastRegisteredNodeId: registration?.node?.nodeId,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      status: 409,
+      code: "NODE_REGISTRATION_REQUIRED",
+      error: message(error),
+      payload: result.payload,
+    };
+  }
+  result = await pushWithRateLimitRetry(runtime, report, options);
+  return result;
+}
+
+async function pushWithRateLimitRetry(runtime, report, options = {}) {
+  const maxRetries = options.retryOnRateLimit ? positiveNumber(options.maxRateLimitRetries, 2) : 0;
+  let attempt = 0;
+  let result = await runtime.push(report, options);
+  while (!result.ok && result.status === 429 && attempt < maxRetries) {
+    attempt += 1;
+    const waitMs = Math.max(1_000, result.retryAfterMs ?? 10_000);
+    console.warn(formatCliBlock({
+      title: "Agent report",
+      status: "rate limited",
+      tone: "error",
+      rows: [
+        ["Fibscope", runtime.config.reportUrl],
+        ["Retry", `${waitMs} ms`],
+        ["Attempt", `${attempt}/${maxRetries}`],
+      ],
+    }));
+    await sleep(waitMs);
+    result = await runtime.push(report, options);
+  }
+  return result;
+}
+
+export async function pushReport(config, report, options = {}) {
+  try {
+    const headers = {
+      "content-type": "application/json",
+      "x-agent-token": config.agentToken,
+    };
+    if (options.intent) headers["x-fibscope-report-intent"] = String(options.intent);
+    const response = await fetch(config.reportUrl, {
+      method: "POST",
+      headers,
+      body: stringify(report),
+    });
+    const text = await response.text();
+    const payload = parsePayload(text);
+    const code = payloadCode(payload);
+    const retryAfterMs = retryAfterToMs(response.headers.get("retry-after"));
+    if (response.status === 409) {
+      return { ok: false, status: 409, code, error: describeAgentHttpError(payload, "STALE_REPORT"), payload };
+    }
+    if (!response.ok) {
+      return { ok: false, status: response.status, code, error: describeAgentHttpError(payload, `HTTP_${response.status}`), payload, retryAfterMs };
+    }
+    return { ok: true, status: response.status, payload };
+  } catch (error) {
+    return { ok: false, status: 0, error: message(error) };
+  }
+}
+
+async function fetchAgentCommands(config) {
+  const commandsUrl = config.commandsUrl ?? config.reportUrl.replace(/\/report\/?$/, "/commands");
+  let response;
+  try {
+    response = await fetch(`${commandsUrl}${commandsUrl.includes("?") ? "&" : "?"}limit=10`, {
+      headers: {
+        "x-agent-token": config.agentToken,
+      },
+    });
+  } catch (error) {
+    throw new Error(`Command poll failed at ${commandsUrl}: ${message(error)}`);
+  }
+  const text = await response.text();
+  const payload = parsePayload(text);
+  if (!response.ok) {
+    throw new Error(`Command poll failed: ${describeAgentHttpError(payload, `HTTP_${response.status}`)}`);
+  }
+  return payload && typeof payload === "object" ? payload : { commands: [] };
+}
+
+async function executeAndReportCommand(runtime, command) {
+  const config = runtime.config;
+  const id = readCommandId(command);
+  console.log(formatCommandEvent("received", command, config, "info"));
+  try {
+    const result = await executeAgentCommand(runtime, command);
+    const body = {
+      commandId: id,
+      command: command.command,
+      status: "completed",
+      result,
+    };
+    await postCommandResult(config, body);
+    console.log(formatCommandEvent("completed", command, config, "success"));
+    return body;
+  } catch (error) {
+    const body = {
+      commandId: id,
+      command: command.command,
+      status: "failed",
+      error: message(error),
+    };
+    await postCommandResult(config, body);
+    console.warn(formatCommandEvent("failed", command, config, "error", body.error));
+    return body;
+  }
+}
+
+async function executeAgentCommand(runtime, command) {
+  const config = runtime.config ?? runtime;
+  const name = normalizeCommandName(command?.command);
+  const params = command?.params && typeof command.params === "object" ? command.params : {};
+  if (name === "OPEN_CHANNEL" || name === "CREATE_CHANNEL") {
+    return openFiberChannel(config, params);
+  }
+  if (name === "SETTLE_CHANNEL" || name === "SHUTDOWN_CHANNEL" || name === "CLOSE_CHANNEL") {
+    return settleFiberChannel(runtime, params);
+  }
+  if (name === "FUNDING_WALLET_STATUS" || name === "REFRESH_FUNDING_BALANCE" || name === "UPDATE_FUNDING_BALANCE") {
+    return refreshFundingBalance(runtime);
+  }
+  if (name === "CREATE_FUNDING_WALLET") {
+    return createFundingWallet(config, params);
+  }
+  if (name === "LINK_FUNDING_WALLET") {
+    return linkFundingWallet(config, params);
+  }
+  if (name === "SIMULATE_ROUTE") {
+    return simulateFiberRoute(config, params);
+  }
+  if (name === "SEND_PAYMENT" || name === "PAY_INVOICE" || name === "FIBER_SEND_PAYMENT") {
+    return sendFiberPayment(config, params);
+  }
+  if (name === "API_NODE_PAYMENT" || name === "NODE_PAYMENT") {
+    return acceptApiNodePayment(runtime, params);
+  }
+  if (name === "API_WALLET_PAYMENT" || name === "WALLET_PAYMENT") {
+    return acceptApiWalletPayment(runtime, params);
+  }
+  if (name === "PAYMENT_INTENT" || name === "ROUTE_INTENT" || name === "INTERNAL_ROUTE_INTENT") {
+    return acknowledgePaymentIntent(config, params, { action: "ROUTE_INTENT" });
+  }
+  throw new Error(`Unsupported agent command: ${name || "unknown"}`);
+}
+
+function normalizeCommandName(value) {
+  return String(value ?? "")
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+async function simulateFiberRoute(config, params) {
+  const localInfo = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
+  const sourceNode = normalizePeerPubkey(textValue(params.sourceNode) || readNodeId(localInfo));
+  const peer = resolveSimulationPeer(params);
+  const destinationNode = normalizePeerPubkey(peer.pubkey);
+  if (peerKey(sourceNode) === peerKey(destinationNode)) {
+    throw new Error("Route simulation needs a destination peer that is different from the selected source node.");
+  }
+  const amount = simulationAmount(params);
+  const assetType = textValue(params.asset ?? params.assetType ?? params.asset_type) || "CKB";
+  const componentState = await collectFiberStateReport({
+    rpcUrl: config.fiberRpcUrl,
+    timeoutMs: config.timeoutMs ?? 8_000,
+  });
+  const result = await virtualizePayment(
+    {
+      sourceNode,
+      destinationNode,
+      amount,
+      assetType,
+    },
+    {
+      componentState,
+      rpcUrl: config.fiberRpcUrl,
+      timeoutMs: config.timeoutMs ?? 8_000,
+      maxHops: positiveNumber(params.maxHops, 6),
+      maxRoutes: positiveNumber(params.maxRoutes, 10),
+    },
+  );
+  return normalizeRouteSimulationResult(result, {
+    sourceNode,
+    destinationNode,
+    amount,
+    assetType,
+    peer,
+    publicFee: normalizeSimulationPublicFee(params.publicFee ?? params.nodeFee ?? params.fee),
+  });
+}
+
+function resolveSimulationPeer(params) {
+  const hasPeerToken = firstTextValue(params.peerToken, params.fibscopePeerToken);
+  if (hasPeerToken) return resolveCommandPeer(params);
+  const pubkey = firstTextValue(params.destinationNode, params.peerPubkey, params.selectedPeerPubkey, params.pubkey, params.peer);
+  return {
+    pubkey,
+    address: firstTextValue(params.peerAddress, params.address),
+    meta: {
+      source: params.mode === "online" ? "online-peer" : params.mode === "token" ? "fibscope-token" : "advanced-pubkey",
+    },
+  };
+}
+
+function simulationAmount(params) {
+  if (params.ckb !== undefined && params.ckb !== "") return ckbToShannons(params.ckb).toString();
+  if (params.amountCkb !== undefined && params.amountCkb !== "") return ckbToShannons(params.amountCkb).toString();
+  const value = params.amount ?? params.amountShannons ?? params.value;
+  if (value !== undefined && value !== "") return quantity(value).startsWith("0x") ? BigInt(quantity(value)).toString() : String(value);
+  return ckbToShannons("1").toString();
+}
+
+function normalizeRouteSimulationResult(result, context) {
+  const simulation = result.simulation ?? {};
+  const steps = Array.isArray(simulation.steps) ? simulation.steps : [];
+  const predictions = Array.isArray(result.predictions) ? result.predictions : [];
+  const baseFeeBreakdown = simulation.feeBreakdown ?? {};
+  const baseTotalFee = bigintValue(baseFeeBreakdown.totalFee ?? simulation.totalFee, 0n);
+  const publicFeeAmount = simulation.result === "success"
+    ? estimateSimulationPublicFee(context.publicFee, context.amount)
+    : 0n;
+  const totalFee = baseTotalFee + publicFeeAmount;
+  const totalDebit = bigintValue(simulation.totalDebit, bigintValue(context.amount, 0n) + baseTotalFee) + publicFeeAmount;
+  const feeBreakdown = withSimulationPublicFeeBreakdown(baseFeeBreakdown, context.publicFee, publicFeeAmount);
+  const augmentedSimulation = {
+    ...simulation,
+    totalFee,
+    totalDebit,
+    feeBreakdown,
+  };
+  return {
+    ok: true,
+    action: "SIMULATE_ROUTE",
+    source: "agent-route-virtualizer",
+    mode: "Read-only route simulation",
+    status: simulation.result === "success" ? "success" : "failed",
+    request: {
+      sourceNode: context.sourceNode,
+      destinationNode: context.destinationNode,
+      amount: context.amount,
+      assetType: context.assetType,
+      peer: context.peer.meta,
+    },
+    totalFee,
+    route: steps.map((step) => ({
+      nodeId: step.toNode,
+      peerId: step.toNode,
+      channelId: step.channelId,
+      fee: step.hopFee,
+      status: step.status,
+      failed: step.status === "blocked",
+      reason: step.reason,
+    })),
+    warnings: predictions.map((prediction) => ({
+      code: prediction.code,
+      title: prediction.code,
+      message: prediction.explanation ?? prediction.recommendation,
+      recommendation: prediction.recommendation,
+      confidence: prediction.confidence,
+    })),
+    liquidityChanges: Array.isArray(simulation.liquidityChanges) ? simulation.liquidityChanges : [],
+    feeBreakdown,
+    diagnostics: result.diagnostics ?? [],
+    selectedRoute: result.selectedRoute ?? null,
+    routes: result.routes ?? [],
+    simulation: augmentedSimulation,
+  };
+}
+
+function normalizeSimulationPublicFee(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const enabled = value.enabled === true || String(value.enabled ?? "").toLowerCase() === "true";
+  const mode = textValue(value.mode).toLowerCase() === "fixed" ? "fixed" : "percent";
+  const feeValue = textField(value.value ?? value.feeValue ?? value.amount ?? value.rate);
+  if (!enabled || !feeValue) return undefined;
+  return { enabled: true, mode, value: feeValue };
+}
+
+function estimateSimulationPublicFee(publicFee, amount) {
+  if (!publicFee?.enabled) return 0n;
+  try {
+    if (publicFee.mode === "fixed") return ckbToShannons(publicFee.value);
+    return percentFee(bigintValue(amount, 0n), publicFee.value);
+  } catch {
+    return 0n;
+  }
+}
+
+function withSimulationPublicFeeBreakdown(feeBreakdown, publicFee, publicFeeAmount) {
+  const base = feeBreakdown && typeof feeBreakdown === "object" && !Array.isArray(feeBreakdown) ? feeBreakdown : {};
+  const hopFees = Array.isArray(base.hopFees) ? base.hopFees : [];
+  const hopTotal = hopFees.reduce((sum, hop) => sum + bigintValue(hop?.fee ?? hop?.hopFee, 0n), 0n);
+  const baseTotal = bigintValue(base.totalFee, hopTotal);
+  const feeRows = hopFees.map((hop, index) => ({
+    label: `Hop ${index + 1}`,
+    nodeId: hop?.nodeId,
+    channelId: hop?.channelId,
+    fee: hop?.fee ?? hop?.hopFee ?? 0n,
+  }));
+  if (publicFee?.enabled && publicFeeAmount > 0n) {
+    feeRows.push({
+      label: "Node fee",
+      fee: publicFeeAmount,
+      mode: publicFee.mode,
+      value: publicFee.value,
+    });
+  }
+  return {
+    ...base,
+    hopFees,
+    feeRows,
+    publicFee: publicFee?.enabled ? {
+      mode: publicFee.mode,
+      value: publicFee.value,
+      fee: publicFeeAmount,
+    } : undefined,
+    totalFee: baseTotal + publicFeeAmount,
+  };
+}
+
+function percentFee(amount, rateValue) {
+  const text = String(rateValue ?? "").trim();
+  const match = /^([0-9]+)(?:\.([0-9]{1,8}))?$/.exec(text);
+  if (!match) return 0n;
+  const fraction = match[2] ?? "";
+  const numerator = BigInt(`${match[1]}${fraction}`);
+  const denominator = 100n * (10n ** BigInt(fraction.length));
+  if (numerator <= 0n || denominator <= 0n) return 0n;
+  return ceilDiv(amount * numerator, denominator);
+}
+
+function ceilDiv(value, divisor) {
+  return value <= 0n ? 0n : (value + divisor - 1n) / divisor;
+}
+
+function bigintValue(value, fallback = 0n) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^[0-9]+$/.test(value.trim())) return BigInt(value.trim());
+  return fallback;
+}
+
+function textField(value) {
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return "";
+}
+
+async function refreshFundingBalance(runtime) {
+  const config = runtime.config ?? runtime;
+  const report = typeof runtime.collect === "function"
+    ? await runtime.collect()
+    : await collectReport(config);
+  let pushResult = { ok: false, skipped: true };
+  if (typeof runtime.push === "function") {
+    pushResult = await pushWithRegistrationRetry(runtime, report, {
+      intent: "funding-refresh",
+      retryOnRateLimit: true,
+      maxRateLimitRetries: 2,
+    });
+    if (!pushResult.ok) {
+      throw new Error(`Funding balance refreshed locally, but the dashboard update failed: ${pushResult.error ?? "Fibscope rejected the report"}`);
+    }
+  }
+  const funding = report.funding ?? {};
+  const wallet = report.fundingWallet ?? {};
+  return {
+    ok: true,
+    action: "REFRESH_FUNDING_BALANCE",
+    message: "Funding balance updated from the agent.",
+    checkedAt: report.collectedAt ?? Date.now(),
+    funding,
+    fundingWallet: wallet,
+    push: {
+      ok: Boolean(pushResult.ok),
+      status: pushResult.status,
+      nodeId: pushResult.payload?.nodeId,
+    },
+  };
+}
+
+async function acknowledgePaymentIntent(config, params, options = {}) {
+  const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
+  const nodePubkey = normalizePeerPubkey(readNodeId(info));
+  const assetType = textValue(params.asset ?? params.assetType) || "CKB";
+  const requesterAddress = textValue(params.requesterAddress);
+  const recipients = paymentIntentRecipients(params);
+  const amount = textValue(params.amount) || totalRecipientAmount(recipients) || "0";
+  const targetType = recipients[0]?.targetType ?? (textValue(params.targetType).toLowerCase() === "wallet" ? "wallet" : "node");
+  const recipientAddress = (recipients[0]?.recipientAddress ?? textValue(params.recipientAddress)) || undefined;
+  const fee = params.fee && typeof params.fee === "object" ? params.fee : undefined;
+  if (recipients.some((recipient) => recipient.targetType === "wallet" && !recipient.recipientAddress)) throw new Error("Payment intent is missing a recipient wallet address.");
+  return {
+    ok: true,
+    action: options.action ?? "PAYMENT_INTENT",
+    mode: options.mode ?? "Internal route intent",
+    message: options.message ?? "Internal payment route intent acknowledged by the node agent.",
+    intentId: textValue(params.intentId) || undefined,
+    requesterAddress: requesterAddress || undefined,
+    amount,
+    assetType,
+    targetType,
+    recipientAddress,
+    recipients,
+    fee,
+    note: textValue(params.note) || undefined,
+    node: {
+      pubkey: nodePubkey,
+      version: textValue(info?.version) || undefined,
+    },
+    acknowledgedAt: Date.now(),
+  };
+}
+
+async function sendFiberPayment(config, params) {
+  const invoice = firstTextValue(params.invoice, params.fiberInvoice, params.paymentRequest, params.payment_request);
+  const targetPubkey = firstTextValue(params.targetPubkey, params.target_pubkey, params.destinationNode, params.destination_node, params.pubkey);
+  const amount = firstTextValue(params.amountShannons, params.amount, params.value);
+  const maxFeeAmount = firstTextValue(params.maxFeeAmount, params.max_fee_amount);
+  const request = {};
+  if (invoice) request.invoice = invoice;
+  else {
+    if (!targetPubkey) throw new Error("Fiber send_payment requires either an invoice/payment request or a target pubkey.");
+    if (!amount) throw new Error("Fiber keysend payment requires an amount.");
+    request.target_pubkey = normalizePeerPubkey(targetPubkey);
+    request.keysend = boolValue(params.keysend, true);
+  }
+  if (amount) request.amount = quantity(amount);
+  if (maxFeeAmount) request.max_fee_amount = quantity(maxFeeAmount);
+  const result = await rpcCall(config.fiberRpcUrl, "send_payment", [request], config.timeoutMs);
+  return {
+    ok: true,
+    action: "SEND_PAYMENT",
+    mode: "Real Fiber invoice payment",
+    paymentId: textValue(params.paymentId) || undefined,
+    quoteId: textValue(params.quoteId) || undefined,
+    candidateId: textValue(params.candidateId) || undefined,
+    invoice: invoice || undefined,
+    targetPubkey: targetPubkey || undefined,
+    amount: amount || undefined,
+    assetType: textValue(params.assetType ?? params.asset) || "CKB",
+    result,
+    sentAt: Date.now(),
+  };
+}
+
+async function acceptApiWalletPayment(runtime, params) {
+  const config = runtime.config ?? runtime;
+  const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
+  const depositTxHash = textValue(params.depositTxHash);
+  const deposit = depositTxHash ? await waitForCkbTransaction(config, depositTxHash, params) : undefined;
+  const payout = await executeProviderWalletPayout(config, {
+    receiverWallet: textValue(params.receiverWallet),
+    amount: textValue(params.amountShannons ?? params.amount),
+    paymentId: textValue(params.paymentId),
+    depositTxHash,
+  });
+  let refreshed;
+  if (typeof runtime.collect === "function" && typeof runtime.push === "function") {
+    refreshed = await pushWithRegistrationRetry(runtime, await runtime.collect(), {
+      intent: "api-wallet-payment-completed",
+      retryOnRateLimit: true,
+      maxRateLimitRetries: 1,
+    }).catch((error) => ({ ok: false, error: message(error) }));
+  }
+  return {
+    ok: true,
+    action: "API_WALLET_PAYMENT",
+    mode: "API-managed wallet payment direct payout",
+    paymentStatus: "completed",
+    message: "Sender deposit is confirmed and the provider funding wallet payout to the recipient wallet was broadcast.",
+    paymentId: textValue(params.paymentId) || undefined,
+    quoteId: textValue(params.quoteId) || undefined,
+    candidateId: textValue(params.candidateId) || undefined,
+    senderWallet: textValue(params.senderWallet) || undefined,
+    receiverWallet: textValue(params.receiverWallet) || undefined,
+    amount: textValue(params.amountShannons ?? params.amount) || undefined,
+    totalDebit: textValue(params.totalDebit) || undefined,
+    feeAmount: textValue(params.feeAmount) || undefined,
+    assetType: textValue(params.assetType ?? params.asset) || "CKB",
+    providerId: textValue(params.providerId) || undefined,
+    providerName: textValue(params.providerName) || undefined,
+    serviceDepositAddress: textValue(params.serviceDepositAddress) || undefined,
+    depositTxHash: depositTxHash || undefined,
+    depositAmount: textValue(params.depositAmount) || undefined,
+    deposit,
+    payout,
+    fundingRefresh: refreshed,
+    routeExecution: {
+      status: "direct_wallet_payout",
+      reason: "Plain CKB wallet recipients are not Fiber channel endpoints, so this executor pays the recipient wallet on-chain from the provider funding wallet after confirming the payer deposit.",
+    },
+    node: {
+      pubkey: normalizePeerPubkey(readNodeId(info)),
+      version: textValue(info?.version) || undefined,
+    },
+    completedAt: Date.now(),
+  };
+}
+
+async function acceptApiNodePayment(runtime, params) {
+  const config = runtime.config ?? runtime;
+  const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
+  const depositTxHash = textValue(params.depositTxHash);
+  const deposit = depositTxHash ? await waitForCkbTransaction(config, depositTxHash, params) : undefined;
+  const targetPubkey = normalizePeerPubkey(firstTextValue(params.receiverNode, params.targetPubkey, params.destinationNode, params.pubkey));
+  const fiberPayment = await sendFiberPayment(config, {
+    ...params,
+    targetPubkey,
+    amountShannons: textValue(params.amountShannons ?? params.amount),
+    keysend: true,
+  });
+  let refreshed;
+  if (typeof runtime.collect === "function" && typeof runtime.push === "function") {
+    refreshed = await pushWithRegistrationRetry(runtime, await runtime.collect(), {
+      intent: "api-node-payment-completed",
+      retryOnRateLimit: true,
+      maxRateLimitRetries: 1,
+    }).catch((error) => ({ ok: false, error: message(error) }));
+  }
+  return {
+    ok: true,
+    action: "API_NODE_PAYMENT",
+    mode: "API-managed Fiber node payment",
+    paymentStatus: "completed",
+    message: "Sender deposit is confirmed and the provider agent submitted the Fiber payment to the recipient node.",
+    paymentId: textValue(params.paymentId) || undefined,
+    quoteId: textValue(params.quoteId) || undefined,
+    candidateId: textValue(params.candidateId) || undefined,
+    senderWallet: textValue(params.senderWallet) || undefined,
+    receiverNode: targetPubkey,
+    targetPubkey,
+    amount: textValue(params.amountShannons ?? params.amount) || undefined,
+    totalDebit: textValue(params.totalDebit) || undefined,
+    feeAmount: textValue(params.feeAmount) || undefined,
+    assetType: textValue(params.assetType ?? params.asset) || "CKB",
+    providerId: textValue(params.providerId) || undefined,
+    providerName: textValue(params.providerName) || undefined,
+    serviceDepositAddress: textValue(params.serviceDepositAddress) || undefined,
+    depositTxHash: depositTxHash || undefined,
+    depositAmount: textValue(params.depositAmount) || undefined,
+    deposit,
+    fiberPayment,
+    fundingRefresh: refreshed,
+    routeExecution: {
+      status: "fiber_send_payment",
+      reason: "Fiber node recipients are channel endpoints, so the provider uses outbound Fiber liquidity after confirming the payer deposit.",
+    },
+    node: {
+      pubkey: normalizePeerPubkey(readNodeId(info)),
+      version: textValue(info?.version) || undefined,
+    },
+    completedAt: Date.now(),
+  };
+}
+
+async function waitForCkbTransaction(config, txHash, params = {}) {
+  const rpcUrl = resolveCkbIndexerUrl(config);
+  if (!rpcUrl) throw new Error("No CKB RPC URL is configured for deposit confirmation.");
+  const timeoutMs = positiveNumber(params.depositConfirmTimeoutMs ?? config.depositConfirmTimeoutMs, 2 * 60_000);
+  const pollMs = positiveNumber(params.depositConfirmPollMs ?? config.depositConfirmPollMs, 5_000);
+  const startedAt = Date.now();
+  let lastStatus = "unknown";
+  while (Date.now() - startedAt <= timeoutMs) {
+    const response = await rpcCall(rpcUrl, "get_transaction", [txHash], config.ckbRpcTimeoutMs ?? config.timeoutMs ?? 10_000);
+    const status = textValue(response?.tx_status?.status ?? response?.txStatus?.status);
+    if (status) lastStatus = status;
+    if (status === "committed") {
+      return {
+        txHash,
+        status,
+        blockHash: textValue(response?.tx_status?.block_hash ?? response?.txStatus?.blockHash) || undefined,
+        blockNumber: textValue(response?.tx_status?.block_number ?? response?.txStatus?.blockNumber) || undefined,
+        confirmedAt: Date.now(),
+      };
+    }
+    const reason = textValue(response?.tx_status?.reason ?? response?.txStatus?.reason);
+    if (status === "rejected") throw new Error(`Deposit transaction was rejected${reason ? `: ${reason}` : "."}`);
+    await sleep(pollMs);
+  }
+  throw new Error(`Deposit transaction ${shortText(txHash, 10, 8)} was not committed within ${timeoutMs}ms. Last status: ${lastStatus}.`);
+}
+
+async function executeProviderWalletPayout(config, input) {
+  const receiverWallet = textValue(input.receiverWallet);
+  if (!receiverWallet) throw new Error("API wallet payment is missing a recipient wallet address.");
+  const amountShannons = amountBigInt(input.amount);
+  if (amountShannons <= 0n) throw new Error("API wallet payment payout amount must be positive.");
+  const walletPath = resolveFundingWalletPath(config);
+  if (!walletPath || !existsSync(walletPath)) throw new Error("Provider funding wallet is not linked, so recipient payout cannot be signed.");
+  const providerWallet = await readFundingWallet(walletPath, config.chain ?? "testnet");
+  const rpcUrl = resolveCkbIndexerUrl(config);
+  if (!rpcUrl) throw new Error("No CKB RPC URL is configured for recipient payout.");
+  const cells = await collectProviderSpendableCells({
+    rpcUrl,
+    lockScript: providerWallet.lockScript,
+    targetCapacity: amountShannons + MIN_SECP_CELL_CAPACITY + 1_000_000n,
+    preferredTxHash: textValue(input.depositTxHash),
+    config,
+  });
+  const built = buildSignedCkbPayoutTransaction({
+    cells,
+    recipientLock: addressToScript(receiverWallet),
+    changeLock: providerWallet.sdkLockScript,
+    privateKey: providerWallet.privateKeyHex,
+    amountShannons,
+    chain: config.chain ?? "testnet",
+  });
+  const txHash = await rpcCall(rpcUrl, "send_transaction", [toRpcTransaction(built.transaction)], config.ckbRpcTimeoutMs ?? config.timeoutMs ?? 10_000);
+  return {
+    status: "broadcast",
+    txHash,
+    paymentId: textValue(input.paymentId) || undefined,
+    receiverWallet,
+    amount: amountShannons.toString(),
+    amountLabel: ckbText(amountShannons),
+    feeShannons: built.fee.toString(),
+    feeLabel: ckbText(built.fee),
+    inputCapacity: built.inputCapacity.toString(),
+    changeCapacity: built.changeCapacity.toString(),
+    inputCount: cells.length,
+    rpcUrl,
+  };
+}
+
+async function collectProviderSpendableCells({ rpcUrl, lockScript, targetCapacity, preferredTxHash, config }) {
+  const searchKey = {
+    script: lockScript,
+    script_type: "lock",
+  };
+  const cells = [];
+  let cursor;
+  const limit = hexQuantity(positiveNumber(config.ckbCellPageSize, 100));
+  const maxPages = Math.max(1, Math.min(50, Math.trunc(positiveNumber(config.ckbCellMaxPages, 20))));
+  for (let page = 0; page < maxPages; page += 1) {
+    const params = [searchKey, "asc", limit];
+    if (cursor) params.push(cursor);
+    const response = await rpcCall(rpcUrl, "get_cells", params, config.ckbRpcTimeoutMs ?? config.timeoutMs ?? 10_000);
+    const objects = Array.isArray(response?.objects) ? response.objects : [];
+    for (const cell of objects) {
+      const output = cell?.output ?? cell?.cell_output ?? {};
+      const data = textValue(cell?.output_data ?? cell?.outputData) || "0x";
+      if (output.type || data !== "0x") continue;
+      const outPoint = normalizeOutPoint(cell?.out_point ?? cell?.outPoint);
+      const capacity = amountBigInt(output.capacity);
+      if (!outPoint || capacity <= 0n) continue;
+      cells.push({ outPoint, capacity });
+    }
+    const nextCursor = typeof response?.last_cursor === "string" && response.last_cursor !== cursor ? response.last_cursor : undefined;
+    if (!objects.length || !nextCursor || nextCursor === "0x") break;
+    cursor = nextCursor;
+  }
+  const preferred = textValue(preferredTxHash).toLowerCase();
+  cells.sort((left, right) => {
+    const leftPreferred = preferred && left.outPoint.txHash.toLowerCase() === preferred ? 0 : 1;
+    const rightPreferred = preferred && right.outPoint.txHash.toLowerCase() === preferred ? 0 : 1;
+    return leftPreferred - rightPreferred;
+  });
+  const selected = [];
+  let total = 0n;
+  for (const cell of cells) {
+    selected.push(cell);
+    total += cell.capacity;
+    if (total >= targetCapacity) break;
+  }
+  if (total < targetCapacity) {
+    throw new Error(`Provider funding wallet has insufficient spendable CKB for recipient payout. Need ${ckbText(targetCapacity)}, found ${ckbText(total)}.`);
+  }
+  return selected;
+}
+
+function buildSignedCkbPayoutTransaction(input) {
+  const inputCapacity = input.cells.reduce((total, cell) => total + cell.capacity, 0n);
+  if (inputCapacity <= input.amountShannons) throw new Error("Provider funding wallet does not have enough CKB for payout and network fee.");
+  let changeCapacity = inputCapacity - input.amountShannons;
+  let fee = 0n;
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    if (changeCapacity < MIN_SECP_CELL_CAPACITY) {
+      throw new Error(`Provider funding wallet cannot create a valid CKB change cell after payout. It needs at least ${ckbText(MIN_SECP_CELL_CAPACITY - changeCapacity)} more change capacity.`);
+    }
+    const unsigned = ckbPayoutTransaction(input.cells, input.recipientLock, input.changeLock, input.amountShannons, changeCapacity, input.chain);
+    fee = ckbTransactionFee(unsigned, DEFAULT_PAYOUT_FEE_RATE);
+    const nextChange = inputCapacity - input.amountShannons - fee;
+    if (nextChange < 0n) throw new Error("Provider funding wallet does not have enough CKB for payout and network fee.");
+    if (nextChange === changeCapacity) {
+      return {
+        transaction: signCkbTransaction(unsigned, input.privateKey),
+        fee,
+        inputCapacity,
+        changeCapacity,
+      };
+    }
+    changeCapacity = nextChange;
+  }
+  const unsigned = ckbPayoutTransaction(input.cells, input.recipientLock, input.changeLock, input.amountShannons, changeCapacity, input.chain);
+  return {
+    transaction: signCkbTransaction(unsigned, input.privateKey),
+    fee,
+    inputCapacity,
+    changeCapacity,
+  };
+}
+
+function ckbPayoutTransaction(cells, recipientLock, changeLock, amountShannons, changeCapacity, chain) {
+  return {
+    version: "0x0",
+    cellDeps: [{
+      outPoint: secpCellDepOutPoint(chain),
+      depType: systemScripts.SECP256K1_BLAKE160.depType,
+    }],
+    headerDeps: [],
+    inputs: cells.map((cell) => ({
+      since: "0x0",
+      previousOutput: cell.outPoint,
+    })),
+    outputs: [
+      {
+        capacity: quantity(amountShannons),
+        lock: recipientLock,
+        type: null,
+      },
+      {
+        capacity: quantity(changeCapacity),
+        lock: changeLock,
+        type: null,
+      },
+    ],
+    outputsData: ["0x", "0x"],
+    witnesses: cells.map(() => "0x"),
+  };
+}
+
+function ckbTransactionFee(transaction, feeRate) {
+  const placeholder = {
+    ...transaction,
+    witnesses: signingPlaceholderWitnesses(transaction.inputs.length),
+  };
+  return BigInt(calculateTransactionFee(BigInt(getTransactionSize(placeholder)), feeRate));
+}
+
+function signCkbTransaction(transaction, privateKey) {
+  const witnessesForSigning = signingPlaceholderWitnesses(transaction.inputs.length);
+  const message = ckbSighashAllMessage(transaction, witnessesForSigning);
+  const signature = new ECPair(privateKey).signRecoverable(message);
+  return {
+    ...transaction,
+    witnesses: [
+      serializeWitnessArgs({ lock: signature, inputType: "", outputType: "" }),
+      ...transaction.inputs.slice(1).map(() => "0x"),
+    ],
+  };
+}
+
+function signingPlaceholderWitnesses(inputCount) {
+  if (inputCount <= 0) return [];
+  return [
+    serializeWitnessArgs({ lock: EMPTY_SECP_SIG, inputType: "", outputType: "" }),
+    ...Array.from({ length: inputCount - 1 }, () => "0x"),
+  ];
+}
+
+function ckbSighashAllMessage(transaction, witnesses) {
+  const txHash = rawTransactionToHash({
+    version: transaction.version,
+    cellDeps: transaction.cellDeps,
+    headerDeps: transaction.headerDeps,
+    inputs: transaction.inputs,
+    outputs: transaction.outputs,
+    outputsData: transaction.outputsData,
+  });
+  const hasher = blake2b(32, null, null, PERSONAL);
+  hasher.update(hexToBytes(txHash));
+  for (const witness of witnesses) {
+    const bytes = hexToBytes(witness);
+    hasher.update(hexToBytes(toUint64Le(BigInt(bytes.length))));
+    hasher.update(bytes);
+  }
+  return bytesToHex(hasher.digest("binary"));
+}
+
+function toRpcTransaction(transaction) {
+  return {
+    version: transaction.version,
+    cell_deps: transaction.cellDeps.map((dep) => ({
+      out_point: {
+        tx_hash: dep.outPoint.txHash,
+        index: dep.outPoint.index,
+      },
+      dep_type: dep.depType === "depGroup" ? "dep_group" : dep.depType,
+    })),
+    header_deps: transaction.headerDeps,
+    inputs: transaction.inputs.map((input) => ({
+      since: input.since,
+      previous_output: {
+        tx_hash: input.previousOutput.txHash,
+        index: input.previousOutput.index,
+      },
+    })),
+    outputs: transaction.outputs.map((output) => ({
+      capacity: output.capacity,
+      lock: toRpcScript(output.lock),
+      type: output.type,
+    })),
+    outputs_data: transaction.outputsData,
+    witnesses: transaction.witnesses,
+  };
+}
+
+function toRpcScript(script) {
+  return {
+    code_hash: script.codeHash ?? script.code_hash,
+    hash_type: script.hashType ?? script.hash_type,
+    args: script.args,
+  };
+}
+
+function secpCellDepOutPoint(chain) {
+  return String(chain).toLowerCase() === "mainnet"
+    ? systemScripts.SECP256K1_BLAKE160.mainnetOutPoint
+    : systemScripts.SECP256K1_BLAKE160.testnetOutPoint;
+}
+
+function normalizeOutPoint(value) {
+  if (!value || typeof value !== "object") return undefined;
+  const txHash = textValue(value.tx_hash ?? value.txHash);
+  const index = textValue(value.index);
+  return txHash && index ? { txHash, index } : undefined;
+}
+
+function paymentIntentRecipients(params) {
+  const rawRecipients = Array.isArray(params.recipients) ? params.recipients.slice(0, 12) : [];
+  const fallbackTargetType = textValue(params.targetType).toLowerCase() === "wallet" ? "wallet" : "node";
+  const fallback = {
+    targetType: fallbackTargetType,
+    recipientAddress: textValue(params.recipientAddress) || undefined,
+    amount: textValue(params.amount) || undefined,
+  };
+  const recipients = rawRecipients.length ? rawRecipients : [fallback];
+  return recipients.map((item) => {
+    const record = item && typeof item === "object" ? item : {};
+    const targetType = textValue(record.targetType).toLowerCase() === "wallet" ? "wallet" : "node";
+    const recipientAddress = textValue(record.recipientAddress ?? record.address) || undefined;
+    const amount = textValue(record.amount) || fallback.amount;
+    return {
+      targetType,
+      recipientAddress,
+      amount,
+    };
+  });
+}
+
+function totalRecipientAmount(recipients) {
+  const shannons = recipients.reduce((total, recipient) => total + paymentAmountToShannons(recipient.amount), 0n);
+  if (shannons <= 0n) return "";
+  const whole = shannons / 100000000n;
+  const fraction = (shannons % 100000000n).toString().padStart(8, "0").replace(/0+$/, "");
+  return fraction ? `${whole}.${fraction}` : String(whole);
+}
+
+function paymentAmountToShannons(value) {
+  const text = textValue(value);
+  if (!/^[0-9]+(?:\.[0-9]{1,8})?$/.test(text)) return 0n;
+  const [whole, fraction = ""] = text.split(".");
+  return BigInt(whole) * 100000000n + BigInt(fraction.padEnd(8, "0"));
+}
+
+async function postCommandResult(config, body) {
+  const resultUrl = config.commandResultUrl ?? config.reportUrl.replace(/\/report\/?$/, "/command-result");
+  let response;
+  try {
+    response = await fetch(resultUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-agent-token": config.agentToken,
+      },
+      body: stringify(body),
+    });
+  } catch (error) {
+    throw new Error(`Command result failed at ${resultUrl}: ${message(error)}`);
+  }
+  if (!response.ok) {
+    const payload = parsePayload(await response.text());
+    throw new Error(`Command result failed: ${describeAgentHttpError(payload, `HTTP_${response.status}`)}`);
+  }
+  return parsePayload(await response.text());
+}
+
+async function openFiberChannel(config, params) {
+  const peer = resolveCommandPeer(params);
+  const pubkey = normalizePeerPubkey(peer.pubkey);
+  await assertNotLocalPeer(config, pubkey);
+  const openRequest = {
+    pubkey,
+    funding_amount: fundingAmount(params),
+    public: boolValue(params.public ?? params.publicChannel, true),
+  };
+  if (params.oneWay !== undefined || params.one_way !== undefined) openRequest.one_way = boolValue(params.oneWay ?? params.one_way, false);
+  if (params.fundingUdtTypeScript ?? params.funding_udt_type_script) openRequest.funding_udt_type_script = params.fundingUdtTypeScript ?? params.funding_udt_type_script;
+  if (params.commitmentFeeRate ?? params.commitment_fee_rate) openRequest.commitment_fee_rate = quantity(params.commitmentFeeRate ?? params.commitment_fee_rate);
+  if (params.fundingFeeRate ?? params.funding_fee_rate) openRequest.funding_fee_rate = quantity(params.fundingFeeRate ?? params.funding_fee_rate);
+  if (params.tlcExpiryDelta ?? params.tlc_expiry_delta) openRequest.tlc_expiry_delta = quantity(params.tlcExpiryDelta ?? params.tlc_expiry_delta);
+  if (params.tlcMinimumValue ?? params.tlc_minimum_value) openRequest.tlc_minimum_value = quantity(params.tlcMinimumValue ?? params.tlc_minimum_value);
+  if (params.tlcFeeProportionalMillionths ?? params.tlc_fee_proportional_millionths) {
+    openRequest.tlc_fee_proportional_millionths = quantity(params.tlcFeeProportionalMillionths ?? params.tlc_fee_proportional_millionths);
+  }
+
+  const fundingCheck = await assertChannelFundingAvailable(config, openRequest.funding_amount);
+  let connectResult;
+  const connectFirst = boolValue(params.connectFirst, true) && !boolValue(params.skipConnect, false);
+  if (connectFirst) {
+    connectResult = await ensurePeerConnected(config, peer, pubkey);
+  }
+  const openResult = await openChannelWhenPeerReady(config, peer, pubkey, openRequest, params);
+  let channelWatch;
+  if (!boolValue(params.wait, false) && !boolValue(params.waitUntilReady, false)) {
+    channelWatch = await watchForImmediateChannelFailure(
+      config.fiberRpcUrl,
+      pubkey,
+      positiveNumber(params.failureWatchMs ?? config.channelFailureWatchMs, DEFAULT_CHANNEL_FAILURE_WATCH_MS),
+      positiveNumber(params.failurePollMs ?? params.pollMs ?? config.channelFailurePollMs, DEFAULT_CHANNEL_FAILURE_POLL_MS),
+    );
+  }
+  const result = {
+    ok: true,
+    action: "OPEN_CHANNEL",
+    peerPubkey: pubkey,
+    peer: peer.meta,
+    peerAddress: peer.address,
+    fundingAmount: openRequest.funding_amount,
+    public: openRequest.public,
+    fundingCheck,
+    connectResult,
+    openResult,
+    channelWatch,
+  };
+  if (boolValue(params.wait, false) || boolValue(params.waitUntilReady, false)) {
+    result.channel = await waitForChannel(config.fiberRpcUrl, pubkey, positiveNumber(params.waitTimeoutMs, 20 * 60_000), positiveNumber(params.pollMs, 10_000));
+  }
+  return result;
+}
+
+async function settleFiberChannel(runtime, params) {
+  const config = runtime.config ?? runtime;
+  const channelId = firstTextValue(params.channelId, params.channel_id, params.id);
+  if (!channelId) throw new Error("Channel settlement requires a channel id.");
+
+  const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
+  const closeScript = params.closeScript ?? params.close_script ?? info?.default_funding_lock_script;
+  if (!closeScript || typeof closeScript !== "object") {
+    throw new Error("Fiber did not report a default funding lock script for channel settlement.");
+  }
+
+  const force = boolValue(params.force, false);
+  const feeRate = params.feeRate ?? params.fee_rate ?? "1000";
+  const before = await findChannelById(config.fiberRpcUrl, channelId, config.timeoutMs).catch(() => undefined);
+  const request = force
+    ? { channel_id: channelId, force: true }
+    : {
+        channel_id: channelId,
+        close_script: closeScript,
+        fee_rate: quantity(feeRate),
+        force: false,
+      };
+  const result = await rpcCall(config.fiberRpcUrl, "shutdown_channel", [request], config.timeoutMs);
+  const after = await findChannelById(config.fiberRpcUrl, channelId, config.timeoutMs).catch(() => undefined);
+
+  let refreshed;
+  if (typeof runtime.collect === "function" && typeof runtime.push === "function") {
+    refreshed = await pushWithRegistrationRetry(runtime, await runtime.collect(), {
+      intent: "channel-settlement",
+      retryOnRateLimit: true,
+      maxRateLimitRetries: 1,
+    }).catch((error) => ({ ok: false, error: message(error) }));
+  }
+
+  return {
+    ok: true,
+    action: "SETTLE_CHANNEL",
+    mode: "Close channel to funding wallet",
+    message: "Fiber does not expose a splice-out or withdraw-channel RPC on this node. Issued shutdown_channel; when the close transaction confirms, this node's local channel balance returns to the funding wallet lock.",
+    channelId,
+    settlement: {
+      settlementMethod: "shutdown_channel",
+      spliceOutSupported: false,
+      withdrawSupported: false,
+      closeToFundingWallet: true,
+      force,
+      feeRate: force ? undefined : quantity(feeRate),
+      closeScript: force ? undefined : closeScript,
+    },
+    before,
+    after,
+    result,
+    refresh: refreshed,
+  };
+}
+
+async function findChannelById(rpcUrl, channelId, timeoutMs) {
+  const response = await rpcCall(rpcUrl, "list_channels", [{ include_closed: true }], timeoutMs);
+  const channels = Array.isArray(response?.channels) ? response.channels : Array.isArray(response) ? response : [];
+  const normalized = channelId.toLowerCase();
+  return channels.find((channel) => textValue(channel?.channel_id ?? channel?.channelId ?? channel?.id).toLowerCase() === normalized);
+}
+
+async function assertNotLocalPeer(config, pubkey) {
+  try {
+    const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
+    const localPubkey = normalizePeerPubkey(readNodeId(info));
+    if (localPubkey && peerKey(localPubkey) === peerKey(pubkey)) {
+      throw new Error("Cannot connect a Fiber node to itself. Use a peer token from a different node.");
+    }
+  } catch (error) {
+    if (message(error).includes("Cannot connect a Fiber node to itself")) throw error;
+  }
+}
+
+async function ensurePeerConnected(config, peer, pubkey) {
+  let lookupWarning;
+  let knownPeer;
+  try {
+    knownPeer = await findPeerByPubkey(config, pubkey);
+  } catch (error) {
+    lookupWarning = message(error);
+  }
+
+  if (knownPeer?.connected) {
+    return {
+      skipped: true,
+      reason: "Peer is already connected.",
+      peer: knownPeer,
+    };
+  }
+
+  const address = peer.address || knownPeer?.address;
+  if (!address && !knownPeer?.connected) {
+    throw new Error(`Peer address is required to connect ${shortText(pubkey, 10, 8)}. Paste the peer multiaddr or choose a public node that advertises a dial address.`);
+  }
+  try {
+    const result = await rpcCall(config.fiberRpcUrl, "connect_peer", [omitUndefined({ pubkey, address })], config.timeoutMs);
+    return {
+      skipped: false,
+      deduped: Boolean(knownPeer),
+      peer: knownPeer,
+      lookupWarning,
+      result,
+    };
+  } catch (error) {
+    const warning = message(error);
+    if (isPeerAlreadyConnectedError(warning)) {
+      return {
+        skipped: true,
+        reason: "Fiber RPC reported that this peer is already connected.",
+        peer: knownPeer,
+        warning,
+      };
+    }
+    if (!address && peer.meta?.source === "fibscope-token") {
+      throw new Error("Fibscope peer token is missing a dial address. Ask the peer to restart their agent with the latest code, wait for a fresh report, then copy a new peer token.");
+    }
+    if (knownPeer) {
+      throw new Error(`Peer ${shortText(pubkey, 10, 8)} is known but could not be reconnected: ${warning}`);
+    }
+    throw error;
+  }
+}
+
+async function assertChannelFundingAvailable(config, requestedAmount) {
+  if (boolValue(config.skipChannelFundingPreflight, false)) {
+    return { skipped: true, reason: "Channel funding preflight disabled." };
+  }
+  const funding = await collectFundingState(config);
+  const wallet = await collectFundingWalletState(config, funding);
+  const requested = amountBigInt(requestedAmount);
+  const reserve = channelFundingReserve(config);
+  const required = requested + reserve;
+  const available = amountBigInt(funding.availableCapacity);
+  const walletStatus = String(wallet.status ?? "").toLowerCase();
+
+  if (walletStatus !== "linked") {
+    throw new Error(channelWalletNotReadyMessage(wallet));
+  }
+
+  if (String(funding.status ?? "").toLowerCase() !== "ready") {
+    throw new Error(funding.error
+      ? `Funding balance unavailable. ${funding.error}`
+      : "Funding balance unavailable. The agent could not verify spendable node wallet capacity, so channel creation was stopped.");
+  }
+
+  if (available < required) {
+    throw new Error(`Insufficient funding balance. Opening this channel needs about ${ckbText(required)} (${ckbText(requested)} channel capacity plus ${ckbText(reserve)} fee reserve), but this node wallet only has ${ckbText(available)} spendable. Fund the node wallet or lower the channel amount.`);
+  }
+
+  return {
+    ok: true,
+    source: funding.source,
+    checkedAt: funding.checkedAt,
+    requestedCapacity: requested.toString(),
+    feeReserve: reserve.toString(),
+    requiredCapacity: required.toString(),
+    availableCapacity: available.toString(),
+    walletStatus: wallet.status,
+    walletAddress: wallet.address,
+  };
+}
+
+function channelWalletNotReadyMessage(wallet) {
+  const status = String(wallet?.status ?? "missing").toLowerCase();
+  if (status === "missing") return "Funding wallet is not linked. Create or link a local funding wallet before opening a channel.";
+  if (status === "pending_restart") return "Funding wallet is saved, but FNN is still using another key. Restart FNN before opening a channel.";
+  if (status === "invalid") return `Funding wallet is invalid. ${wallet?.error ? `${wallet.error}` : "Repair or replace it in Agent Setup before opening a channel."}`;
+  if (status === "unavailable") return `Funding wallet status is unavailable. ${wallet?.error ? `${wallet.error}` : "Start or bind the agent to the correct FNN instance."}`;
+  return `Funding wallet is not ready (${status}). Set up the local funding wallet before opening a channel.`;
+}
+
+async function openChannelWhenPeerReady(config, peer, pubkey, openRequest, params) {
+  const timeoutMs = positiveNumber(params.openTimeoutMs ?? params.peerReadyTimeoutMs ?? config.channelOpenTimeoutMs ?? config.peerReadyTimeoutMs, DEFAULT_CHANNEL_OPEN_TIMEOUT_MS);
+  const retryMs = positiveNumber(params.openRetryMs ?? params.peerReadyPollMs ?? config.channelOpenRetryMs ?? config.peerReadyPollMs, DEFAULT_CHANNEL_OPEN_RETRY_MS);
+  const startedAt = Date.now();
+  const deadline = Date.now() + timeoutMs;
+  let attempts = 0;
+  let lastPeer;
+  let lastError;
+  let announcedWait = false;
+
+  while (Date.now() <= deadline) {
+    attempts += 1;
+    try {
+      const result = await rpcCall(config.fiberRpcUrl, "open_channel", [openRequest], config.timeoutMs);
+      return {
+        ...asObject(result),
+        attempts,
+        peerReadyWaitMs: Math.max(0, Date.now() - startedAt),
+      };
+    } catch (error) {
+      const detail = message(error);
+      if (isInsufficientFundingError(detail)) {
+        throw new Error(`Channel funding failed: insufficient node wallet capacity. ${cleanFundingFailureText(detail)}`);
+      }
+      if (!isPeerFeaturePendingError(detail)) throw error;
+      lastError = detail;
+      if (!announcedWait) {
+        console.log(formatCliBlock({
+          title: "Fiber handshake",
+          status: "waiting",
+          tone: "info",
+          rows: [
+            ["Peer", shortText(pubkey, 10, 8)],
+            ["Timeout", `${timeoutMs} ms`],
+            ["Retry", `${retryMs} ms`],
+            ["Reason", "FNN has not received the peer Init/features message yet."],
+          ],
+        }));
+        announcedWait = true;
+      }
+      lastPeer = await findPeerByPubkey(config, pubkey).catch(() => lastPeer);
+      if (Date.now() + retryMs > deadline) break;
+      if (!lastPeer && peer.address) {
+        await ensurePeerConnected(config, peer, pubkey).catch(() => undefined);
+      }
+      await sleep(retryMs);
+    }
+  }
+
+  const peerSummary = lastPeer
+    ? `Last peer state: ${JSON.stringify(lastPeer)}`
+    : "The peer never appeared in list_peers during the wait window.";
+  throw new Error(`Peer connected, but Fiber handshake is not ready yet. FNN is still waiting for the peer Init/features message for ${shortText(pubkey, 10, 8)} after ${timeoutMs}ms. ${peerSummary} Last RPC error: ${lastError ?? "none"}`);
+}
+
+async function findPeerByPubkey(config, pubkey) {
+  const raw = await rpcCall(config.fiberRpcUrl, "list_peers", [], config.timeoutMs);
+  const normalizedPubkey = peerKey(pubkey);
+  return extractPeerList(raw)
+    .map(normalizePeer)
+    .find((peer) => peerKey(peer.peerId) === normalizedPubkey || peerKey(peer.pubkey) === normalizedPubkey);
+}
+
+function extractPeerList(raw) {
+  if (Array.isArray(raw)) return raw;
+  if (!raw || typeof raw !== "object") return [];
+  for (const key of ["peers", "peer_states", "items", "list"]) {
+    const value = raw[key];
+    if (Array.isArray(value)) return value;
+  }
+  return [];
+}
+
+function normalizePeer(peer) {
+  const status = textValue(peer?.status ?? peer?.state ?? peer?.connection_state);
+  return {
+    peerId: textValue(peer?.peerId ?? peer?.peer_id ?? peer?.nodeId ?? peer?.node_id ?? peer?.id ?? peer?.pubkey ?? peer?.public_key),
+    pubkey: textValue(peer?.pubkey ?? peer?.public_key ?? peer?.nodeId ?? peer?.node_id),
+    connected: booleanMaybe(peer?.connected ?? peer?.is_connected ?? peer?.online) ?? (status ? peerStatusConnected(status) : true),
+    address: textValue(peer?.address ?? peer?.addr ?? peer?.multiaddr ?? peer?.multi_addr) || firstString(peer?.addresses),
+  };
+}
+
+function peerKey(value) {
+  return String(value ?? "").trim().replace(/^0x/i, "").toLowerCase();
+}
+
+function booleanMaybe(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
+    if (["false", "0", "no", "n", "off"].includes(normalized)) return false;
+  }
+  return undefined;
+}
+
+function peerStatusConnected(value) {
+  return ["connected", "online", "active", "established", "ready"].includes(String(value ?? "").trim().toLowerCase());
+}
+
+function isPeerAlreadyConnectedError(value) {
+  return /already\s+(connected|exists|known)|duplicate\s+peer|peer\s+.*connected/i.test(String(value ?? ""));
+}
+
+function isPeerFeaturePendingError(value) {
+  return /feature\s+not\s+found|waiting\s+for\s+peer\s+to\s+send\s+init\s+message/i.test(String(value ?? ""));
+}
+
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : { value };
+}
+
+function firstString(value) {
+  if (!Array.isArray(value)) return "";
+  return textValue(value.find((item) => typeof item === "string" && item.trim()));
+}
+
+async function loadConfig(configPath, options = {}) {
+  let config;
+  let label = configPath;
+  if (!existsSync(configPath) && hasEnvConfig()) {
+    config = {
+      pushIntervalMs: Number(process.env.FIBSCOPE_AGENT_PUSH_INTERVAL_MS ?? DEFAULT_PUSH_INTERVAL_MS),
+      commandPollMs: Number(process.env.FIBSCOPE_AGENT_COMMAND_POLL_MS ?? DEFAULT_COMMAND_POLL_MS),
+      knownPeerReconnectMs: Number(process.env.FIBSCOPE_AGENT_KNOWN_PEER_RECONNECT_MS ?? DEFAULT_KNOWN_PEER_RECONNECT_MS),
+      publicProfileEnabled: yes(process.env.FIBSCOPE_AGENT_PUBLIC_PROFILE),
+      overwriteNodeRegistration: yes(process.env.FIBSCOPE_AGENT_OVERWRITE_NODE_REGISTRATION),
+      publicFields: {},
+      chain: process.env.FIBSCOPE_AGENT_CHAIN ?? "testnet",
+      reportUrl: resolveReportUrl({ reportUrl: configuredReportUrl() }),
+      agentToken: envValue(ENV_AGENT_TOKEN, ENV_AGENT_TOKEN_ALIAS),
+      fiberRpcUrl: process.env.FIBSCOPE_AGENT_FIBER_RPC_URL,
+      ckbRpcUrl: process.env.FIBSCOPE_AGENT_CKB_RPC_URL ?? envValue(ENV_CKB_RPC_URL),
+      ckbIndexerUrl: process.env.FIBSCOPE_AGENT_CKB_INDEXER_URL,
+      walletPath: process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH),
+      peerAddress: process.env.FIBSCOPE_AGENT_PEER_ADDRESS,
+    };
+    label = "agent/.env";
+  } else if (!existsSync(configPath)) {
+    throw new Error(`Missing agent config at ${configPath}. Run: npm run agent:init`);
+  } else {
+    config = await readJson(configPath);
+  }
+
+  return normalizeConfig(await bindAgentConfigToFnn(config, label, options), label);
+}
+
+function configuredReportUrl(config = {}) {
+  return textValue(config.reportUrl) || envValue(ENV_REPORT_URL, ENV_REPORT_URL_ALIAS);
+}
+
+function resolveReportUrl(config = {}) {
+  return configuredReportUrl(config) || DEFAULT_REPORT_URL;
+}
+
+async function fetchAgentConfig(config) {
+  const configUrl = config.configUrl ?? config.reportUrl.replace(/\/report\/?$/, "/config");
+  const response = await fetch(configUrl, {
+    headers: {
+      "x-agent-token": config.agentToken,
+    },
+  });
+  const text = await response.text();
+  const payload = parsePayload(text);
+  if (!response.ok) throw new Error(`Agent config unavailable: ${describeAgentHttpError(payload, `HTTP_${response.status}`)}`);
+  return payload;
+}
+
+function mergeAgentRemoteConfig(previous, next) {
+  if (!previous) return next;
+  if (!next || typeof next !== "object") return previous;
+  const previousNode = previous?.node && typeof previous.node === "object" ? previous.node : {};
+  const nextNode = next?.node && typeof next.node === "object" ? next.node : {};
+  const knownPeers = Array.isArray(nextNode.knownPeers) && nextNode.knownPeers.length
+    ? nextNode.knownPeers
+    : Array.isArray(previousNode.knownPeers) ? previousNode.knownPeers : [];
+  return {
+    ...previous,
+    ...next,
+    node: {
+      ...previousNode,
+      ...nextNode,
+      knownPeers,
+    },
+  };
+}
+
+async function registerAgentNode(config, report, remoteConfig) {
+  const localNodeId = readNodeId(report.node);
+  const remoteNodeId = remoteConfig?.node?.nodeId;
+  const registerUrl = config.registerUrl ?? config.reportUrl.replace(/\/report\/?$/, "/register");
+  const response = await fetch(registerUrl, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-agent-token": config.agentToken,
+    },
+    body: stringify({
+      agentVersion: report.agentVersion,
+      chain: report.chain ?? config.chain,
+      collectedAt: report.collectedAt,
+      nodeId: localNodeId ?? remoteNodeId,
+      fiberNodeId: localNodeId,
+      displayName: config.nodeDisplayName ?? remoteConfig?.node?.displayName,
+      publicProfileEnabled: Boolean(report.publicProfileEnabled),
+      overwrite: Boolean(config.overwriteNodeRegistration),
+      node: report.node ?? {},
+    }),
+  });
+  const text = await response.text();
+  const payload = parsePayload(text);
+  if (!response.ok) {
+    throw new Error(`Agent registration failed: ${describeAgentHttpError(payload, `HTTP_${response.status}`)}`);
+  }
+  return payload;
+}
+
+async function reconnectKnownPeersFromGateway(config, remoteConfig, options = {}) {
+  const candidates = Array.isArray(remoteConfig?.node?.knownPeers)
+    ? remoteConfig.node.knownPeers.map(normalizeKnownPeerCandidate).filter((peer) => Boolean(peer?.pubkey && peer?.address))
+    : [];
+  if (!candidates.length) {
+    return { attempted: 0, reconnected: 0, skipped: [{ reason: "no-known-peers" }] };
+  }
+
+  const localInfo = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs).catch(() => ({}));
+  const localPubkey = peerKey(readNodeId(localInfo));
+  const currentPeers = extractPeerList(await rpcCall(config.fiberRpcUrl, "list_peers", [], config.timeoutMs)).map(normalizePeer);
+  const connected = new Set(currentPeers.filter((peer) => peer.connected).map((peer) => peerKey(peer.pubkey || peer.peerId)));
+
+  const result = {
+    attempted: 0,
+    reconnected: 0,
+    skipped: [],
+    failed: [],
+  };
+
+  for (const candidate of candidates) {
+    const pubkey = peerKey(candidate.pubkey);
+    if (!pubkey || !candidate.address) continue;
+    if (localPubkey && pubkey === localPubkey) {
+      result.skipped.push({ pubkey: candidate.pubkey, reason: "self" });
+      continue;
+    }
+    if (connected.has(pubkey)) {
+      result.skipped.push({ pubkey: candidate.pubkey, reason: "already-connected" });
+      continue;
+    }
+    result.attempted += 1;
+    try {
+      await rpcCall(config.fiberRpcUrl, "connect_peer", [omitUndefined({ pubkey: candidate.pubkey, address: candidate.address })], config.timeoutMs);
+      connected.add(pubkey);
+      result.reconnected += 1;
+    } catch (error) {
+      const detail = message(error);
+      if (isPeerAlreadyConnectedError(detail)) {
+        connected.add(pubkey);
+        result.skipped.push({ pubkey: candidate.pubkey, reason: "already-connected" });
+        continue;
+      }
+      result.failed.push({ pubkey: candidate.pubkey, reason: detail });
+    }
+  }
+
+  return result;
+}
+
+function normalizeKnownPeerCandidate(value) {
+  if (!value || typeof value !== "object") return null;
+  return {
+    id: textValue(value.id),
+    pubkey: textValue(value.pubkey ?? value.peerId ?? value.peer_id ?? value.nodeId ?? value.node_id ?? value.id),
+    address: textValue(value.address ?? value.addr ?? value.multiaddr ?? value.multi_addr) || firstString(value.addresses),
+  };
+}
+
+function parsePayload(text) {
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+function payloadCode(payload) {
+  if (!payload || typeof payload !== "object") return undefined;
+  const code = payload.code ?? payload.error;
+  return typeof code === "string" ? code : undefined;
+}
+
+function retryAfterToMs(value) {
+  const text = String(value ?? "").trim();
+  if (!text) return undefined;
+  const seconds = Number(text);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds * 1000);
+  const dateMs = Date.parse(text);
+  return Number.isFinite(dateMs) ? Math.max(0, dateMs - Date.now()) : undefined;
+}
+
+function readCommandId(command) {
+  const id = command && typeof command === "object" ? command.commandId ?? command.id : undefined;
+  if (typeof id === "string" && id.trim()) return id.trim();
+  throw new Error("Command is missing an id.");
+}
+
+function describeAgentHttpError(payload, fallback) {
+  const code = payloadCode(payload) ?? fallback;
+  const detail = payload && typeof payload === "object" && typeof payload.message === "string" ? payload.message : "";
+  if (fallback === "HTTP_429" || code === "RATE_LIMITED" || code === "Rate Limited") {
+    return "Rate limited: Fibscope is already accepting a recent report for this node. The agent will retry shortly when this is a manual refresh.";
+  }
+  if (code === "NODE_REGISTRATION_REQUIRED") {
+    const node = payload && typeof payload === "object" && typeof payload.nodeId === "string" ? ` (${payload.nodeId})` : "";
+    return `NODE_REGISTRATION_REQUIRED${node}: register this Fiber node with the API key before reports can be accepted.`;
+  }
+  if (code === "NODE_REPLACEMENT_REQUIRES_OVERWRITE") {
+    return "NODE_REPLACEMENT_REQUIRES_OVERWRITE: this API key is already bound to another registered Fiber node. Set FIBSCOPE_AGENT_OVERWRITE_NODE_REGISTRATION=true only if you want this node to replace it.";
+  }
+  if (code === "NODE_ALREADY_REGISTERED") {
+    return "NODE_ALREADY_REGISTERED: this Fiber node is already owned by another account or API key.";
+  }
+  if (code === "AGENT_TOKEN_INVALID" || code === "AGENT_TOKEN_REQUIRED") {
+    return `${code}: create a fresh agent token from Agent Setup and restart the agent with ${ENV_AGENT_TOKEN}.`;
+  }
+  return detail && detail !== code ? `${code}: ${detail}` : code;
+}
+
+function normalizeConfig(config, label) {
+  const normalized = {
+    pushIntervalMs: DEFAULT_PUSH_INTERVAL_MS,
+    commandPollMs: DEFAULT_COMMAND_POLL_MS,
+    knownPeerReconnectMs: DEFAULT_KNOWN_PEER_RECONNECT_MS,
+    publicProfileEnabled: false,
+    overwriteNodeRegistration: false,
+    publicFields: {},
+    chain: "testnet",
+    ...config,
+    reportUrl: resolveReportUrl(config),
+    agentToken: textValue(config.agentToken) || envValue(ENV_AGENT_TOKEN, ENV_AGENT_TOKEN_ALIAS),
+    ckbRpcUrl: process.env.FIBSCOPE_AGENT_CKB_RPC_URL ?? envValue(ENV_CKB_RPC_URL) ?? config.ckbRpcUrl,
+    ckbIndexerUrl: process.env.FIBSCOPE_AGENT_CKB_INDEXER_URL ?? config.ckbIndexerUrl,
+    walletPath: process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH) ?? config.walletPath,
+    pushIntervalMs: positiveNumber(config.pushIntervalMs, DEFAULT_PUSH_INTERVAL_MS),
+    commandPollMs: positiveNumber(config.commandPollMs, DEFAULT_COMMAND_POLL_MS),
+    knownPeerReconnectMs: positiveNumber(config.knownPeerReconnectMs, DEFAULT_KNOWN_PEER_RECONNECT_MS),
+  };
+  const required = ["reportUrl", "agentToken", "fiberRpcUrl"];
+  for (const field of required) {
+    if (!normalized[field]) throw new Error(`Missing ${field} in ${label}`);
+  }
+  return normalized;
+}
+
+async function bindAgentConfigToFnn(config, label, options = {}) {
+  const next = { ...config };
+  if (options.fiberRpcUrl) {
+    next.fiberRpcUrl = options.fiberRpcUrl;
+    return enrichConfigFromMatchingFnn(next);
+  }
+  if (process.env.FIBSCOPE_AGENT_FIBER_RPC_URL) {
+    next.fiberRpcUrl = process.env.FIBSCOPE_AGENT_FIBER_RPC_URL;
+    return enrichConfigFromMatchingFnn(next);
+  }
+
+  if (options.noBindFnn) return enrichConfigFromMatchingFnn(next);
+  if (next.fiberRpcUrl && await rpcResponds(next.fiberRpcUrl, 1200)) return enrichConfigFromMatchingFnn(next);
+
+  const selected = await discoverAgentFnnInstance(next.fiberRpcUrl);
+  if (!selected?.rpcUrl) return enrichConfigFromMatchingFnn(next);
+
+  next.fiberRpcUrl = selected.rpcUrl;
+  next.ckbRpcUrl ??= selected.ckbRpcUrl;
+  next.fnnBaseDir ??= selected.baseDir;
+  next.fnnConfigPath ??= selected.configPath;
+  next.fnnP2pListenAddr ??= selected.p2pListenAddr;
+  next.chain ??= selected.network;
+  console.log(`Bound agent to running FNN: ${describeFnnInstance(selected)}`);
+  return applyFnnMatchToAgentConfig(next, selected);
+}
+
+async function enrichConfigFromMatchingFnn(config) {
+  if (!config.fiberRpcUrl) return config;
+  try {
+    const instances = await discoverFnnInstances({ timeoutMs: 800 });
+    const match = instances.find((instance) => sameRpcUrl(instance.rpcUrl, config.fiberRpcUrl));
+    if (!match) return config;
+    return applyFnnMatchToAgentConfig(config, match);
+  } catch {
+    return config;
+  }
+}
+
+function applyFnnMatchToAgentConfig(config, match) {
+  const peerAddress = normalizeLocalListenAddress(match?.p2pListenAddr);
+  const hasConfiguredPeerAddress = configuredPeerAddresses(config).length > 0;
+  return {
+    ...config,
+    ckbRpcUrl: config.ckbRpcUrl ?? match.ckbRpcUrl,
+    fnnBaseDir: config.fnnBaseDir ?? match.baseDir,
+    fnnConfigPath: config.fnnConfigPath ?? match.configPath,
+    fnnP2pListenAddr: config.fnnP2pListenAddr ?? match.p2pListenAddr,
+    ...(!hasConfiguredPeerAddress && peerAddress ? { peerAddress } : {}),
+    chain: config.chain ?? match.network,
+  };
+}
+
+async function discoverAgentRpcUrl(currentRpcUrl, options = {}) {
+  if (currentRpcUrl && await rpcResponds(currentRpcUrl, 1200)) return currentRpcUrl;
+  const selected = await discoverAgentFnnInstance(currentRpcUrl, options);
+  return selected?.rpcUrl;
+}
+
+async function discoverAgentFnnInstance(currentRpcUrl, options = {}) {
+  const instances = await discoverFnnInstances({ timeoutMs: 1200 });
+  return chooseFnnInstance(instances, {
+    currentRpcUrl,
+    interactive: process.stdin.isTTY && process.stdout.isTTY,
+    prompt: options.prompt ?? promptLine,
+  });
+}
+
+async function writeStatus(statusPath, patch) {
+  let current = {};
+  if (existsSync(statusPath)) {
+    try {
+      current = await readJson(statusPath);
+    } catch (error) {
+      current = {
+        previousStatusUnreadable: true,
+        previousStatusError: message(error),
+      };
+    }
+  }
+  await writeJson(statusPath, { ...current, ...patch, updatedAt: Date.now() });
+}
+
+async function prompt(terminal, label, fallback) {
+  const answer = await terminal.question(`${label}${fallback ? ` [${fallback}]` : ""}: `);
+  return answer.trim() || fallback;
+}
+
+function readNodeId(node) {
+  if (!node || typeof node !== "object") return undefined;
+  for (const key of ["nodeId", "node_id", "peerId", "peer_id", "id", "pubkey", "public_key"]) {
+    const value = node[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return undefined;
+}
+
+function normalizePeerPubkey(value) {
+  const text = String(value ?? "").trim().replace(/^0x/i, "");
+  if (!/^[0-9a-fA-F]{66}$/.test(text)) throw new Error("Peer pubkey must be a 33-byte compressed public key.");
+  return text;
+}
+
+function resolveCommandPeer(params) {
+  const peerToken = firstTextValue(params.peerToken, params.fibscopePeerToken);
+  if (peerToken) {
+    const token = decodeFibscopePeerToken(peerToken);
+    return {
+      pubkey: token.pubkey,
+      address: token.address,
+      meta: {
+        source: "fibscope-token",
+        nodeId: token.nodeId,
+        displayName: token.displayName,
+        chain: token.chain,
+        address: token.address,
+      },
+    };
+  }
+  const pubkey = firstTextValue(params.peerPubkey, params.selectedPeerPubkey, params.pubkey, params.peer);
+  return {
+    pubkey,
+    address: firstTextValue(params.peerAddress, params.address),
+    meta: {
+      source: params.mode === "online" ? "online-peer" : "advanced-pubkey",
+    },
+  };
+}
+
+function decodeFibscopePeerToken(value) {
+  const text = String(value ?? "").replace(/\s+/g, "").trim();
+  const encoded = text.startsWith("fibpeer_") ? text.slice("fibpeer_".length) : text;
+  if (!encoded) throw new Error("Fibscope peer token is empty.");
+  let payload;
+  try {
+    const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    payload = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+  } catch {
+    throw new Error("Fibscope peer token is invalid.");
+  }
+  if (!payload || typeof payload !== "object") throw new Error("Fibscope peer token is invalid.");
+  if (payload.platform && payload.platform !== "fibscope") throw new Error("Fibscope peer token was created for another platform.");
+  const pubkey = textValue(payload.pubkey ?? payload.peerPubkey ?? payload.fiberNodeId);
+  if (!pubkey) throw new Error("Fibscope peer token is missing a peer pubkey.");
+  const addresses = readAddressList(payload.addresses ?? payload.peerAddresses);
+  const address = textValue(payload.address ?? payload.peerAddress) || addresses[0];
+  return {
+    pubkey,
+    address,
+    addresses,
+    nodeId: textValue(payload.nodeId),
+    displayName: textValue(payload.displayName),
+    chain: textValue(payload.chain),
+  };
+}
+
+function fundingAmount(params) {
+  if (params.ckb !== undefined && params.ckb !== "") return ckbToShannonsHex(params.ckb);
+  const value = params.fundingAmount ?? params.funding_amount ?? params.amount;
+  if (value !== undefined && value !== "") return quantity(value);
+  return ckbToShannonsHex(DEFAULT_CHANNEL_FUNDING_CKB);
+}
+
+function ckbToShannonsHex(value) {
+  return `0x${ckbToShannons(value).toString(16)}`;
+}
+
+function ckbToShannons(value) {
+  const text = String(value).trim();
+  const match = text.match(/^([0-9]+)(?:\.([0-9]{1,8}))?$/);
+  if (!match) throw new Error("Funding amount must be a decimal CKB value with up to 8 fractional digits.");
+  const whole = BigInt(match[1]) * 100_000_000n;
+  const fraction = BigInt((match[2] ?? "").padEnd(8, "0"));
+  return whole + fraction;
+}
+
+function quantity(value) {
+  const text = String(value).trim();
+  if (/^0x[0-9a-fA-F]+$/.test(text)) return text.toLowerCase();
+  if (/^[0-9]+$/.test(text)) return `0x${BigInt(text).toString(16)}`;
+  throw new Error(`Invalid integer quantity: ${text}`);
+}
+
+function textValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function firstTextValue(...values) {
+  for (const value of values) {
+    const text = textValue(value);
+    if (text) return text;
+  }
+  return "";
+}
+
+function readAddressList(value) {
+  if (Array.isArray(value)) return value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim());
+  if (typeof value === "string" && value.trim()) return [value.trim()];
+  return [];
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.trim()).map((value) => value.trim()))];
+}
+
+function stripAnsi(value) {
+  return String(value ?? "").replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "");
+}
+
+function omitUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined && entry !== ""));
+}
+
+function boolValue(value, fallback) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    if (["true", "1", "yes", "y", "on"].includes(value.trim().toLowerCase())) return true;
+    if (["false", "0", "no", "n", "off"].includes(value.trim().toLowerCase())) return false;
+  }
+  return fallback;
+}
+
+function positiveNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+async function rpcCall(rpcUrl, method, params = [], timeoutMs = 10_000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id: 1, jsonrpc: "2.0", method, params }),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      throw new Error(`RPC ${method} returned non-JSON response: HTTP ${response.status} ${text.slice(0, 200)}`);
+    }
+    if (!response.ok) throw new Error(`RPC ${method} HTTP ${response.status}: ${text.slice(0, 300)}`);
+    if (payload.error) throw new Error(`RPC ${method} failed: ${payload.error.message ?? "unknown error"}${formatRpcErrorData(payload.error.data)}`);
+    return payload.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function formatRpcErrorData(data) {
+  if (data === undefined || data === null || data === "") return "";
+  if (typeof data === "string") return ` (${data})`;
+  try {
+    return ` (${JSON.stringify(data)})`;
+  } catch {
+    return ` (${String(data)})`;
+  }
+}
+
+async function waitForChannel(rpcUrl, pubkey, timeoutMs, pollMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastChannel;
+  while (Date.now() < deadline) {
+    const response = await rpcCall(rpcUrl, "list_channels", [{ pubkey, include_closed: true }]);
+    const channels = Array.isArray(response?.channels) ? response.channels : Array.isArray(response) ? response : [];
+    lastChannel = channels[0] ?? lastChannel;
+    const ready = channels.find((channel) => channelStateName(channel) === "ChannelReady" || channelStateName(channel).toLowerCase() === "open");
+    if (ready) return ready;
+    const failed = channels.find((channel) => ["Closed", "Abandoned", "Failed"].includes(channelStateName(channel)));
+    if (failed) throw new Error(describeChannelTerminalFailure(failed));
+    await sleep(pollMs);
+  }
+  throw new Error(`Timed out waiting for channel readiness. Last channel: ${JSON.stringify(lastChannel ?? null)}`);
+}
+
+async function watchForImmediateChannelFailure(rpcUrl, pubkey, timeoutMs, pollMs) {
+  if (timeoutMs <= 0) return { skipped: true, reason: "Immediate channel failure watch disabled." };
+  const deadline = Date.now() + timeoutMs;
+  let lastChannel;
+  while (Date.now() < deadline) {
+    const response = await rpcCall(rpcUrl, "list_channels", [{ pubkey, include_closed: true }]);
+    const channels = Array.isArray(response?.channels) ? response.channels : Array.isArray(response) ? response : [];
+    lastChannel = channels[0] ?? lastChannel;
+    const failed = channels.find((channel) => ["Closed", "Abandoned", "Failed"].includes(channelStateName(channel)));
+    if (failed) throw new Error(describeChannelTerminalFailure(failed));
+    const ready = channels.find((channel) => channelStateName(channel) === "ChannelReady" || channelStateName(channel).toLowerCase() === "open");
+    if (ready) return { status: "ready", channel: ready };
+    await sleep(pollMs);
+  }
+  return {
+    status: "pending",
+    watchedMs: timeoutMs,
+    lastChannelState: lastChannel ? channelStateName(lastChannel) : "none",
+  };
+}
+
+function channelStateName(channel) {
+  const state = channel?.state;
+  if (!state) return String(channel?.status ?? channel?.state_name ?? "Unknown");
+  if (typeof state === "string") return state;
+  if (state.state_name) return String(state.state_name);
+  const [variant] = Object.keys(state).filter((key) => key !== "flags");
+  return variant ?? "Unknown";
+}
+
+function describeChannelTerminalFailure(channel) {
+  const state = channelStateName(channel);
+  const detail = channelFailureDetail(channel);
+  const normalizedDetail = cleanFundingFailureText(detail);
+  if (isInsufficientFundingError(normalizedDetail)) {
+    return `Channel funding failed: insufficient node wallet capacity. ${normalizedDetail}`;
+  }
+  return `Channel entered terminal state ${state}${normalizedDetail ? `: ${normalizedDetail}` : "."}`;
+}
+
+function channelFailureDetail(channel) {
+  for (const key of ["failure_detail", "failureDetail", "failure_reason", "failureReason", "reason", "error", "message"]) {
+    const value = channel?.[key];
+    if (value === undefined || value === null || value === "") continue;
+    return typeof value === "string" ? value : stringify(value);
+  }
+  const state = channel?.state;
+  if (state && typeof state === "object") {
+    for (const value of Object.values(state)) {
+      if (typeof value === "string" && value.trim()) return value.trim();
+      if (value && typeof value === "object" && Object.keys(value).length) return stringify(value);
+    }
+  }
+  return "";
+}
+
+function cleanFundingFailureText(value) {
+  return String(value ?? "").replace(/`+/g, "").replace(/\s+/g, " ").trim();
+}
+
+function isInsufficientFundingError(value) {
+  return /capacity\s+not\s+enough|balance\s+capacity\s+error|insufficient/i.test(String(value ?? ""));
+}
+
+function buildProgress({ chain, collectedAt, state, funding, observability, recommendations }) {
+  const peers = state.peers ?? [];
+  const channels = state.channels ?? [];
+  const diagnostics = state.diagnostics ?? [];
+  const alerts = observability.alerts ?? [];
+  const health = observability.health ?? state.health ?? {};
+  const online = Boolean(state.node?.online);
+  const connectedPeers = peers.filter((peer) => peer?.connected).length;
+  const openChannels = channels.filter((channel) => channel?.status === "open").length;
+  const critical = diagnostics.find((item) => item?.severity === "critical");
+  const warning = diagnostics.find((item) => item?.severity === "warning");
+  const topIssue = critical ?? warning ?? diagnostics[0];
+  return {
+    source: "agent",
+    status: online && health?.overall?.status !== "critical" ? "active" : online ? "degraded" : "unavailable",
+    chain,
+    collectedAt,
+    nodeId: readNodeId(state.node),
+    online,
+    health: {
+      score: numeric(health?.overall?.score, 0),
+      status: text(health?.overall?.status, online ? "healthy" : "critical"),
+    },
+    peers: {
+      total: peers.length,
+      connected: connectedPeers,
+      offline: Math.max(0, peers.length - connectedPeers),
+    },
+    channels: {
+      total: channels.length,
+      open: openChannels,
+    },
+    liquidity: {
+      outbound: amountString(state.liquidity?.totalOutbound),
+      inbound: amountString(state.liquidity?.totalInbound),
+      channelCount: numeric(state.liquidity?.channelCount, openChannels),
+    },
+    funding: {
+      status: text(funding?.status, "unavailable"),
+      availableCapacity: amountString(funding?.availableCapacity),
+      totalCapacity: amountString(funding?.totalCapacity),
+      cellCount: numeric(funding?.cellCount, 0),
+      checkedAt: numeric(funding?.checkedAt, collectedAt),
+    },
+    diagnostics: {
+      total: diagnostics.length,
+      critical: diagnostics.filter((item) => item?.severity === "critical").length,
+      warning: diagnostics.filter((item) => item?.severity === "warning").length,
+      topIssue: topIssue ? {
+        code: text(topIssue.code, "UNKNOWN"),
+        severity: text(topIssue.severity, "info"),
+        title: text(topIssue.title, "Status update"),
+      } : null,
+    },
+    alerts: {
+      total: alerts.length,
+      unread: alerts.length,
+    },
+    recommendations: {
+      total: recommendations.length,
+      top: recommendations[0] ? {
+        priority: numeric(recommendations[0].priority, 0),
+        title: text(recommendations[0].title, "Recommendation"),
+        actionType: text(recommendations[0].actionType, "ACTION"),
+      } : null,
+    },
+  };
+}
+
+function deriveProgressEvents(previousReport, current) {
+  const events = [];
+  const previousOnline = previousReport?.progress?.online ?? previousReport?.node?.online;
+  if (previousReport && previousOnline !== current.progress.online) {
+    events.push({
+      id: stableEventId(current.progress.online ? "node-online" : "node-offline", current.progress.nodeId, current.collectedAt),
+      timestamp: current.collectedAt,
+      category: "node",
+      type: current.progress.online ? "NODE_ONLINE" : "NODE_OFFLINE",
+      visibility: "public",
+      payload: {
+        chain: current.chain,
+        nodeId: current.progress.nodeId,
+        online: current.progress.online,
+      },
+    });
+  }
+  const previousIssue = previousReport?.progress?.diagnostics?.topIssue?.code;
+  const currentIssue = current.progress.diagnostics?.topIssue?.code;
+  if (previousReport && currentIssue && currentIssue !== previousIssue) {
+    events.push({
+      id: stableEventId("node-issue", current.progress.nodeId, currentIssue, current.collectedAt),
+      timestamp: current.collectedAt,
+      category: "diagnostic",
+      type: "NODE_ISSUE_CHANGED",
+      visibility: "private",
+      payload: {
+        chain: current.chain,
+        nodeId: current.progress.nodeId,
+        issue: current.progress.diagnostics.topIssue,
+      },
+    });
+  }
+  return events;
+}
+
+function stableEventId(...parts) {
+  return parts
+    .filter((part) => part !== undefined && part !== null && part !== "")
+    .map((part) => String(part).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""))
+    .filter(Boolean)
+    .join("-")
+    .slice(0, 160);
+}
+
+function amountString(value) {
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "number" && Number.isFinite(value)) return String(Math.trunc(value));
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value.trim())) return BigInt(value).toString();
+  if (typeof value === "string" && value.trim()) return value.trim();
+  return "0";
+}
+
+function ckbText(value) {
+  const shannons = amountBigInt(value);
+  const whole = shannons / 100_000_000n;
+  const fraction = shannons % 100_000_000n;
+  if (fraction === 0n) return `${whole.toLocaleString("en-US")} CKB`;
+  const fractionText = fraction.toString().padStart(8, "0").replace(/0+$/, "");
+  return `${whole.toLocaleString("en-US")}.${fractionText} CKB`;
+}
+
+function numeric(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function text(value, fallback) {
+  const string = String(value ?? "").trim();
+  return string || fallback;
+}
+
+function nextBackoff(current) {
+  return Math.min(MAX_BACKOFF_MS, Math.max(1_000, current * 2));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function yes(value) {
+  return ["y", "yes", "true", "1", "on"].includes(String(value).trim().toLowerCase());
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function stringify(value) {
+  return JSON.stringify(value, (_key, nested) => typeof nested === "bigint" ? nested.toString() : nested);
+}
+
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function formatAgentStarted(runtime, remoteNode) {
+  return formatCliBlock({
+    title: "Fibscope agent",
+    status: "running",
+    tone: "success",
+    rows: [
+      ["Config", runtime.configPath],
+      ["Fiber RPC", runtime.config.fiberRpcUrl],
+      ["Fibscope", runtime.config.reportUrl],
+      ["Node", remoteNode ?? "registration pending"],
+      ["Push", `${runtime.config.pushIntervalMs} ms`],
+      ["Commands", `${runtime.config.commandPollMs} ms`],
+    ],
+  });
+}
+
+function formatFnnPreflightError(rpcUrl, detail) {
+  return formatCliBlock({
+    title: "Fibscope agent",
+    status: "FNN unreachable",
+    tone: "error",
+    rows: [
+      ["Fiber RPC", rpcUrl],
+      ["Probe", "node_info"],
+      ["Result", detail],
+      ["Next", "Start the matching FNN instance on this port, then run the agent again."],
+    ],
+  });
+}
+
+function formatCommandEvent(status, command, config, tone, detail = undefined) {
+  const params = command?.params && typeof command.params === "object" ? command.params : {};
+  const rows = [
+    ["Command", String(command?.command ?? "unknown")],
+    ["ID", shortText(command?.id ?? command?.commandId, 8, 4)],
+    ["Node", shortText(command?.nodeId, 9, 6)],
+    ["Fiber RPC", config.fiberRpcUrl],
+  ];
+  const peer = commandPeerSummary(params);
+  if (peer) rows.push(["Peer", peer]);
+  const amount = commandAmountSummary(params);
+  if (amount) rows.push(["Amount", amount]);
+  if (detail) rows.push(["Result", detail]);
+  return formatCliBlock({
+    title: "Agent command",
+    status,
+    tone,
+    rows,
+  });
+}
+
+function commandPeerSummary(params) {
+  if (textValue(params.peerToken ?? params.fibscopePeerToken)) return "Fibscope token";
+  const peer = textValue(params.peerPubkey ?? params.selectedPeerPubkey ?? params.pubkey ?? params.peer);
+  return peer ? shortText(peer, 10, 8) : "";
+}
+
+function commandAmountSummary(params) {
+  if (params.ckb !== undefined && params.ckb !== "") return `${params.ckb} CKB`;
+  const value = params.fundingAmount ?? params.funding_amount ?? params.amount;
+  return value !== undefined && value !== "" ? String(value) : "";
+}
+
+function shortText(value, start = 8, end = 4) {
+  const text = String(value ?? "").trim();
+  if (!text) return "";
+  if (text.length <= start + end + 3) return text;
+  return `${text.slice(0, start)}...${text.slice(-end)}`;
+}
+
+function formatCliBlock({ title, status, tone, rows }) {
+  const width = Math.max(8, ...rows.map(([label]) => label.length));
+  const statusColor = tone === "success" ? green : tone === "error" ? red : cyan;
+  const lines = [
+    `${bold(cyan(title))} ${statusColor(status)}`,
+    ...rows.map(([label, value]) => `  ${dim(label.padEnd(width))}  ${valueColor(tone, String(value ?? ""))}`),
+  ];
+  return lines.join("\n");
+}
+
+function valueColor(tone, value) {
+  if (!value) return dim("-");
+  if (tone === "error") return value.includes("Start ") ? yellow(value) : value;
+  return value.startsWith("http://") || value.startsWith("https://") ? cyan(value) : value;
+}
+
+function bold(value) {
+  return paint(1, value);
+}
+
+function dim(value) {
+  return paint(2, value);
+}
+
+function red(value) {
+  return paint(31, value);
+}
+
+function green(value) {
+  return paint(32, value);
+}
+
+function yellow(value) {
+  return paint(33, value);
+}
+
+function cyan(value) {
+  return paint(36, value);
+}
+
+function paint(code, value) {
+  if (process.env.NO_COLOR || process.env.FIBSCOPE_NO_COLOR) return String(value);
+  return `\x1b[${code}m${value}\x1b[0m`;
+}
+
+function loadAgentEnv() {
+  for (const envPath of AGENT_ENV_PATHS) {
+    if (!existsSync(envPath)) continue;
+    const lines = readFileSync(envPath, "utf8").split(/\r?\n/);
+    for (const line of lines) applyEnvLine(line);
+  }
+}
+
+function applyEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return;
+  const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(trimmed);
+  if (!match) return;
+  const [, key, rawValue] = match;
+  if (process.env[key] !== undefined) return;
+  process.env[key] = normalizeEnvValue(rawValue);
+}
+
+function normalizeEnvValue(rawValue) {
+  let value = rawValue.trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  const commentIndex = value.indexOf(" #");
+  if (commentIndex >= 0) value = value.slice(0, commentIndex).trim();
+  return value;
+}
+
+function hasEnvConfig() {
+  return Boolean(
+    envValue(ENV_REPORT_URL, ENV_REPORT_URL_ALIAS) ||
+    envValue(ENV_AGENT_TOKEN, ENV_AGENT_TOKEN_ALIAS) ||
+    process.env.FIBSCOPE_AGENT_FIBER_RPC_URL,
+  );
+}
+
+function envValue(...keys) {
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value !== undefined && String(value).trim()) return value;
+  }
+  return undefined;
+}
+
+function parseArgs(argv) {
+  if (argv[0] === "--help" || argv[0] === "-h") return { command: "help", options: {} };
+  const command = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "status";
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    const [flag, inline] = raw.split("=", 2);
+    const value = () => inline ?? argv[++index];
+    if (flag === "--config") options.config = value();
+    else if (flag === "--status") options.status = value();
+    else if (flag === "--fiber-rpc-url") options.fiberRpcUrl = value();
+    else if (flag === "--no-bind-fnn") options.noBindFnn = true;
+    else if (flag === "--skip-fnn-preflight") options.skipFnnPreflight = true;
+    else if (flag === "--help" || flag === "-h") options.help = true;
+    else throw new Error(`Unknown option ${flag}`);
+  }
+  return { command, options };
+}
+
+async function help() {
+  console.log([
+    "Fibscope Agent for Fiber node owners.",
+    "",
+    "Usage:",
+    "  agent init [--config .fiber/agent.json]",
+    "  agent start [--config .fiber/agent.json]",
+    "  agent once [--config .fiber/agent.json]",
+    "  agent status [--status .fiber/agent-status.json]",
+    "",
+    "Options:",
+    "  --config <path>           Agent config path. Default: .fiber/agent.json",
+    "  --status <path>           Status file path. Default: .fiber/agent-status.json",
+    "  --fiber-rpc-url <url>     Override local FNN RPC URL",
+    "  --no-bind-fnn             Do not auto-bind to a running FNN process",
+    "  --skip-fnn-preflight      Skip FNN RPC readiness check",
+    "  --help                    Show this help",
+    "",
+    "Config sources:",
+    "  agent/.env",
+    "  .env",
+    "  .fiber/agent.json",
+  ].join("\n"));
+}
+
+async function promptLine(label) {
+  const terminal = createInterface({ input, output });
+  try {
+    return await terminal.question(label);
+  } finally {
+    terminal.close();
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  const commands = { init, start, once, status, help };
+  if (!commands[command]) {
+    console.error(`Unknown command ${command}. Use init, start, once, status, or help.`);
+    process.exitCode = 1;
+  } else if (options.help) {
+    help();
+  } else {
+    commands[command](options).catch((error) => {
+      console.error(message(error));
+      process.exitCode = 1;
+    });
+  }
+}