docs(known-issues): add settle-false-negative orphans + no-auto-refund

[raahulrahl]

Summary

Adds two medium-severity entries to bugs/known-issues.md under Bindu Core, both grounded in the #562/#565 settle-first work that just landed:

Slug	What it documents
x402-settle-false-negative-silent-orphans	Facilitator /settle can time out while the chain ultimately confirms — payer debited but task marked failed, with no payment-orphaned tag because the worker's only signal was settle's success=False. The fields needed for reconciliation are persisted (via _settle_payment's _failure_metadata), but the periodic worker that uses them doesn't exist.
x402-no-auto-refund-for-orphan-payments	When orphans ARE tagged, Bindu has no outbound-wallet path. pay_to_address has only ever been a config string — no private key, no Base RPC, no gas balance. Refunding is fully manual. We agreed to defer because of the custody surface.

Both entries include the operator workaround (manual reconciliation using the EIP-3009 metadata that we now persist on every failed task) and cross-reference each other as the detection/remediation pair.

Also bumps the Bindu Core medium-count in the TOC (6 → 8) and updates the "Last updated" preamble to reflect this session's additions.

Test plan

• No code changes, docs only.
• Pre-commit hooks pass.
• Internal references to file paths and metadata field names verified against current main (bindu/server/workers/manifest_worker.py has the _failure_metadata helper and the _handle_task_failure orphan-payment tagging path).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added two new known issues related to payment settlement behavior, including detailed descriptions and workarounds for handling orphaned payments and settlement timeouts.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 005cb3bc-7e87-4623-b79b-4c102dea8da9

📥 Commits

Reviewing files that changed from the base of the PR and between b3f2cfe and d0cd0d1.

📒 Files selected for processing (1)

• bugs/known-issues.md

---

📝 Walkthrough

Walkthrough

Documentation update to bugs/known-issues.md adding two Bindu Core (Python) Medium-severity known issues: facilitator settle timeout false-negatives that fail to detect on-chain confirmed payments, and missing automated refund mechanism for orphaned payments. The document header, table-of-contents count, quick index, and detailed issue sections are updated together.

Changes

Settle-first orphan payment known issues

Layer / File(s)

Summary

Settle-first orphan payment issues and index updates bugs/known-issues.md

The known-issues documentation is updated with two new Bindu Core Medium entries: x402-settle-false-negative-silent-orphans (facilitator timeout scenarios and reconciliation workarounds) and x402-no-auto-refund-for-orphan-payments (manual USDC refund procedures). The document's "Last updated" banner, table-of-contents Medium count, quick-reference index, and full issue sections are updated together, with cross-pairing notes referencing the shared detection and remediation contexts.

🎯 2 (Simple) | ⏱️ ~8 minutes

🐰 A payment got stuck between chains,
Two issues now caught with clear lanes.
Settle false-negatives caught at last,
Refunds manual till speed grows fast.
Documentation logs the path indeed! 🌟

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/known-issues-payment-orphans

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}