Contacts module gated on Ledger pairing — blocks first-run UX

[szhygulin]

Summary

add_contact returns CONTACTS_LEDGER_NOT_PAIRED whenever no Ledger has been paired. This blocks the natural first-run / demo-mode flow where a user wants to label addresses before setting up signing — especially for read-only / accountant-share use cases. Reverse-decoration (preflight Invariant #7) consequently degrades to literal-address-only on every demo flow.

Repro

Smoke-test scripts 001/002/003/004/011 (and many others). Every add_contact({chain: "evm" | "btc", label, address}) call in default demo mode rejects with CONTACTS_LEDGER_NOT_PAIRED, even though the user only wants to label an address read-only.

Suggested fix

Allow a local/unsigned contacts store that:

1. accepts add_contact calls without a paired Ledger (returns a contact tagged unsigned: true),
2. verifies cryptographically and upgrades to verified: true once a Ledger is paired,
3. surfaces both states clearly ((contact: <label> — unsigned) vs (contact: <label> — verified) in the verification block), so the agent's Invariant Fix Compound dust rendering and add tx simulation #7 surfacing keeps working in degraded form.

Optional: extend EVM-only contacts to Solana/TRON/BTC (currently CONTACTS_CHAIN_NOT_YET_SUPPORTED for non-EVM in v1.0).

Source

120-script Claude Code smoke-test. Smoke-test reference: 001, 002, 003, 004, 011.

🤖 Generated with Claude Code

[szhygulin]

For future readers: this issue closed as partially fixed, partially deferred via PR #471 (merged).

What shipped

The user-visible gap is closed. add_contact / remove_contact / list_contacts / verify_contacts and the resolver work without a paired Ledger in non-demo mode. No-Ledger writes fall through to a process-local in-memory store and return unsigned: true. Reads merge the unsigned overlay on top of the verified signed view (signed always wins per (label, chain)). The resolver decorates literal addresses + forward-resolves unsigned labels with an "(unsigned)" warning so Invariant #7 keeps working in degraded form. First-run / accountant-share users can label addresses without entering demo mode (which intercepts broadcasts).

What's deferred

The full state machine — restart-survivable persistence, promote_unsigned_contacts sign-on-pair upgrade, tamper-aware merge with signed/unsigned label disagreement, Solana / TRON unsigned support — is documented in claude-work/plan-contacts-unsigned-state-machine.md and surfaced in the README roadmap under "Security hardening". Roughly 600 LoC of additional work; the plan is the entry point when this is picked up.

Trust note

The unsigned overlay does not carry the same safety guarantees as the signed blob. A compromised MCP can inject entries into the in-memory store; the resolver surfaces them with a warning. The Ledger device's clear-sign of the literal address remains the safety net — the unsigned flag exists so users with read-only / accountant-share use cases can opt into the weaker guarantee explicitly.