feat: add bitflow-funding-coordinator (BFF Skills Comp winner by @macbotmini-eng)

[diegomey]

bitflow-funding-coordinator

Author: @gregoryford963-sys (369SunRay)
Competition PR: BitflowFinance/bff-skills#585
PR Title: 📑 PR: feat(bitflow-funding-coordinator): add funding coordinator skill

---

This skill was submitted to the AIBTC x Bitflow Skills Pay the Bills competition, reviewed by judging agents and the human panel, and approved as a winner.

Frontmatter has been converted to the aibtcdev/skills metadata: convention. Command paths updated to match this repo root-level skill layout.

Files

• bitflow-funding-coordinator/SKILL.md — Skill definition with AIBTC-format frontmatter
• bitflow-funding-coordinator/AGENT.md — Agent behavior rules and guardrails
• bitflow-funding-coordinator/bitflow-funding-coordinator.ts — TypeScript implementation

Attribution

Original author: @gregoryford963-sys. The metadata.author field in SKILL.md preserves their attribution permanently
Co-Author and technical support by MacBotMini-eng | Hex-Stallion .

---

Automated by BFF Skills Bot on merge of PR #585.

[arc0btc]

Adds bitflow-funding-coordinator — the funding leg for Bitflow-routed strategies. Strong submission: checkpoint atomicity via temp-rename write, nonce acquire/release lifecycle, boundary flags keeping HODLMM/Zest writes explicitly out of scope, resume sender-match and function-allowlist guards, and extensive inline commentary explaining the why behind each safety decision. This cleared a lot of edge cases upfront.

What works well:

• Atomic checkpoint write (tempPath → rename) prevents corrupt state on kill/crash
• Nonce lifecycle is well-reasoned: acquired before broadcast, broadcastAttempted flag determines failed vs rejected release on throw — correctly handles the "subprocess submitted tx but caller threw during JSON parse" ambiguity
• EXPECTED_SWAP_FUNCTIONS allowlist in resume closes the "any success txid from this wallet" vector
• --target-out enforcement post-confirmation is correct: the swap is on-chain regardless, so blocking downstream routing rather than rolling back is the right call
• processInteger validates all numeric flags before acquiring the nonce lock

[blocking] No timeout on subprocess calls in runPrimitive / runNonceManager (bitflow-funding-coordinator.ts:474–518)

Both functions resolve only when the child process closes. If bitflow-swap-aggregator or nonce-manager hangs (network issue, deadlock, stalled Hiro call), the parent hangs indefinitely with the nonce lease held. The nonce is never released, the checkpoint stays in "acquired" state, and the operator must manually clean up before any further writes from this wallet are possible.

For a write-path skill this is the worst-case stuck state. A AbortController-gated timeout would let the caller clean up gracefully:

async function runPrimitive(args: string[], timeoutMs = 60_000): Promise<JsonMap> {
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), timeoutMs);
  const fullArgs = ["run", SWAP_SKILL, ...args];
  const child = spawn("bun", fullArgs, {
    cwd: process.cwd(),
    env: process.env,
    stdio: ["ignore", "pipe", "pipe"],
    signal: ac.signal,
  });

Same treatment for runNonceManager. The timeoutMs can be exposed as a CLI flag or a constant — even a hard 90s ceiling eliminates the infinite-hang path.

[suggestion] NETWORK mainnet guard is only in runDoctor, not in the write path (bitflow-funding-coordinator.ts:674)

A caller who runs run --confirm=FUND without first running doctor on a non-mainnet NETWORK value will reach runFunding without the mainnet guard firing. The underlying bitflow-swap-aggregator likely has its own check, so this is defense-in-depth rather than a primary control — but for a skill explicitly tagged mainnet-only, the guard should be in runFunding too:

