proof-aware-crypto-tooling-agent/docs/runbook-latch.md

Runbook: the custody latch fired

You are here because outbound custody is frozen and every signing request returns CUSTODY_LATCHED. This is the wallet doing its job: an unexplained quorum divergence or a firewall quarantine occurred, and the wallet refuses to certify anything — including its own refusals, which now arrive unsigned on purpose.

Do not unlatch first. Diagnose first. The latch is cheap; a released forged signature is not.

1. Read what happened (2 minutes)

pacta wallet status --wallet <dir>          # latch reason + incident ref
cat <dir>/latch.json
cat <dir>/incidents/<ref>.json              # the full divergence trail
ls <dir>/quarantine/                        # any withheld signatures
pacta wallet verify-ledger --wallet <dir>   # is the history itself intact?

The incident file names, per quorum member, its verdict and its binary hash at the moment of divergence. That table is your suspect list.

2. Classify (the incident file already did; check its work)

• classification: semantic-edge (severity note) — the input hit a documented degenerate class (small-order R, non-canonical s). This does NOT latch by itself; if you are latched, something else also happened.
• classification: unexplained (severity tamper) — members disagreed with no documented reason, or one errored. Assume fault or tampering until shown otherwise.

3. Investigate the three usual suspects, in order

1. A corrupted/updated member binary. Compare each member's current hash against the capsule: shasum -a 256 dogfood/state/quorum/pacta-verify-* (GNU: sha256sum) vs capsule.json → members[].binary_sha256. A mismatch on exactly the dissenting member is the common benign case (a rebuild happened); a mismatch you cannot explain is not benign.
2. Hardware/memory fault. Re-run the exact input from the incident file through the quorum (payload_sha256, signature_hex, public_key_hex are all recorded). A divergence that does not reproduce points at a transient fault; log that finding in the unlatch note.
3. Actual tampering. Divergence reproduces, hashes match the capsule, input is not a documented edge → treat the host as suspect: rebuild members from pinned sources on a machine you trust, re-run, compare.

4. Remediate

• Benign rebuild drift → rebuild all members (pacta wallet build-quorum), then re-init or re-seal the capsule so the pins match reality again.
• Transient fault → document it; consider the machine's RAM.
• Suspected tamper → do not unlatch on this host. Preserve the wallet directory (it is the evidence), stand up a fresh wallet from fresh builds + fresh evidence elsewhere.

5. Unlatch — a deliberate, recorded act

pacta wallet unlatch --wallet <dir> --note "<what happened, what you checked, why it is safe now>"

The note is permanent: it lands in the hash-chained ledger next to the latch it releases, and shows up in every future audit. Write it for the auditor you hope never needs it. An empty or lazy note defeats the design; the CLI requires the flag, your discipline supplies the content.

6. Afterwards

Re-run a signing smoke test and confirm unanimous-accept; check pacta wallet status shows latched: false, chain intact, and the incident count where you expect it. If this wallet participates in a choir, expect peers to ask about the head gap — that is the system working.