From 91bee1bd661a3ce32654481b0bd71bb82728c7af Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 01:46:47 +0000
Subject: [PATCH 1/7] feat(scripts): add live env config writer

---
 README.md                                  |   6 +
 package.json                               |   1 +
 scripts/ickb-live-config-from-env.mjs      | 402 +++++++++++++++++
 scripts/ickb-live-config-from-env.test.mjs | 490 +++++++++++++++++++++
 4 files changed, 899 insertions(+)
 create mode 100644 scripts/ickb-live-config-from-env.mjs
 create mode 100644 scripts/ickb-live-config-from-env.test.mjs

diff --git a/README.md b/README.md
index 1081f402..5aa63cd3 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,12 @@ pnpm --filter @ickb/supervisor build
 pnpm live:supervisor
 ```
 
+To rebuild the standard ignored testnet configs from environment variables without printing private keys, set `ICKB_TESTNET_BOT_PRIVATE_KEY` and `ICKB_TESTNET_TESTER_PRIVATE_KEY`, optionally set `ICKB_TESTNET_RPC_URL`, `ICKB_TESTNET_SLEEP_INTERVAL_SECONDS`, `ICKB_TESTNET_MAX_ITERATIONS`, and `ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS`, then run:
+
+```bash
+pnpm live:config-from-env
+```
+
 By default the supervisor uses ignored `config/bot-testnet.json` and `config/tester-testnet.json`, writes artifacts under ignored `logs/live-supervisor/<run-id>/` paths, and runs deterministic bounded bot/tester commands only. It does not patch, verify, rebuild, relaunch, or invoke an LLM; external loops and operators consume `summary.json` between runs.
 
 For repeated bounded invocations, keep loop-owned options before `--` and supervisor options after it:
diff --git a/package.json b/package.json
index 66983336..a1a93ed1 100644
--- a/package.json
+++ b/package.json
@@ -25,6 +25,7 @@
     "forks:ccc:smoke": "node scripts/forks-ccc-smoke.mjs",
     "forks:ccc:watch": "node scripts/forks-ccc.mjs --watch",
     "live:generate-config": "node scripts/ickb-generate-config.mjs",
+    "live:config-from-env": "node scripts/ickb-live-config-from-env.mjs",
     "live:preflight": "node scripts/ickb-live-preflight.mjs",
     "live:supervisor": "node apps/supervisor/dist/index.js",
     "live:supervisor:loop": "node scripts/ickb-supervisor-loop.mjs",
diff --git a/scripts/ickb-live-config-from-env.mjs b/scripts/ickb-live-config-from-env.mjs
new file mode 100644
index 00000000..333ab26b
--- /dev/null
+++ b/scripts/ickb-live-config-from-env.mjs
@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const rootDir = fileURLToPath(new URL("..", import.meta.url));
+const SECP256K1_ORDER = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
+const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
+const OUTPUTS = [
+  { role: "bot", envName: "ICKB_TESTNET_BOT_PRIVATE_KEY", out: "config/bot-testnet.json" },
+  { role: "tester", envName: "ICKB_TESTNET_TESTER_PRIVATE_KEY", out: "config/tester-testnet.json" },
+];
+
+export function parseArgs(argv) {
+  const args = { force: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") {
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      args.help = true;
+      continue;
+    }
+    if (arg === "--force") {
+      args.force = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return args;
+}
+
+export function usage() {
+  return [
+    "Usage: node scripts/ickb-live-config-from-env.mjs [--force]",
+    "Required env: ICKB_TESTNET_BOT_PRIVATE_KEY, ICKB_TESTNET_TESTER_PRIVATE_KEY",
+    "Optional env: ICKB_TESTNET_RPC_URL, ICKB_TESTNET_SLEEP_INTERVAL_SECONDS, ICKB_TESTNET_MAX_ITERATIONS, ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS",
+    "Writes ignored testnet configs under config/ without printing secrets. Omitted RPC URL lets CCC use its default endpoint.",
+  ].join("\n");
+}
+
+export async function runLiveConfigFromEnv({ argv, env = process.env, root = rootDir, dependencies = {} }) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    return { help: usage() };
+  }
+
+  const sleepIntervalSeconds = parseOptionalPositiveInteger(env.ICKB_TESTNET_SLEEP_INTERVAL_SECONDS, "ICKB_TESTNET_SLEEP_INTERVAL_SECONDS") ?? 1;
+  const maxIterations = parseOptionalPositiveInteger(env.ICKB_TESTNET_MAX_ITERATIONS, "ICKB_TESTNET_MAX_ITERATIONS") ?? 1;
+  const maxRetryableAttempts = parseOptionalPositiveInteger(env.ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS, "ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS") ?? 10;
+  const rpcUrl = parseOptionalRpcUrl(env.ICKB_TESTNET_RPC_URL, "ICKB_TESTNET_RPC_URL");
+  const outputs = OUTPUTS.map((output) => ({
+    ...output,
+    privateKey: parsePrivateKey(env[output.envName], output.envName),
+    target: outputPath(root, output.out),
+  }));
+  for (const output of outputs) {
+    assertIgnoredPath(root, output.target.relativePath, dependencies.checkIgnored);
+  }
+  if (!args.force) {
+    await assertNoExistingTargets(outputs.map((output) => output.target.absolutePath), dependencies);
+  }
+
+  for (const output of outputs) {
+    await makeSafeParentDir(output.target.absolutePath, root, dependencies);
+  }
+
+  const staged = [];
+  let caught;
+  try {
+    for (const [index, output] of outputs.entries()) {
+      const config = buildRuntimeConfig({
+        privateKey: output.privateKey,
+        rpcUrl,
+        sleepIntervalSeconds,
+        maxIterations,
+        maxRetryableAttempts,
+      });
+      const tempPath = tempConfigPath(output.target.absolutePath, "tmp", index);
+      await writeConfigFile(tempPath, `${JSON.stringify(config)}\n`, false, dependencies);
+      staged.push({ ...output, tempPath });
+    }
+    await commitStagedConfigs(staged, args.force, dependencies);
+  } catch (error) {
+    caught = error;
+  }
+  try {
+    await cleanupPaths(staged.map((output) => output.tempPath), dependencies);
+  } catch (error) {
+    if (caught === undefined) {
+      throw error;
+    }
+  }
+  if (caught !== undefined) {
+    throw caught;
+  }
+
+  return {
+    written: outputs.map((output) => ({
+      role: output.role,
+      outputPath: output.target.relativePath,
+      chain: "testnet",
+      rpcConfigured: rpcUrl !== undefined,
+      sleepIntervalSeconds,
+      maxIterations,
+      maxRetryableAttempts,
+      privateKey: "<written-to-config-file>",
+    })),
+  };
+}
+
+export function buildRuntimeConfig({ privateKey, rpcUrl, sleepIntervalSeconds, maxIterations, maxRetryableAttempts }) {
+  return {
+    chain: "testnet",
+    privateKey,
+    ...(rpcUrl === undefined ? {} : { rpcUrl }),
+    sleepIntervalSeconds,
+    maxIterations,
+    maxRetryableAttempts,
+  };
+}
+
+async function commitStagedConfigs(staged, force, dependencies) {
+  for (const output of staged) {
+    await assertNoSymlinkTarget(output.target.absolutePath, dependencies);
+  }
+  if (force) {
+    await replaceStagedConfigs(staged, dependencies);
+    return;
+  }
+  await createStagedConfigs(staged, dependencies);
+}
+
+async function createStagedConfigs(staged, dependencies) {
+  const linked = [];
+  try {
+    for (const output of staged) {
+      await (dependencies.link ?? link)(output.tempPath, output.target.absolutePath);
+      linked.push(output.target.absolutePath);
+    }
+  } catch (error) {
+    await cleanupPaths(linked, dependencies);
+    throw error;
+  }
+}
+
+async function replaceStagedConfigs(staged, dependencies) {
+  const backups = [];
+  const installedWithoutBackup = [];
+  try {
+    for (const [index, output] of staged.entries()) {
+      const backupPath = tempConfigPath(output.target.absolutePath, "backup", index);
+      if (await pathExists(output.target.absolutePath, dependencies)) {
+        await (dependencies.rename ?? rename)(output.target.absolutePath, backupPath);
+        backups.push({ targetPath: output.target.absolutePath, backupPath });
+      }
+    }
+    const backedUpTargets = new Set(backups.map((backup) => backup.targetPath));
+    for (const output of staged) {
+      await (dependencies.rename ?? rename)(output.tempPath, output.target.absolutePath);
+      if (!backedUpTargets.has(output.target.absolutePath)) {
+        installedWithoutBackup.push(output.target.absolutePath);
+      }
+    }
+  } catch (error) {
+    for (const backup of backups.reverse()) {
+      if (await pathExists(backup.backupPath, dependencies)) {
+        await (dependencies.rename ?? rename)(backup.backupPath, backup.targetPath);
+      }
+    }
+    await cleanupPaths(installedWithoutBackup, dependencies);
+    throw error;
+  }
+  await cleanupPaths(backups.map((backup) => backup.backupPath), dependencies);
+}
+
+function tempConfigPath(path, kind, index) {
+  return `${path}.${kind}-${process.pid}-${Date.now()}-${index}`;
+}
+
+async function pathExists(path, dependencies) {
+  try {
+    await (dependencies.lstat ?? lstat)(path);
+    return true;
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function cleanupPaths(paths, dependencies) {
+  for (const path of paths) {
+    try {
+      await (dependencies.unlink ?? unlink)(path);
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+    }
+  }
+}
+
+function parsePrivateKey(value, envName) {
+  if (typeof value !== "string") {
+    throw new Error(`Missing env ${envName}`);
+  }
+  if (!/^0x[0-9a-f]{64}$/u.test(value)) {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  const key = BigInt(value);
+  if (key <= 0n || key >= SECP256K1_ORDER) {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  return value;
+}
+
+function parseOptionalPositiveInteger(value, envName) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  if (!/^[1-9][0-9]*$/u.test(value)) {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  const parsed = BigInt(value);
+  if (parsed > MAX_SAFE_INTEGER) {
+    throw new Error(`Invalid env ${envName}: expected a safe integer`);
+  }
+  return Number(parsed);
+}
+
+function parseOptionalRpcUrl(value, envName) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (/\s/u.test(value[index] ?? "") || code < 0x20 || code === 0x7f) {
+      throw new Error(`Invalid env ${envName}`);
+    }
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Invalid env ${envName}`);
+  }
+  return value;
+}
+
+async function assertNoExistingTargets(paths, dependencies) {
+  for (const path of paths) {
+    try {
+      await (dependencies.lstat ?? lstat)(path);
+      throw new Error("Config already exists; rerun with --force to overwrite");
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+function isNotFoundError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function outputPath(root, out) {
+  const absolutePath = isAbsolute(out) ? out : resolve(root, out);
+  const relativePath = relative(root, absolutePath);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error("Output path must stay inside the repo");
+  }
+  return { absolutePath, relativePath };
+}
+
+async function writeConfigFile(path, text, force, dependencies) {
+  if (dependencies.writeFile !== undefined) {
+    await dependencies.writeFile(path, text, { flag: force ? "w" : "wx", mode: 0o600 });
+    return;
+  }
+  await assertNoSymlinkTarget(path, dependencies);
+  await assertRealParent(path, dependencies);
+  const flags = constants.O_WRONLY |
+    constants.O_CREAT |
+    constants.O_NOFOLLOW |
+    (force ? constants.O_TRUNC : constants.O_EXCL);
+  const handle = await (dependencies.open ?? open)(path, flags, 0o600);
+  try {
+    await handle.writeFile(text, "utf8");
+    await handle.chmod(0o600);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function makeSafeParentDir(path, root, dependencies) {
+  const parent = dirname(path);
+  await assertRealAncestor(root, dependencies);
+  const missing = [];
+  let current = parent;
+  for (;;) {
+    try {
+      await assertRealAncestor(current, dependencies);
+      break;
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        missing.push(current);
+        const next = dirname(current);
+        if (next === current) {
+          throw error;
+        }
+        current = next;
+        continue;
+      }
+      throw error;
+    }
+  }
+  for (const dir of missing.reverse()) {
+    await (dependencies.mkdir ?? mkdir)(dir, { mode: 0o700 });
+    await assertRealAncestor(dir, dependencies);
+  }
+}
+
+async function assertRealAncestor(path, dependencies) {
+  const stat = await (dependencies.lstat ?? lstat)(path);
+  if (stat.isSymbolicLink()) {
+    throw new Error("Refusing to write config through symlinked parent directory");
+  }
+}
+
+async function assertNoSymlinkTarget(path, dependencies) {
+  try {
+    const stat = await (dependencies.lstat ?? lstat)(path);
+    if (stat.isSymbolicLink()) {
+      throw new Error("Refusing to write through symlink config path");
+    }
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return;
+    }
+    throw error;
+  }
+}
+
+async function assertRealParent(path, dependencies) {
+  const parent = dirname(path);
+  await assertRealAncestor(parent, dependencies);
+  const resolvedParent = await (dependencies.realpath ?? realpath)(parent);
+  if (resolvedParent !== parent) {
+    throw new Error("Refusing to write config through symlinked parent directory");
+  }
+}
+
+function assertIgnoredPath(root, relativePath, checkIgnored = defaultCheckIgnored) {
+  if (!checkIgnored(root, relativePath)) {
+    throw new Error(`Refusing to write non-ignored config path: ${relativePath}`);
+  }
+}
+
+function defaultCheckIgnored(root, relativePath) {
+  const result = spawnSync("git", ["-C", root, "check-ignore", "--", relativePath], {
+    encoding: "utf8",
+  });
+  return result.status === 0;
+}
+
+export async function main(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  try {
+    const result = await runLiveConfigFromEnv({ argv });
+    if (result.help !== undefined) {
+      stdout.write(`${result.help}\n`);
+      return 0;
+    }
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    stderr.write(`Live config rebuild failed: ${message}\n${usage()}\n`);
+    return 1;
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  process.exit(await main(process.argv.slice(2)));
+}
diff --git a/scripts/ickb-live-config-from-env.test.mjs b/scripts/ickb-live-config-from-env.test.mjs
new file mode 100644
index 00000000..b8f3e38c
--- /dev/null
+++ b/scripts/ickb-live-config-from-env.test.mjs
@@ -0,0 +1,490 @@
+import assert from "node:assert/strict";
+import { constants } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, stat, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+  buildRuntimeConfig,
+  parseArgs,
+  runLiveConfigFromEnv,
+  usage,
+} from "./ickb-live-config-from-env.mjs";
+
+const botPrivateKey = `0x${"11".repeat(32)}`;
+const testerPrivateKey = `0x${"22".repeat(32)}`;
+
+test("live env config helper parses CLI arguments", () => {
+  assert.deepEqual(parseArgs([]), { force: false });
+  assert.deepEqual(parseArgs(["--force"]), { force: true });
+  assert.deepEqual(parseArgs(["--", "--help"]), { force: false, help: true });
+  assert.throws(() => parseArgs(["--chain", "testnet"]), /Unknown argument/u);
+  assert.match(usage(), /ICKB_TESTNET_BOT_PRIVATE_KEY/u);
+  assert.match(usage(), /ICKB_TESTNET_RPC_URL/u);
+  assert.match(usage(), /ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS/u);
+});
+
+test("live env config helper builds configs with optional RPC URL", () => {
+  assert.deepEqual(buildRuntimeConfig({
+    privateKey: botPrivateKey,
+    rpcUrl: undefined,
+    sleepIntervalSeconds: 1,
+    maxIterations: 1,
+    maxRetryableAttempts: 10,
+  }), {
+    chain: "testnet",
+    privateKey: botPrivateKey,
+    sleepIntervalSeconds: 1,
+    maxIterations: 1,
+    maxRetryableAttempts: 10,
+  });
+  assert.deepEqual(buildRuntimeConfig({
+    privateKey: botPrivateKey,
+    rpcUrl: "https://testnet.example/",
+    sleepIntervalSeconds: 2,
+    maxIterations: 3,
+    maxRetryableAttempts: 4,
+  }), {
+    chain: "testnet",
+    privateKey: botPrivateKey,
+    rpcUrl: "https://testnet.example/",
+    sleepIntervalSeconds: 2,
+    maxIterations: 3,
+    maxRetryableAttempts: 4,
+  });
+});
+
+test("live env config helper writes both ignored testnet configs from env", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  try {
+    const result = await runLiveConfigFromEnv({
+      argv: [],
+      root: dir,
+      env: {
+        ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+        ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+      },
+      dependencies: {
+        checkIgnored: (_root, relativePath) => relativePath.startsWith("config/"),
+      },
+    });
+
+    assert.deepEqual(result, {
+      written: [
+        {
+          role: "bot",
+          outputPath: "config/bot-testnet.json",
+          chain: "testnet",
+          rpcConfigured: false,
+          sleepIntervalSeconds: 1,
+          maxIterations: 1,
+          maxRetryableAttempts: 10,
+          privateKey: "<written-to-config-file>",
+        },
+        {
+          role: "tester",
+          outputPath: "config/tester-testnet.json",
+          chain: "testnet",
+          rpcConfigured: false,
+          sleepIntervalSeconds: 1,
+          maxIterations: 1,
+          maxRetryableAttempts: 10,
+          privateKey: "<written-to-config-file>",
+        },
+      ],
+    });
+    assert.doesNotMatch(JSON.stringify(result), /0x11|0x22/u);
+
+    const botConfigPath = join(dir, "config", "bot-testnet.json");
+    const testerConfigPath = join(dir, "config", "tester-testnet.json");
+    assert.deepEqual(JSON.parse(await readFile(botConfigPath, "utf8")), {
+      chain: "testnet",
+      privateKey: botPrivateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+      maxRetryableAttempts: 10,
+    });
+    assert.deepEqual(JSON.parse(await readFile(testerConfigPath, "utf8")), {
+      chain: "testnet",
+      privateKey: testerPrivateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+      maxRetryableAttempts: 10,
+    });
+    assert.equal((await stat(botConfigPath)).mode & 0o777, 0o600);
+    assert.equal((await stat(testerConfigPath)).mode & 0o777, 0o600);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper reports configured RPC URLs without exposing them", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const written = [];
+  const dirs = new Set([dir]);
+  try {
+    const result = await runLiveConfigFromEnv({
+      argv: [],
+      root: dir,
+      env: {
+        ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+        ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        ICKB_TESTNET_RPC_URL: "https://user:pass@testnet.example/path?token=secret",
+        ICKB_TESTNET_SLEEP_INTERVAL_SECONDS: "10",
+        ICKB_TESTNET_MAX_ITERATIONS: "2",
+        ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS: "3",
+      },
+      dependencies: {
+        checkIgnored: () => true,
+        mkdir: async (path) => {
+          dirs.add(path);
+        },
+        lstat: async (path) => {
+          if (dirs.has(path)) {
+            return { isSymbolicLink: () => false };
+          }
+          const error = new Error("missing");
+          error.code = "ENOENT";
+          throw error;
+        },
+        realpath: async (path) => path,
+        writeFile: async (path, text, options) => {
+          written.push({ path, text, options });
+        },
+        link: async () => undefined,
+        unlink: async () => undefined,
+      },
+    });
+
+    assert.equal(written.length, 2);
+    assert.deepEqual(written.map((entry) => entry.options), [
+      { flag: "wx", mode: 0o600 },
+      { flag: "wx", mode: 0o600 },
+    ]);
+    assert.deepEqual(written.map((entry) => JSON.parse(entry.text)), [
+      {
+        chain: "testnet",
+        privateKey: botPrivateKey,
+        rpcUrl: "https://user:pass@testnet.example/path?token=secret",
+        sleepIntervalSeconds: 10,
+        maxIterations: 2,
+        maxRetryableAttempts: 3,
+      },
+      {
+        chain: "testnet",
+        privateKey: testerPrivateKey,
+        rpcUrl: "https://user:pass@testnet.example/path?token=secret",
+        sleepIntervalSeconds: 10,
+        maxIterations: 2,
+        maxRetryableAttempts: 3,
+      },
+    ]);
+    assert.deepEqual(result.written.map((entry) => entry.rpcConfigured), [true, true]);
+    assert.doesNotMatch(JSON.stringify(result), /0x11|0x22|user:pass|token=secret/u);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper validates env before writing", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const writes = [];
+  try {
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: { ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey },
+        dependencies: {
+          checkIgnored: () => true,
+          writeFile: async () => {
+            writes.push("write");
+          },
+          link: async () => undefined,
+          unlink: async () => undefined,
+        },
+      }),
+      /Missing env ICKB_TESTNET_TESTER_PRIVATE_KEY/u,
+    );
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+          ICKB_TESTNET_RPC_URL: "",
+        },
+        dependencies: {
+          checkIgnored: () => true,
+          writeFile: async () => {
+            writes.push("write");
+          },
+          link: async () => undefined,
+          unlink: async () => undefined,
+        },
+      }),
+      /Invalid env ICKB_TESTNET_RPC_URL/u,
+    );
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+          ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS: "0",
+        },
+        dependencies: {
+          checkIgnored: () => true,
+          writeFile: async () => {
+            writes.push("write");
+          },
+          link: async () => undefined,
+          unlink: async () => undefined,
+        },
+      }),
+      /Invalid env ICKB_TESTNET_MAX_RETRYABLE_ATTEMPTS/u,
+    );
+    assert.deepEqual(writes, []);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper refuses non-ignored outputs and existing configs", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  try {
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: { checkIgnored: () => false },
+      }),
+      /Refusing to write non-ignored config path/u,
+    );
+
+    await runLiveConfigFromEnv({
+      argv: [],
+      root: dir,
+      env: {
+        ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+        ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+      },
+      dependencies: { checkIgnored: () => true },
+    });
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: { checkIgnored: () => true },
+      }),
+      /Config already exists/u,
+    );
+    await runLiveConfigFromEnv({
+      argv: ["--force"],
+      root: dir,
+      env: {
+        ICKB_TESTNET_BOT_PRIVATE_KEY: `0x${"33".repeat(32)}`,
+        ICKB_TESTNET_TESTER_PRIVATE_KEY: `0x${"44".repeat(32)}`,
+      },
+      dependencies: { checkIgnored: () => true },
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper opens output with no-follow and exclusive defaults", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const opened = [];
+  const dirs = new Set([dir]);
+  try {
+    await runLiveConfigFromEnv({
+      argv: [],
+      root: dir,
+      env: {
+        ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+        ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+      },
+      dependencies: {
+        checkIgnored: () => true,
+        mkdir: async (path) => {
+          dirs.add(path);
+        },
+        lstat: async (path) => {
+          if (dirs.has(path)) {
+            return { isSymbolicLink: () => false };
+          }
+          const error = new Error("missing");
+          error.code = "ENOENT";
+          throw error;
+        },
+        realpath: async (path) => path,
+        open: async (path, flags, mode) => {
+          opened.push({ path, flags, mode });
+          return {
+            writeFile: async () => undefined,
+            chmod: async () => undefined,
+            close: async () => undefined,
+          };
+        },
+        link: async () => undefined,
+        unlink: async () => undefined,
+      },
+    });
+
+    assert.equal(opened.length, 2);
+    for (const entry of opened) {
+      assert.equal(entry.flags & constants.O_NOFOLLOW, constants.O_NOFOLLOW);
+      assert.equal(entry.flags & constants.O_EXCL, constants.O_EXCL);
+      assert.equal(entry.mode, 0o600);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper removes partial create outputs when pair commit fails", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const dirs = new Set([dir]);
+  const linked = [];
+  const unlinked = [];
+  try {
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: {
+          checkIgnored: () => true,
+          mkdir: async (path) => {
+            dirs.add(path);
+          },
+          lstat: async (path) => {
+            if (dirs.has(path)) {
+              return { isSymbolicLink: () => false };
+            }
+            const error = new Error("missing");
+            error.code = "ENOENT";
+            throw error;
+          },
+          realpath: async (path) => path,
+          writeFile: async () => undefined,
+          link: async (_from, to) => {
+            if (linked.length === 1) {
+              throw new Error("second link failed");
+            }
+            linked.push(to);
+          },
+          unlink: async (path) => {
+            unlinked.push(path);
+          },
+        },
+      }),
+      /second link failed/u,
+    );
+
+    assert.equal(linked.length, 1);
+    assert.match(linked[0], /config\/bot-testnet\.json$/u);
+    assert(unlinked.includes(linked[0]));
+    assert.equal(new Set(unlinked.filter((path) => /\.tmp-/u.test(path))).size, 2);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper restores previous configs when forced pair replace fails", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const botPath = join(dir, "config", "bot-testnet.json");
+  const testerPath = join(dir, "config", "tester-testnet.json");
+  const dirs = new Set([dir, join(dir, "config")]);
+  const files = new Set([botPath, testerPath]);
+  const renames = [];
+  try {
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: ["--force"],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: {
+          checkIgnored: () => true,
+          mkdir: async (path) => {
+            dirs.add(path);
+          },
+          lstat: async (path) => {
+            if (dirs.has(path) || files.has(path)) {
+              return { isSymbolicLink: () => false };
+            }
+            const error = new Error("missing");
+            error.code = "ENOENT";
+            throw error;
+          },
+          realpath: async (path) => path,
+          writeFile: async (path) => {
+            files.add(path);
+          },
+          rename: async (from, to) => {
+            if (/\.tmp-/u.test(from) && to === testerPath) {
+              throw new Error("second rename failed");
+            }
+            renames.push({ from, to });
+            files.delete(from);
+            files.add(to);
+          },
+          unlink: async (path) => {
+            files.delete(path);
+          },
+        },
+      }),
+      /second rename failed/u,
+    );
+
+    assert(files.has(botPath));
+    assert(files.has(testerPath));
+    assert.equal([...files].filter((path) => /\.tmp-|\.backup-/u.test(path)).length, 0);
+    assert(renames.some((entry) => entry.from === botPath && /bot-testnet\.json\.backup-/u.test(entry.to)));
+    assert(renames.some((entry) => entry.from === testerPath && /tester-testnet\.json\.backup-/u.test(entry.to)));
+    assert(renames.some((entry) => /bot-testnet\.json\.backup-/u.test(entry.from) && entry.to === botPath));
+    assert(renames.some((entry) => /tester-testnet\.json\.backup-/u.test(entry.from) && entry.to === testerPath));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("live env config helper refuses symlinked output paths", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  try {
+    await mkdir(join(dir, "target"));
+    await symlink(join(dir, "target"), join(dir, "config"), "dir");
+
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: { checkIgnored: () => true },
+      }),
+      /symlinked parent directory/u,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