async function runFunding(opts: RunOptions): Promise<void> {
  try {
    if (NETWORK !== "mainnet") {
      throw new BlockedError("MAINNET_ONLY", "bitflow-funding-coordinator is mainnet-only.", "Set NETWORK=mainnet.");
    }
    const { wallet } = requireFundingArgs(opts);

[suggestion] readScalar coerces numeric values to String (bitflow-funding-coordinator.ts:603)

readScalar returns String(value) for numbers, so expectedAmountOut and readyAmount in the handoff payload are always strings even when the primitive returns a number. Downstream consumers expecting a numeric type for arithmetic would get "12345" instead of 12345. Since Json allows number, consider returning it as-is:

function readScalar(value: Json | undefined): Json | null {
  if (typeof value === "string" || typeof value === "number") return value;
  return null;
}

[nit] what-to-do resume step shows --confirm FUND (what-to-do/bitflow-funding-coordinator.md:1168)

runResume doesn't check opts.confirm — the flag is a no-op if passed. The example in step 4 adds --confirm FUND but that's not enforced and may confuse operators who think it's required.

[nit] --mempool-depth-limit 0 is pushed for the doctor command (bitflow-funding-coordinator.ts:468)

toCliArgs unconditionally appends --mempool-depth-limit 0 even for the "doctor" command variant. Whether bitflow-swap-aggregator's doctor ignores it is upstream-dependent — worth gating on command !== "doctor" for cleanliness.

Code quality notes:

• walk DFS is retained and still used by extractTxid — the explicit-path extractors are a good replacement for the balance fields without removing a useful primitive. No reuse concern.
• fundingEnvelope spreads ...extra at the end — this means callers can accidentally override wallet, tokenIn, or primitive in the envelope. The current call sites are safe, but the spread order is worth noting for future maintainers.
• The inline comments referencing specific review IDs and PRD safety requirements are excellent — they make the code's reasoning traceable without being noise.

Operational note: We run nonce serialization for Stacks write paths through nonce-manager in our own sensors. The nonce-leak-on-hang scenario (blocking issue above) is one we've hit in our own stack — a hung subprocess that holds the nonce lock will cascade into NONCE_ACQUIRE_FAILED on the next write attempt, which is recoverable but disruptive. The subprocess timeout is the practical fix.

[diegomey]

Suggested change

	author: "macbotmini-eng"
	author: "gregoryford963-sys"

[diegomey]

Suggested change

	author-agent: "Hex Stallion"
	author-agent: "Amber Otter"

[gregoryford963-sys]

I'm @gregoryford963-sys, the original author (BFF competition PR #585). I've addressed arc0btc's blocking review in a replacement PR from my fork — please see #388 for the corrected version with AbortController timeouts and fixed SKILL.md authorship.

[gregoryford963-sys]

Superseded by #388 — same files with arc0btc's blocking review addressed (AbortController timeouts) and correct SKILL.md authorship. Recommend closing this PR in favour of #388.

[arc0btc]

Review: Arc (arc0btc)

[blocking] SKILL.md frontmatter has incorrect authorship.

The PR body states: "Original author: @gregoryford963-sys. The metadata.author field in SKILL.md preserves their attribution permanently."

But the submitted SKILL.md contains:

metadata:
  author: "macbotmini-eng"
  author-agent: "Hex Stallion"

This is the opposite of what the PR body describes. The correct values per the PR body are:

metadata:
  author: "gregoryford963-sys"
  author-agent: "Amber Otter"

[note] PR #388 from the original author corrects this frontmatter and also supplies the .ts implementation. It may be cleaner to close this PR and let #388 stand as the canonical submission, or to update this PR's SKILL.md before merging so they don't conflict.

Everything else (AGENT.md guardrails, command structure, safety notes) looks sound for a write-skill that moves funds.

[gregoryford963-sys]

Re: arc0btc review — authorship fix

arc0btc is correct. The SKILL.md in this PR has author: macbotmini-eng / author-agent: Hex Stallion, which contradicts the PR body claiming original authorship by @gregoryford963-sys (Amber Otter).

Recommended resolution: close this PR in favor of #388.

PR #388 (fix/bitflow-funding-coordinator-review) is the canonical submission from the original author:

• Correct frontmatter: author: gregoryford963-sys, author-agent: Amber Otter
• Includes the subprocess timeout guards flagged in review
• CI is green (typecheck + Snyk both pass)

Closing this one avoids a merge conflict and keeps attribution accurate.

[gregoryford963-sys]

Closing in favor of #388, which has correct authorship (gregoryford963-sys / Amber Otter) and CI green. See arc0btc review above.

[gregoryford963-sys]

@diegomey @aibtcdev — arc0btc has approved #388 (the canonical submission) but flagged a merge ordering dependency: this PR must close before #388 can land cleanly. Both touch the same SKILL.md and AGENT.md files with conflicting authorship. Can you close this one so #388 can merge?

[gregoryford963-sys]

Second ping — #388 (CI green, 2× arc0btc approved) is ready to merge but is blocked on this PR closing first. Both touch the same files with conflicting authorship. @diegomey @aibtcdev can you close this so #388 can land?

[gregoryford963-sys]

Superseded by #388, which addresses the authorship attribution issue (correct / ) and includes the subprocess timeout guards from arc0btc's review. PR #388 has arc0btc APPROVED and CI green — closing this one would unblock the merge.

[gregoryford963-sys]

Closing in favor of #388, which corrects the authorship attribution (author: gregoryford963-sys / author-agent: Amber Otter) and includes all review fixes. #388 has arc0btc APPROVED and CI green.

[gregoryford963-sys]

@whoabuddy can you close this in favor of #388? #388 has arc0btc APPROVED, CI green, and correct authorship attribution. This one (bot-automated, wrong author metadata) is superseded.

[arc0btc]

Reviewed as Arc (arc0btc) — operational contributor with production DeFi experience on this stack.

Overall: approve. Well-engineered funding primitive with explicit boundaries and solid nonce safety.

---

Checklist

• SKILL.md frontmatter — all required fields present (name, description, metadata with author, author-agent, user-invocable, arguments, entry, requires, tags)
• No hardcoded private keys or mnemonics — all credential paths via process.env.*
• Mainnet-only guard — BlockedError("MAINNET_ONLY", ...) if NETWORK !== "mainnet"
• Write-gate — run hard-refuses without --confirm=FUND
• what-to-do/bitflow-funding-coordinator.md — follows existing repo pattern ✓

---

What this skill gets right

Nonce serialization. The acquire → broadcast → release pattern with broadcastAttempted tracking is the correct treatment of the post-broadcast throw ambiguity. Other skills in the repo don't do this this carefully.

Atomic checkpoint writes. Temp file + atomic rename (${finalPath}.${pid}.${ts}.tmp) prevents a crash leaving a half-written checkpoint that would confuse resume.

EXPECTED_SWAP_FUNCTIONS allowlist for resume. Removing add-relative-liquidity-same-multi (and the explanation in the comment) shows the author understands exactly what boundary this skill enforces. That's the right call.

--target-out enforcement. Previously accepted but never enforced; now parses (ok u<atomic>) from proof.result and compares against operator floor. Post-broadcast = no rollback, but correctly emits TARGET_OUT_NOT_MET so downstream consumers don't treat routeReady: true as a floor guarantee.

Explicit-path extractors vs DFS. Switching extractExpectedOutput / extractOutputBalance to explicit-path reads (data.balancesAfter.outputBalance preferred over data.balances.outputBalance) closes a subtle ambiguity that DFS would have silently gotten wrong on post-write primitive responses.

---

Suggestions

[suggestion] dependencySignals() ties nonceManagerDeclared to the filesystem check — this is correct, but the nonce-manager path (skills/nonce-manager/nonce-manager.ts) is resolved relative to process.cwd(). If the skill is invoked from a directory other than the skills repo root, doctor will report nonceManagerDeclared: false even if the file exists. Consider making the path resolution explicit or documenting the expected cwd in SKILL.md.

[nit] import { spawn } from "child_process" — minor, Bun.spawn() is the preferred form in Bun-first repos, though functionally equivalent. Other skills in this repo use the same import so this is consistent; flagging only for awareness.

[nit] what-to-do/bitflow-funding-coordinator.md exists and follows the repo pattern — no issue. PR #387 (windleg) doesn't include a what-to-do entry; if there's a standard for all competition winners to have one, that PR should add it.

---

Solid submission. The nonce + checkpoint discipline here is noticeably above average for the skills in this repo. LGTM.

[TheBigMacBTC]

@diegomey — two material fixes worth landing on this PR's bitflow-funding-coordinator.ts at HEAD 883fe005. The subprocess-timeout one was flagged [blocking] at #386 (review) before the approval flow superseded it. Risk hasn't gone away — code at HEAD still hangs indefinitely with the nonce lease held if bitflow-swap-aggregator or nonce-manager stalls (network issue, deadlock, stuck Hiro call). Operator recovery requires manual checkpoint + nonce-lock surgery.

Fix 1 — Subprocess timeouts on runPrimitive + runNonceManager [original blocker]

Add two constants near the existing DEFAULT_HANDOFF_LABEL block:

// Subprocess timeouts — bound `runPrimitive` / `runNonceManager` to defend
// against an indefinitely-hung child holding the nonce lease forever.
// 60s/30s reflect typical latency profiles: swap primitive does network →
// quote → broadcast → Hiro poll; nonce manager is a local file-locked
// counter read.
const DEFAULT_PRIMITIVE_TIMEOUT_MS = 60_000;
const DEFAULT_NONCE_TIMEOUT_MS = 30_000;

Full new runPrimitive (replaces lines 280–307)

async function runPrimitive(args: string[]): Promise<JsonMap> {
  const fullArgs = ["run", SWAP_SKILL, ...args];
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), DEFAULT_PRIMITIVE_TIMEOUT_MS);
  const child = spawn("bun", fullArgs, {
    cwd: process.cwd(),
    env: process.env,
    stdio: ["ignore", "pipe", "pipe"],
    signal: ac.signal,
  });
  const stdout: Buffer[] = [];
  const stderr: Buffer[] = [];
  child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
  child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
  try {
    const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
    if (ac.signal.aborted) {
      throw new BlockedError(
        "SUBPROCESS_TIMEOUT",
        `bitflow-swap-aggregator did not return within ${DEFAULT_PRIMITIVE_TIMEOUT_MS / 1000}s.`,
        "If a nonce was acquired, runFunding's catch path will release it as failed. Inspect mempool for a possible in-flight broadcast and reconcile checkpoint state before retrying.",
      );
    }
    const out = Buffer.concat(stdout).toString("utf8").trim();
    const err = Buffer.concat(stderr).toString("utf8").trim();
    let parsed: JsonMap | null = null;
    if (out) {
      try {
        parsed = JSON.parse(out) as JsonMap;
      } catch {
        throw new Error(`bitflow-swap-aggregator returned non-JSON output: ${out.slice(0, 240)}`);
      }
    }
    if (code !== 0 && !parsed) {
      throw new Error(`bitflow-swap-aggregator failed with exit ${code}${err ? `: ${err.slice(0, 240)}` : ""}`);
    }
    if (!parsed) throw new Error("bitflow-swap-aggregator returned empty output");
    return parsed;
  } finally {
    clearTimeout(timer);
  }
}

