@fiber-pay/cli 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/cli.js

@@ -1,17 +1,168 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { join as join7 } from "path";
+import { join as join9 } from "path";
 import { Command as Command13 } from "commander";
 
 // src/commands/binary.ts
-import {
-  DEFAULT_FIBER_VERSION,
-  downloadFiberBinary,
-  getFiberBinaryInfo
-} from "@fiber-pay/node";
+import { DEFAULT_FIBER_VERSION, downloadFiberBinary } from "@fiber-pay/node";
 import { Command } from "commander";
 
+// src/lib/binary-path.ts
+import { dirname, join } from "path";
+import { BinaryManager, getFiberBinaryInfo } from "@fiber-pay/node";
+
+// src/lib/node-runtime-daemon.ts
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+function getCustomBinaryState(binaryPath) {
+  const exists = existsSync(binaryPath);
+  if (!exists) {
+    return { path: binaryPath, ready: false, version: "unknown" };
+  }
+  try {
+    const result = spawnSync(binaryPath, ["--version"], { encoding: "utf-8" });
+    if (result.status !== 0) {
+      return { path: binaryPath, ready: false, version: "unknown" };
+    }
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    const firstLine = output.split("\n").find((line) => line.trim().length > 0) ?? "unknown";
+    return { path: binaryPath, ready: true, version: firstLine.trim() };
+  } catch {
+    return { path: binaryPath, ready: false, version: "unknown" };
+  }
+}
+function getBinaryVersion(binaryPath) {
+  try {
+    const result = spawnSync(binaryPath, ["--version"], { encoding: "utf-8" });
+    if (result.status !== 0) {
+      return "unknown";
+    }
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    if (!output) {
+      return "unknown";
+    }
+    const firstLine = output.split("\n").find((line) => line.trim().length > 0);
+    return firstLine?.trim() ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function getCliEntrypoint() {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    throw new Error("Unable to resolve CLI entrypoint path");
+  }
+  return entrypoint;
+}
+function startRuntimeDaemonFromNode(params) {
+  const cliEntrypoint = getCliEntrypoint();
+  const result = spawnSync(
+    process.execPath,
+    [
+      cliEntrypoint,
+      "--data-dir",
+      params.dataDir,
+      "--rpc-url",
+      params.rpcUrl,
+      "runtime",
+      "start",
+      "--daemon",
+      "--fiber-rpc-url",
+      params.rpcUrl,
+      "--proxy-listen",
+      params.proxyListen,
+      "--state-file",
+      params.stateFilePath,
+      "--alert-logs-base-dir",
+      params.alertLogsBaseDir,
+      "--json"
+    ],
+    { encoding: "utf-8" }
+  );
+  if (result.status === 0) {
+    return { ok: true };
+  }
+  const stderr = (result.stderr ?? "").trim();
+  const stdout = (result.stdout ?? "").trim();
+  const details = stderr || stdout || `exit code ${result.status ?? "unknown"}`;
+  return { ok: false, message: details };
+}
+function stopRuntimeDaemonFromNode(params) {
+  const cliEntrypoint = getCliEntrypoint();
+  spawnSync(
+    process.execPath,
+    [
+      cliEntrypoint,
+      "--data-dir",
+      params.dataDir,
+      "--rpc-url",
+      params.rpcUrl,
+      "runtime",
+      "stop",
+      "--json"
+    ],
+    { encoding: "utf-8" }
+  );
+}
+
+// src/lib/binary-path.ts
+function getProfileBinaryInstallDir(dataDir) {
+  return join(dataDir, "bin");
+}
+function getProfileManagedBinaryPath(dataDir) {
+  return new BinaryManager(getProfileBinaryInstallDir(dataDir)).getBinaryPath();
+}
+function validateConfiguredBinaryPath(binaryPath) {
+  const value = binaryPath.trim();
+  if (!value) {
+    throw new Error("Configured binaryPath cannot be empty");
+  }
+  if (value.includes("\0")) {
+    throw new Error("Configured binaryPath contains an invalid null byte");
+  }
+  return value;
+}
+function resolveBinaryPath(config) {
+  const managedPath = getProfileManagedBinaryPath(config.dataDir);
+  if (config.binaryPath) {
+    const binaryPath2 = validateConfiguredBinaryPath(config.binaryPath);
+    const installDir2 = dirname(binaryPath2);
+    const expectedPath = new BinaryManager(installDir2).getBinaryPath();
+    const managedByBinaryManager = expectedPath === binaryPath2;
+    const source = binaryPath2 === managedPath ? "profile-managed" : "configured-path";
+    return {
+      binaryPath: binaryPath2,
+      installDir: managedByBinaryManager ? installDir2 : null,
+      managedPath,
+      managedByBinaryManager,
+      source
+    };
+  }
+  const installDir = getProfileBinaryInstallDir(config.dataDir);
+  const binaryPath = managedPath;
+  return {
+    binaryPath,
+    installDir,
+    managedPath,
+    managedByBinaryManager: true,
+    source: "profile-managed"
+  };
+}
+function getBinaryManagerInstallDirOrThrow(resolvedBinary) {
+  if (resolvedBinary.installDir) {
+    return resolvedBinary.installDir;
+  }
+  throw new Error(
+    `Configured binaryPath "${resolvedBinary.binaryPath}" is incompatible with BinaryManager-managed path naming. BinaryManager expects "${new BinaryManager(dirname(resolvedBinary.binaryPath)).getBinaryPath()}". Set binaryPath to a standard managed name (fnn/fnn.exe) in the target directory, or unset binaryPath to use the profile-managed binary.`
+  );
+}
+async function getBinaryDetails(config) {
+  const resolvedBinary = resolveBinaryPath(config);
+  const info = resolvedBinary.installDir ? await getFiberBinaryInfo(resolvedBinary.installDir) : getCustomBinaryState(resolvedBinary.binaryPath);
+  return { resolvedBinary, info };
+}
+
 // src/lib/format.ts
 import {
   ChannelState,
@@ -284,21 +435,6 @@ function printPeerListHuman(peers) {
     console.log(`${peerId} ${pubkey} ${peer.address}`);
   }
 }
-function printNodeInfoHuman(data) {
-  console.log("Node Info");
-  console.log(`  Node ID:              ${data.nodeId}`);
-  console.log(`  Version:              ${data.version}`);
-  console.log(`  Chain Hash:           ${data.chainHash}`);
-  console.log(`  Funding Address:      ${data.fundingAddress}`);
-  console.log(`  Channels:             ${data.channelCount} (${data.pendingChannelCount} pending)`);
-  console.log(`  Peers:                ${data.peersCount}`);
-  if (data.addresses.length > 0) {
-    console.log("  Addresses:");
-    for (const addr of data.addresses) {
-      console.log(`    - ${addr}`);
-    }
-  }
-}
 
 // src/commands/binary.ts
 function showProgress(progress) {
@@ -311,14 +447,36 @@ function showProgress(progress) {
 function createBinaryCommand(config) {
   const binary = new Command("binary").description("Fiber binary management");
   binary.command("download").option("--version <version>", "Fiber binary version", DEFAULT_FIBER_VERSION).option("--force", "Force re-download").option("--json").action(async (options) => {
+    const resolvedBinary = resolveBinaryPath(config);
+    let installDir;
+    try {
+      installDir = getBinaryManagerInstallDirOrThrow(resolvedBinary);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (options.json) {
+        printJsonError({
+          code: "BINARY_PATH_INCOMPATIBLE",
+          message,
+          recoverable: true,
+          suggestion: "Use `fiber-pay config profile unset binaryPath` or set binaryPath to a standard fnn filename in the target directory."
+        });
+      } else {
+        console.error(`\u274C ${message}`);
+      }
+      process.exit(1);
+    }
     const info = await downloadFiberBinary({
-      installDir: `${config.dataDir}/bin`,
+      installDir,
       version: options.version,
       force: Boolean(options.force),
       onProgress: options.json ? void 0 : showProgress
     });
     if (options.json) {
-      printJsonSuccess(info);
+      printJsonSuccess({
+        ...info,
+        source: resolvedBinary.source,
+        resolvedPath: resolvedBinary.binaryPath
+      });
     } else {
       console.log("\n\u2705 Binary installed successfully!");
       console.log(`  Path:    ${info.path}`);
@@ -327,9 +485,13 @@ function createBinaryCommand(config) {
     }
   });
   binary.command("info").option("--json").action(async (options) => {
-    const info = await getFiberBinaryInfo(`${config.dataDir}/bin`);
+    const { resolvedBinary, info } = await getBinaryDetails(config);
     if (options.json) {
-      printJsonSuccess(info);
+      printJsonSuccess({
+        ...info,
+        source: resolvedBinary.source,
+        resolvedPath: resolvedBinary.binaryPath
+      });
     } else {
       console.log(info.ready ? "\u2705 Binary is ready" : "\u274C Binary not found or not executable");
       console.log(`  Path:    ${info.path}`);
@@ -341,7 +503,7 @@ function createBinaryCommand(config) {
 
 // src/commands/channel.ts
 import { randomUUID } from "crypto";
-import { ckbToShannons } from "@fiber-pay/sdk";
+import { ckbToShannons as ckbToShannons2 } from "@fiber-pay/sdk";
 import { Command as Command2 } from "commander";
 
 // src/lib/async.ts
@@ -353,17 +515,17 @@ function sleep(ms) {
 import { FiberRpcClient } from "@fiber-pay/sdk";
 
 // src/lib/pid.ts
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { join } from "path";
+import { existsSync as existsSync2, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
 function getPidFilePath(dataDir) {
-  return join(dataDir, "fiber.pid");
+  return join2(dataDir, "fiber.pid");
 }
 function writePidFile(dataDir, pid) {
   writeFileSync(getPidFilePath(dataDir), String(pid));
 }
 function readPidFile(dataDir) {
   const pidPath = getPidFilePath(dataDir);
-  if (!existsSync(pidPath)) return null;
+  if (!existsSync2(pidPath)) return null;
   try {
     return parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
   } catch {
@@ -372,7 +534,7 @@ function readPidFile(dataDir) {
 }
 function removePidFile(dataDir) {
   const pidPath = getPidFilePath(dataDir);
-  if (existsSync(pidPath)) {
+  if (existsSync2(pidPath)) {
     unlinkSync(pidPath);
   }
 }
@@ -386,20 +548,20 @@ function isProcessRunning(pid) {
 }
 
 // src/lib/runtime-meta.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
 function getRuntimePidFilePath(dataDir) {
-  return join2(dataDir, "runtime.pid");
+  return join3(dataDir, "runtime.pid");
 }
 function getRuntimeMetaFilePath(dataDir) {
-  return join2(dataDir, "runtime.meta.json");
+  return join3(dataDir, "runtime.meta.json");
 }
 function writeRuntimePid(dataDir, pid) {
   writeFileSync2(getRuntimePidFilePath(dataDir), String(pid));
 }
 function readRuntimePid(dataDir) {
   const pidPath = getRuntimePidFilePath(dataDir);
-  if (!existsSync2(pidPath)) return null;
+  if (!existsSync3(pidPath)) return null;
   try {
     return Number.parseInt(readFileSync2(pidPath, "utf-8").trim(), 10);
   } catch {
@@ -411,7 +573,7 @@ function writeRuntimeMeta(dataDir, meta) {
 }
 function readRuntimeMeta(dataDir) {
   const metaPath = getRuntimeMetaFilePath(dataDir);
-  if (!existsSync2(metaPath)) return null;
+  if (!existsSync3(metaPath)) return null;
   try {
     return JSON.parse(readFileSync2(metaPath, "utf-8"));
   } catch {
@@ -421,10 +583,10 @@ function readRuntimeMeta(dataDir) {
 function removeRuntimeFiles(dataDir) {
   const pidPath = getRuntimePidFilePath(dataDir);
   const metaPath = getRuntimeMetaFilePath(dataDir);
-  if (existsSync2(pidPath)) {
+  if (existsSync3(pidPath)) {
     unlinkSync2(pidPath);
   }
-  if (existsSync2(metaPath)) {
+  if (existsSync3(metaPath)) {
     unlinkSync2(metaPath);
   }
 }
@@ -457,7 +619,10 @@ function resolveRuntimeProxyUrl(config) {
 }
 function createRpcClient(config) {
   const resolved = resolveRpcEndpoint(config);
-  return new FiberRpcClient({ url: resolved.url });
+  return new FiberRpcClient({
+    url: resolved.url,
+    biscuitToken: config.rpcBiscuitToken
+  });
 }
 function resolveRpcEndpoint(config) {
   const runtimeProxyUrl = resolveRuntimeProxyUrl(config);
@@ -534,6 +699,235 @@ async function waitForRuntimeJobTerminal(runtimeUrl, jobId, timeoutSeconds) {
   throw new Error(`Timed out waiting for runtime job ${jobId}`);
 }
 
+// src/commands/rebalance.ts
+import { ckbToShannons, shannonsToCkb as shannonsToCkb2 } from "@fiber-pay/sdk";
+async function executeRebalance(config, params) {
+  const rpc = await createReadyRpcClient(config);
+  const amountCkb = parseFloat(params.amountInput);
+  const maxFeeCkb = params.maxFeeInput !== void 0 ? parseFloat(params.maxFeeInput) : void 0;
+  const manualHops = params.hops ?? [];
+  if (!Number.isFinite(amountCkb) || amountCkb <= 0) {
+    const message = "Invalid --amount value. Expected a positive CKB amount.";
+    if (params.json) {
+      printJsonError({
+        code: params.errorCode,
+        message,
+        recoverable: true,
+        suggestion: "Provide a positive number, e.g. `--amount 10`.",
+        details: { amount: params.amountInput }
+      });
+    } else {
+      console.error(`Error: ${message}`);
+    }
+    process.exit(1);
+  }
+  if (maxFeeCkb !== void 0 && (!Number.isFinite(maxFeeCkb) || maxFeeCkb < 0 || manualHops.length > 0)) {
+    const message = manualHops.length > 0 ? "--max-fee is only supported in auto rebalance mode (without manual hops)." : "Invalid --max-fee value. Expected a non-negative CKB amount.";
+    if (params.json) {
+      printJsonError({
+        code: params.errorCode,
+        message,
+        recoverable: true,
+        suggestion: manualHops.length > 0 ? "Remove `--max-fee` or run auto mode without manual hops." : "Provide a non-negative number, e.g. `--max-fee 0.01`.",
+        details: { maxFee: params.maxFeeInput, hasManualHops: manualHops.length > 0 }
+      });
+    } else {
+      console.error(`Error: ${message}`);
+    }
+    process.exit(1);
+  }
+  const selfPubkey = (await rpc.nodeInfo()).node_id;
+  const amount = ckbToShannons(amountCkb);
+  const isManual = manualHops.length > 0;
+  let routeHopCount;
+  const result = isManual ? await (async () => {
+    const hopsInfo = [
+      ...manualHops.map((pubkey) => ({ pubkey })),
+      ...manualHops[manualHops.length - 1] === selfPubkey ? [] : [{ pubkey: selfPubkey }]
+    ];
+    const route = await rpc.buildRouter({
+      amount,
+      hops_info: hopsInfo
+    });
+    routeHopCount = route.router_hops.length;
+    return rpc.sendPaymentWithRouter({
+      router: route.router_hops,
+      keysend: true,
+      allow_self_payment: true,
+      dry_run: params.dryRun ? true : void 0
+    });
+  })() : await rpc.sendPayment({
+    target_pubkey: selfPubkey,
+    amount,
+    keysend: true,
+    allow_self_payment: true,
+    max_fee_amount: maxFeeCkb !== void 0 ? ckbToShannons(maxFeeCkb) : void 0,
+    dry_run: params.dryRun ? true : void 0
+  });
+  const payload = {
+    mode: isManual ? "manual" : "auto",
+    selfPubkey,
+    amountCkb,
+    maxFeeCkb: isManual ? void 0 : maxFeeCkb,
+    routeHopCount,
+    paymentHash: result.payment_hash,
+    status: result.status === "Success" ? "success" : result.status === "Failed" ? "failed" : "pending",
+    feeCkb: shannonsToCkb2(result.fee),
+    failureReason: result.failed_error,
+    dryRun: params.dryRun
+  };
+  if (params.json) {
+    printJsonSuccess(payload);
+  } else {
+    console.log(
+      payload.dryRun ? `Rebalance dry-run complete (${payload.mode} route)` : `Rebalance sent (${payload.mode} route)`
+    );
+    console.log(`  Self:   ${payload.selfPubkey}`);
+    console.log(`  Amount: ${payload.amountCkb} CKB`);
+    if (payload.mode === "manual" && payload.routeHopCount !== void 0) {
+      console.log(`  Hops:   ${payload.routeHopCount}`);
+    }
+    console.log(`  Hash:   ${payload.paymentHash}`);
+    console.log(`  Status: ${payload.status}`);
+    console.log(`  Fee:    ${payload.feeCkb} CKB`);
+    if (payload.mode === "auto" && payload.maxFeeCkb !== void 0) {
+      console.log(`  MaxFee: ${payload.maxFeeCkb} CKB`);
+    }
+    if (payload.failureReason) {
+      console.log(`  Error:  ${payload.failureReason}`);
+    }
+  }
+}
+function registerPaymentRebalanceCommand(parent, config) {
+  parent.command("rebalance").description("Technical rebalance command mapped to payment-layer circular self-payment").requiredOption("--amount <ckb>", "Amount in CKB to rebalance").option("--max-fee <ckb>", "Maximum fee in CKB (auto mode only)").option(
+    "--hops <pubkeys>",
+    "Comma-separated peer pubkeys for manual route mode (self pubkey appended automatically)"
+  ).option("--dry-run", "Simulate route/payment and return estimated result").option("--json").action(async (options) => {
+    const hasHopsOption = typeof options.hops === "string";
+    const manualHops = hasHopsOption ? options.hops.split(",").map((item) => item.trim()).filter(Boolean) : [];
+    if (hasHopsOption && manualHops.length === 0) {
+      const message = "Invalid --hops value. Expected a non-empty comma-separated list of pubkeys.";
+      if (options.json) {
+        printJsonError({
+          code: "PAYMENT_REBALANCE_INPUT_INVALID",
+          message,
+          recoverable: true,
+          suggestion: "Provide pubkeys like `--hops 0xabc...,0xdef...`.",
+          details: { hops: options.hops }
+        });
+      } else {
+        console.error(`Error: ${message}`);
+      }
+      process.exit(1);
+    }
+    await executeRebalance(config, {
+      amountInput: options.amount,
+      maxFeeInput: options.maxFee,
+      hops: manualHops,
+      dryRun: Boolean(options.dryRun),
+      json: Boolean(options.json),
+      errorCode: "PAYMENT_REBALANCE_INPUT_INVALID"
+    });
+  });
+}
+function registerChannelRebalanceCommand(parent, config) {
+  parent.command("rebalance").description("High-level channel rebalance wrapper using payment-layer orchestration").requiredOption("--amount <ckb>", "Amount in CKB to rebalance").option("--from-channel <channelId>", "Source-biased channel id (optional)").option("--to-channel <channelId>", "Destination-biased channel id (optional)").option("--max-fee <ckb>", "Maximum fee in CKB (auto mode only)").option("--dry-run", "Simulate route/payment and return estimated result").option("--json").action(async (options) => {
+    const json = Boolean(options.json);
+    const fromChannelId = options.fromChannel;
+    const toChannelId = options.toChannel;
+    if (fromChannelId && !toChannelId || !fromChannelId && toChannelId) {
+      const message = "Both --from-channel and --to-channel must be provided together for guided channel rebalance.";
+      if (json) {
+        printJsonError({
+          code: "CHANNEL_REBALANCE_INPUT_INVALID",
+          message,
+          recoverable: true,
+          suggestion: "Provide both channel ids, or provide neither to run auto mode.",
+          details: { fromChannel: fromChannelId, toChannel: toChannelId }
+        });
+      } else {
+        console.error(`Error: ${message}`);
+      }
+      process.exit(1);
+    }
+    let guidedHops;
+    if (fromChannelId && toChannelId) {
+      const rpc = await createReadyRpcClient(config);
+      const channels = (await rpc.listChannels({ include_closed: true })).channels;
+      const fromChannel = channels.find((item) => item.channel_id === fromChannelId);
+      const toChannel = channels.find((item) => item.channel_id === toChannelId);
+      if (!fromChannel || !toChannel) {
+        const message = "Invalid channel selection: source/target channel id not found.";
+        if (json) {
+          printJsonError({
+            code: "CHANNEL_REBALANCE_INPUT_INVALID",
+            message,
+            recoverable: true,
+            suggestion: "Run `channel list --json` and retry with valid channel ids.",
+            details: { fromChannel: fromChannelId, toChannel: toChannelId }
+          });
+        } else {
+          console.error(`Error: ${message}`);
+        }
+        process.exit(1);
+      }
+      if (fromChannel.peer_id === toChannel.peer_id) {
+        const message = "Source and target channels point to the same peer; choose two different channel peers.";
+        if (json) {
+          printJsonError({
+            code: "CHANNEL_REBALANCE_INPUT_INVALID",
+            message,
+            recoverable: true,
+            suggestion: "Select channels with different peer ids for guided rebalance.",
+            details: {
+              fromChannel: fromChannelId,
+              toChannel: toChannelId,
+              peerId: fromChannel.peer_id
+            }
+          });
+        } else {
+          console.error(`Error: ${message}`);
+        }
+        process.exit(1);
+      }
+      const peers = (await rpc.listPeers()).peers;
+      const pubkeyByPeerId = new Map(peers.map((peer) => [peer.peer_id, peer.pubkey]));
+      const fromPubkey = pubkeyByPeerId.get(fromChannel.peer_id);
+      const toPubkey = pubkeyByPeerId.get(toChannel.peer_id);
+      if (!fromPubkey || !toPubkey) {
+        const message = "Unable to resolve selected channel peer_id to pubkey for guided rebalance route.";
+        if (json) {
+          printJsonError({
+            code: "CHANNEL_REBALANCE_INPUT_INVALID",
+            message,
+            recoverable: true,
+            suggestion: "Ensure both peers are connected (`peer list --json`) and retry guided mode, or use `payment rebalance --hops`.",
+            details: {
+              fromChannel: fromChannelId,
+              toChannel: toChannelId,
+              fromPeerId: fromChannel.peer_id,
+              toPeerId: toChannel.peer_id,
+              resolvedPeers: peers.length
+            }
+          });
+        } else {
+          console.error(`Error: ${message}`);
+        }
+        process.exit(1);
+      }
+      guidedHops = [fromPubkey, toPubkey];
+    }
+    await executeRebalance(config, {
+      amountInput: options.amount,
+      maxFeeInput: options.maxFee,
+      hops: guidedHops,
+      dryRun: Boolean(options.dryRun),
+      json,
+      errorCode: "CHANNEL_REBALANCE_INPUT_INVALID"
+    });
+  });
+}
+
 // src/commands/channel.ts
 function createChannelCommand(config) {
   const channel = new Command2("channel").description("Channel lifecycle and status commands");
@@ -708,7 +1102,7 @@ function createChannelCommand(config) {
           peerId,
           openChannelParams: {
             peer_id: peerId,
-            funding_amount: ckbToShannons(fundingCkb),
+            funding_amount: ckbToShannons2(fundingCkb),
             public: !options.private
           },
           waitForReady: false
@@ -741,7 +1135,7 @@ function createChannelCommand(config) {
     }
     const result = await rpc.openChannel({
       peer_id: peerId,
-      funding_amount: ckbToShannons(fundingCkb),
+      funding_amount: ckbToShannons2(fundingCkb),
       public: !options.private
     });
     const payload = { temporaryChannelId: result.temporary_channel_id, peer: peerId, fundingCkb };
@@ -765,7 +1159,7 @@ function createChannelCommand(config) {
           action: "accept",
           acceptChannelParams: {
             temporary_channel_id: temporaryChannelId,
-            funding_amount: ckbToShannons(fundingCkb)
+            funding_amount: ckbToShannons2(fundingCkb)
           }
         },
         options: {
@@ -793,7 +1187,7 @@ function createChannelCommand(config) {
     }
     const result = await rpc.acceptChannel({
       temporary_channel_id: temporaryChannelId,
-      funding_amount: ckbToShannons(fundingCkb)
+      funding_amount: ckbToShannons2(fundingCkb)
     });
     const payload = { channelId: result.channel_id, temporaryChannelId, fundingCkb };
     if (json) {
@@ -818,7 +1212,7 @@ function createChannelCommand(config) {
             channel_id: channelId,
             force: Boolean(options.force)
           },
-          waitForClosed: false
+          waitForClosed: Boolean(options.force)
         },
         options: {
           idempotencyKey: `shutdown:channel:${channelId}`
@@ -903,6 +1297,7 @@ function createChannelCommand(config) {
       console.log(`  Channel ID: ${payload.channelId}`);
     }
   });
+  registerChannelRebalanceCommand(channel, config);
   channel.command("update").argument("<channelId>").option("--enabled <enabled>").option("--tlc-expiry-delta <ms>").option("--tlc-minimum-value <shannonsHex>").option("--tlc-fee-proportional-millionths <value>").option("--json").action(async (channelId, options) => {
     const rpc = await createReadyRpcClient(config);
     const json = Boolean(options.json);
@@ -956,22 +1351,22 @@ function createChannelCommand(config) {
 }
 
 // src/commands/config.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
 import { Command as Command3 } from "commander";
 import { parseDocument, stringify as yamlStringify } from "yaml";
 
 // src/lib/config.ts
-import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
 
 // src/lib/config-templates.ts
-var TESTNET_CONFIG_TEMPLATE_V061 = `# This configuration file only contains the necessary configurations for the testnet deployment.
+var TESTNET_CONFIG_TEMPLATE_V071 = `# This configuration file only contains the necessary configurations for the testnet deployment.
 # All options' descriptions can be found via \`fnn --help\` and be overridden by command line arguments or environment variables.
 fiber:
-  listening_addr: "/ip4/127.0.0.1/tcp/8228"
+  listening_addr: "/ip4/0.0.0.0/tcp/8228"
   bootnode_addrs:
     - "/ip4/54.179.226.154/tcp/8228/p2p/Qmes1EBD4yNo9Ywkfe6eRw9tG1nVNGLDmMud1xJMsoYFKy"
-    - "/ip4/54.179.226.154/tcp/18228/p2p/QmdyQWjPtbK4NWWsvy8s69NGJaQULwgeQDT5ZpNDrTNaeV"
+    - "/ip4/16.163.7.105/tcp/8228/p2p/QmdyQWjPtbK4NWWsvy8s69NGJaQULwgeQDT5ZpNDrTNaeV"
   announce_listening_addr: true
   announced_addrs:
     # If you want to announce your fiber node public address to the network, you need to add the address here, please change the ip to your public ip accordingly.
@@ -1037,7 +1432,7 @@ services:
   - rpc
   - ckb
 `;
-var MAINNET_CONFIG_TEMPLATE_V061 = `# This configuration file only contains the necessary configurations for the mainnet deployment.
+var MAINNET_CONFIG_TEMPLATE_V071 = `# This configuration file only contains the necessary configurations for the mainnet deployment.
 # All options' descriptions can be found via \`fnn --help\` and be overridden by command line arguments or environment variables.
 fiber:
   listening_addr: "/ip4/0.0.0.0/tcp/8228"
@@ -1113,7 +1508,7 @@ services:
   - ckb
 `;
 function getConfigTemplate(network) {
-  return network === "mainnet" ? MAINNET_CONFIG_TEMPLATE_V061 : TESTNET_CONFIG_TEMPLATE_V061;
+  return network === "mainnet" ? MAINNET_CONFIG_TEMPLATE_V071 : TESTNET_CONFIG_TEMPLATE_V071;
 }
 
 // src/lib/config.ts
@@ -1121,7 +1516,7 @@ var DEFAULT_DATA_DIR = `${process.env.HOME}/.fiber-pay`;
 var DEFAULT_RPC_URL = "http://127.0.0.1:8227";
 var DEFAULT_NETWORK = "testnet";
 function getConfigPath(dataDir) {
-  return join3(dataDir, "config.yml");
+  return join4(dataDir, "config.yml");
 }
 function parseNetworkFromConfig(configContent) {
   const match = configContent.match(/^\s*chain:\s*(testnet|mainnet)\s*$/m);
@@ -1153,11 +1548,11 @@ function parseCkbRpcUrlFromConfig(configContent) {
   return match?.[1]?.trim() || void 0;
 }
 function getProfilePath(dataDir) {
-  return join3(dataDir, "profile.json");
+  return join4(dataDir, "profile.json");
 }
 function loadProfileConfig(dataDir) {
   const profilePath = getProfilePath(dataDir);
-  if (!existsSync3(profilePath)) return void 0;
+  if (!existsSync4(profilePath)) return void 0;
   try {
     const raw = readFileSync3(profilePath, "utf-8");
     return JSON.parse(raw);
@@ -1166,7 +1561,7 @@ function loadProfileConfig(dataDir) {
   }
 }
 function saveProfileConfig(dataDir, profile) {
-  if (!existsSync3(dataDir)) {
+  if (!existsSync4(dataDir)) {
     mkdirSync(dataDir, { recursive: true });
   }
   const profilePath = getProfilePath(dataDir);
@@ -1175,11 +1570,11 @@ function saveProfileConfig(dataDir, profile) {
 }
 function writeNetworkConfigFile(dataDir, network, options = {}) {
   const configPath = getConfigPath(dataDir);
-  const alreadyExists = existsSync3(configPath);
+  const alreadyExists = existsSync4(configPath);
   if (alreadyExists && !options.force) {
     return { path: configPath, created: false, overwritten: false };
   }
-  if (!existsSync3(dataDir)) {
+  if (!existsSync4(dataDir)) {
     mkdirSync(dataDir, { recursive: true });
   }
   let content = getConfigTemplate(network);
@@ -1205,7 +1600,7 @@ function writeNetworkConfigFile(dataDir, network, options = {}) {
 }
 function ensureNodeConfigFile(dataDir, network) {
   const configPath = getConfigPath(dataDir);
-  if (!existsSync3(configPath)) {
+  if (!existsSync4(configPath)) {
     writeNetworkConfigFile(dataDir, network);
   }
   return configPath;
@@ -1214,7 +1609,7 @@ function getEffectiveConfig(explicitFlags2) {
   const dataDir = process.env.FIBER_DATA_DIR || DEFAULT_DATA_DIR;
   const dataDirSource = explicitFlags2?.has("dataDir") ? "cli" : process.env.FIBER_DATA_DIR ? "env" : "default";
   const configPath = getConfigPath(dataDir);
-  const configExists = existsSync3(configPath);
+  const configExists = existsSync4(configPath);
   const configContent = configExists ? readFileSync3(configPath, "utf-8") : void 0;
   const profile = loadProfileConfig(dataDir);
   const cliNetwork = explicitFlags2?.has("network") ? process.env.FIBER_NETWORK : void 0;
@@ -1227,6 +1622,10 @@ function getEffectiveConfig(explicitFlags2) {
   const fileRpcUrl = configContent ? parseRpcUrlFromConfig(configContent) : void 0;
   const rpcUrl = cliRpcUrl || envRpcUrl || fileRpcUrl || DEFAULT_RPC_URL;
   const rpcUrlSource = cliRpcUrl ? "cli" : envRpcUrl ? "env" : fileRpcUrl ? "config" : "default";
+  const cliRpcBiscuitToken = explicitFlags2?.has("rpcBiscuitToken") ? process.env.FIBER_RPC_BISCUIT_TOKEN : void 0;
+  const envRpcBiscuitToken = !explicitFlags2?.has("rpcBiscuitToken") ? process.env.FIBER_RPC_BISCUIT_TOKEN : void 0;
+  const rpcBiscuitToken = cliRpcBiscuitToken || envRpcBiscuitToken || void 0;
+  const rpcBiscuitTokenSource = cliRpcBiscuitToken ? "cli" : envRpcBiscuitToken ? "env" : "unset";
   const cliBinaryPath = explicitFlags2?.has("binaryPath") ? process.env.FIBER_BINARY_PATH : void 0;
   const profileBinaryPath = profile?.binaryPath;
   const envBinaryPath = !explicitFlags2?.has("binaryPath") ? process.env.FIBER_BINARY_PATH : void 0;
@@ -1253,6 +1652,7 @@ function getEffectiveConfig(explicitFlags2) {
       configPath,
       network,
       rpcUrl,
+      rpcBiscuitToken,
       keyPassword,
       ckbRpcUrl,
       runtimeProxyListen
@@ -1262,6 +1662,7 @@ function getEffectiveConfig(explicitFlags2) {
       configPath: "derived",
       network: networkSource,
       rpcUrl: rpcUrlSource,
+      rpcBiscuitToken: rpcBiscuitTokenSource,
       ckbRpcUrl: ckbRpcUrlSource,
       runtimeProxyListen: runtimeProxyListenSource
     }
@@ -1356,7 +1757,7 @@ function parseTypedValue(raw, valueType) {
   return raw;
 }
 function ensureConfigFileOrExit(configPath, json) {
-  if (!existsSync4(configPath)) {
+  if (!existsSync5(configPath)) {
     const msg = `Config file not found: ${configPath}. Run \`fiber-pay config init\` first.`;
     if (json) {
       printJsonError({
@@ -1728,7 +2129,7 @@ function createConfigCommand(_config) {
 }
 
 // src/commands/graph.ts
-import { shannonsToCkb as shannonsToCkb2, toHex as toHex2 } from "@fiber-pay/sdk";
+import { shannonsToCkb as shannonsToCkb3, toHex as toHex2 } from "@fiber-pay/sdk";
 import { Command as Command4 } from "commander";
 function printGraphNodeListHuman(nodes) {
   if (nodes.length === 0) {
@@ -1743,7 +2144,7 @@ function printGraphNodeListHuman(nodes) {
     const nodeId = truncateMiddle(node.node_id, 10, 8).padEnd(22, " ");
     const alias = (node.node_name || "(unnamed)").slice(0, 20).padEnd(20, " ");
     const version = (node.version || "?").slice(0, 10).padEnd(10, " ");
-    const minFunding = shannonsToCkb2(node.auto_accept_min_ckb_funding_amount).toString().padStart(12, " ");
+    const minFunding = shannonsToCkb3(node.auto_accept_min_ckb_funding_amount).toString().padStart(12, " ");
     const age = formatAge(parseHexTimestampMs(node.timestamp));
     console.log(`${nodeId} ${alias} ${version} ${minFunding} ${age}`);
   }
@@ -1765,7 +2166,7 @@ function printGraphChannelListHuman(channels) {
     const outpoint = ch.channel_outpoint ? truncateMiddle(`${ch.channel_outpoint.tx_hash}:${ch.channel_outpoint.index}`, 10, 8) : "n/a";
     const n1 = truncateMiddle(ch.node1, 10, 8).padEnd(22, " ");
     const n2 = truncateMiddle(ch.node2, 10, 8).padEnd(22, " ");
-    const capacity = `${shannonsToCkb2(ch.capacity)} CKB`.padStart(12, " ");
+    const capacity = `${shannonsToCkb3(ch.capacity)} CKB`.padStart(12, " ");
     const age = formatAge(parseHexTimestampMs(ch.created_timestamp));
     console.log(`${outpoint.padEnd(22, " ")} ${n1} ${n2} ${capacity} ${age}`);
   }
@@ -1810,7 +2211,7 @@ Next cursor: ${result.last_cursor}`);
 }
 
 // src/commands/invoice.ts
-import { ckbToShannons as ckbToShannons2, randomBytes32, shannonsToCkb as shannonsToCkb3, toHex as toHex3 } from "@fiber-pay/sdk";
+import { ckbToShannons as ckbToShannons3, randomBytes32, shannonsToCkb as shannonsToCkb4, toHex as toHex3 } from "@fiber-pay/sdk";
 import { Command as Command5 } from "commander";
 function createInvoiceCommand(config) {
   const invoice = new Command5("invoice").description("Invoice lifecycle and status commands");
@@ -1839,7 +2240,7 @@ function createInvoiceCommand(config) {
         params: {
           action: "create",
           newInvoiceParams: {
-            amount: ckbToShannons2(amountCkb),
+            amount: ckbToShannons3(amountCkb),
             currency,
             description: options.description,
             expiry: toHex3(expirySeconds),
@@ -1876,7 +2277,7 @@ function createInvoiceCommand(config) {
       }
     }
     const result = await rpc.newInvoice({
-      amount: ckbToShannons2(amountCkb),
+      amount: ckbToShannons3(amountCkb),
       currency,
       description: options.description,
       expiry: toHex3(expirySeconds),
@@ -1908,7 +2309,7 @@ function createInvoiceCommand(config) {
       paymentHash,
       status: result.status,
       invoice: result.invoice_address,
-      amountCkb: result.invoice.amount ? shannonsToCkb3(result.invoice.amount) : void 0,
+      amountCkb: result.invoice.amount ? shannonsToCkb4(result.invoice.amount) : void 0,
       currency: result.invoice.currency,
       description: metadata.description,
       createdAt: createdAtMs ? new Date(createdAtMs).toISOString() : result.invoice.data.timestamp,
@@ -2028,19 +2429,104 @@ function createInvoiceCommand(config) {
 }
 
 // src/commands/job.ts
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import { Command as Command6 } from "commander";
 
 // src/lib/log-files.ts
-import { closeSync, createReadStream, existsSync as existsSync5, openSync, readSync, statSync } from "fs";
-import { join as join4 } from "path";
-function resolvePersistedLogPaths(dataDir, meta) {
+import {
+  appendFileSync,
+  closeSync,
+  createReadStream,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync2,
+  openSync,
+  readdirSync,
+  readSync,
+  statSync
+} from "fs";
+import { join as join5 } from "path";
+var DATE_DIR_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+function todayDateString() {
+  const now = /* @__PURE__ */ new Date();
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+function validateLogDate(date) {
+  const value = date.trim();
+  if (!DATE_DIR_PATTERN.test(value)) {
+    throw new Error(`Invalid date '${value}'. Expected format YYYY-MM-DD.`);
+  }
+  if (value.includes("/") || value.includes("\\") || value.includes("..")) {
+    throw new Error(`Invalid date '${value}'. Path separators or '..' are not allowed.`);
+  }
+  return value;
+}
+function resolveLogDirForDate(dataDir, date) {
+  return resolveLogDirForDateWithOptions(dataDir, date, {});
+}
+function resolveLogDirForDateWithOptions(dataDir, date, options) {
+  const dateStr = date ?? todayDateString();
+  const logsBaseDir = options.logsBaseDir ?? join5(dataDir, "logs");
+  if (date !== void 0) {
+    validateLogDate(dateStr);
+  }
+  const dir = join5(logsBaseDir, dateStr);
+  const ensureExists = options.ensureExists ?? true;
+  if (ensureExists) {
+    mkdirSync2(dir, { recursive: true });
+  }
+  return dir;
+}
+function resolvePersistedLogPaths(dataDir, meta, date) {
+  const logsBaseDir = meta?.logsBaseDir ?? join5(dataDir, "logs");
+  if (date) {
+    const dir2 = resolveLogDirForDateWithOptions(dataDir, date, {
+      logsBaseDir,
+      ensureExists: false
+    });
+    return {
+      runtimeAlerts: join5(dir2, "runtime.alerts.jsonl"),
+      fnnStdout: join5(dir2, "fnn.stdout.log"),
+      fnnStderr: join5(dir2, "fnn.stderr.log")
+    };
+  }
+  if (meta?.alertLogFilePath || meta?.fnnStdoutLogPath || meta?.fnnStderrLogPath) {
+    const defaultDir = resolveLogDirForDateWithOptions(dataDir, void 0, {
+      logsBaseDir,
+      ensureExists: false
+    });
+    return {
+      runtimeAlerts: meta.alertLogFilePath ?? join5(defaultDir, "runtime.alerts.jsonl"),
+      fnnStdout: meta.fnnStdoutLogPath ?? join5(defaultDir, "fnn.stdout.log"),
+      fnnStderr: meta.fnnStderrLogPath ?? join5(defaultDir, "fnn.stderr.log")
+    };
+  }
+  const dir = resolveLogDirForDateWithOptions(dataDir, void 0, {
+    logsBaseDir,
+    ensureExists: false
+  });
   return {
-    runtimeAlerts: meta?.alertLogFilePath ?? join4(dataDir, "logs", "runtime.alerts.jsonl"),
-    fnnStdout: meta?.fnnStdoutLogPath ?? join4(dataDir, "logs", "fnn.stdout.log"),
-    fnnStderr: meta?.fnnStderrLogPath ?? join4(dataDir, "logs", "fnn.stderr.log")
+    runtimeAlerts: join5(dir, "runtime.alerts.jsonl"),
+    fnnStdout: join5(dir, "fnn.stdout.log"),
+    fnnStderr: join5(dir, "fnn.stderr.log")
   };
 }
+function listLogDates(dataDir, logsBaseDir) {
+  const logsDir = logsBaseDir ?? join5(dataDir, "logs");
+  if (!existsSync6(logsDir)) {
+    return [];
+  }
+  const entries = readdirSync(logsDir, { withFileTypes: true });
+  const dates = entries.filter((entry) => entry.isDirectory() && DATE_DIR_PATTERN.test(entry.name)).map((entry) => entry.name);
+  dates.sort((a, b) => a > b ? -1 : a < b ? 1 : 0);
+  return dates;
+}
+function appendToTodayLog(dataDir, filename, text) {
+  const dir = resolveLogDirForDate(dataDir);
+  appendFileSync(join5(dir, filename), text, "utf-8");
+}
 function resolvePersistedLogTargets(paths, source) {
   const all = [
     {
@@ -2065,7 +2551,7 @@ function resolvePersistedLogTargets(paths, source) {
   return all.filter((target) => target.source === source);
 }
 function readLastLines(filePath, maxLines) {
-  if (!existsSync5(filePath)) {
+  if (!existsSync6(filePath)) {
     return [];
   }
   if (!Number.isFinite(maxLines) || maxLines <= 0) {
@@ -2109,7 +2595,7 @@ function readLastLines(filePath, maxLines) {
   }
 }
 async function readAppendedLines(filePath, offset, remainder = "") {
-  if (!existsSync5(filePath)) {
+  if (!existsSync6(filePath)) {
     return { lines: [], nextOffset: 0, remainder: "" };
   }
   const size = statSync(filePath).size;
@@ -2209,10 +2695,11 @@ function createJobCommand(config) {
       console.log(`    ${JSON.stringify(payload.result)}`);
     }
   });
-  job.command("trace").argument("<jobId>").option("--tail <n>", "Max lines to inspect per log file", "400").option("--json").action(async (jobId, options) => {
+  job.command("trace").argument("<jobId>").option("--tail <n>", "Max lines to inspect per log file", "400").option("--date <YYYY-MM-DD>", "Date of log directory to search (default: today UTC)").option("--json").action(async (jobId, options) => {
     const json = Boolean(options.json);
     const tailInput = Number.parseInt(String(options.tail ?? "400"), 10);
     const tail = Number.isFinite(tailInput) && tailInput > 0 ? tailInput : 400;
+    const date = options.date ? String(options.date).trim() : void 0;
     const runtimeUrl = getRuntimeUrlOrExit(config, json);
     const jobResponse = await fetch(`${runtimeUrl}/jobs/${jobId}`);
     if (!jobResponse.ok) {
@@ -2226,7 +2713,24 @@ function createJobCommand(config) {
     const eventsPayload = await eventsResponse.json();
     const tokens = collectTraceTokens(jobRecord, eventsPayload.events);
     const meta = readRuntimeMeta(config.dataDir);
-    const logPaths = resolvePersistedLogPaths(config.dataDir, meta);
+    let logPaths;
+    try {
+      logPaths = resolvePersistedLogPaths(config.dataDir, meta, date);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Invalid --date value.";
+      if (json) {
+        printJsonError({
+          code: "JOB_TRACE_DATE_INVALID",
+          message,
+          recoverable: true,
+          suggestion: "Retry with --date in YYYY-MM-DD format.",
+          details: { date }
+        });
+      } else {
+        console.error(`Error: ${message}`);
+      }
+      process.exit(1);
+    }
     const runtimeAlertMatches = collectRelatedLines(logPaths.runtimeAlerts, tokens, tail);
     const fnnStdoutMatches = collectRelatedLines(logPaths.fnnStdout, tokens, tail);
     const fnnStderrMatches = collectRelatedLines(logPaths.fnnStderr, tokens, tail);
@@ -2429,7 +2933,7 @@ function collectStructuredTokens(set, input, depth = 0) {
   }
 }
 function collectRelatedLines(filePath, tokens, tail) {
-  if (!existsSync6(filePath)) {
+  if (!existsSync7(filePath)) {
     return [];
   }
   const lines = readLastLines(filePath, tail);
@@ -2445,7 +2949,7 @@ function collectRelatedLines(filePath, tokens, tail) {
 function printTraceSection(title, filePath, lines) {
   console.log(`
 ${title}: ${filePath}`);
-  if (!existsSync6(filePath)) {
+  if (!existsSync7(filePath)) {
     console.log("  (file not found)");
     return;
   }
@@ -2459,7 +2963,8 @@ ${title}: ${filePath}`);
 }
 
 // src/commands/logs.ts
-import { existsSync as existsSync7, statSync as statSync2 } from "fs";
+import { existsSync as existsSync8, statSync as statSync2 } from "fs";
+import { join as join6 } from "path";
 import { formatRuntimeAlert } from "@fiber-pay/runtime";
 import { Command as Command7 } from "commander";
 var ALLOWED_SOURCES = /* @__PURE__ */ new Set([
@@ -2468,6 +2973,7 @@ var ALLOWED_SOURCES = /* @__PURE__ */ new Set([
   "fnn-stdout",
   "fnn-stderr"
 ]);
+var DATE_DIR_PATTERN2 = /^\d{4}-\d{2}-\d{2}$/;
 function parseRuntimeAlertLine(line) {
   try {
     const parsed = JSON.parse(line);
@@ -2493,9 +2999,45 @@ function coerceJsonLineForOutput(source, line) {
   return parseRuntimeAlertLine(line) ?? line;
 }
 function createLogsCommand(config) {
-  return new Command7("logs").alias("log").description("View persisted runtime/fnn logs").option("--source <source>", "Log source: all|runtime|fnn-stdout|fnn-stderr", "all").option("--tail <n>", "Number of recent lines per source", "80").option("--follow", "Keep streaming appended log lines (human output mode only)").option("--interval-ms <ms>", "Polling interval for --follow mode", "1000").option("--json").action(async (options) => {
+  return new Command7("logs").alias("log").description("View persisted runtime/fnn logs").option("--source <source>", "Log source: all|runtime|fnn-stdout|fnn-stderr", "all").option("--tail <n>", "Number of recent lines per source", "80").option("--date <YYYY-MM-DD>", "Date of log directory to read (default: today UTC)").option("--list-dates", "List available log dates and exit").option("--follow", "Keep streaming appended log lines (human output mode only)").option("--interval-ms <ms>", "Polling interval for --follow mode", "1000").option("--json").action(async (options) => {
     const json = Boolean(options.json);
     const follow = Boolean(options.follow);
+    const listDates = Boolean(options.listDates);
+    const date = options.date ? String(options.date).trim() : void 0;
+    const meta = readRuntimeMeta(config.dataDir);
+    if (follow && date) {
+      const message = "--follow cannot be used with --date. --follow only streams today's logs.";
+      if (json) {
+        printJsonError({
+          code: "LOG_FOLLOW_DATE_UNSUPPORTED",
+          message,
+          recoverable: true,
+          suggestion: "Remove --date or remove --follow and retry."
+        });
+      } else {
+        console.error(`Error: ${message}`);
+      }
+      process.exit(1);
+    }
+    if (listDates) {
+      const logsDir = meta?.logsBaseDir ?? join6(config.dataDir, "logs");
+      const dates = listLogDates(config.dataDir, logsDir);
+      if (json) {
+        printJsonSuccess({ dates, logsDir });
+      } else {
+        if (dates.length === 0) {
+          console.log("No log dates found.");
+        } else {
+          console.log(`Log dates (${dates.length}):`);
+          for (const date2 of dates) {
+            console.log(`  ${date2}`);
+          }
+          console.log(`
+Logs directory: ${logsDir}`);
+        }
+      }
+      return;
+    }
     const sourceInput = String(options.source ?? "all").trim().toLowerCase();
     if (json && follow) {
       const message = "--follow is not supported with --json. Use human mode for streaming logs.";
@@ -2527,18 +3069,36 @@ function createLogsCommand(config) {
     const tail = Number.isFinite(tailInput) && tailInput > 0 ? tailInput : 80;
     const intervalInput = Number.parseInt(String(options.intervalMs ?? "1000"), 10);
     const intervalMs = Number.isFinite(intervalInput) && intervalInput > 0 ? intervalInput : 1e3;
-    const meta = readRuntimeMeta(config.dataDir);
-    const paths = resolvePersistedLogPaths(config.dataDir, meta);
+    let paths;
+    try {
+      paths = resolvePersistedLogPaths(config.dataDir, meta, date);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Invalid --date value.";
+      if (json) {
+        printJsonError({
+          code: "LOG_DATE_INVALID",
+          message,
+          recoverable: true,
+          suggestion: "Retry with --date in YYYY-MM-DD format.",
+          details: { date }
+        });
+      } else {
+        console.error(`Error: ${message}`);
+      }
+      process.exit(1);
+    }
     const targets = resolvePersistedLogTargets(paths, source);
-    if (source !== "all" && targets.length === 1 && !existsSync7(targets[0].path)) {
-      const message = `Log file not found for source ${source}: ${targets[0].path}`;
+    const displayDate = date ?? inferDateFromPaths(paths);
+    if (source !== "all" && targets.length === 1 && !existsSync8(targets[0].path)) {
+      const dateLabel = displayDate ? ` on ${displayDate}` : "";
+      const message = `Log file not found for source ${source}${dateLabel}: ${targets[0].path}`;
       if (json) {
         printJsonError({
           code: "LOG_FILE_NOT_FOUND",
           message,
           recoverable: true,
-          suggestion: "Start node/runtime or generate activity, then retry logs command.",
-          details: { source, path: targets[0].path }
+          suggestion: "Start node/runtime or generate activity, then retry logs command. Use --list-dates to see available dates.",
+          details: { source, date: displayDate ?? null, path: targets[0].path }
         });
       } else {
         console.error(`Error: ${message}`);
@@ -2547,7 +3107,7 @@ function createLogsCommand(config) {
     }
     const entries = [];
     for (const target of targets) {
-      const exists = existsSync7(target.path);
+      const exists = existsSync8(target.path);
       let lines = [];
       if (exists) {
         try {
@@ -2582,6 +3142,7 @@ function createLogsCommand(config) {
       printJsonSuccess({
         source,
         tail,
+        date: displayDate ?? null,
         entries: entries.map((entry) => ({
           source: entry.source,
           title: entry.title,
@@ -2593,7 +3154,8 @@ function createLogsCommand(config) {
       });
       return;
     }
-    console.log(`Logs (source: ${source}, tail: ${tail})`);
+    const headerDate = displayDate ? `, date: ${displayDate}` : "";
+    console.log(`Logs (source: ${source}${headerDate}, tail: ${tail})`);
     for (const entry of entries) {
       console.log(`
 ${entry.title}: ${entry.path}`);
@@ -2647,7 +3209,7 @@ Following logs (interval: ${intervalMs}ms). Press Ctrl+C to stop.`);
           for (const target of targets) {
             const state = states.get(target.source);
             if (!state) continue;
-            if (!existsSync7(state.path)) {
+            if (!existsSync8(state.path)) {
               state.offset = 0;
               state.remainder = "";
               continue;
@@ -2678,116 +3240,32 @@ Following logs (interval: ${intervalMs}ms). Press Ctrl+C to stop.`);
     });
   });
 }
-
-// src/commands/node.ts
-import { nodeIdToPeerId as nodeIdToPeerId2, scriptToAddress as scriptToAddress2 } from "@fiber-pay/sdk";
-import { Command as Command8 } from "commander";
-
-// src/lib/node-runtime-daemon.ts
-import { spawnSync } from "child_process";
-import { existsSync as existsSync8 } from "fs";
-function getCustomBinaryState(binaryPath) {
-  const exists = existsSync8(binaryPath);
-  if (!exists) {
-    return { path: binaryPath, ready: false, version: "unknown" };
-  }
-  try {
-    const result = spawnSync(binaryPath, ["--version"], { encoding: "utf-8" });
-    if (result.status !== 0) {
-      return { path: binaryPath, ready: false, version: "unknown" };
-    }
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
-    const firstLine = output.split("\n").find((line) => line.trim().length > 0) ?? "unknown";
-    return { path: binaryPath, ready: true, version: firstLine.trim() };
-  } catch {
-    return { path: binaryPath, ready: false, version: "unknown" };
-  }
-}
-function getBinaryVersion(binaryPath) {
-  try {
-    const result = spawnSync(binaryPath, ["--version"], { encoding: "utf-8" });
-    if (result.status !== 0) {
-      return "unknown";
-    }
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
-    if (!output) {
-      return "unknown";
-    }
-    const firstLine = output.split("\n").find((line) => line.trim().length > 0);
-    return firstLine?.trim() ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-function getCliEntrypoint() {
-  const entrypoint = process.argv[1];
-  if (!entrypoint) {
-    throw new Error("Unable to resolve CLI entrypoint path");
+function inferDateFromPaths(paths) {
+  const candidate = paths.runtimeAlerts.split("/").at(-2);
+  if (!candidate || !DATE_DIR_PATTERN2.test(candidate)) {
+    return void 0;
   }
-  return entrypoint;
-}
-function startRuntimeDaemonFromNode(params) {
-  const cliEntrypoint = getCliEntrypoint();
-  const result = spawnSync(
-    process.execPath,
-    [
-      cliEntrypoint,
-      "--data-dir",
-      params.dataDir,
-      "--rpc-url",
-      params.rpcUrl,
-      "runtime",
-      "start",
-      "--daemon",
-      "--fiber-rpc-url",
-      params.rpcUrl,
-      "--proxy-listen",
-      params.proxyListen,
-      "--state-file",
-      params.stateFilePath,
-      "--alert-log-file",
-      params.alertLogFile,
-      "--json"
-    ],
-    { encoding: "utf-8" }
-  );
-  if (result.status === 0) {
-    return { ok: true };
+  const stdoutDate = paths.fnnStdout.split("/").at(-2);
+  const stderrDate = paths.fnnStderr.split("/").at(-2);
+  if (stdoutDate !== candidate || stderrDate !== candidate) {
+    return void 0;
   }
-  const stderr = (result.stderr ?? "").trim();
-  const stdout = (result.stdout ?? "").trim();
-  const details = stderr || stdout || `exit code ${result.status ?? "unknown"}`;
-  return { ok: false, message: details };
-}
-function stopRuntimeDaemonFromNode(params) {
-  const cliEntrypoint = getCliEntrypoint();
-  spawnSync(
-    process.execPath,
-    [
-      cliEntrypoint,
-      "--data-dir",
-      params.dataDir,
-      "--rpc-url",
-      params.rpcUrl,
-      "runtime",
-      "stop",
-      "--json"
-    ],
-    { encoding: "utf-8" }
-  );
+  return candidate;
 }
 
+// src/commands/node.ts
+import { Command as Command8 } from "commander";
+
 // src/lib/node-start.ts
 import { spawn } from "child_process";
-import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
-import { join as join5 } from "path";
+import { mkdirSync as mkdirSync3 } from "fs";
+import { join as join7 } from "path";
 import {
+  createKeyManager,
   ensureFiberBinary,
-  getDefaultBinaryPath,
   ProcessManager
 } from "@fiber-pay/node";
 import { startRuntimeService } from "@fiber-pay/runtime";
-import { createKeyManager } from "@fiber-pay/sdk";
 
 // src/lib/bootnode.ts
 import { existsSync as existsSync9, readFileSync as readFileSync5 } from "fs";
@@ -2823,6 +3301,182 @@ async function autoConnectBootnodes(rpc, bootnodes) {
   }
 }
 
+// src/lib/node-migration.ts
+import { dirname as dirname2 } from "path";
+import { BinaryManager as BinaryManager2, MigrationManager } from "@fiber-pay/node";
+
+// src/lib/migration-utils.ts
+function replaceRawMigrateHint(message) {
+  return message.replace(
+    /Fiber need to run some database migrations, please run `fnn-migrate[^`]*` to start migrations\.?/g,
+    "Fiber database migration is required."
+  );
+}
+function normalizeMigrationCheck(check) {
+  return {
+    ...check,
+    message: replaceRawMigrateHint(check.message)
+  };
+}
+
+// src/lib/node-migration.ts
+async function runMigrationGuard(opts) {
+  const { dataDir, binaryPath, json } = opts;
+  if (!MigrationManager.storeExists(dataDir)) {
+    return { checked: false, skippedReason: "store does not exist" };
+  }
+  const storePath = MigrationManager.resolveStorePath(dataDir);
+  const binaryDir = dirname2(binaryPath);
+  const bm = new BinaryManager2(binaryDir);
+  const migrateBinPath = bm.getMigrateBinaryPath();
+  let migrationCheck;
+  try {
+    const migrationManager = new MigrationManager(migrateBinPath);
+    migrationCheck = await migrationManager.check(storePath);
+  } catch {
+    return { checked: false, skippedReason: "fnn-migrate binary not available" };
+  }
+  if (migrationCheck.needed) {
+    const message = migrationCheck.valid ? "Database migration required. Run `fiber-pay node upgrade --force-migrate` before starting." : replaceRawMigrateHint(migrationCheck.message);
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_REQUIRED",
+        message,
+        recoverable: true,
+        suggestion: `Back up your store first (directory: "${storePath}"). Then run \`fiber-pay node upgrade --force-migrate\`. If migration still fails, close channels on the old fnn version, remove the store, and restart with a fresh store. If backup exists, restore it to roll back.`,
+        details: {
+          storePath,
+          migrationCheck: {
+            ...migrationCheck,
+            message
+          }
+        }
+      });
+    } else {
+      console.error(`\u274C ${message}`);
+      console.error(`   1) Back up store directory: ${storePath}`);
+      console.error("   2) Run: fiber-pay node upgrade --force-migrate");
+      console.error(
+        "   3) If it still fails, close channels on old fnn, remove store, then restart."
+      );
+      console.error("   4) If backup exists, restore it to roll back.");
+    }
+    process.exit(1);
+  }
+  return { checked: true, migrationCheck };
+}
+
+// src/lib/runtime-port.ts
+import { spawnSync as spawnSync2 } from "child_process";
+function parsePortFromListen(listen) {
+  const value = listen.trim();
+  if (!value) {
+    return void 0;
+  }
+  const lastColon = value.lastIndexOf(":");
+  if (lastColon < 0 || lastColon === value.length - 1) {
+    return void 0;
+  }
+  const port = Number(value.slice(lastColon + 1));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    return void 0;
+  }
+  return port;
+}
+function extractFirstPidFromLsofOutput(output) {
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("p") || trimmed.length < 2) {
+      continue;
+    }
+    const pid = Number(trimmed.slice(1));
+    if (Number.isInteger(pid) && pid > 0) {
+      return pid;
+    }
+  }
+  return void 0;
+}
+function readProcessCommand(pid) {
+  const result = spawnSync2("ps", ["-p", String(pid), "-o", "command="], {
+    encoding: "utf-8"
+  });
+  if (result.error || result.status !== 0) {
+    return void 0;
+  }
+  const command = (result.stdout ?? "").trim();
+  return command.length > 0 ? command : void 0;
+}
+function findListeningProcessByPort(listen) {
+  const port = parsePortFromListen(listen);
+  if (!port) {
+    return void 0;
+  }
+  const result = spawnSync2("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fp"], {
+    encoding: "utf-8"
+  });
+  if (result.error || result.status !== 0) {
+    return void 0;
+  }
+  const pid = extractFirstPidFromLsofOutput(result.stdout ?? "");
+  if (!pid) {
+    return void 0;
+  }
+  return {
+    pid,
+    command: readProcessCommand(pid)
+  };
+}
+function isFiberRuntimeCommand(command) {
+  if (!command) {
+    return false;
+  }
+  const normalized = command.toLowerCase();
+  const hasFiberIdentifier = normalized.includes("fiber-pay") || normalized.includes("@fiber-pay/cli") || normalized.includes("/packages/cli/dist/cli.js") || normalized.includes("\\packages\\cli\\dist\\cli.js") || normalized.includes("/dist/cli.js") || normalized.includes("\\dist\\cli.js");
+  if (!hasFiberIdentifier) {
+    return false;
+  }
+  return normalized.includes("runtime") && normalized.includes("start");
+}
+async function terminateProcess(pid, timeoutMs = 5e3) {
+  if (!isProcessRunning(pid)) {
+    return true;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (error) {
+    if (error.code === "ESRCH") {
+      return true;
+    }
+    return false;
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessRunning(pid)) {
+      return true;
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, 100));
+  }
+  if (!isProcessRunning(pid)) {
+    return true;
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch (error) {
+    if (error.code === "ESRCH") {
+      return true;
+    }
+    return false;
+  }
+  const killDeadline = Date.now() + 1e3;
+  while (Date.now() < killDeadline) {
+    if (!isProcessRunning(pid)) {
+      return true;
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, 50));
+  }
+  return !isProcessRunning(pid);
+}
+
 // src/lib/node-start.ts
 async function runNodeStartCommand(config, options) {
   const json = Boolean(options.json);
@@ -2932,25 +3586,41 @@ async function runNodeStartCommand(config, options) {
     options.runtimeProxyListen ?? config.runtimeProxyListen ?? "127.0.0.1:8229"
   );
   const proxyListenSource = options.runtimeProxyListen ? "cli" : config.runtimeProxyListen ? "profile" : "default";
-  const runtimeStateFilePath = join5(config.dataDir, "runtime-state.json");
-  const logsDir = join5(config.dataDir, "logs");
-  const fnnStdoutLogPath = join5(logsDir, "fnn.stdout.log");
-  const fnnStderrLogPath = join5(logsDir, "fnn.stderr.log");
-  const runtimeAlertLogPath = join5(logsDir, "runtime.alerts.jsonl");
-  mkdirSync2(logsDir, { recursive: true });
-  const binaryPath = config.binaryPath || getDefaultBinaryPath();
-  await ensureFiberBinary();
+  const runtimeStateFilePath = join7(config.dataDir, "runtime-state.json");
+  const logsBaseDir = join7(config.dataDir, "logs");
+  mkdirSync3(logsBaseDir, { recursive: true });
+  resolveLogDirForDate(config.dataDir);
+  const resolvedBinary = resolveBinaryPath(config);
+  const binaryPath = resolvedBinary.binaryPath;
+  if (resolvedBinary.source === "profile-managed") {
+    const installDir = getBinaryManagerInstallDirOrThrow(resolvedBinary);
+    await ensureFiberBinary({ installDir });
+  }
   const binaryVersion = getBinaryVersion(binaryPath);
   const configFilePath = ensureNodeConfigFile(config.dataDir, config.network);
   emitStage("binary_resolved", "ok", {
     binaryPath,
     binaryVersion,
+    binarySource: resolvedBinary.source,
     configFilePath
   });
   if (!json) {
     console.log(`\u{1F9E9} Binary: ${binaryPath}`);
     console.log(`\u{1F9E9} Version: ${binaryVersion}`);
   }
+  const guardResult = await runMigrationGuard({ dataDir: config.dataDir, binaryPath, json });
+  if (guardResult.checked) {
+    emitStage("migration_check", "ok", {
+      storePath: `${config.dataDir}/store`,
+      needed: false
+    });
+  } else {
+    emitStage("migration_check", "ok", {
+      storePath: `${config.dataDir}/store`,
+      skipped: true,
+      reason: guardResult.skippedReason
+    });
+  }
   const nodeConfig = {
     binaryPath,
     dataDir: config.dataDir,
@@ -2992,11 +3662,11 @@ async function runNodeStartCommand(config, options) {
     removePidFile(config.dataDir);
   });
   processManager.on("stdout", (text) => {
-    appendFileSync(fnnStdoutLogPath, text, "utf-8");
+    appendToTodayLog(config.dataDir, "fnn.stdout.log", text);
     emitFnnLog("stdout", text);
   });
   processManager.on("stderr", (text) => {
-    appendFileSync(fnnStderrLogPath, text, "utf-8");
+    appendToTodayLog(config.dataDir, "fnn.stderr.log", text);
     emitFnnLog("stderr", text);
   });
   await processManager.start();
@@ -3041,13 +3711,38 @@ async function runNodeStartCommand(config, options) {
     process.exit(1);
   }
   try {
+    const runtimePortProcess = findListeningProcessByPort(runtimeProxyListen);
+    if (runtimePortProcess) {
+      if (isFiberRuntimeCommand(runtimePortProcess.command)) {
+        const terminated = await terminateProcess(runtimePortProcess.pid);
+        if (!terminated) {
+          throw new Error(
+            `Runtime proxy ${runtimeProxyListen} is occupied by stale fiber-pay runtime PID ${runtimePortProcess.pid}, but termination failed`
+          );
+        }
+        removeRuntimeFiles(config.dataDir);
+        emitStage("runtime_preflight", "ok", {
+          proxyListen: runtimeProxyListen,
+          cleanedStaleProcessPid: runtimePortProcess.pid
+        });
+      } else if (runtimePortProcess.command) {
+        const details = runtimePortProcess.command ? `PID ${runtimePortProcess.pid} (${runtimePortProcess.command})` : `PID ${runtimePortProcess.pid}`;
+        throw new Error(
+          `Runtime proxy ${runtimeProxyListen} is already in use by non-fiber-pay process: ${details}`
+        );
+      } else {
+        throw new Error(
+          `Runtime proxy ${runtimeProxyListen} is already in use by process PID ${runtimePortProcess.pid}. Unable to determine command owner; inspect this PID manually before retrying.`
+        );
+      }
+    }
     if (runtimeDaemon) {
       const daemonStart = startRuntimeDaemonFromNode({
         dataDir: config.dataDir,
         rpcUrl: config.rpcUrl,
         proxyListen: runtimeProxyListen,
         stateFilePath: runtimeStateFilePath,
-        alertLogFile: runtimeAlertLogPath
+        alertLogsBaseDir: logsBaseDir
       });
       if (!daemonStart.ok) {
         throw new Error(daemonStart.message);
@@ -3062,23 +3757,25 @@ async function runNodeStartCommand(config, options) {
         storage: {
           stateFilePath: runtimeStateFilePath
         },
-        alerts: [{ type: "stdout" }, { type: "file", path: runtimeAlertLogPath }],
+        alerts: [{ type: "stdout" }, { type: "daily-file", baseLogsDir: logsBaseDir }],
         jobs: {
           enabled: true,
-          dbPath: join5(config.dataDir, "runtime-jobs.db")
+          dbPath: join7(config.dataDir, "runtime-jobs.db")
         }
       });
       const runtimeStatus = runtime.service.getStatus();
       writeRuntimePid(config.dataDir, process.pid);
+      const todayLogDir = resolveLogDirForDate(config.dataDir);
       writeRuntimeMeta(config.dataDir, {
         pid: process.pid,
         startedAt: runtimeStatus.startedAt,
         fiberRpcUrl: runtimeStatus.targetUrl,
         proxyListen: runtimeStatus.proxyListen,
         stateFilePath: runtimeStateFilePath,
-        alertLogFilePath: runtimeAlertLogPath,
-        fnnStdoutLogPath,
-        fnnStderrLogPath,
+        alertLogFilePath: join7(todayLogDir, "runtime.alerts.jsonl"),
+        fnnStdoutLogPath: join7(todayLogDir, "fnn.stdout.log"),
+        fnnStderrLogPath: join7(todayLogDir, "fnn.stderr.log"),
+        logsBaseDir,
         daemon: false
       });
     }
@@ -3148,7 +3845,7 @@ async function runNodeStartCommand(config, options) {
     process.exit(1);
   }
   emitStage("rpc_ready", "ok", { rpcUrl: config.rpcUrl });
-  const bootnodes = nodeConfig.configFilePath ? extractBootnodeAddrs(nodeConfig.configFilePath) : extractBootnodeAddrs(join5(config.dataDir, "config.yml"));
+  const bootnodes = nodeConfig.configFilePath ? extractBootnodeAddrs(nodeConfig.configFilePath) : extractBootnodeAddrs(join7(config.dataDir, "config.yml"));
   if (bootnodes.length > 0) {
     await autoConnectBootnodes(rpc, bootnodes);
   }
@@ -3189,9 +3886,8 @@ async function runNodeStartCommand(config, options) {
       proxyUrl: `http://${runtimeProxyListen}`,
       proxyListenSource,
       logs: {
-        fnnStdout: fnnStdoutLogPath,
-        fnnStderr: fnnStderrLogPath,
-        runtimeAlerts: runtimeAlertLogPath
+        baseDir: logsBaseDir,
+        todayDir: resolveLogDirForDate(config.dataDir)
       }
     });
   } else {
@@ -3201,7 +3897,7 @@ async function runNodeStartCommand(config, options) {
       `   Runtime proxy: http://${runtimeProxyListen} (browser-safe endpoint + monitoring)`
     );
     console.log(`   Runtime mode:  ${runtimeDaemon ? "daemon" : "embedded"}`);
-    console.log(`   Log files:     ${logsDir}`);
+    console.log(`   Log files:     ${logsBaseDir}`);
     console.log("   Press Ctrl+C to stop.");
   }
   let shutdownRequested = false;
@@ -3269,8 +3965,6 @@ async function runNodeStartCommand(config, options) {
 
 // src/lib/node-status.ts
 import { existsSync as existsSync10 } from "fs";
-import { join as join6 } from "path";
-import { getFiberBinaryInfo as getFiberBinaryInfo2 } from "@fiber-pay/node";
 import {
   buildMultiaddrFromNodeId,
   buildMultiaddrFromRpcUrl,
@@ -3437,24 +4131,29 @@ async function runNodeStatusCommand(config, options) {
   const json = Boolean(options.json);
   const pid = readPidFile(config.dataDir);
   const resolvedRpc = resolveRpcEndpoint(config);
-  const managedBinaryPath = join6(config.dataDir, "bin", "fnn");
-  const binaryInfo = config.binaryPath ? getCustomBinaryState(config.binaryPath) : await getFiberBinaryInfo2(join6(config.dataDir, "bin"));
+  const { resolvedBinary, info: binaryInfo } = await getBinaryDetails(config);
   const configExists = existsSync10(config.configPath);
   const nodeRunning = Boolean(pid && isProcessRunning(pid));
   let rpcResponsive = false;
   let nodeId = null;
+  let addresses = [];
+  let chainHash = null;
+  let version = null;
   let peerId = null;
+  let peersCount = 0;
   let peerIdError = null;
   let multiaddr = null;
   let multiaddrError = null;
   let multiaddrInferred = false;
   let channelsTotal = 0;
   let channelsReady = 0;
+  let pendingChannelCount = 0;
   let canSend = false;
   let canReceive = false;
   let localCkb = 0;
   let remoteCkb = 0;
   let fundingAddress = null;
+  let fundingLockScript = null;
   let fundingCkb = 0;
   let fundingBalanceError = null;
   if (nodeRunning) {
@@ -3464,6 +4163,10 @@ async function runNodeStatusCommand(config, options) {
       const channels = await rpc.listChannels({ include_closed: false });
       rpcResponsive = true;
       nodeId = nodeInfo.node_id;
+      addresses = nodeInfo.addresses;
+      chainHash = nodeInfo.chain_hash;
+      version = nodeInfo.version;
+      peersCount = parseInt(nodeInfo.peers_count, 16);
       try {
         peerId = await nodeIdToPeerId(nodeInfo.node_id);
       } catch (error) {
@@ -3490,18 +4193,17 @@ async function runNodeStatusCommand(config, options) {
         (channel) => channel.state?.state_name === ChannelState2.ChannelReady
       );
       channelsReady = readyChannels.length;
+      pendingChannelCount = Math.max(channelsTotal - channelsReady, 0);
       const liquidity = summarizeChannelLiquidity(readyChannels);
       canSend = liquidity.canSend;
       canReceive = liquidity.canReceive;
       localCkb = liquidity.localCkb;
       remoteCkb = liquidity.remoteCkb;
       fundingAddress = scriptToAddress(nodeInfo.default_funding_lock_script, config.network);
+      fundingLockScript = nodeInfo.default_funding_lock_script;
       if (config.ckbRpcUrl) {
         try {
-          const fundingBalance = await getLockBalanceShannons(
-            config.ckbRpcUrl,
-            nodeInfo.default_funding_lock_script
-          );
+          const fundingBalance = await getLockBalanceShannons(config.ckbRpcUrl, fundingLockScript);
           fundingCkb = Number(fundingBalance) / 1e8;
         } catch (error) {
           fundingBalanceError = error instanceof Error ? error.message : "Failed to query CKB balance for funding address";
@@ -3532,18 +4234,24 @@ async function runNodeStatusCommand(config, options) {
     rpcTarget: resolvedRpc.target,
     resolvedRpcUrl: resolvedRpc.url,
     nodeId,
+    addresses,
+    chainHash,
+    version,
     peerId,
+    peersCount,
     peerIdError,
     multiaddr,
     multiaddrError,
     multiaddrInferred,
+    fundingLockScript,
     checks: {
       binary: {
         path: binaryInfo.path,
         ready: binaryInfo.ready,
         version: binaryInfo.version,
-        source: config.binaryPath ? "env-binary-path" : "managed-binary-dir",
-        managedPath: managedBinaryPath
+        source: resolvedBinary.source,
+        managedPath: resolvedBinary.managedPath,
+        resolvedPath: resolvedBinary.binaryPath
       },
       config: {
         path: config.configPath,
@@ -3561,6 +4269,7 @@ async function runNodeStatusCommand(config, options) {
       channels: {
         total: channelsTotal,
         ready: channelsReady,
+        pending: pendingChannelCount,
         canSend,
         canReceive
       }
@@ -3587,6 +4296,12 @@ async function runNodeStatusCommand(config, options) {
     console.log(`\u2705 Node is running (PID: ${output.pid})`);
     if (output.rpcResponsive) {
       console.log(`   Node ID: ${String(output.nodeId)}`);
+      if (output.version) {
+        console.log(`   Version: ${String(output.version)}`);
+      }
+      if (output.chainHash) {
+        console.log(`   Chain Hash: ${String(output.chainHash)}`);
+      }
       if (output.peerId) {
         console.log(`   Peer ID: ${String(output.peerId)}`);
       } else if (output.peerIdError) {
@@ -3602,6 +4317,12 @@ async function runNodeStatusCommand(config, options) {
       } else {
         console.log("   Multiaddr: unavailable");
       }
+      if (output.addresses.length > 0) {
+        console.log("   Addresses:");
+        for (const address of output.addresses) {
+          console.log(`     - ${address}`);
+        }
+      }
     } else {
       console.log("   \u26A0\uFE0F  RPC not responding");
     }
@@ -3613,11 +4334,17 @@ async function runNodeStatusCommand(config, options) {
   console.log("");
   console.log("Diagnostics");
   console.log(`  Binary:        ${output.checks.binary.ready ? "ready" : "missing"}`);
+  console.log(`  Binary Path:   ${output.checks.binary.resolvedPath}`);
   console.log(`  Config:        ${output.checks.config.exists ? "present" : "missing"}`);
   console.log(`  RPC:           ${output.checks.node.rpcReachable ? "reachable" : "unreachable"}`);
   console.log(
-    `  Channels:      ${output.checks.channels.ready}/${output.checks.channels.total} ready/total`
+    `  Channels:      ${output.checks.channels.ready}/${output.checks.channels.pending}/${output.checks.channels.total} ready/pending/total`
   );
+  if (output.rpcResponsive) {
+    console.log(`  Peers:         ${output.peersCount}`);
+  } else {
+    console.log("  Peers:         unavailable");
+  }
   console.log(`  Can Send:      ${output.checks.channels.canSend ? "yes" : "no"}`);
   console.log(`  Can Receive:   ${output.checks.channels.canReceive ? "yes" : "no"}`);
   console.log(`  Recommendation:${output.recommendation}`);
@@ -3721,67 +4448,351 @@ async function runNodeReadyCommand(config, options) {
   }
 }
 
-// src/commands/node.ts
-function createNodeCommand(config) {
-  const node = new Command8("node").description("Node management");
-  node.command("start").option("--daemon", "Start node in detached background mode (node + runtime)").option("--runtime-proxy-listen <host:port>", "Runtime monitor proxy listen address").option("--event-stream <format>", "Event stream format for --json mode (jsonl)", "jsonl").option("--quiet-fnn", "Do not mirror fnn stdout/stderr to console; keep file persistence").option("--json").action(async (options) => {
-    await runNodeStartCommand(config, options);
-  });
-  node.command("stop").option("--json").action(async (options) => {
-    const json = Boolean(options.json);
-    const runtimeMeta = readRuntimeMeta(config.dataDir);
-    const runtimePid = readRuntimePid(config.dataDir);
-    if (runtimeMeta?.daemon && runtimePid && isProcessRunning(runtimePid)) {
-      stopRuntimeDaemonFromNode({ dataDir: config.dataDir, rpcUrl: config.rpcUrl });
+// src/lib/node-stop.ts
+async function runNodeStopCommand(config, options) {
+  const json = Boolean(options.json);
+  const runtimeMeta = readRuntimeMeta(config.dataDir);
+  const runtimePid = readRuntimePid(config.dataDir);
+  if (runtimeMeta?.daemon && runtimePid && isProcessRunning(runtimePid)) {
+    stopRuntimeDaemonFromNode({ dataDir: config.dataDir, rpcUrl: config.rpcUrl });
+  }
+  removeRuntimeFiles(config.dataDir);
+  const pid = readPidFile(config.dataDir);
+  if (!pid) {
+    if (json) {
+      printJsonError({
+        code: "NODE_NOT_RUNNING",
+        message: "No PID file found. Node may not be running.",
+        recoverable: true,
+        suggestion: "Run `fiber-pay node start` first if you intend to stop a node."
+      });
+    } else {
+      console.log("\u274C No PID file found. Node may not be running.");
     }
-    removeRuntimeFiles(config.dataDir);
-    const pid = readPidFile(config.dataDir);
-    if (!pid) {
-      if (json) {
-        printJsonError({
-          code: "NODE_NOT_RUNNING",
-          message: "No PID file found. Node may not be running.",
-          recoverable: true,
-          suggestion: "Run `fiber-pay node start` first if you intend to stop a node."
-        });
-      } else {
-        console.log("\u274C No PID file found. Node may not be running.");
-      }
-      process.exit(1);
+    process.exit(1);
+  }
+  if (!isProcessRunning(pid)) {
+    if (json) {
+      printJsonError({
+        code: "NODE_NOT_RUNNING",
+        message: `Process ${pid} is not running. Cleaning up PID file.`,
+        recoverable: true,
+        suggestion: "Start the node again if needed; stale PID has been cleaned.",
+        details: { pid, stalePidFileCleaned: true }
+      });
+    } else {
+      console.log(`\u274C Process ${pid} is not running. Cleaning up PID file.`);
     }
-    if (!isProcessRunning(pid)) {
-      if (json) {
-        printJsonError({
-          code: "NODE_NOT_RUNNING",
-          message: `Process ${pid} is not running. Cleaning up PID file.`,
-          recoverable: true,
-          suggestion: "Start the node again if needed; stale PID has been cleaned.",
-          details: { pid, stalePidFileCleaned: true }
-        });
-      } else {
-        console.log(`\u274C Process ${pid} is not running. Cleaning up PID file.`);
+    removePidFile(config.dataDir);
+    process.exit(1);
+  }
+  if (!json) {
+    console.log(`\u{1F6D1} Stopping node (PID: ${pid})...`);
+  }
+  process.kill(pid, "SIGTERM");
+  let attempts = 0;
+  while (isProcessRunning(pid) && attempts < 30) {
+    await new Promise((resolve2) => setTimeout(resolve2, 100));
+    attempts++;
+  }
+  if (isProcessRunning(pid)) {
+    process.kill(pid, "SIGKILL");
+  }
+  removePidFile(config.dataDir);
+  if (json) {
+    printJsonSuccess({ pid, stopped: true });
+  } else {
+    console.log("\u2705 Node stopped.");
+  }
+}
+
+// src/lib/node-upgrade.ts
+import { BinaryManager as BinaryManager3, MigrationManager as MigrationManager2 } from "@fiber-pay/node";
+async function runNodeUpgradeCommand(config, options) {
+  const json = Boolean(options.json);
+  const resolvedBinary = resolveBinaryPath(config);
+  let installDir;
+  try {
+    installDir = getBinaryManagerInstallDirOrThrow(resolvedBinary);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) {
+      printJsonError({
+        code: "BINARY_PATH_INCOMPATIBLE",
+        message,
+        recoverable: true,
+        suggestion: "Use `fiber-pay config profile unset binaryPath` or set binaryPath to a standard fnn filename in the target directory."
+      });
+    } else {
+      console.error(`\u274C ${message}`);
+    }
+    process.exit(1);
+  }
+  const binaryManager = new BinaryManager3(installDir);
+  const pid = readPidFile(config.dataDir);
+  if (pid && isProcessRunning(pid)) {
+    const msg = "The Fiber node is currently running. Stop it before upgrading.";
+    if (json) {
+      printJsonError({
+        code: "NODE_RUNNING",
+        message: msg,
+        recoverable: true,
+        suggestion: "Run `fiber-pay node stop` first, then retry the upgrade."
+      });
+    } else {
+      console.error(`\u274C ${msg}`);
+      console.log("   Run: fiber-pay node stop");
+    }
+    process.exit(1);
+  }
+  let targetTag;
+  if (options.version) {
+    targetTag = binaryManager.normalizeTag(options.version);
+  } else {
+    if (!json) console.log("\u{1F50D} Resolving latest Fiber release...");
+    targetTag = await binaryManager.getLatestTag();
+  }
+  if (!json) console.log(`\u{1F4E6} Target version: ${targetTag}`);
+  const currentInfo = await binaryManager.getBinaryInfo();
+  const targetVersion = targetTag.startsWith("v") ? targetTag.slice(1) : targetTag;
+  const storePath = MigrationManager2.resolveStorePath(config.dataDir);
+  const migrateBinaryPath = binaryManager.getMigrateBinaryPath();
+  let migrationCheck = null;
+  const storeExists = MigrationManager2.storeExists(config.dataDir);
+  if (!json && storeExists) {
+    console.log("\u{1F4C2} Existing store detected.");
+  }
+  if (currentInfo.ready && currentInfo.version === targetVersion && !options.forceMigrate) {
+    if (storeExists) {
+      migrationCheck = await runMigrationAndReport({
+        migrateBinaryPath,
+        storePath,
+        json,
+        checkOnly: Boolean(options.checkOnly),
+        targetVersion,
+        backup: options.backup !== false,
+        forceMigrateAttempt: false
+      });
+    }
+    const msg = migrationCheck ? `Already installed ${targetTag}. Store compatibility checked.` : `Already installed ${targetTag}. Use --force-migrate to run migration flow anyway.`;
+    if (json) {
+      printJsonSuccess({
+        action: "none",
+        currentVersion: currentInfo.version,
+        targetVersion,
+        message: msg,
+        migration: migrationCheck
+      });
+    } else {
+      console.log(`\u2705 ${msg}`);
+    }
+    return;
+  }
+  const versionMatches = currentInfo.ready && currentInfo.version === targetVersion;
+  const shouldDownload = !versionMatches;
+  if (!json && currentInfo.ready) {
+    console.log(`   Current version: v${currentInfo.version}`);
+  }
+  if (shouldDownload) {
+    if (!json && storeExists) {
+      console.log("\u{1F4C2} Existing store detected, will check migration after download.");
+    }
+    if (!json) console.log("\u2B07\uFE0F  Downloading new binary...");
+    const showProgress2 = (progress) => {
+      if (!json) {
+        const percent = progress.percent !== void 0 ? ` (${progress.percent}%)` : "";
+        process.stdout.write(`\r   [${progress.phase}]${percent} ${progress.message}`.padEnd(80));
+        if (progress.phase === "installing") console.log();
       }
-      removePidFile(config.dataDir);
-      process.exit(1);
+    };
+    await binaryManager.download({
+      version: targetTag,
+      force: true,
+      onProgress: showProgress2
+    });
+  } else if (!json && options.forceMigrate) {
+    console.log("\u23ED\uFE0F  Skipping binary download: target version is already installed.");
+    console.log("\u{1F501} --force-migrate enabled: attempting migration flow on existing binaries.");
+  }
+  if (storeExists) {
+    migrationCheck = await runMigrationAndReport({
+      migrateBinaryPath,
+      storePath,
+      json,
+      checkOnly: Boolean(options.checkOnly),
+      targetVersion,
+      backup: options.backup !== false,
+      forceMigrateAttempt: Boolean(options.forceMigrate)
+    });
+  }
+  const newInfo = await binaryManager.getBinaryInfo();
+  if (json) {
+    printJsonSuccess({
+      action: "upgraded",
+      previousVersion: currentInfo.ready ? currentInfo.version : null,
+      currentVersion: newInfo.version,
+      binaryPath: newInfo.path,
+      migrateBinaryPath,
+      migration: migrationCheck
+    });
+  } else {
+    console.log("\n\u2705 Upgrade complete!");
+    console.log(`   Version: v${newInfo.version}`);
+    console.log(`   Binary:  ${newInfo.path}`);
+    console.log("\n   Start the node with: fiber-pay node start");
+  }
+}
+async function runMigrationAndReport(opts) {
+  const {
+    migrateBinaryPath,
+    storePath,
+    json,
+    checkOnly,
+    targetVersion,
+    backup,
+    forceMigrateAttempt
+  } = opts;
+  let migrationManager;
+  try {
+    migrationManager = new MigrationManager2(migrateBinaryPath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "fnn-migrate binary not available";
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_TOOL_MISSING",
+        message: msg,
+        recoverable: true,
+        suggestion: "Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      });
+    } else {
+      console.error(`
+\u26A0\uFE0F  ${msg}`);
+      console.log(
+        "   Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      );
     }
-    if (!json) {
-      console.log(`\u{1F6D1} Stopping node (PID: ${pid})...`);
+    process.exit(1);
+  }
+  if (!json) console.log("\u{1F50D} Checking store compatibility...");
+  let migrationCheck;
+  try {
+    migrationCheck = await migrationManager.check(storePath);
+  } catch (checkErr) {
+    const msg = checkErr instanceof Error ? checkErr.message : String(checkErr);
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_TOOL_MISSING",
+        message: `Migration check failed: ${msg}`,
+        recoverable: true,
+        suggestion: "Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      });
+    } else {
+      console.error(`
+\u26A0\uFE0F  Migration check failed: ${msg}`);
+      console.log(
+        "   Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      );
     }
-    process.kill(pid, "SIGTERM");
-    let attempts = 0;
-    while (isProcessRunning(pid) && attempts < 30) {
-      await new Promise((resolve2) => setTimeout(resolve2, 100));
-      attempts++;
+    process.exit(1);
+  }
+  if (checkOnly) {
+    const normalizedCheck = normalizeMigrationCheck(migrationCheck);
+    if (json) {
+      printJsonSuccess({
+        action: "check-only",
+        targetVersion,
+        migration: normalizedCheck
+      });
+    } else {
+      console.log(`
+\u{1F4CB} Migration status: ${normalizedCheck.message}`);
     }
-    if (isProcessRunning(pid)) {
-      process.kill(pid, "SIGKILL");
+    process.exit(0);
+  }
+  if (!migrationCheck.needed) {
+    if (!json) console.log("   Store is compatible, no migration needed.");
+    return normalizeMigrationCheck(migrationCheck);
+  }
+  if (!migrationCheck.valid && !forceMigrateAttempt) {
+    const normalizedMessage = replaceRawMigrateHint(migrationCheck.message);
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_INCOMPATIBLE",
+        message: normalizedMessage,
+        recoverable: false,
+        suggestion: `Back up your store first (directory: "${storePath}"). Then run \`fiber-pay node upgrade --force-migrate\`. If it still fails, close all channels with the old fnn version, remove the store, and restart with a fresh store. If you attempted migration with backup enabled, you can roll back by restoring the backup directory.`,
+        details: {
+          storePath,
+          migrationCheck: {
+            ...migrationCheck,
+            message: normalizedMessage
+          }
+        }
+      });
+    } else {
+      console.error("\n\u274C Store migration is not possible automatically.");
+      console.log(normalizedMessage);
+      console.log(`   1) Back up store directory: ${storePath}`);
+      console.log("   2) Try: fiber-pay node upgrade --force-migrate");
+      console.log(
+        "   3) If it still fails, close channels on old fnn, remove store, then restart."
+      );
+      console.log("   4) If migration created a backup, you can roll back by restoring it.");
     }
-    removePidFile(config.dataDir);
+    process.exit(1);
+  }
+  if (!migrationCheck.valid && !json) {
+    console.log("\u26A0\uFE0F  Store check reported incompatibility, but --force-migrate is set.");
+    console.log("   Attempting migration anyway with backup enabled (unless --no-backup).");
+  }
+  if (!json) console.log("\u{1F504} Running database migration...");
+  const result = await migrationManager.migrate({
+    storePath,
+    backup,
+    force: forceMigrateAttempt
+  });
+  if (!result.success) {
     if (json) {
-      printJsonSuccess({ pid, stopped: true });
+      printJsonError({
+        code: "MIGRATION_FAILED",
+        message: result.message,
+        recoverable: !!result.backupPath,
+        suggestion: result.backupPath ? `To roll back, delete the current store at "${storePath}" and restore the backup from "${result.backupPath}".` : "Re-download the previous version or start fresh.",
+        details: { output: result.output, backupPath: result.backupPath }
+      });
     } else {
-      console.log("\u2705 Node stopped.");
+      console.error("\n\u274C Migration failed.");
+      console.log(result.message);
+    }
+    process.exit(1);
+  }
+  if (!json) {
+    console.log(`\u2705 ${result.message}`);
+    if (result.backupPath) {
+      console.log(`   Backup: ${result.backupPath}`);
+    }
+  }
+  try {
+    const postCheck = await migrationManager.check(storePath);
+    return normalizeMigrationCheck(postCheck);
+  } catch (err) {
+    if (!json) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("\u26A0\uFE0F  Post-migration check failed; final migration status may be stale.");
+      console.error(`   ${message}`);
     }
+    return normalizeMigrationCheck(migrationCheck);
+  }
+}
+
+// src/commands/node.ts
+function createNodeCommand(config) {
+  const node = new Command8("node").description("Node management");
+  node.command("start").option("--daemon", "Start node in detached background mode (node + runtime)").option("--runtime-proxy-listen <host:port>", "Runtime monitor proxy listen address").option("--event-stream <format>", "Event stream format for --json mode (jsonl)", "jsonl").option("--quiet-fnn", "Do not mirror fnn stdout/stderr to console; keep file persistence").option("--json").action(async (options) => {
+    await runNodeStartCommand(config, options);
+  });
+  node.command("stop").option("--json").action(async (options) => {
+    await runNodeStopCommand(config, options);
   });
   node.command("status").option("--json").action(async (options) => {
     await runNodeStatusCommand(config, options);
@@ -3789,34 +4800,17 @@ function createNodeCommand(config) {
   node.command("ready").description("Agent-oriented readiness summary for automation").option("--json").action(async (options) => {
     await runNodeReadyCommand(config, options);
   });
-  node.command("info").option("--json").action(async (options) => {
-    const rpc = await createReadyRpcClient(config);
-    const nodeInfo = await rpc.nodeInfo();
-    const fundingAddress = scriptToAddress2(nodeInfo.default_funding_lock_script, config.network);
-    const peerId = await nodeIdToPeerId2(nodeInfo.node_id);
-    const output = {
-      nodeId: nodeInfo.node_id,
-      peerId,
-      addresses: nodeInfo.addresses,
-      chainHash: nodeInfo.chain_hash,
-      fundingAddress,
-      fundingLockScript: nodeInfo.default_funding_lock_script,
-      version: nodeInfo.version,
-      channelCount: parseInt(nodeInfo.channel_count, 16),
-      pendingChannelCount: parseInt(nodeInfo.pending_channel_count, 16),
-      peersCount: parseInt(nodeInfo.peers_count, 16)
-    };
-    if (options.json) {
-      printJsonSuccess(output);
-    } else {
-      printNodeInfoHuman(output);
-    }
+  node.command("upgrade").description("Upgrade the Fiber node binary and migrate the database if needed").option("--version <version>", "Target Fiber version (default: latest)").option("--no-backup", "Skip creating a store backup before migration").option("--check-only", "Only check if migration is needed, do not migrate").option(
+    "--force-migrate",
+    "Force migration attempt even when compatibility check reports incompatible data"
+  ).option("--json").action(async (options) => {
+    await runNodeUpgradeCommand(config, options);
   });
   return node;
 }
 
 // src/commands/payment.ts
-import { ckbToShannons as ckbToShannons3, shannonsToCkb as shannonsToCkb4 } from "@fiber-pay/sdk";
+import { ckbToShannons as ckbToShannons4, shannonsToCkb as shannonsToCkb5 } from "@fiber-pay/sdk";
 import { Command as Command9 } from "commander";
 function createPaymentCommand(config) {
   const payment = new Command9("payment").description("Payment lifecycle and status commands");
@@ -3858,9 +4852,9 @@ function createPaymentCommand(config) {
     const paymentParams = {
       invoice,
       target_pubkey: recipientNodeId,
-      amount: amountCkb ? ckbToShannons3(amountCkb) : void 0,
+      amount: amountCkb ? ckbToShannons4(amountCkb) : void 0,
       keysend: recipientNodeId ? true : void 0,
-      max_fee_amount: maxFeeCkb ? ckbToShannons3(maxFeeCkb) : void 0
+      max_fee_amount: maxFeeCkb ? ckbToShannons4(maxFeeCkb) : void 0
     };
     const endpoint = resolveRpcEndpoint(config);
     if (endpoint.target === "runtime-proxy") {
@@ -3902,7 +4896,7 @@ function createPaymentCommand(config) {
     const payload = {
       paymentHash: result.payment_hash,
       status: result.status === "Success" ? "success" : result.status === "Failed" ? "failed" : "pending",
-      feeCkb: shannonsToCkb4(result.fee),
+      feeCkb: shannonsToCkb5(result.fee),
       failureReason: result.failed_error
     };
     if (json) {
@@ -3917,6 +4911,7 @@ function createPaymentCommand(config) {
       }
     }
   });
+  registerPaymentRebalanceCommand(payment, config);
   payment.command("get").argument("<paymentHash>").option("--json").action(async (paymentHash, options) => {
     const rpc = await createReadyRpcClient(config);
     const result = await rpc.getPayment({ payment_hash: paymentHash });
@@ -4065,7 +5060,7 @@ function createPaymentCommand(config) {
       process.exit(1);
     }
     const hopsInfo = pubkeys.map((pubkey) => ({ pubkey }));
-    const amount = options.amount ? ckbToShannons3(parseFloat(options.amount)) : void 0;
+    const amount = options.amount ? ckbToShannons4(parseFloat(options.amount)) : void 0;
     const result = await rpc.buildRouter({
       hops_info: hopsInfo,
       amount
@@ -4081,7 +5076,7 @@ function createPaymentCommand(config) {
         console.log(
           `    Outpoint:   ${hop.channel_outpoint.tx_hash}:${hop.channel_outpoint.index}`
         );
-        console.log(`    Amount:     ${shannonsToCkb4(hop.amount_received)} CKB`);
+        console.log(`    Amount:     ${shannonsToCkb5(hop.amount_received)} CKB`);
         console.log(`    Expiry:     ${hop.incoming_tlc_expiry}`);
       }
     }
@@ -4089,7 +5084,7 @@ function createPaymentCommand(config) {
   payment.command("send-route").description("Send a payment using a pre-built route from `payment route`").requiredOption(
     "--router <json>",
     "JSON array of router hops (output of `payment route --json`)"
-  ).option("--invoice <invoice>", "Invoice to pay").option("--payment-hash <hash>", "Payment hash (for keysend)").option("--keysend", "Keysend mode").option("--dry-run", "Simulate\u2014do not actually send").option("--json").action(async (options) => {
+  ).option("--invoice <invoice>", "Invoice to pay").option("--payment-hash <hash>", "Payment hash (for keysend)").option("--keysend", "Keysend mode").option("--allow-self-payment", "Allow self-payment for circular route rebalancing").option("--dry-run", "Simulate\u2014do not actually send").option("--json").action(async (options) => {
     const rpc = await createReadyRpcClient(config);
     const json = Boolean(options.json);
     let router;
@@ -4114,12 +5109,13 @@ function createPaymentCommand(config) {
       invoice: options.invoice,
       payment_hash: options.paymentHash,
       keysend: options.keysend ? true : void 0,
+      allow_self_payment: options.allowSelfPayment ? true : void 0,
       dry_run: options.dryRun ? true : void 0
     });
     const payload = {
       paymentHash: result.payment_hash,
       status: result.status === "Success" ? "success" : result.status === "Failed" ? "failed" : "pending",
-      feeCkb: shannonsToCkb4(result.fee),
+      feeCkb: shannonsToCkb5(result.fee),
       failureReason: result.failed_error,
       dryRun: Boolean(options.dryRun)
     };
@@ -4143,7 +5139,7 @@ function getJobPaymentHash(job) {
 }
 function getJobFeeCkb(job) {
   const result = job.result;
-  return result?.fee ? shannonsToCkb4(result.fee) : 0;
+  return result?.fee ? shannonsToCkb5(result.fee) : 0;
 }
 function getJobFailure(job) {
   const result = job.result;
@@ -4215,7 +5211,7 @@ function createPeerCommand(config) {
 
 // src/commands/runtime.ts
 import { spawn as spawn2 } from "child_process";
-import { resolve } from "path";
+import { join as join8, resolve } from "path";
 import {
   alertPriorityOrder,
   formatRuntimeAlert as formatRuntimeAlert2,
@@ -4289,15 +5285,22 @@ function shouldPrintAlert(alert, filter) {
   }
   return true;
 }
+function resolveRuntimeRecoveryListen(config) {
+  const meta = readRuntimeMeta(config.dataDir);
+  return meta?.proxyListen ?? config.runtimeProxyListen ?? "127.0.0.1:8229";
+}
 function createRuntimeCommand(config) {
   const runtime = new Command11("runtime").description("Polling monitor and alert runtime service");
-  runtime.command("start").description("Start runtime monitor service in foreground").option("--daemon", "Start runtime monitor in detached background mode").option("--fiber-rpc-url <url>", "Target fiber rpc URL (defaults to --rpc-url/global config)").option("--proxy-listen <host:port>", "Monitor proxy listen address").option("--channel-poll-ms <ms>", "Channel polling interval in milliseconds").option("--invoice-poll-ms <ms>", "Invoice polling interval in milliseconds").option("--payment-poll-ms <ms>", "Payment polling interval in milliseconds").option("--peer-poll-ms <ms>", "Peer polling interval in milliseconds").option("--health-poll-ms <ms>", "RPC health polling interval in milliseconds").option("--include-closed <bool>", "Monitor closed channels (true|false)").option("--completed-ttl-seconds <seconds>", "TTL for completed invoices/payments in tracker").option("--state-file <path>", "State file path for snapshots and history").option("--alert-log-file <path>", "Path to runtime alert JSONL log file").option("--flush-ms <ms>", "State flush interval in milliseconds").option("--webhook <url>", "Webhook URL to receive alert POST payloads").option("--websocket <host:port>", "WebSocket alert broadcast listen address").option(
+  runtime.command("start").description("Start runtime monitor service in foreground").option("--daemon", "Start runtime monitor in detached background mode").option("--fiber-rpc-url <url>", "Target fiber rpc URL (defaults to --rpc-url/global config)").option("--proxy-listen <host:port>", "Monitor proxy listen address").option("--channel-poll-ms <ms>", "Channel polling interval in milliseconds").option("--invoice-poll-ms <ms>", "Invoice polling interval in milliseconds").option("--payment-poll-ms <ms>", "Payment polling interval in milliseconds").option("--peer-poll-ms <ms>", "Peer polling interval in milliseconds").option("--health-poll-ms <ms>", "RPC health polling interval in milliseconds").option("--include-closed <bool>", "Monitor closed channels (true|false)").option("--completed-ttl-seconds <seconds>", "TTL for completed invoices/payments in tracker").option("--state-file <path>", "State file path for snapshots and history").option("--alert-log-file <path>", "Path to runtime alert JSONL log file (legacy static path)").option("--alert-logs-base-dir <dir>", "Base logs directory for daily-rotated alert files").option("--flush-ms <ms>", "State flush interval in milliseconds").option("--webhook <url>", "Webhook URL to receive alert POST payloads").option("--websocket <host:port>", "WebSocket alert broadcast listen address").option(
     "--log-min-priority <priority>",
     "Minimum runtime log priority (critical|high|medium|low)"
   ).option("--log-type <types>", "Comma-separated runtime alert types to print").option("--json").action(async (options) => {
     const asJson = Boolean(options.json);
     const daemon = Boolean(options.daemon);
     const isRuntimeChild = process.env.FIBER_RUNTIME_CHILD === "1";
+    const runtimeListen = String(
+      options.proxyListen ?? config.runtimeProxyListen ?? "127.0.0.1:8229"
+    );
     try {
       const existingPid = readRuntimePid(config.dataDir);
       if (existingPid && isProcessRunning(existingPid) && (!isRuntimeChild || existingPid !== process.pid)) {
@@ -4317,6 +5320,32 @@ function createRuntimeCommand(config) {
       if (existingPid && !isProcessRunning(existingPid)) {
         removeRuntimeFiles(config.dataDir);
       }
+      const discovered = findListeningProcessByPort(runtimeListen);
+      if (discovered && (!existingPid || discovered.pid !== existingPid)) {
+        if (isFiberRuntimeCommand(discovered.command)) {
+          const terminated = await terminateProcess(discovered.pid);
+          if (!terminated) {
+            throw new Error(
+              `Runtime port ${runtimeListen} is occupied by stale fiber-pay runtime PID ${discovered.pid} but termination failed.`
+            );
+          }
+          removeRuntimeFiles(config.dataDir);
+          if (!asJson) {
+            console.log(
+              `Recovered stale runtime process on ${runtimeListen} (PID: ${discovered.pid}).`
+            );
+          }
+        } else if (discovered.command) {
+          const details = discovered.command ? `PID ${discovered.pid} (${discovered.command})` : `PID ${discovered.pid}`;
+          throw new Error(
+            `Runtime proxy listen ${runtimeListen} is already in use by non-fiber-pay process: ${details}`
+          );
+        } else {
+          throw new Error(
+            `Runtime proxy listen ${runtimeListen} is already in use by process PID ${discovered.pid}. Unable to determine the owning command; inspect this PID manually before retrying.`
+          );
+        }
+      }
       if (daemon && !isRuntimeChild) {
         const childArgv = process.argv.filter((arg) => arg !== "--daemon");
         const child = spawn2(process.execPath, childArgv.slice(1), {
@@ -4359,7 +5388,7 @@ function createRuntimeCommand(config) {
         ),
         proxy: {
           enabled: true,
-          listen: String(options.proxyListen ?? config.runtimeProxyListen ?? "127.0.0.1:8229")
+          listen: runtimeListen
         },
         storage: {
           stateFilePath: options.stateFile ? resolve(String(options.stateFile)) : resolve(config.dataDir, "runtime-state.json"),
@@ -4370,9 +5399,21 @@ function createRuntimeCommand(config) {
           dbPath: resolve(config.dataDir, "runtime-jobs.db")
         }
       };
-      const alertLogFile = options.alertLogFile ? resolve(String(options.alertLogFile)) : resolve(config.dataDir, "logs", "runtime.alerts.jsonl");
+      let alertLogsBaseDir;
+      let alertLogFile;
+      if (options.alertLogsBaseDir) {
+        alertLogsBaseDir = resolve(String(options.alertLogsBaseDir));
+      } else if (options.alertLogFile) {
+        alertLogFile = resolve(String(options.alertLogFile));
+      } else {
+        alertLogsBaseDir = resolve(config.dataDir, "logs");
+      }
       const alerts = [{ type: "stdout" }];
-      alerts.push({ type: "file", path: alertLogFile });
+      if (alertLogsBaseDir) {
+        alerts.push({ type: "daily-file", baseLogsDir: alertLogsBaseDir });
+      } else if (alertLogFile) {
+        alerts.push({ type: "file", path: alertLogFile });
+      }
       if (options.webhook) {
         alerts.push({ type: "webhook", url: String(options.webhook) });
       }
@@ -4394,6 +5435,12 @@ function createRuntimeCommand(config) {
       }
       const runtime2 = await startRuntimeService2(runtimeConfig);
       const status = runtime2.service.getStatus();
+      const logsBaseDir = alertLogsBaseDir ?? resolve(config.dataDir, "logs");
+      const todayLogDir = resolveLogDirForDateWithOptions(config.dataDir, void 0, {
+        logsBaseDir,
+        ensureExists: false
+      });
+      const effectiveAlertLogPath = alertLogsBaseDir ? join8(todayLogDir, "runtime.alerts.jsonl") : alertLogFile ?? join8(todayLogDir, "runtime.alerts.jsonl");
       writeRuntimePid(config.dataDir, process.pid);
       writeRuntimeMeta(config.dataDir, {
         pid: process.pid,
@@ -4401,7 +5448,10 @@ function createRuntimeCommand(config) {
         fiberRpcUrl: status.targetUrl,
         proxyListen: status.proxyListen,
         stateFilePath: runtimeConfig.storage?.stateFilePath,
-        alertLogFilePath: alertLogFile,
+        alertLogFilePath: effectiveAlertLogPath,
+        fnnStdoutLogPath: join8(todayLogDir, "fnn.stdout.log"),
+        fnnStderrLogPath: join8(todayLogDir, "fnn.stderr.log"),
+        logsBaseDir,
         daemon: daemon || isRuntimeChild
       });
       runtime2.service.on("alert", (alert) => {
@@ -4420,14 +5470,16 @@ function createRuntimeCommand(config) {
           fiberRpcUrl: status.targetUrl,
           proxyListen: status.proxyListen,
           stateFilePath: runtimeConfig.storage?.stateFilePath,
-          alertLogFile
+          alertLogFile: effectiveAlertLogPath,
+          logsBaseDir
         });
         printJsonEvent("runtime_started", status);
       } else {
         console.log(`Fiber RPC:    ${status.targetUrl}`);
         console.log(`Proxy listen: ${status.proxyListen}`);
         console.log(`State file:   ${runtimeConfig.storage?.stateFilePath}`);
-        console.log(`Alert log:    ${alertLogFile}`);
+        console.log(`Logs dir:     ${logsBaseDir}`);
+        console.log(`Alert log:    ${effectiveAlertLogPath}`);
         console.log("Runtime monitor is running. Press Ctrl+C to stop.");
       }
       const signal = await runtime2.waitForShutdownSignal();
@@ -4461,8 +5513,42 @@ function createRuntimeCommand(config) {
   });
   runtime.command("status").description("Show runtime process and health status").option("--json").action(async (options) => {
     const asJson = Boolean(options.json);
-    const pid = readRuntimePid(config.dataDir);
+    let pid = readRuntimePid(config.dataDir);
     const meta = readRuntimeMeta(config.dataDir);
+    const recoveryListen = resolveRuntimeRecoveryListen(config);
+    if (!pid) {
+      const fallback = findListeningProcessByPort(recoveryListen);
+      if (fallback && isFiberRuntimeCommand(fallback.command)) {
+        pid = fallback.pid;
+        writeRuntimePid(config.dataDir, pid);
+      } else if (fallback && fallback.command) {
+        const details = fallback.command ? `PID ${fallback.pid} (${fallback.command})` : `PID ${fallback.pid}`;
+        if (asJson) {
+          printJsonError({
+            code: "RUNTIME_PORT_IN_USE",
+            message: `Runtime proxy port is in use by non-fiber-pay process: ${details}`,
+            recoverable: true,
+            suggestion: "Stop that process or use a different --proxy-listen port."
+          });
+        } else {
+          console.log(`Runtime proxy port is in use by non-fiber-pay process: ${details}`);
+        }
+        process.exit(1);
+      } else if (fallback) {
+        const message = `Runtime proxy port is in use by process PID ${fallback.pid}. The owning command could not be determined; inspect this PID manually.`;
+        if (asJson) {
+          printJsonError({
+            code: "RUNTIME_PORT_IN_USE",
+            message,
+            recoverable: true,
+            suggestion: "Inspect the PID owner manually or use a different --proxy-listen port."
+          });
+        } else {
+          console.log(message);
+        }
+        process.exit(1);
+      }
+    }
     if (!pid) {
       if (asJson) {
         printJsonError({
@@ -4493,9 +5579,11 @@ function createRuntimeCommand(config) {
       process.exit(1);
     }
     let rpcStatus;
-    if (meta?.proxyListen) {
+    if (meta?.proxyListen ?? recoveryListen) {
       try {
-        const response = await fetch(`http://${meta.proxyListen}/monitor/status`);
+        const response = await fetch(
+          `http://${meta?.proxyListen ?? recoveryListen}/monitor/status`
+        );
         if (response.ok) {
           rpcStatus = await response.json();
         }
@@ -4523,7 +5611,41 @@ function createRuntimeCommand(config) {
   });
   runtime.command("stop").description("Stop runtime process by PID").option("--json").action(async (options) => {
     const asJson = Boolean(options.json);
-    const pid = readRuntimePid(config.dataDir);
+    let pid = readRuntimePid(config.dataDir);
+    const recoveryListen = resolveRuntimeRecoveryListen(config);
+    if (!pid) {
+      const fallback = findListeningProcessByPort(recoveryListen);
+      if (fallback && isFiberRuntimeCommand(fallback.command)) {
+        pid = fallback.pid;
+        writeRuntimePid(config.dataDir, pid);
+      } else if (fallback && fallback.command) {
+        const details = fallback.command ? `PID ${fallback.pid} (${fallback.command})` : `PID ${fallback.pid}`;
+        if (asJson) {
+          printJsonError({
+            code: "RUNTIME_PORT_IN_USE",
+            message: `Runtime proxy port is in use by non-fiber-pay process: ${details}`,
+            recoverable: true,
+            suggestion: "Stop that process manually; it is not managed by fiber-pay runtime PID files."
+          });
+        } else {
+          console.log(`Runtime proxy port is in use by non-fiber-pay process: ${details}`);
+        }
+        process.exit(1);
+      } else if (fallback) {
+        const message = `Runtime proxy port is in use by process PID ${fallback.pid}. The owning command could not be determined; inspect this PID manually.`;
+        if (asJson) {
+          printJsonError({
+            code: "RUNTIME_PORT_IN_USE",
+            message,
+            recoverable: true,
+            suggestion: "Inspect the PID owner manually; it may not be managed by fiber-pay runtime PID files."
+          });
+        } else {
+          console.log(message);
+        }
+        process.exit(1);
+      }
+    }
     if (!pid) {
       if (asJson) {
         printJsonError({
@@ -4552,14 +5674,19 @@ function createRuntimeCommand(config) {
       }
       process.exit(1);
     }
-    process.kill(pid, "SIGTERM");
-    let attempts = 0;
-    while (isProcessRunning(pid) && attempts < 50) {
-      await new Promise((resolve2) => setTimeout(resolve2, 100));
-      attempts += 1;
-    }
-    if (isProcessRunning(pid)) {
-      process.kill(pid, "SIGKILL");
+    const terminated = await terminateProcess(pid);
+    if (!terminated) {
+      if (asJson) {
+        printJsonError({
+          code: "RUNTIME_STOP_FAILED",
+          message: `Failed to terminate runtime process ${pid}.`,
+          recoverable: true,
+          suggestion: `Try stopping PID ${pid} manually and rerun runtime stop.`
+        });
+      } else {
+        console.log(`Failed to terminate runtime process ${pid}.`);
+      }
+      process.exit(1);
     }
     removeRuntimeFiles(config.dataDir);
     if (asJson) {
@@ -4575,8 +5702,8 @@ function createRuntimeCommand(config) {
 import { Command as Command12 } from "commander";
 
 // src/lib/build-info.ts
-var CLI_VERSION = "0.1.0-rc.3";
-var CLI_COMMIT = "6f39077caade6d3a307db28b8d3e9cfdee7eaf99";
+var CLI_VERSION = "0.1.0-rc.5";
+var CLI_COMMIT = "28cee07226e004d775ed747bbcbf61474f93c492";
 
 // src/commands/version.ts
 function createVersionCommand() {
@@ -4594,6 +5721,55 @@ function createVersionCommand() {
   });
 }
 
+// src/lib/argv.ts
+var GLOBAL_OPTIONS_WITH_VALUE = /* @__PURE__ */ new Set([
+  "--profile",
+  "--data-dir",
+  "--rpc-url",
+  "--network",
+  "--key-password",
+  "--binary-path"
+]);
+function isOptionToken(token) {
+  return token.startsWith("-") && token !== "-";
+}
+function hasInlineValue(token) {
+  return token.includes("=");
+}
+function getFirstPositional(argv) {
+  for (let index = 2; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === "--") {
+      return argv[index + 1];
+    }
+    if (!isOptionToken(token)) {
+      return token;
+    }
+    if (GLOBAL_OPTIONS_WITH_VALUE.has(token) && !hasInlineValue(token)) {
+      const next = argv[index + 1];
+      if (next && !isOptionToken(next)) {
+        index++;
+      }
+    }
+  }
+  return void 0;
+}
+function hasTopLevelVersionFlag(argv) {
+  for (let index = 2; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === "--") {
+      return false;
+    }
+    if (token === "--version" || token === "-v") {
+      return true;
+    }
+  }
+  return false;
+}
+function isTopLevelVersionRequest(argv) {
+  return !getFirstPositional(argv) && hasTopLevelVersionFlag(argv);
+}
+
 // src/index.ts
 function shouldOutputJson() {
   return process.argv.includes("--json");
@@ -4635,6 +5811,14 @@ function applyGlobalOverrides(argv) {
         }
         break;
       }
+      case "--rpc-biscuit-token": {
+        const value = getFlagValue(argv, index);
+        if (value) {
+          process.env.FIBER_RPC_BISCUIT_TOKEN = value;
+          explicitFlags.add("rpcBiscuitToken");
+        }
+        break;
+      }
       case "--network": {
         const value = getFlagValue(argv, index);
         if (value) {
@@ -4674,7 +5858,7 @@ function applyGlobalOverrides(argv) {
   }
   if (!explicitDataDir && profileName) {
     const homeDir = process.env.HOME ?? process.cwd();
-    process.env.FIBER_DATA_DIR = join7(homeDir, ".fiber-pay", "profiles", profileName);
+    process.env.FIBER_DATA_DIR = join9(homeDir, ".fiber-pay", "profiles", profileName);
   }
 }
 function printFatal(error) {
@@ -4695,10 +5879,15 @@ function printFatal(error) {
   }
 }
 async function main() {
-  applyGlobalOverrides(process.argv);
+  const argv = process.argv;
+  if (isTopLevelVersionRequest(argv)) {
+    console.log(`${CLI_VERSION} (${CLI_COMMIT})`);
+    return;
+  }
+  applyGlobalOverrides(argv);
   const config = getEffectiveConfig(explicitFlags).config;
   const program = new Command13();
-  program.name("fiber-pay").description("AI Agent Payment SDK for CKB Lightning Network").version(`${CLI_VERSION} (${CLI_COMMIT})`, "-v, --version", "Show version and commit id").option("--profile <name>", "Use profile at ~/.fiber-pay/profiles/<name>").option("--data-dir <path>", "Override data directory for all commands").option("--rpc-url <url>", "Override RPC URL for all commands").option("--network <network>", "Override network for all commands (testnet|mainnet)").option("--key-password <password>", "Override key password for all commands").option("--binary-path <path>", "Override fiber binary path for all commands").showHelpAfterError().showSuggestionAfterError();
+  program.name("fiber-pay").description("AI Agent Payment SDK for CKB Lightning Network").option("--profile <name>", "Use profile at ~/.fiber-pay/profiles/<name>").option("--data-dir <path>", "Override data directory for all commands").option("--rpc-url <url>", "Override RPC URL for all commands").option("--rpc-biscuit-token <token>", "Set RPC Authorization Bearer token for all commands").option("--network <network>", "Override network for all commands (testnet|mainnet)").option("--key-password <password>", "Override key password for all commands").option("--binary-path <path>", "Override fiber binary path for all commands").showHelpAfterError().showSuggestionAfterError();
   program.exitOverride();
   program.configureOutput({
     writeOut: (str) => process.stdout.write(str),
@@ -4720,7 +5909,7 @@ async function main() {
   program.addCommand(createConfigCommand(config));
   program.addCommand(createRuntimeCommand(config));
   program.addCommand(createVersionCommand());
-  await program.parseAsync(process.argv);
+  await program.parseAsync(argv);
 }
 main().catch((error) => {
   const commanderCode = error && typeof error === "object" && "code" in error ? String(error.code) : void 0;