From 30e72091fb23cab0e7c9793e007a1864404324be Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 01:47:26 +0000
Subject: [PATCH 2/7] feat(scripts): extend generated runtime config

---
 apps/bot/README.md                    |   4 +-
 apps/tester/README.md                 |   4 +-
 scripts/ickb-generate-config.mjs      | 112 +++++++++++++++++---------
 scripts/ickb-generate-config.test.mjs |  65 ++++++++++++++-
 4 files changed, 143 insertions(+), 42 deletions(-)

diff --git a/apps/bot/README.md b/apps/bot/README.md
index 7e0bae18..a1481cb4 100644
--- a/apps/bot/README.md
+++ b/apps/bot/README.md
@@ -13,10 +13,10 @@ The bot minimizes excess iCKB holdings so more liquidity stays available in CKB
 The bot reads one strict JSON config file named by `BOT_CONFIG_FILE`:
 
 ```json
-{"chain":"testnet","privateKey":"0x...","rpcUrl":"http://127.0.0.1:8114/","sleepIntervalSeconds":60}
+{"chain":"testnet","privateKey":"0x...","sleepIntervalSeconds":60,"maxRetryableAttempts":10}
 ```
 
-The JSON config accepts exactly `chain`, `privateKey`, `rpcUrl`, `sleepIntervalSeconds`, and optional `maxIterations`. Unknown keys, wrong types, non-HTTP(S) RPC URLs, whitespace/control characters in `rpcUrl`, and non-canonical private keys are rejected. The private key must be exactly lowercase `0x` plus 64 lowercase hex characters, with no newline, spaces, tabs, or comments. Local config files under `config/` are ignored by git.
+The JSON config accepts exactly `chain`, `privateKey`, optional `rpcUrl`, `sleepIntervalSeconds`, optional `maxIterations`, and optional `maxRetryableAttempts`. Unknown keys, wrong types, non-HTTP(S) RPC URLs, whitespace/control characters in `rpcUrl`, and non-canonical private keys are rejected. Omitting `rpcUrl` lets CCC use its default endpoint. The private key must be exactly lowercase `0x` plus 64 lowercase hex characters, with no newline, spaces, tabs, or comments. Local config files under `config/` are ignored by git.
 
 Current network support:
 