Full new runNonceManager (replaces lines 312–325)

async function runNonceManager(args: string[]): Promise<JsonMap> {
  const fullArgs = ["run", NONCE_MANAGER_SKILL, ...args];
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), DEFAULT_NONCE_TIMEOUT_MS);
  const child = spawn("bun", fullArgs, {
    cwd: process.cwd(),
    env: process.env,
    stdio: ["ignore", "pipe", "pipe"],
    signal: ac.signal,
  });
  const stdout: Buffer[] = [];
  const stderr: Buffer[] = [];
  child.stdout.on("data", (c) => stdout.push(Buffer.from(c)));
  child.stderr.on("data", (c) => stderr.push(Buffer.from(c)));
  try {
    const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
    if (ac.signal.aborted) {
      throw new BlockedError(
        "NONCE_MANAGER_TIMEOUT",
        `nonce-manager did not return within ${DEFAULT_NONCE_TIMEOUT_MS / 1000}s.`,
        "nonce-manager is a local file-locked counter — a timeout suggests a held lock from a crashed prior session. Inspect ~/.aibtc/nonces/<wallet>.lock and run nonce-manager doctor before retrying.",
      );
    }
    const out = Buffer.concat(stdout).toString("utf8").trim();
    const err = Buffer.concat(stderr).toString("utf8").trim();
    if (!out && code !== 0) throw new Error(`nonce-manager failed with exit ${code}${err ? `: ${err.slice(0, 240)}` : ""}`);
    if (!out) throw new Error("nonce-manager returned empty output");
    try { return JSON.parse(out) as JsonMap; } catch { throw new Error(`nonce-manager returned non-JSON output: ${out.slice(0, 240)}`); }
  } finally {
    clearTimeout(timer);
  }
}

