docs(manual-test)(#218): full two-peer + daemon + IPFS-only recovery walkthrough

[vrogojin]

Summary

Closes #218. Adds manual-test-full-recovery.md as a companion to
manual-test-drain-fix.md, covering the §A–§E scenarios called out in
the issue:

• §A Second profile instance per wallet (peer2-alice, peer2-bob in separate CWDs) — verifies per-instance OrbitDB / IPFS sync for the same identity.
• §B Long-running foreground sphere daemon listeners on peer2 — documents the exact --event / --action quick-mode flags and the per-CWD daemon PID collision gotcha.
• §C Bidirectional invoice flow (11 UCT) with daemons running — asserts peer2 sees the new state without a manual sphere payments sync.
• §D Wipe-and-recover BOTH profiles on BOTH peers using sphere init --no-nostr --mnemonic — proves the published CARs survive without faucet or live Nostr input.
• §E Recovery preserves the invoice ledger — sphere invoice list --state COVERED diffed pre/post wipe must be empty.

Why a sibling doc (vs. extending in-place)

The issue's acceptance section explicitly allows both. The existing
243-line drain-fix doc is tightly focused on the PR #127 follow-up
(sync() drain). Extending it would balloon it to ~700 lines and dilute
its narrative. The sibling cross-references §0 of the drain-fix doc for
prereqs and matches its style (numbered sections, "what you're looking
for" assertions, gotchas, command cheat sheet).

Layout decision

Three CWDs under ~/sphere-full-test/:

peer1/         ← primary; both alice + bob via `sphere wallet use`
peer2-alice/   ← secondary instance of alice (own daemon)
peer2-bob/     ← secondary instance of bob   (own daemon)

Rationale: ./.sphere-cli/{config.json,daemon.pid,daemon.log} are
CWD-relative and not profile-scoped. Two daemons in one CWD collide on
PID without explicit --pid/--log overrides. Per-peer-wallet CWDs
sidestep the collision and keep the daemon commands simple.

Test plan

• Operator follows §0–§E on a fresh testnet checkout, all five
  assertions pass.
• §A's peer1↔peer2 balance diff is empty after init --mnemonic + sync.
• §B daemons report Daemon running. Waiting for events... with no
  PID-collision error.
• §C.4 peer2 balance reflects the 11 UCT invoice payment without a
  manual sphere payments sync (auto-receive worked).
• §D.5 — all four diff outputs empty after --no-nostr recovery on
  both peers.
• §E — invoice list --state COVERED diff pre/post wipe is empty;
  the §C invoice spot-check shows COVERED with the same memo.

Out of scope

Per the issue: scripted automation lives separately in tests/e2e/*.test.ts
(profile-multi-device-sync.test.ts, ipfs-multi-device-sync.test.ts,
two-device-local-mint-convergence.test.ts). This walkthrough is meant
to be human-runnable on testnet.

Refs

• Issue: docs(manual-test): extend manual-test-drain-fix.md to cover full two-peer + daemon + bidirectional invoice + IPFS-only recovery scenario #218
• Companion: manual-test-drain-fix.md
• Related automated tests: tests/e2e/profile-multi-device-sync.test.ts,
  tests/e2e/ipfs-multi-device-sync.test.ts,
  tests/e2e/two-device-local-mint-convergence.test.ts

[vrogojin]

Updated with live-testnet companion script + 3 fixes

Pushed commit 108e9ac adding manual-test-full-recovery.sh — the automated re-run companion that mirrors every CLI command from the walkthrough. Three fixes from live testnet validation:

1. Mnemonic extraction: original \b...\b regex matched a 12-word lowercase span inside the SDK's deprecation-warning text before the real mnemonic. Anchored to full lines (^...$) and added 12-word fallback alongside the existing 24-word path.
2. Nametag suffix length: default epoch-pid suffix pushed alice-full-${SUFFIX} past the 20-char Unicity ID limit. Trimmed to 8 chars.
3. Bob pre-pay sync: added explicit payments sync + payments receive --finalize for bob between §C.1 invoice mint and §C.2 invoice pay.

What the script validates end-to-end on live testnet

Section	Status
§0 Prereqs	✓
§1 Peer1 setup (alice + bob init, faucet 7 coins, sync, balance)	✓
§A.1 Peer2-alice (mnemonic recovery → sync → receive 7 coins)	✓
§A.2 Peer2-bob (mnemonic recovery → sync → balance)	✓
§C.1 Invoice create with @bob-... target	✓ (after the CLI nametag fix below)
§B Daemon start	❌ known gap
§C.2 Invoice pay	❌ known gap

The §A.1 cross-process recovery (peer2-alice receiving all 7 faucet coins from peer1-alice) exercises the same fetchCarFromIpfs block-walk path that #223 (PR #225, merged) fixed — successfully ingesting tokens via IPFS: +7 added on the receive side. This is independent live-testnet validation of #223 via the CLI surface.

Known gaps not addressed in this PR (separate work)

• §B daemon start — sphere daemon start --detach exits between PID-file write and the next check; manifests as "Daemon is not running (stale PID file)". Separate sphere-cli issue.
• §C.2 invoice pay — bob's local ledger doesn't see invoices targeting his address even after explicit sync. Likely needs either (a) per-invoice DM delivery, (b) cross-profile OrbitDB lookup, or (c) IPFS-pinned invoice-by-target index. Separate SDK work.

Companion CLI fix

The §C.1 invoice nametag fix lives in sphere-cli: unicity-sphere/sphere-cli#17 (fix(invoice): accept @nametag as --target). That PR + this one together are what got §C.1 working on testnet.

[vrogojin]

Update — §C round-trip validated end-to-end against testnet (2026-05-23)

Two follow-up commits push the §C section past the prior "Bob can't discover invoice" + "Bob has no UCT" limitations:

• 533033e docs(manual-test)(docs(manual-test): extend manual-test-drain-fix.md to cover full two-peer + daemon + bidirectional invoice + IPFS-only recovery scenario #218): insert §C.1b explicit invoice-deliver step

  • Inserts sphere invoice deliver $INV between mint and pay, exercising the new SDK API from PR Invoice delivery: payer can't discover invoices targeting their address even after explicit sync #226 (accounting.deliverInvoice — UXF-bundle delivery over NIP-17 DM).
  • Updates the companion .md walkthrough with a §C.1b narrative + expected JSON outcome.

• 44a2189 docs(manual-test)(docs(manual-test): extend manual-test-drain-fix.md to cover full two-peer + daemon + bidirectional invoice + IPFS-only recovery scenario #218): faucet Bob in §1 so §C.2 invoice pay can succeed

  • Without this, Bob has 0 UCT and invoice pay errors with "Insufficient balance" — even though §C.1b deliver successfully puts the invoice in his local ledger.

Live testnet run (/tmp/manual-cli-test-226-v6.log):

Step	Outcome
§C.1 — Alice mints invoice (0000422124..., 68-char imprint form)	✓ Invoice created
§C.1b — sphere invoice deliver → inline uxf-car DM	✓ { sent: 1, failed: 0, recipients: [{ success: true, shape: "inline" }] }
§C.2 — Bob pays	✓ Payment status: "submitted"

§C.3/§C.4 (peer2 daemon events) still hit the pre-existing --detach stale-PID limitation that this PR's original commit message already calls out — out of scope for this PR.

Dependencies that needed to land first:

• sphere-sdk PR Invoice delivery: payer can't discover invoices targeting their address even after explicit sync #226 (accounting.deliverInvoice) — merged to integration/all-fixes (commit 90a5cc3).
• sphere-sdk PR fix(uxf)(#226): accept 64- or 68-char tokenId so invoice tokens ride UXF #227 (uxf accept 68-char tokenIds) — merged to integration/all-fixes (commit 3c0bbac). Required because invoice tokens use new TokenId(hash.imprint) (68 chars) while UXF previously enforced exactly 64.
• sphere-cli PR (pending push) — adds the sphere invoice deliver subcommand.