diff --git a/apps/tester/README.md b/apps/tester/README.md
index 5aedc322..7f3e5337 100644
--- a/apps/tester/README.md
+++ b/apps/tester/README.md
@@ -7,10 +7,10 @@ The tester is now CCC-native. It waits while its own fresh matchable orders are
 The tester reads one strict JSON config file named by `TESTER_CONFIG_FILE`:
 
 ```json
-{"chain":"testnet","privateKey":"0x...","rpcUrl":"http://127.0.0.1:8114/","sleepIntervalSeconds":10,"maxIterations":1}
+{"chain":"testnet","privateKey":"0x...","sleepIntervalSeconds":10,"maxIterations":1,"maxRetryableAttempts":10}
 ```
 
-The JSON config accepts exactly `chain`, `privateKey`, `rpcUrl`, `sleepIntervalSeconds`, and optional `maxIterations`. Unknown keys, wrong types, non-HTTP(S) RPC URLs, whitespace/control characters in `rpcUrl`, and non-canonical private keys are rejected. The private key must be exactly lowercase `0x` plus 64 lowercase hex characters, with no newline, spaces, tabs, or comments. Local config files under `config/` are ignored by git.
+The JSON config accepts exactly `chain`, `privateKey`, optional `rpcUrl`, `sleepIntervalSeconds`, optional `maxIterations`, and optional `maxRetryableAttempts`. Unknown keys, wrong types, non-HTTP(S) RPC URLs, whitespace/control characters in `rpcUrl`, and non-canonical private keys are rejected. Omitting `rpcUrl` lets CCC use its default endpoint. The private key must be exactly lowercase `0x` plus 64 lowercase hex characters, with no newline, spaces, tabs, or comments. Local config files under `config/` are ignored by git.
 
 Current network support:
 