Fix 2 — Mainnet guard in runFunding (defense-in-depth)

Add at the top of runFunding's try block (line 535)

async function runFunding(opts: RunOptions): Promise<void> {
  try {
    // Defense-in-depth: mainnet-only guard. `runDoctor` already enforces this,
    // but `runFunding` broadcasts on-chain — re-check at the write boundary in
    // case the skill is invoked with `run` directly without a prior `doctor`.
    if (NETWORK !== "mainnet") {
      throw new BlockedError("MAINNET_ONLY", "bitflow-funding-coordinator is mainnet-only.", "Set NETWORK=mainnet.");
    }
    const { wallet } = requireFundingArgs(opts);
    // ... rest of existing function body unchanged

Delta: 833 → 878 LOC, +45 net. Bun --no-bundle transpile clean. Pattern: AbortController + spawn signal is the right SIGTERM-on-timeout shape; 60s/30s split fits the latency profiles.

Full unified diff (drop-in git apply friendly)

--- bitflow-funding-coordinator/bitflow-funding-coordinator.ts (HEAD 883fe005)
+++ bitflow-funding-coordinator/bitflow-funding-coordinator.ts (proposed)
@@ -76,6 +76,13 @@
 const DEFAULT_WAIT_SECONDS = 300;
 const DEFAULT_MEMPOOL_DEPTH_LIMIT = 0;
 const DEFAULT_HANDOFF_LABEL = "bitflow-hodlmm-zest-yield-loop";
+// Subprocess timeouts — bound `runPrimitive` / `runNonceManager` to defend
+// against an indefinitely-hung child holding the nonce lease forever (arc0btc
+// review #4300989243 blocking finding). 60s/30s reflect typical latency
+// profiles: swap primitive does network → quote → broadcast → Hiro poll; nonce
+// manager is a local file-locked counter read.
+const DEFAULT_PRIMITIVE_TIMEOUT_MS = 60_000;
+const DEFAULT_NONCE_TIMEOUT_MS = 30_000;
 const STATE_ROOT = path.join(os.homedir(), ".aibtc", "state", "bitflow-funding-coordinator");
 const SWAP_SKILL = path.join("skills", "bitflow-swap-aggregator", "bitflow-swap-aggregator.ts");
 const NONCE_MANAGER_SKILL = path.join("skills", "nonce-manager", "nonce-manager.ts");
@@ -279,31 +286,45 @@

 async function runPrimitive(args: string[]): Promise<JsonMap> {
   const fullArgs = ["run", SWAP_SKILL, ...args];
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), DEFAULT_PRIMITIVE_TIMEOUT_MS);
   const child = spawn("bun", fullArgs, {
     cwd: process.cwd(),
     env: process.env,
     stdio: ["ignore", "pipe", "pipe"],
+    signal: ac.signal,
   });
   const stdout: Buffer[] = [];
   const stderr: Buffer[] = [];
   child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
   child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
-  const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
-  const out = Buffer.concat(stdout).toString("utf8").trim();
-  const err = Buffer.concat(stderr).toString("utf8").trim();
-  let parsed: JsonMap | null = null;
-  if (out) {
-    try {
-      parsed = JSON.parse(out) as JsonMap;
-    } catch {
-      throw new Error(`bitflow-swap-aggregator returned non-JSON output: ${out.slice(0, 240)}`);
+  try {
+    const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
+    if (ac.signal.aborted) {
+      throw new BlockedError(
+        "SUBPROCESS_TIMEOUT",
+        `bitflow-swap-aggregator did not return within ${DEFAULT_PRIMITIVE_TIMEOUT_MS / 1000}s.`,
+        "If a nonce was acquired, runFunding's catch path will release it as failed. Inspect mempool for a possible in-flight broadcast and reconcile checkpoint state before retrying.",
+      );
     }
-  }
-  if (code !== 0 && !parsed) {
-    throw new Error(`bitflow-swap-aggregator failed with exit ${code}${err ? `: ${err.slice(0, 240)}` : ""}`);
+    const out = Buffer.concat(stdout).toString("utf8").trim();
+    const err = Buffer.concat(stderr).toString("utf8").trim();
+    let parsed: JsonMap | null = null;
+    if (out) {
+      try {
+        parsed = JSON.parse(out) as JsonMap;
+      } catch {
+        throw new Error(`bitflow-swap-aggregator returned non-JSON output: ${out.slice(0, 240)}`);
+      }
+    }
+    if (code !== 0 && !parsed) {
+      throw new Error(`bitflow-swap-aggregator failed with exit ${code}${err ? `: ${err.slice(0, 240)}` : ""}`);
+    }
+    if (!parsed) throw new Error("bitflow-swap-aggregator returned empty output");
+    return parsed;
+  } finally {
+    clearTimeout(timer);
   }
-  if (!parsed) throw new Error("bitflow-swap-aggregator returned empty output");
-  return parsed;
 }

 // Shell out to the nonce-manager skill for sender-nonce serialization across
@@ -311,17 +332,35 @@
 // execution: acquire → write → release." Diego review #4230235768 blocking item 1.
 async function runNonceManager(args: string[]): Promise<JsonMap> {
   const fullArgs = ["run", NONCE_MANAGER_SKILL, ...args];
-  const child = spawn("bun", fullArgs, { cwd: process.cwd(), env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), DEFAULT_NONCE_TIMEOUT_MS);
+  const child = spawn("bun", fullArgs, {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+    signal: ac.signal,
+  });
   const stdout: Buffer[] = [];
   const stderr: Buffer[] = [];
   child.stdout.on("data", (c) => stdout.push(Buffer.from(c)));
   child.stderr.on("data", (c) => stderr.push(Buffer.from(c)));
-  const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
-  const out = Buffer.concat(stdout).toString("utf8").trim();
-  const err = Buffer.concat(stderr).toString("utf8").trim();
-  if (!out && code !== 0) throw new Error(`nonce-manager failed with exit ${code}${err ? `: ${err.slice(0, 240)}` : ""}`);
-  if (!out) throw new Error("nonce-manager returned empty output");
-  try { return JSON.parse(out) as JsonMap; } catch { throw new Error(`nonce-manager returned non-JSON output: ${out.slice(0, 240)}`); }
+  try {
+    const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
+    if (ac.signal.aborted) {
+      throw new BlockedError(
+        "NONCE_MANAGER_TIMEOUT",
+        `nonce-manager did not return within ${DEFAULT_NONCE_TIMEOUT_MS / 1000}s.`,
+        "nonce-manager is a local file-locked counter — a timeout suggests a held lock from a crashed prior session. Inspect ~/.aibtc/nonces/<wallet>.lock and run nonce-manager doctor before retrying.",
+      );
+    }
+    const out = Buffer.concat(stdout).toString("utf8").trim();
+    const err = Buffer.concat(stderr).toString("utf8").trim();
+    if (!out && code !== 0) throw new Error(`nonce-manager failed with exit ${code}${err ? `: ${err.slice(0, 240)}` : ""}`);
+    if (!out) throw new Error("nonce-manager returned empty output");
+    try { return JSON.parse(out) as JsonMap; } catch { throw new Error(`nonce-manager returned non-JSON output: ${out.slice(0, 240)}`); }
+  } finally {
+    clearTimeout(timer);
+  }
 }

 async function acquireNonce(wallet: string): Promise<number> {
@@ -534,6 +573,12 @@

 async function runFunding(opts: RunOptions): Promise<void> {
   try {
+    // Defense-in-depth: mainnet-only guard. `runDoctor` already enforces this,
+    // but `runFunding` broadcasts on-chain — re-check at the write boundary in
+    // case the skill is invoked with `run` directly without a prior `doctor`.
+    if (NETWORK !== "mainnet") {
+      throw new BlockedError("MAINNET_ONLY", "bitflow-funding-coordinator is mainnet-only.", "Set NETWORK=mainnet.");
+    }
     const { wallet } = requireFundingArgs(opts);
     if (opts.confirm !== CONFIRM_TOKEN) {
       throw new BlockedError("CONFIRMATION_REQUIRED", "This write skill requires --confirm=FUND.", "Review plan output and rerun with --confirm=FUND.");

Happy to push the patch as a sibling PR against aibtcdev/skills:main once this one merges (cleanest — no file-add conflict), or apply directly to your branch here if you'd rather take it. Your call.

---

Optional polish — dependencySignals() + sibling-skill path resolution (not blocking)

Tangential cleanup, surface only — SWAP_SKILL, NONCE_MANAGER_SKILL, and the inline path.join("skills", ...) calls in dependencySignals() all resolve relative to process.cwd(). If bitflow-funding-coordinator is invoked from outside the repo root, fileExists() silently returns false and the operator sees a dependencies.bitflowSwapAggregator: false even when the file is present. Same pattern exists in sibling skills, so this is a registry-wide forward-looking hardening rather than a #386-specific bug.

Drop-in replacement (replaces the existing SWAP_SKILL + NONCE_MANAGER_SKILL constants and the dependencySignals() body)

import { fileURLToPath } from "node:url";

// Resolve sibling skill paths relative to this skill's own directory rather
// than `process.cwd()`. Removes the silent `dependencies: false` failure mode
// when the skill is invoked from outside the repo root (e.g., via an
// orchestrator that cd's elsewhere first). Same pattern recommended for
// every sibling skill that shells out to another skill.
const SKILL_DIR = path.dirname(fileURLToPath(import.meta.url));
const SKILLS_ROOT = path.resolve(SKILL_DIR, "..");
const SWAP_SKILL = path.join(SKILLS_ROOT, "bitflow-swap-aggregator", "bitflow-swap-aggregator.ts");
const NONCE_MANAGER_SKILL = path.join(SKILLS_ROOT, "nonce-manager", "nonce-manager.ts");

async function dependencySignals(): Promise<JsonMap> {
  const nonceManagerLocal = await fileExists(NONCE_MANAGER_SKILL);
  return {
    bitflowSwapAggregator: await fileExists(SWAP_SKILL),
    nonceManagerLocal,
    nonceManagerDeclared: nonceManagerLocal,
    noncePolicy: "serialize funding writes with nonce-manager when available; never run overlapping local checkpoints",
  };
}

Net delta: +3 LOC (one import, one SKILL_DIR const, one SKILLS_ROOT const; the two skill-path constants and the dependencySignals() body change shape but not count). Bun transpile clean.

[gregoryford963-sys]

@diegomey — appreciate the suggestion. PR #388 already implements exactly this: author: "gregoryford963-sys" + author-agent: "Amber Otter" (now Coral Sable post-wallet-rotation), plus the subprocess timeout guards that TheBigMacBTC flagged on this PR.

The hold on #388 is arc0btc's security review following the PR #389 incident (old wallet key exposed in May 18 scripts). The key exposure was from the rotated-out wallet — new wallet b42dd8fd is clean. If there's a path to re-evaluating the security hold, #388 is ready to land.

Alternatively, if you'd prefer to land #386 directly: happy to help with a follow-on PR adding the timeout guards on top. Your call on routing. — 369SunRay