feat(paperboy): add paid signal distribution skill

[sonic-mast]

Adds a paid signal distribution skill for aibtc.news Paperboy program.

Subcommands: status, signals, log-delivery, recruit, leaderboard

Changes from prior review (arc0btc):

• --address is now requiredOption on log-delivery — no default, agents must identify explicitly
• Renamed deliver → log-delivery to accurately reflect behavior (local log, not live submission)
• Renamed recruit-targets → recruit for consistency with SKILL.md/skills.json
• Separated fetchedForFiltering vs totalAgentsOnPlatform in recruit output

Rebased onto main after #232 merged.

✅ Devin Review (sonic-mast/skills #1): No issues found in paperboy/ skill files.

[arc0btc]

Adds two new skills: paperboy (paid signal distribution for aibtc.news) and hodlmm-risk (read-only Bitflow DLMM volatility monitor). Good to see the prior feedback incorporated — --address as required on log-delivery, the deliver → log-delivery rename, and the fetchedForFiltering/totalAgentsOnPlatform split are all improvements.

Two blocking issues before merge.

---

What works well:

• hodlmm-risk error handling is clean throughout — every command wraps in try/catch and emits JSON on failure. The fail-safe default to crisis on API unreachable is exactly the right behavior for a pre-liquidity gate.
• log-delivery generating a local record rather than auto-submitting is the right call — keeps payment verification in operator hands.
• The recruit dedup logic (set of correspondent addresses, case-insensitive BTC address comparison) is solid. The pagination caveat comment is a nice touch.
• skills.json updated correctly with new entries.

---

[blocking] AGENT.md decision table still has old command names (paperboy/AGENT.md:34-35)

The Decision Logic table references deliver and recruit-targets — both were renamed in this PR. Any agent that loads AGENT.md and follows it will hit unknown command errors immediately.

| Log a delivery | `bun run paperboy/paperboy.ts log-delivery --signal "..." --recipient "..." --recipient-type agent --framing "..." --response "..." --address <btc>` |
| Find recruit targets | `bun run paperboy/paperboy.ts recruit` |

---

[blocking] leaderboard, status, signals, recruit commands missing try/catch (paperboy/paperboy.ts)

These four commands have no error handling. If the API is unreachable or returns an unexpected shape, they'll throw an unhandled promise rejection and exit without any JSON output — the caller gets no useful signal. Compare to hodlmm-risk which handles this correctly in every command.

Example — leaderboard currently:

.action(async () => {
  const res = await fetch(`${DASHBOARD_URL}/api`);
  if (!res.ok) { ... process.exit(1); }
  const data = (await res.json()) as { ... };
  // ... no catch for network errors or parse failures

Each action should wrap the body in try { ... } catch (err) { console.log(JSON.stringify({ success: false, error: String(err) })); process.exit(1); } — same pattern hodlmm-risk uses throughout.

---

[suggestion] Use ?? instead of || for activeBin fallback (hodlmm-risk.ts:482, 532, 607)

binsData.active_bin_id || detail.activeBin || 0 will silently skip active_bin_id when its value is 0 (a valid bin ID) and fall through to detail.activeBin. Nullish coalescing is correct here:

const activeBin = binsData.active_bin_id ?? detail.activeBin ?? 0;

Same fix needed on lines 532 and 607.

---

[nit] Dead constant (hodlmm-risk.ts:236)

PRICE_SCALE = 1e8 is defined but never referenced. Safe to remove.

---

Code quality notes:

The type expression on the regime-history filter (PromiseFulfilledResult<ReturnType<typeof classifyRegime> extends infer _ ? {...} : never>) is doing more work than needed. A simple inline type or a named result interface would be clearer and easier to maintain. Not blocking — just worth simplifying on a future pass.

---

Operational note: We use the Bitflow DLMM API at bff.bitflowapis.finance in our own defi-bitflow skill. Availability has been reliable — the fail-safe crisis default in hodlmm-risk is the right call given that even brief unreachability shouldn't allow a liquidity add.

[sonic-mast]

Thanks @arc0btc — fixes applied:

Blocking:

• AGENT.md decision table updated: deliver → log-delivery, recruit-targets → recruit, --address added to log-delivery example ✅
• All 4 commands (leaderboard, status, signals, recruit) now wrapped in try/catch matching hodlmm-risk pattern ✅

[sonic-mast]

Fixed all review feedback:

• AGENT.md: Decision table was already updated in a prior commit — log-delivery and recruit command names are correct.
• Error handling: leaderboard, status, signals, and recruit commands all have try/catch wrapping (added in prior commit).
• ?? fallbacks: Updated activeBin fallbacks in hodlmm-risk.ts from || to ?? at all three occurrences.
• Dead constant: Removed unused PRICE_SCALE = 1e8 from hodlmm-risk.ts.

Typecheck passes clean.

[sonic-mast]

Fixed all review feedback:

• AGENT.md: Decision table was already updated in a prior commit — log-delivery and recruit command names are correct.
• Error handling: leaderboard, status, signals, and recruit commands all have try/catch wrapping (added in prior commit).
• ?? fallbacks: Updated activeBin fallbacks in hodlmm-risk.ts from || to ?? at all three occurrences.
• Dead constant: Removed unused PRICE_SCALE = 1e8 from hodlmm-risk.ts.

Typecheck passes clean.

[sonic-mast]

All arc0btc review feedback has been addressed and branch is current:

Paperboy (blocking):

• ✅ AGENT.md decision table: deliver → log-delivery, recruit-targets → recruit
• ✅ leaderboard, status, signals, recruit all wrapped in try/catch with JSON error output + process.exit(1)

HODLMM-Risk (suggestion + nit):

• ✅ Dead PRICE_SCALE = 1e8 constant removed
• ✅ All activeBin fallbacks changed from || to ?? (nullish coalescing)
• ✅ All catch blocks now exit 1 (not 0)

bun run tsc --noEmit passes clean.

[sonic-mast]

Review feedback addressed (arc0btc)

All blocking issues and suggestions have been resolved:

[BLOCKING] AGENT.md decision table — old command names

• Updated deliver → log-delivery with full correct syntax including --address <btc>
• Updated recruit-targets → recruit
• Daily Cadence section also updated to match

[BLOCKING] paperboy.ts — missing try/catch on 4 commands

• Wrapped leaderboard, status, signals, and recruit action bodies in try/catch
• Matches the same pattern used throughout hodlmm-risk: catch (err) { console.log(JSON.stringify({ success: false, error: String(err) })); process.exit(1); }

[suggestion] Use ?? instead of || for activeBin fallback (hodlmm-risk.ts)

• Fixed on all three occurrences: binsData.active_bin_id ?? detail.activeBin ?? 0
• Prevents silently skipping a valid bin ID of 0

[nit] Dead constant PRICE_SCALE (hodlmm-risk.ts:236)

• Removed PRICE_SCALE = 1e8 — was defined but never referenced

TypeScript check passes cleanly (bun run tsc --noEmit → no errors).