diff --git a/scripts/ickb-generate-config.mjs b/scripts/ickb-generate-config.mjs
index 33fdcbfd..68c636dc 100644
--- a/scripts/ickb-generate-config.mjs
+++ b/scripts/ickb-generate-config.mjs
@@ -2,7 +2,7 @@
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { link, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -21,6 +21,7 @@ export function parseArgs(argv) {
     role: "bot",
     sleepIntervalSeconds: 1,
     maxIterations: 1,
+    maxRetryableAttempts: 10,
     force: false,
   };
   for (let index = 0; index < argv.length; index += 1) {
@@ -56,6 +57,14 @@ export function parseArgs(argv) {
       args.maxIterations = parsePositiveInteger(valueAfter(argv, ++index, arg), arg);
       continue;
     }
+    if (arg === "--max-retryable-attempts") {
+      args.maxRetryableAttempts = parsePositiveInteger(valueAfter(argv, ++index, arg), arg);
+      continue;
+    }
+    if (arg === "--no-max-retryable-attempts") {
+      args.maxRetryableAttempts = undefined;
+      continue;
+    }
     if (arg === "--no-max-iterations") {
       args.maxIterations = undefined;
       continue;
@@ -74,8 +83,8 @@ export function parseArgs(argv) {
 
 export function usage() {
   return [
-    "Usage: node scripts/ickb-generate-config.mjs [--chain testnet|mainnet] [--role <label>] [--out <ignored-json-config>] [--rpc-url <url>] [--sleep-interval-seconds <n>] [--max-iterations <n>|--no-max-iterations] [--force]",
-    "Defaults: --chain testnet --role bot --out config/<role>-<chain>.json --sleep-interval-seconds 1 --max-iterations 1",
+    "Usage: node scripts/ickb-generate-config.mjs [--chain testnet|mainnet] [--role <label>] [--out <ignored-json-config>] [--rpc-url <url>] [--sleep-interval-seconds <n>] [--max-iterations <n>|--no-max-iterations] [--max-retryable-attempts <n>|--no-max-retryable-attempts] [--force]",
+    "Defaults: --chain testnet --role bot --out config/<role>-<chain>.json --sleep-interval-seconds 1 --max-iterations 1 --max-retryable-attempts 10",
   ].join("\n");
 }
 
@@ -99,6 +108,7 @@ export function buildRuntimeConfig({
   rpcUrl,
   sleepIntervalSeconds,
   maxIterations,
+  maxRetryableAttempts,
 }) {
   return {
     chain,
@@ -106,6 +116,7 @@ export function buildRuntimeConfig({
     rpcUrl,
     sleepIntervalSeconds,
     ...(maxIterations === undefined ? {} : { maxIterations }),
+    ...(maxRetryableAttempts === undefined ? {} : { maxRetryableAttempts }),
   };
 }
 
@@ -120,20 +131,16 @@ export async function runGenerateConfig({ argv, root = rootDir, dependencies = {
   const output = outputPath(root, args.out);
   assertIgnoredPath(root, output.relativePath, dependencies.checkIgnored);
   await makeSafeParentDir(output.absolutePath, root, dependencies);
-  await writeConfigFile(
-    output.absolutePath,
-    `${JSON.stringify(config)}\n`,
-    args.force,
-    dependencies,
-  );
+  await writeStagedConfigFile(output.absolutePath, `${JSON.stringify(config)}\n`, args.force, dependencies);
 
   return {
     outputPath: output.relativePath,
     role: args.role,
     chain: args.chain,
-    redactedRpcUrl: redactRpcUrl(args.rpcUrl),
+    rpcConfigured: args.rpcUrl !== undefined,
     sleepIntervalSeconds: args.sleepIntervalSeconds,
     maxIterations: args.maxIterations,
+    maxRetryableAttempts: args.maxRetryableAttempts,
     privateKey: "<written-to-config-file>",
   };
 }
@@ -205,39 +212,64 @@ function parseRpcUrl(value) {
   return value;
 }
 
-function redactRpcUrl(rpcUrl) {
-  let url;
-  try {
-    url = new URL(rpcUrl);
-  } catch {
-    return "<invalid-url>";
+function outputPath(root, out) {
+  const absolutePath = isAbsolute(out) ? out : resolve(root, out);
+  const relativePath = relative(root, absolutePath);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error("Output path must stay inside the repo");
   }
+  return { absolutePath, relativePath };
+}
 
-  if (url.username !== "" || url.password !== "") {
-    url.username = "redacted";
-    url.password = url.password === "" ? "" : "redacted";
-  }
-  if (url.pathname !== "" && url.pathname !== "/") {
-    url.pathname = "/...";
+async function writeStagedConfigFile(path, text, force, dependencies) {
+  const tempPath = tempConfigPath(path);
+  let caught;
+  try {
+    await writeConfigFile(tempPath, text, false, dependencies);
+    await installStagedConfig(tempPath, path, force, dependencies);
+  } catch (error) {
+    caught = error;
   }
-  if (url.search !== "") {
-    const redactedParams = new URLSearchParams();
-    for (const [key] of url.searchParams) {
-      redactedParams.append(key, "redacted");
+  try {
+    await cleanupPath(tempPath, dependencies);
+  } catch (error) {
+    if (caught === undefined) {
+      throw error;
     }
-    url.search = redactedParams.toString();
   }
+  if (caught !== undefined) {
+    throw caught;
+  }
+}
 
-  return url.toString();
+function tempConfigPath(path) {
+  return `${path}.tmp-${process.pid}-${Date.now()}`;
 }
 
-function outputPath(root, out) {
-  const absolutePath = isAbsolute(out) ? out : resolve(root, out);
-  const relativePath = relative(root, absolutePath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-    throw new Error("Output path must stay inside the repo");
+async function installStagedConfig(tempPath, targetPath, force, dependencies) {
+  await assertNoSymlinkTarget(targetPath, dependencies);
+  if (force) {
+    await (dependencies.rename ?? rename)(tempPath, targetPath);
+    return;
+  }
+  try {
+    await (dependencies.link ?? link)(tempPath, targetPath);
+  } catch (error) {
+    if (isAlreadyExistsError(error)) {
+      throw new Error("Config already exists; rerun with --force to overwrite", { cause: error });
+    }
+    throw error;
+  }
+}
+
+async function cleanupPath(path, dependencies) {
+  try {
+    await (dependencies.unlink ?? unlink)(path);
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw error;
+    }
   }
-  return { absolutePath, relativePath };
 }
 
 async function writeConfigFile(path, text, force, dependencies) {
@@ -270,7 +302,7 @@ async function makeSafeParentDir(path, root, dependencies) {
       await assertRealAncestor(current, dependencies);
       break;
     } catch (error) {
-      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      if (isNotFoundError(error)) {
         missing.push(current);
         const next = dirname(current);
         if (next === current) {
@@ -302,13 +334,21 @@ async function assertNoSymlinkTarget(path, dependencies) {
       throw new Error("Refusing to write through symlink config path");
     }
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    if (isNotFoundError(error)) {
       return;
     }
     throw error;
   }
 }
 
+function isNotFoundError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function isAlreadyExistsError(error) {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+
 async function assertRealParent(path, dependencies) {
   const parent = dirname(path);
   await assertRealAncestor(parent, dependencies);
diff --git a/scripts/ickb-generate-config.test.mjs b/scripts/ickb-generate-config.test.mjs
index bd4e2834..8bb985c0 100644
--- a/scripts/ickb-generate-config.test.mjs
+++ b/scripts/ickb-generate-config.test.mjs
@@ -18,6 +18,7 @@ test("config generator parses defaults and explicit options", () => {
     role: "bot",
     sleepIntervalSeconds: 1,
     maxIterations: 1,
+    maxRetryableAttempts: 10,
     force: false,
     rpcUrl: "https://testnet.ckb.dev/",
     out: "config/bot-testnet.json",
@@ -29,12 +30,14 @@ test("config generator parses defaults and explicit options", () => {
     "--rpc-url", "https://user:pass@mainnet.example/path?token=secret",
     "--sleep-interval-seconds", "10",
     "--no-max-iterations",
+    "--max-retryable-attempts", "3",
     "--force",
   ]), {
     chain: "mainnet",
     role: "tester_role",
     sleepIntervalSeconds: 10,
     maxIterations: undefined,
+    maxRetryableAttempts: 3,
     force: true,
     out: "config/custom.json",
     rpcUrl: "https://user:pass@mainnet.example/path?token=secret",
@@ -52,7 +55,10 @@ test("config generator parses defaults and explicit options", () => {
   assert.match(usage(), /--sleep-interval-seconds/u);
   assert.match(usage(), /--max-iterations/u);
   assert.match(usage(), /--no-max-iterations/u);
+  assert.match(usage(), /--max-retryable-attempts/u);
+  assert.match(usage(), /--no-max-retryable-attempts/u);
   assert.match(usage(), /--force/u);
+  assert.equal(parseArgs(["--no-max-retryable-attempts"]).maxRetryableAttempts, undefined);
 });
 
 test("config generator rejects RPC URLs the runtime parser rejects", () => {
@@ -131,10 +137,13 @@ test("config generator opens output with no-follow and exclusive defaults", asyn
             close: async () => undefined,
           };
         },
+        link: async () => undefined,
+        unlink: async () => undefined,
       },
     });
 
     assert.equal(opened.length, 1);
+    assert.match(opened[0].path, /config\/bot-testnet\.json\.tmp-/u);
     assert.equal(opened[0].flags & constants.O_NOFOLLOW, constants.O_NOFOLLOW);
     assert.equal(opened[0].flags & constants.O_EXCL, constants.O_EXCL);
     assert.equal(opened[0].mode, 0o600);
@@ -172,6 +181,8 @@ test("config generator checks existing ancestors before creating missing parents
           chmod: async () => undefined,
           close: async () => undefined,
         }),
+        link: async () => undefined,
+        unlink: async () => undefined,
       },
     });
 
@@ -184,6 +195,49 @@ test("config generator checks existing ancestors before creating missing parents
   }
 });
 
+test("config generator removes staged config when final install fails", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-generate-config-"));
+  const unlinked = [];
+  const dirs = new Set([dir]);
+  try {
+    await assert.rejects(
+      () => runGenerateConfig({
+        argv: ["--out", "config/bot-testnet.json"],
+        root: dir,
+        dependencies: {
+          randomBytes: () => Buffer.from("66".repeat(32), "hex"),
+          checkIgnored: () => true,
+          mkdir: async (path) => {
+            dirs.add(path);
+          },
+          lstat: async (path) => {
+            if (dirs.has(path)) {
+              return { isSymbolicLink: () => false };
+            }
+            const error = new Error("missing");
+            error.code = "ENOENT";
+            throw error;
+          },
+          realpath: async (path) => path,
+          writeFile: async () => undefined,
+          link: async () => {
+            throw new Error("link failed");
+          },
+          unlink: async (path) => {
+            unlinked.push(path);
+          },
+        },
+      }),
+      /link failed/u,
+    );
+
+    assert.equal(unlinked.length, 1);
+    assert.match(unlinked[0], /config\/bot-testnet\.json\.tmp-/u);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("config generator builds strict runtime config shape", () => {
   assert.deepEqual(buildRuntimeConfig({
     chain: "testnet",
@@ -191,12 +245,14 @@ test("config generator builds strict runtime config shape", () => {
     rpcUrl: "https://testnet.ckb.dev/",
     sleepIntervalSeconds: 1,
     maxIterations: 1,
+    maxRetryableAttempts: 10,
   }), {
     chain: "testnet",
     privateKey: `0x${"11".repeat(32)}`,
     rpcUrl: "https://testnet.ckb.dev/",
     sleepIntervalSeconds: 1,
     maxIterations: 1,
+    maxRetryableAttempts: 10,
   });
   assert.deepEqual(buildRuntimeConfig({
     chain: "mainnet",
@@ -204,6 +260,7 @@ test("config generator builds strict runtime config shape", () => {
     rpcUrl: "https://mainnet.ckb.dev/",
     sleepIntervalSeconds: 60,
     maxIterations: undefined,
+    maxRetryableAttempts: undefined,
   }), {
     chain: "mainnet",
     privateKey: `0x${"22".repeat(32)}`,
@@ -238,11 +295,13 @@ test("config generator writes only ignored configs and reports public metadata",
         writeFile: async (path, text, options) => {
           written.push({ path, text, options });
         },
+        link: async () => undefined,
+        unlink: async () => undefined,
       },
     });
 
     assert.equal(written.length, 1);
-    assert.match(String(written[0].path), /config\/bot-testnet\.json$/u);
+    assert.match(String(written[0].path), /config\/bot-testnet\.json\.tmp-/u);
     assert.deepEqual(written[0].options, { flag: "wx", mode: 0o600 });
     assert.deepEqual(JSON.parse(written[0].text), {
       chain: "testnet",
@@ -250,14 +309,16 @@ test("config generator writes only ignored configs and reports public metadata",
       rpcUrl: "https://user:pass@testnet.example/path?token=secret",
       sleepIntervalSeconds: 1,
       maxIterations: 1,
+      maxRetryableAttempts: 10,
     });
     assert.deepEqual(result, {
       outputPath: "config/bot-testnet.json",
       role: "bot",
       chain: "testnet",
-      redactedRpcUrl: "https://redacted:redacted@testnet.example/...?token=redacted",
+      rpcConfigured: true,
       sleepIntervalSeconds: 1,
       maxIterations: 1,
+      maxRetryableAttempts: 10,
       privateKey: "<written-to-config-file>",
     });
     assert.doesNotMatch(JSON.stringify(result), /0x33/u);

From 9e4c79cced9ce252e72586314f9d11165bbb625e Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 01:47:33 +0000
Subject: [PATCH 3/7] feat(preflight): report live balance reserves

---
 scripts/ickb-live-preflight.mjs      |  30 ++++-
 scripts/ickb-live-preflight.test.mjs | 157 +++++++++++++++++++++++++--
 2 files changed, 173 insertions(+), 14 deletions(-)

diff --git a/scripts/ickb-live-preflight.mjs b/scripts/ickb-live-preflight.mjs
index 27b5dfcc..26486bfc 100644
--- a/scripts/ickb-live-preflight.mjs
+++ b/scripts/ickb-live-preflight.mjs
@@ -6,6 +6,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const rootDir = fileURLToPath(new URL("..", import.meta.url));
 const ROLE_PATTERN = /^[a-z](?:[a-z0-9_-]{0,30}[a-z0-9])?$/u;
+const CKB = 100000000n;
+const BOT_CKB_RESERVE = 1000n * CKB;
+const TESTER_CKB_RESERVE = 2000n * CKB;
 
 export function parseArgs(argv) {
   const args = { role: "preflight" };
@@ -57,6 +60,12 @@ export function redactErrorMessage(error, secrets = {}) {
   return message;
 }
 
+export function ckbReserveForRole(role) {
+  return role === "tester" || role.startsWith("tester-") || role.startsWith("tester_")
+    ? TESTER_CKB_RESERVE
+    : BOT_CKB_RESERVE;
+}
+
 export async function runPreflight({ configPath, role, root = rootDir, dependencies }) {
   const config = resolveConfigPath(root, configPath, dependencies?.checkIgnored);
   await assertReadableConfigPath(root, config.absolutePath, dependencies);
@@ -67,7 +76,7 @@ export async function runPreflight({ configPath, role, root = rootDir, dependenc
     runtimeConfig = nodeUtils.parseRuntimeConfig(configText, "LIVE_PREFLIGHT_CONFIG_FILE");
   } catch (cause) {
     throw new Error(
-      "Invalid live preflight config: expected exact JSON with chain, privateKey, rpcUrl, sleepIntervalSeconds, and optional maxIterations",
+      "Invalid live preflight config: expected exact JSON with chain, privateKey, optional rpcUrl, sleepIntervalSeconds, optional maxIterations, and optional maxRetryableAttempts",
       { cause },
     );
   }
@@ -81,7 +90,7 @@ export async function runPreflight({ configPath, role, root = rootDir, dependenc
   const secrets = {
     privateKey: runtimeConfig.privateKey,
     rpcUrl: runtimeConfig.rpcUrl,
-    redactedRpcUrl: nodeUtils.redactRpcUrl(runtimeConfig.rpcUrl),
+    redactedRpcUrl: runtimeConfig.rpcUrl === undefined ? undefined : nodeUtils.redactRpcUrl(runtimeConfig.rpcUrl),
     redactSecretText: nodeUtils.redactSecretText,
   };
 
@@ -125,6 +134,10 @@ export async function buildPreflightReport({
     collectedOrdersAvailable: true,
   });
   const totalCkb = projection.ckbAvailable + projection.ckbPending;
+  const depositCapacity = core.convert(false, core.ICKB_DEPOSIT_CAP, exchangeRatio);
+  const minimumCkbCapital = (21n * depositCapacity) / 20n;
+  const ckbReserve = ckbReserveForRole(role);
+  const spendableCkb = maxBigInt(0n, projection.ckbAvailable - ckbReserve);
   const totalEquivalentCkb = totalCkb + core.convert(false, projection.ickbAvailable, exchangeRatio);
   const totalEquivalentIckb = core.convert(true, totalCkb, exchangeRatio) + projection.ickbAvailable;
 
@@ -133,7 +146,9 @@ export async function buildPreflightReport({
     chain: runtimeConfig.chain,
     bounded: runtimeConfig.maxIterations !== undefined,
     maxIterations: runtimeConfig.maxIterations,
+    maxRetryableAttempts: runtimeConfig.maxRetryableAttempts,
     sleepIntervalSeconds: runtimeConfig.sleepIntervalMs / 1000,
+    rpcConfigured: runtimeConfig.rpcUrl !== undefined,
     chainIdentity: chain,
     key: {
       recommendedAddress: recommended.toString(),
@@ -143,6 +158,8 @@ export async function buildPreflightReport({
     balances: {
       CKB: {
         available: nodeUtils.formatCkb(projection.ckbAvailable),
+        reserve: nodeUtils.formatCkb(ckbReserve),
+        spendable: nodeUtils.formatCkb(spendableCkb),
         unavailable: nodeUtils.formatCkb(projection.ckbPending),
         total: nodeUtils.formatCkb(totalCkb),
       },
@@ -154,6 +171,11 @@ export async function buildPreflightReport({
         ICKB: nodeUtils.formatCkb(totalEquivalentIckb),
       },
     },
+    capital: {
+      depositCapacity: nodeUtils.formatCkb(depositCapacity),
+      minimumCkbCapital: nodeUtils.formatCkb(minimumCkbCapital),
+      totalEquivalentCkb: nodeUtils.formatCkb(totalEquivalentCkb),
+    },
     inventory: {
       userOrderCount: null,
       userOrderScan: "skipped-global-scan",
@@ -249,6 +271,10 @@ function parseRole(value) {
   return value;
 }
 
+function maxBigInt(left, right) {
+  return left > right ? left : right;
+}
+
 function resolveConfigPath(root, configPath, checkIgnored = defaultCheckIgnored) {
   const absolutePath = isAbsolute(configPath) ? configPath : resolve(root, configPath);
   const relativePath = relative(root, absolutePath);
diff --git a/scripts/ickb-live-preflight.test.mjs b/scripts/ickb-live-preflight.test.mjs
index d96c3bde..3a8d39b7 100644
--- a/scripts/ickb-live-preflight.test.mjs
+++ b/scripts/ickb-live-preflight.test.mjs
@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import {
+  ckbReserveForRole,
   parseArgs,
   publicScript,
   redactErrorMessage,
@@ -63,6 +64,12 @@ test("preflight CLI redacts private key and RPC URL in errors", () => {
   assert.doesNotMatch(message, /\buser\b|\bpass\b/u);
 });
 
+test("preflight CLI exposes role-specific CKB reserves", () => {
+  assert.equal(ckbReserveForRole("bot").toString(), "100000000000");
+  assert.equal(ckbReserveForRole("tester").toString(), "200000000000");
+  assert.equal(ckbReserveForRole("tester-watch").toString(), "200000000000");
+});
+
 test("preflight run reports public evidence for a generated unfunded key", async () => {
   const privateKey = `0x${randomBytes(32).toString("hex")}`;
   const rawRpcUrl = "https://user:pass@testnet.example/path?token=secret";
@@ -75,6 +82,7 @@ test("preflight run reports public evidence for a generated unfunded key", async
       rpcUrl: rawRpcUrl,
       sleepIntervalSeconds: 1,
       maxIterations: 1,
+      maxRetryableAttempts: 3,
     }));
 
     const report = await runPreflight({
@@ -89,6 +97,8 @@ test("preflight run reports public evidence for a generated unfunded key", async
     assert.equal(report.chain, "testnet");
     assert.equal(report.bounded, true);
     assert.equal(report.maxIterations, 1);
+    assert.equal(report.maxRetryableAttempts, 3);
+    assert.equal(report.rpcConfigured, true);
     assert.equal(report.chainIdentity.redactedRpcUrl, "https://redacted:redacted@testnet.example/...?token=redacted");
     assert.equal(report.chainIdentity.matches.genesisHash, true);
     assert.equal(report.key.recommendedAddress, "ckt1generatedoffline");
@@ -98,6 +108,11 @@ test("preflight run reports public evidence for a generated unfunded key", async
       args: "0x" + "22".repeat(20),
     });
     assert.equal(report.balances.CKB.total, "0");
+    assert.equal(report.balances.CKB.reserve, "100000000000");
+    assert.equal(report.balances.CKB.spendable, "0");
+    assert.equal(report.capital.depositCapacity, "10000000000000");
+    assert.equal(report.capital.minimumCkbCapital, "10500000000000");
+    assert.equal(report.capital.totalEquivalentCkb, "0");
     assert.equal(report.inventory.userOrderCount, null);
     assert.equal(report.inventory.userOrderScan, "skipped-global-scan");
     assert.doesNotMatch(json, new RegExp(privateKey, "u"));
@@ -108,6 +123,116 @@ test("preflight run reports public evidence for a generated unfunded key", async
   }
 });
 
+test("preflight reports CKB reserve and spendable balance separately", async () => {
+  const privateKey = `0x${randomBytes(32).toString("hex")}`;
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-preflight-"));
+  try {
+    const configPath = join(dir, "config.json");
+    await writeFile(configPath, JSON.stringify({
+      chain: "testnet",
+      privateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+    }));
+
+    const dependencies = mockDependencies({
+      projection: {
+        ckbAvailable: 150000000000n,
+        ckbPending: 25000000000n,
+        ickbAvailable: 20000000000n,
+        readyWithdrawals: [],
+        pendingWithdrawals: [],
+      },
+    });
+    const report = await runPreflight({
+      configPath,
+      role: "bot",
+      root: dir,
+      dependencies: { ...dependencies, checkIgnored: () => true },
+    });
+
+    assert.deepEqual(report.balances.CKB, {
+      available: "150000000000",
+      reserve: "100000000000",
+      spendable: "50000000000",
+      unavailable: "25000000000",
+      total: "175000000000",
+    });
+    assert.equal(report.capital.totalEquivalentCkb, "195000000000");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("preflight reports tester reserve and spendable balance separately", async () => {
+  const privateKey = `0x${randomBytes(32).toString("hex")}`;
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-preflight-"));
+  try {
+    const configPath = join(dir, "config.json");
+    await writeFile(configPath, JSON.stringify({
+      chain: "testnet",
+      privateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+    }));
+
+    const dependencies = mockDependencies({
+      projection: {
+        ckbAvailable: 250000000000n,
+        ckbPending: 25000000000n,
+        ickbAvailable: 20000000000n,
+        readyWithdrawals: [],
+        pendingWithdrawals: [],
+      },
+    });
+    const report = await runPreflight({
+      configPath,
+      role: "tester",
+      root: dir,
+      dependencies: { ...dependencies, checkIgnored: () => true },
+    });
+
+    assert.deepEqual(report.balances.CKB, {
+      available: "250000000000",
+      reserve: "200000000000",
+      spendable: "50000000000",
+      unavailable: "25000000000",
+      total: "275000000000",
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("preflight run accepts configs that omit custom RPC URLs", async () => {
+  const privateKey = `0x${randomBytes(32).toString("hex")}`;
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-preflight-"));
+  try {
+    const configPath = join(dir, "config.json");
+    await writeFile(configPath, JSON.stringify({
+      chain: "testnet",
+      privateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+    }));
+
+    const calls = [];
+    const dependencies = mockDependencies({ createPublicClientCalls: calls });
+    const report = await runPreflight({
+      configPath,
+      role: "tester",
+      root: dir,
+      dependencies: { ...dependencies, checkIgnored: () => true },
+    });
+
+    assert.equal(report.role, "tester");
+    assert.equal(report.rpcConfigured, false);
+    assert.deepEqual(calls, [{ chain: "testnet", rpcUrl: undefined }]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("preflight preserves parse failure cause without leaking config contents", async () => {
   const privateKey = `0x${"11".repeat(32)}`;
   const dir = await mkdtemp(join(tmpdir(), "ickb-live-preflight-"));
@@ -220,24 +345,29 @@ test("preflight refuses symlinked config parent paths", async () => {
   }
 });
 
-function mockDependencies() {
+function mockDependencies(options = {}) {
   const expectedGenesis = "0x10639e0895502b5688a6be8cf69460d76541bfa4821629d86d62ba0aae3f9606";
   const nodeUtils = {
     parseRuntimeConfig: (text) => {
       const parsed = JSON.parse(text);
       return {
         ...parsed,
+        rpcUrl: parsed.rpcUrl,
         sleepIntervalMs: parsed.sleepIntervalSeconds * 1000,
+        maxRetryableAttempts: parsed.maxRetryableAttempts,
       };
     },
     redactRpcUrl: () => "https://redacted:redacted@testnet.example/...?token=redacted",
     redactSecretText,
-    createPublicClient: () => ({
-      url: "mock",
-      addressPrefix: "ckt",
-      getTipHeader: async () => ({ hash: "0x" + "44".repeat(32), number: 3n, timestamp: 4n }),
-      getFeeRate: async () => 1000n,
-    }),
+    createPublicClient: (chain, rpcUrl) => {
+      options.createPublicClientCalls?.push({ chain, rpcUrl });
+      return {
+        url: "mock",
+        addressPrefix: "ckt",
+        getTipHeader: async () => ({ hash: "0x" + "44".repeat(32), number: 3n, timestamp: 4n }),
+        getFeeRate: async () => 1000n,
+      };
+    },
     verifyChainPreflight: async () => ({
       chain: "testnet",
       redactedRpcUrl: "https://redacted:redacted@testnet.example/...?token=redacted",
@@ -277,15 +407,18 @@ function mockDependencies() {
         }),
       },
       projectAccountAvailability: () => ({
-        ckbAvailable: 0n,
-        ckbPending: 0n,
-        ickbAvailable: 0n,
-        readyWithdrawals: [],
-        pendingWithdrawals: [],
+        ...(options.projection ?? {
+          ckbAvailable: 0n,
+          ckbPending: 0n,
+          ickbAvailable: 0n,
+          readyWithdrawals: [],
+          pendingWithdrawals: [],
+        }),
       }),
     },
     core: {
       ickbExchangeRatio: () => ({ ckbScale: 1n, udtScale: 1n }),
+      ICKB_DEPOSIT_CAP: 10000000000000n,
       convert: (_toIckb, value) => value,
     },
   };

From b0a81df27723274a4f299f5aa8e120356d8c91b1 Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 01:57:23 +0000
Subject: [PATCH 4/7] fix(scripts): accept symlinked repo roots

---
 scripts/ickb-generate-config.mjs           | 33 +++++++++++-----
 scripts/ickb-generate-config.test.mjs      | 45 +++++++++++++++++++++-
 scripts/ickb-live-config-from-env.mjs      | 33 +++++++++++-----
 scripts/ickb-live-config-from-env.test.mjs | 36 +++++++++++++++++
 scripts/ickb-live-preflight.mjs            | 38 +++++++++++++-----
 scripts/ickb-live-preflight.test.mjs       | 39 ++++++++++++++++++-
 6 files changed, 194 insertions(+), 30 deletions(-)

diff --git a/scripts/ickb-generate-config.mjs b/scripts/ickb-generate-config.mjs
index 68c636dc..b3c87e60 100644
--- a/scripts/ickb-generate-config.mjs
+++ b/scripts/ickb-generate-config.mjs
@@ -125,12 +125,14 @@ export async function runGenerateConfig({ argv, root = rootDir, dependencies = {
   if (args.help) {
     return { help: usage() };
   }
+  const originalRoot = resolve(root);
+  const resolvedRoot = await (dependencies.realpath ?? realpath)(originalRoot);
 
   const privateKey = generateSecp256k1PrivateKey(dependencies.randomBytes ?? randomBytes);
   const config = buildRuntimeConfig({ ...args, privateKey });
-  const output = outputPath(root, args.out);
-  assertIgnoredPath(root, output.relativePath, dependencies.checkIgnored);
-  await makeSafeParentDir(output.absolutePath, root, dependencies);
+  const output = outputPath(originalRoot, resolvedRoot, args.out);
+  assertIgnoredPath(resolvedRoot, output.relativePath, dependencies.checkIgnored);
+  await makeSafeParentDir(output.absolutePath, resolvedRoot, dependencies);
   await writeStagedConfigFile(output.absolutePath, `${JSON.stringify(config)}\n`, args.force, dependencies);
 
   return {
@@ -212,13 +214,26 @@ function parseRpcUrl(value) {
   return value;
 }
 
-function outputPath(root, out) {
-  const absolutePath = isAbsolute(out) ? out : resolve(root, out);
-  const relativePath = relative(root, absolutePath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-    throw new Error("Output path must stay inside the repo");
+function outputPath(originalRoot, resolvedRoot, out) {
+  const absolutePath = isAbsolute(out) ? out : resolve(resolvedRoot, out);
+  const relativePath = relative(resolvedRoot, absolutePath);
+  if (isInsideRelativePath(relativePath)) {
+    return { absolutePath, relativePath };
   }
-  return { absolutePath, relativePath };
+  if (isAbsolute(out)) {
+    const originalRelativePath = relative(originalRoot, out);
+    if (isInsideRelativePath(originalRelativePath)) {
+      return {
+        absolutePath: resolve(resolvedRoot, originalRelativePath),
+        relativePath: originalRelativePath,
+      };
+    }
+  }
+  throw new Error("Output path must stay inside the repo");
+}
+
+function isInsideRelativePath(relativePath) {
+  return !relativePath.startsWith("..") && !isAbsolute(relativePath);
 }
 
 async function writeStagedConfigFile(path, text, force, dependencies) {
diff --git a/scripts/ickb-generate-config.test.mjs b/scripts/ickb-generate-config.test.mjs
index 8bb985c0..e85e7682 100644
--- a/scripts/ickb-generate-config.test.mjs
+++ b/scripts/ickb-generate-config.test.mjs
@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { constants } from "node:fs";
-import { mkdir, mkdtemp, rm, symlink } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -238,6 +238,49 @@ test("config generator removes staged config when final install fails", async ()
   }
 });
 
+test("config generator accepts absolute outputs through a symlinked repo root", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-generate-config-root-"));
+  const realRoot = join(dir, "real");
+  const symlinkRoot = join(dir, "link");
+  try {
+    await mkdir(realRoot);
+    await symlink(realRoot, symlinkRoot, "dir");
+
+    const result = await runGenerateConfig({
+      argv: ["--out", join(symlinkRoot, "config", "bot-testnet.json")],
+      root: symlinkRoot,
+      dependencies: {
+        randomBytes: () => Buffer.from("77".repeat(32), "hex"),
+        checkIgnored: (_root, relativePath) => relativePath.startsWith("config/"),
+      },
+    });
+
+    assert.equal(result.outputPath, "config/bot-testnet.json");
+    assert.deepEqual(JSON.parse(await readFile(join(realRoot, "config", "bot-testnet.json"), "utf8")), {
+      chain: "testnet",
+      privateKey: `0x${"77".repeat(32)}`,
+      rpcUrl: "https://testnet.ckb.dev/",
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+      maxRetryableAttempts: 10,
+    });
+
+    await assert.rejects(
+      () => runGenerateConfig({
+        argv: ["--out", join(dir, "outside.json")],
+        root: symlinkRoot,
+        dependencies: {
+          randomBytes: () => Buffer.from("88".repeat(32), "hex"),
+          checkIgnored: () => true,
+        },
+      }),
+      /Output path must stay inside the repo/u,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("config generator builds strict runtime config shape", () => {
   assert.deepEqual(buildRuntimeConfig({
     chain: "testnet",
diff --git a/scripts/ickb-live-config-from-env.mjs b/scripts/ickb-live-config-from-env.mjs
index 333ab26b..bbd023f9 100644
--- a/scripts/ickb-live-config-from-env.mjs
+++ b/scripts/ickb-live-config-from-env.mjs
@@ -47,6 +47,8 @@ export async function runLiveConfigFromEnv({ argv, env = process.env, root = roo
   if (args.help) {
     return { help: usage() };
   }
+  const originalRoot = resolve(root);
+  const resolvedRoot = await (dependencies.realpath ?? realpath)(originalRoot);
 
   const sleepIntervalSeconds = parseOptionalPositiveInteger(env.ICKB_TESTNET_SLEEP_INTERVAL_SECONDS, "ICKB_TESTNET_SLEEP_INTERVAL_SECONDS") ?? 1;
   const maxIterations = parseOptionalPositiveInteger(env.ICKB_TESTNET_MAX_ITERATIONS, "ICKB_TESTNET_MAX_ITERATIONS") ?? 1;
@@ -55,17 +57,17 @@ export async function runLiveConfigFromEnv({ argv, env = process.env, root = roo
   const outputs = OUTPUTS.map((output) => ({
     ...output,
     privateKey: parsePrivateKey(env[output.envName], output.envName),
-    target: outputPath(root, output.out),
+    target: outputPath(originalRoot, resolvedRoot, output.out),
   }));
   for (const output of outputs) {
-    assertIgnoredPath(root, output.target.relativePath, dependencies.checkIgnored);
+    assertIgnoredPath(resolvedRoot, output.target.relativePath, dependencies.checkIgnored);
   }
   if (!args.force) {
     await assertNoExistingTargets(outputs.map((output) => output.target.absolutePath), dependencies);
   }
 
   for (const output of outputs) {
-    await makeSafeParentDir(output.target.absolutePath, root, dependencies);
+    await makeSafeParentDir(output.target.absolutePath, resolvedRoot, dependencies);
   }
 
   const staged = [];
@@ -279,13 +281,26 @@ function isNotFoundError(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
-function outputPath(root, out) {
-  const absolutePath = isAbsolute(out) ? out : resolve(root, out);
-  const relativePath = relative(root, absolutePath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-    throw new Error("Output path must stay inside the repo");
+function outputPath(originalRoot, resolvedRoot, out) {
+  const absolutePath = isAbsolute(out) ? out : resolve(resolvedRoot, out);
+  const relativePath = relative(resolvedRoot, absolutePath);
+  if (isInsideRelativePath(relativePath)) {
+    return { absolutePath, relativePath };
+  }
+  if (isAbsolute(out)) {
+    const originalRelativePath = relative(originalRoot, out);
+    if (isInsideRelativePath(originalRelativePath)) {
+      return {
+        absolutePath: resolve(resolvedRoot, originalRelativePath),
+        relativePath: originalRelativePath,
+      };
+    }
   }
-  return { absolutePath, relativePath };
+  throw new Error("Output path must stay inside the repo");
+}
+
+function isInsideRelativePath(relativePath) {
+  return !relativePath.startsWith("..") && !isAbsolute(relativePath);
 }
 
 async function writeConfigFile(path, text, force, dependencies) {
diff --git a/scripts/ickb-live-config-from-env.test.mjs b/scripts/ickb-live-config-from-env.test.mjs
index b8f3e38c..bf4be3aa 100644
--- a/scripts/ickb-live-config-from-env.test.mjs
+++ b/scripts/ickb-live-config-from-env.test.mjs
@@ -488,3 +488,39 @@ test("live env config helper refuses symlinked output paths", async () => {
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("live env config helper accepts absolute outputs through a symlinked repo root", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-root-"));
+  const realRoot = join(dir, "real");
+  const symlinkRoot = join(dir, "link");
+  try {
+    await mkdir(realRoot);
+    await symlink(realRoot, symlinkRoot, "dir");
+
+    const result = await runLiveConfigFromEnv({
+      argv: [],
+      root: symlinkRoot,
+      env: {
+        ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+        ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+      },
+      dependencies: {
+        checkIgnored: (_root, relativePath) => relativePath.startsWith("config/"),
+      },
+    });
+
+    assert.deepEqual(result.written.map((entry) => entry.outputPath), [
+      "config/bot-testnet.json",
+      "config/tester-testnet.json",
+    ]);
+    assert.deepEqual(JSON.parse(await readFile(join(realRoot, "config", "bot-testnet.json"), "utf8")), {
+      chain: "testnet",
+      privateKey: botPrivateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+      maxRetryableAttempts: 10,
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/ickb-live-preflight.mjs b/scripts/ickb-live-preflight.mjs
index 26486bfc..325e1141 100644
--- a/scripts/ickb-live-preflight.mjs
+++ b/scripts/ickb-live-preflight.mjs
@@ -67,8 +67,10 @@ export function ckbReserveForRole(role) {
 }
 
 export async function runPreflight({ configPath, role, root = rootDir, dependencies }) {
-  const config = resolveConfigPath(root, configPath, dependencies?.checkIgnored);
-  await assertReadableConfigPath(root, config.absolutePath, dependencies);
+  const originalRoot = resolve(root);
+  const resolvedRoot = await (dependencies?.realpath ?? realpath)(originalRoot);
+  const config = resolveConfigPath(originalRoot, resolvedRoot, configPath, dependencies?.checkIgnored);
+  await assertReadableConfigPath(resolvedRoot, config.absolutePath, dependencies);
   const configText = await readFile(config.absolutePath, "utf8");
   const { nodeUtils } = dependencies ?? await loadBuiltNodeUtils(root);
   let runtimeConfig;
@@ -275,16 +277,32 @@ function maxBigInt(left, right) {
   return left > right ? left : right;
 }
 
-function resolveConfigPath(root, configPath, checkIgnored = defaultCheckIgnored) {
-  const absolutePath = isAbsolute(configPath) ? configPath : resolve(root, configPath);
-  const relativePath = relative(root, absolutePath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-    throw new Error("Config path must stay inside the repo");
+function resolveConfigPath(originalRoot, resolvedRoot, configPath, checkIgnored = defaultCheckIgnored) {
+  const absolutePath = isAbsolute(configPath) ? configPath : resolve(resolvedRoot, configPath);
+  const relativePath = relative(resolvedRoot, absolutePath);
+  if (isInsideRelativePath(relativePath)) {
+    if (!checkIgnored(resolvedRoot, relativePath)) {
+      throw new Error(`Refusing to read non-ignored config path: ${relativePath}`);
+    }
+    return { absolutePath, relativePath };
   }
-  if (!checkIgnored(root, relativePath)) {
-    throw new Error(`Refusing to read non-ignored config path: ${relativePath}`);
+  if (isAbsolute(configPath)) {
+    const originalRelativePath = relative(originalRoot, configPath);
+    if (isInsideRelativePath(originalRelativePath)) {
+      if (!checkIgnored(resolvedRoot, originalRelativePath)) {
+        throw new Error(`Refusing to read non-ignored config path: ${originalRelativePath}`);
+      }
+      return {
+        absolutePath: resolve(resolvedRoot, originalRelativePath),
+        relativePath: originalRelativePath,
+      };
+    }
   }
-  return { absolutePath, relativePath };
+  throw new Error("Config path must stay inside the repo");
+}
+
+function isInsideRelativePath(relativePath) {
+  return !relativePath.startsWith("..") && !isAbsolute(relativePath);
 }
 
 async function assertReadableConfigPath(root, configPath, dependencies = {}) {
diff --git a/scripts/ickb-live-preflight.test.mjs b/scripts/ickb-live-preflight.test.mjs
index 3a8d39b7..7f84e5e8 100644
--- a/scripts/ickb-live-preflight.test.mjs
+++ b/scripts/ickb-live-preflight.test.mjs
@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { randomBytes } from "node:crypto";
-import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -233,6 +233,43 @@ test("preflight run accepts configs that omit custom RPC URLs", async () => {
   }
 });
 
+test("preflight accepts absolute config paths through a symlinked repo root", async () => {
+  const privateKey = `0x${randomBytes(32).toString("hex")}`;
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-preflight-root-"));
+  const realRoot = join(dir, "real");
+  const symlinkRoot = join(dir, "link");
+  try {
+    await mkdir(realRoot);
+    await symlink(realRoot, symlinkRoot, "dir");
+    await writeFile(join(realRoot, "config.json"), JSON.stringify({
+      chain: "testnet",
+      privateKey,
+      sleepIntervalSeconds: 1,
+      maxIterations: 1,
+    }));
+
+    const report = await runPreflight({
+      configPath: join(symlinkRoot, "config.json"),
+      role: "bot",
+      root: symlinkRoot,
+      dependencies: { ...mockDependencies(), checkIgnored: () => true },
+    });
+
+    assert.equal(report.role, "bot");
+    await assert.rejects(
+      () => runPreflight({
+        configPath: join(dir, "outside.json"),
+        role: "bot",
+        root: symlinkRoot,
+        dependencies: { ...mockDependencies(), checkIgnored: () => true },
+      }),
+      /Config path must stay inside the repo/u,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("preflight preserves parse failure cause without leaking config contents", async () => {
   const privateKey = `0x${"11".repeat(32)}`;
   const dir = await mkdtemp(join(tmpdir(), "ickb-live-preflight-"));

From 1e5e04bd4d824c099d1bdc79bd62b9bd71ed067e Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 02:04:36 +0000
Subject: [PATCH 5/7] fix(scripts): clean up failed config rewrites

---
 scripts/ickb-live-config-from-env.mjs      |  16 ++-
 scripts/ickb-live-config-from-env.test.mjs | 110 +++++++++++++++++++++
 2 files changed, 122 insertions(+), 4 deletions(-)

diff --git a/scripts/ickb-live-config-from-env.mjs b/scripts/ickb-live-config-from-env.mjs
index bbd023f9..7fd73c5d 100644
--- a/scripts/ickb-live-config-from-env.mjs
+++ b/scripts/ickb-live-config-from-env.mjs
@@ -82,8 +82,8 @@ export async function runLiveConfigFromEnv({ argv, env = process.env, root = roo
         maxRetryableAttempts,
       });
       const tempPath = tempConfigPath(output.target.absolutePath, "tmp", index);
-      await writeConfigFile(tempPath, `${JSON.stringify(config)}\n`, false, dependencies);
       staged.push({ ...output, tempPath });
+      await writeConfigFile(tempPath, `${JSON.stringify(config)}\n`, false, dependencies);
     }
     await commitStagedConfigs(staged, args.force, dependencies);
   } catch (error) {
@@ -169,11 +169,19 @@ async function replaceStagedConfigs(staged, dependencies) {
     }
   } catch (error) {
     for (const backup of backups.reverse()) {
-      if (await pathExists(backup.backupPath, dependencies)) {
-        await (dependencies.rename ?? rename)(backup.backupPath, backup.targetPath);
+      try {
+        if (await pathExists(backup.backupPath, dependencies)) {
+          await (dependencies.rename ?? rename)(backup.backupPath, backup.targetPath);
+        }
+      } catch {
+        // Try every rollback path; the original install error is the actionable failure.
       }
     }
-    await cleanupPaths(installedWithoutBackup, dependencies);
+    try {
+      await cleanupPaths(installedWithoutBackup, dependencies);
+    } catch {
+      // Preserve the original install failure.
+    }
     throw error;
   }
   await cleanupPaths(backups.map((backup) => backup.backupPath), dependencies);
diff --git a/scripts/ickb-live-config-from-env.test.mjs b/scripts/ickb-live-config-from-env.test.mjs
index bf4be3aa..bef200f7 100644
--- a/scripts/ickb-live-config-from-env.test.mjs
+++ b/scripts/ickb-live-config-from-env.test.mjs
@@ -405,6 +405,55 @@ test("live env config helper removes partial create outputs when pair commit fai
   }
 });
 
+test("live env config helper removes partial temp files when writes fail", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const dirs = new Set([dir]);
+  const unlinked = [];
+  try {
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: [],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: {
+          checkIgnored: () => true,
+          mkdir: async (path) => {
+            dirs.add(path);
+          },
+          lstat: async (path) => {
+            if (dirs.has(path)) {
+              return { isSymbolicLink: () => false };
+            }
+            const error = new Error("missing");
+            error.code = "ENOENT";
+            throw error;
+          },
+          realpath: async (path) => path,
+          open: async () => ({
+            writeFile: async () => {
+              throw new Error("write failed");
+            },
+            chmod: async () => undefined,
+            close: async () => undefined,
+          }),
+          unlink: async (path) => {
+            unlinked.push(path);
+          },
+        },
+      }),
+      /write failed/u,
+    );
+
+    assert.equal(unlinked.length, 1);
+    assert.match(unlinked[0], /config\/bot-testnet\.json\.tmp-/u);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("live env config helper restores previous configs when forced pair replace fails", async () => {
   const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
   const botPath = join(dir, "config", "bot-testnet.json");
@@ -466,6 +515,67 @@ test("live env config helper restores previous configs when forced pair replace
   }
 });
 
+test("live env config helper continues restoring backups after one restore fails", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
+  const botPath = join(dir, "config", "bot-testnet.json");
+  const testerPath = join(dir, "config", "tester-testnet.json");
+  const dirs = new Set([dir, join(dir, "config")]);
+  const files = new Set([botPath, testerPath]);
+  const restoreAttempts = [];
+  try {
+    await assert.rejects(
+      () => runLiveConfigFromEnv({
+        argv: ["--force"],
+        root: dir,
+        env: {
+          ICKB_TESTNET_BOT_PRIVATE_KEY: botPrivateKey,
+          ICKB_TESTNET_TESTER_PRIVATE_KEY: testerPrivateKey,
+        },
+        dependencies: {
+          checkIgnored: () => true,
+          mkdir: async (path) => {
+            dirs.add(path);
+          },
+          lstat: async (path) => {
+            if (dirs.has(path) || files.has(path)) {
+              return { isSymbolicLink: () => false };
+            }
+            const error = new Error("missing");
+            error.code = "ENOENT";
+            throw error;
+          },
+          realpath: async (path) => path,
+          writeFile: async (path) => {
+            files.add(path);
+          },
+          rename: async (from, to) => {
+            if (/\.tmp-/u.test(from) && to === botPath) {
+              throw new Error("install failed");
+            }
+            if (/\.backup-/u.test(from)) {
+              restoreAttempts.push(to);
+              if (to === testerPath) {
+                throw new Error("restore failed");
+              }
+            }
+            files.delete(from);
+            files.add(to);
+          },
+          unlink: async (path) => {
+            files.delete(path);
+          },
+        },
+      }),
+      /install failed/u,
+    );
+
+    assert.deepEqual(restoreAttempts, [testerPath, botPath]);
+    assert(files.has(botPath));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("live env config helper refuses symlinked output paths", async () => {
   const dir = await mkdtemp(join(tmpdir(), "ickb-live-config-env-"));
   try {

From bff085a463eeeae0dd9da8a399c227680e0c8be2 Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 07:08:24 +0000
Subject: [PATCH 6/7] fix(scripts): tighten live config helpers

---
 scripts/ickb-live-config-from-env.mjs      |  4 ++--
 scripts/ickb-live-config-from-env.test.mjs | 11 +++++++++++
 scripts/ickb-live-preflight.mjs            |  5 +++++
 scripts/ickb-live-preflight.test.mjs       |  2 ++
 4 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/scripts/ickb-live-config-from-env.mjs b/scripts/ickb-live-config-from-env.mjs
index 7fd73c5d..cd02df3d 100644
--- a/scripts/ickb-live-config-from-env.mjs
+++ b/scripts/ickb-live-config-from-env.mjs
@@ -120,8 +120,8 @@ export function buildRuntimeConfig({ privateKey, rpcUrl, sleepIntervalSeconds, m
     privateKey,
     ...(rpcUrl === undefined ? {} : { rpcUrl }),
     sleepIntervalSeconds,
-    maxIterations,
-    maxRetryableAttempts,
+    ...(maxIterations === undefined ? {} : { maxIterations }),
+    ...(maxRetryableAttempts === undefined ? {} : { maxRetryableAttempts }),
   };
 }
 
diff --git a/scripts/ickb-live-config-from-env.test.mjs b/scripts/ickb-live-config-from-env.test.mjs
index bef200f7..48b36b3b 100644
--- a/scripts/ickb-live-config-from-env.test.mjs
+++ b/scripts/ickb-live-config-from-env.test.mjs
@@ -25,6 +25,17 @@ test("live env config helper parses CLI arguments", () => {
 });
 
 test("live env config helper builds configs with optional RPC URL", () => {
+  assert.deepEqual(buildRuntimeConfig({
+    privateKey: botPrivateKey,
+    rpcUrl: undefined,
+    sleepIntervalSeconds: 1,
+    maxIterations: undefined,
+    maxRetryableAttempts: undefined,
+  }), {
+    chain: "testnet",
+    privateKey: botPrivateKey,
+    sleepIntervalSeconds: 1,
+  });
   assert.deepEqual(buildRuntimeConfig({
     privateKey: botPrivateKey,
     rpcUrl: undefined,
diff --git a/scripts/ickb-live-preflight.mjs b/scripts/ickb-live-preflight.mjs
index 325e1141..47fe4363 100644
--- a/scripts/ickb-live-preflight.mjs
+++ b/scripts/ickb-live-preflight.mjs
@@ -61,6 +61,11 @@ export function redactErrorMessage(error, secrets = {}) {
 }
 
 export function ckbReserveForRole(role) {
+  if (!ROLE_PATTERN.test(role)) {
+    throw new Error(
+      "Invalid role: expected 1-32 lowercase letters, numbers, hyphens, or underscores without trailing separators",
+    );
+  }
   return role === "tester" || role.startsWith("tester-") || role.startsWith("tester_")
     ? TESTER_CKB_RESERVE
     : BOT_CKB_RESERVE;
diff --git a/scripts/ickb-live-preflight.test.mjs b/scripts/ickb-live-preflight.test.mjs
index 7f84e5e8..b0af85b7 100644
--- a/scripts/ickb-live-preflight.test.mjs
+++ b/scripts/ickb-live-preflight.test.mjs
@@ -68,6 +68,8 @@ test("preflight CLI exposes role-specific CKB reserves", () => {
   assert.equal(ckbReserveForRole("bot").toString(), "100000000000");
   assert.equal(ckbReserveForRole("tester").toString(), "200000000000");
   assert.equal(ckbReserveForRole("tester-watch").toString(), "200000000000");
+  assert.equal(ckbReserveForRole("tester_watch").toString(), "200000000000");
+  assert.throws(() => ckbReserveForRole("tester-"), /Invalid role/u);
 });
 
 test("preflight run reports public evidence for a generated unfunded key", async () => {

From 068c736a7e3372d3c4c549df43b6965f7ad54cc3 Mon Sep 17 00:00:00 2001
From: phroi <90913182+phroi@users.noreply.github.com>
Date: Wed, 27 May 2026 07:17:46 +0000
Subject: [PATCH 7/7] fix(scripts): report git ignore check failures

---
 scripts/ickb-generate-config.mjs      |  9 +----
 scripts/ickb-live-config-from-env.mjs |  9 +----
 scripts/ickb-live-config-git.mjs      | 18 ++++++++++
 scripts/ickb-live-config-git.test.mjs | 48 +++++++++++++++++++++++++++
 scripts/ickb-live-preflight.mjs       |  9 +----
 5 files changed, 69 insertions(+), 24 deletions(-)
 create mode 100644 scripts/ickb-live-config-git.mjs
 create mode 100644 scripts/ickb-live-config-git.test.mjs

diff --git a/scripts/ickb-generate-config.mjs b/scripts/ickb-generate-config.mjs
index b3c87e60..630615f3 100644
--- a/scripts/ickb-generate-config.mjs
+++ b/scripts/ickb-generate-config.mjs
@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
 import { link, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { defaultCheckIgnored } from "./ickb-live-config-git.mjs";
 
 const rootDir = fileURLToPath(new URL("..", import.meta.url));
 const SECP256K1_ORDER = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
@@ -379,13 +379,6 @@ function assertIgnoredPath(root, relativePath, checkIgnored = defaultCheckIgnore
   }
 }
 
-function defaultCheckIgnored(root, relativePath) {
-  const result = spawnSync("git", ["-C", root, "check-ignore", "--", relativePath], {
-    encoding: "utf8",
-  });
-  return result.status === 0;
-}
-
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
   process.exit(await main(process.argv.slice(2)));
 }
diff --git a/scripts/ickb-live-config-from-env.mjs b/scripts/ickb-live-config-from-env.mjs
index cd02df3d..11c3baee 100644
--- a/scripts/ickb-live-config-from-env.mjs
+++ b/scripts/ickb-live-config-from-env.mjs
@@ -3,7 +3,7 @@ import { constants } from "node:fs";
 import { link, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { spawnSync } from "node:child_process";
+import { defaultCheckIgnored } from "./ickb-live-config-git.mjs";
 
 const rootDir = fileURLToPath(new URL("..", import.meta.url));
 const SECP256K1_ORDER = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
@@ -395,13 +395,6 @@ function assertIgnoredPath(root, relativePath, checkIgnored = defaultCheckIgnore
   }
 }
 
-function defaultCheckIgnored(root, relativePath) {
-  const result = spawnSync("git", ["-C", root, "check-ignore", "--", relativePath], {
-    encoding: "utf8",
-  });
-  return result.status === 0;
-}
-
 export async function main(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
diff --git a/scripts/ickb-live-config-git.mjs b/scripts/ickb-live-config-git.mjs
new file mode 100644
index 00000000..29353d90
--- /dev/null
+++ b/scripts/ickb-live-config-git.mjs
@@ -0,0 +1,18 @@
+import { spawnSync } from "node:child_process";
+
+export function defaultCheckIgnored(root, relativePath, spawnSyncFn = spawnSync) {
+  const result = spawnSyncFn("git", ["-C", root, "check-ignore", "--", relativePath], {
+    encoding: "utf8",
+  });
+  if (result.error !== undefined) {
+    throw new Error("Failed to run git check-ignore", { cause: result.error });
+  }
+  if (result.status === 0) {
+    return true;
+  }
+  if (result.status === 1) {
+    return false;
+  }
+  const stderr = result.stderr === undefined ? "" : String(result.stderr).trim();
+  throw new Error(stderr === "" ? "Failed to run git check-ignore" : `Failed to run git check-ignore: ${stderr}`);
+}
diff --git a/scripts/ickb-live-config-git.test.mjs b/scripts/ickb-live-config-git.test.mjs
new file mode 100644
index 00000000..372d8db8
--- /dev/null
+++ b/scripts/ickb-live-config-git.test.mjs
@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { defaultCheckIgnored } from "./ickb-live-config-git.mjs";
+
+test("git ignore helper checks a repo-relative path", () => {
+  const calls = [];
+  const ignored = defaultCheckIgnored("/repo", "config/bot-testnet.json", (command, args, options) => {
+    calls.push({ command, args, options });
+    return { status: 0 };
+  });
+
+  assert.equal(ignored, true);
+  assert.deepEqual(calls, [
+    {
+      command: "git",
+      args: ["-C", "/repo", "check-ignore", "--", "config/bot-testnet.json"],
+      options: { encoding: "utf8" },
+    },
+  ]);
+});
+
+test("git ignore helper treats status 1 as not ignored", () => {
+  assert.equal(defaultCheckIgnored("/repo", "README.md", () => ({ status: 1 })), false);
+});
+
+test("git ignore helper reports missing git separately from not ignored", () => {
+  const cause = new Error("spawn git ENOENT");
+
+  assert.throws(
+    () => defaultCheckIgnored("/repo", "config/bot-testnet.json", () => ({ status: null, error: cause })),
+    (error) => {
+      assert(error instanceof Error);
+      assert.equal(error.message, "Failed to run git check-ignore");
+      assert.equal(error.cause, cause);
+      return true;
+    },
+  );
+});
+
+test("git ignore helper reports fatal git results", () => {
+  assert.throws(
+    () => defaultCheckIgnored("/repo", "config/bot-testnet.json", () => ({
+      status: 128,
+      stderr: "fatal: not a git repository\n",
+    })),
+    /Failed to run git check-ignore: fatal: not a git repository/u,
+  );
+});
diff --git a/scripts/ickb-live-preflight.mjs b/scripts/ickb-live-preflight.mjs
index 47fe4363..5de3d266 100644
--- a/scripts/ickb-live-preflight.mjs
+++ b/scripts/ickb-live-preflight.mjs
@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
 import { lstat, readFile, realpath } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { defaultCheckIgnored } from "./ickb-live-config-git.mjs";
 
 const rootDir = fileURLToPath(new URL("..", import.meta.url));
 const ROLE_PATTERN = /^[a-z](?:[a-z0-9_-]{0,30}[a-z0-9])?$/u;
@@ -337,13 +337,6 @@ async function assertNoSymlinkedConfigAncestors(root, configPath, dependencies)
   }
 }
 
-function defaultCheckIgnored(root, relativePath) {
-  const result = spawnSync("git", ["-C", root, "check-ignore", "--", relativePath], {
-    encoding: "utf8",
-  });
-  return result.status === 0;
-}
-
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
   process.exit(await main(process.argv.slice(2)));
 }