What this does

tps mail send can now be driven safely by a program that answers mail — the four gaps in #429 — and on the receiving side bodies and threads require verification: an unverified record is still listed, but only with its claimed metadata (id, claimed sender and recipient, timestamp, location, lifecycle fields), never its body or thread; and a reply obligation is acknowledged only on a verified receipt.

tps mail send

• --stdin reads the body from fd 0 (UTF-8) with readSync until EOF — retrying EAGAIN, capped at the 64 KiB envelope body limit, with distinct errors for empty input and for a stdin that never delivers — and never through process.stdin (under bun a regular-file or memfd stdin reads as 0 bytes once process.stdin exists). The 64 KiB limit is enforced on the SIGNED message (the body plus its signature, chain and envelope fields) before any route, so a body just under the limit whose signed envelope is over it is refused by name (Refusing to send: the signed message is too large to send…) with nothing written. The command never prints the body: --json prints delivery metadata only, on every route — status, route (local / outbox / bridge / remote-branch), to, from, the signed messageId, replyToId when set, signedAt, and on the local route the record id and timestamp.
• --reply-to <messageId> carries the signed messageId being answered inside the envelope, so the signature covers it.
• --message-id <id> signs the envelope with that messageId instead of a fresh UUID, so a sender that re-sends after an unknown outcome sends the same message (a recipient's replay gate discards the copy).
• One id rule — 1-128 letters, digits, dot, underscore or hyphen — for --reply-to and --message-id on send and for every envelope's messageId and replyToId on receipt.
• Keys. Both ~/.flair/keys/<id>.key and ~/.tps/identity/<id>.key (where tps init / tps agent create put it) are read. When both exist they must hold the same key: two different keys are refused, naming both paths and the remedy, instead of one being chosen silently. A key file that cannot be read or parsed is an error naming its path. Formats: a raw 32-byte seed, one line of base64 PKCS8 DER, raw PKCS8 DER, or exactly one unencrypted PEM PRIVATE KEY block (what bob onboard writes), each parsed strictly; encrypted keys and other algorithms are refused by name; errors never carry key material.
• A send that cannot sign fails: non-zero exit, the key path(s) and the remedy, and nothing written to any maildir, outbox, sandbox or wire, on every route. There is no unsigned mode; --unsigned is refused by name.

Receipt views (CLI). The thread is shown by mail check, mail list, mail read and mail log for verified mail. An unverified record — new/, dlq/, or a cur/ record that does not re-verify — is presented through an allowlist: its id, claimed sender and recipient, timestamp, location and lifecycle fields. Its body, thread fields (replyToId, envelopeId, the stored envelope), headers (X-TPS-InReplyTo, X-TPS-Obligation, X-TPS-Nack among them) and every other field are withheld, in mail list and mail read, text and JSON.

openclaw-tps-mail.

• A dispatcher reply signs the inbound's verified envelope messageId as replyToId inside the envelope, and so does the nack for every obligation this version opens; an obligation opened by an earlier version records no envelope id, so its nack is signed but unthreaded. A reply or nack that cannot be signed is not sent (named failure; an owed nack stays pending for the next start).
• A receipt acks an obligation only when the reply it carries verifies: a signed envelope from the obligated agent, addressed to the inbound's verified sender, whose signatures verify against the key Flair holds for that agent (the same verifyEnvelope + Flair client promote() uses), and — for an obligation this version opens — whose signed replyToId is the inbound's verified envelope id. This holds for all three receipt forms: the posted record, the bridge sandbox record and the metadata receipt. A delivered record must also agree with the envelope it carries: its to is the envelope's to, and a record the recipient already promoted (plaintext body, signed envelope stored beside it) counts only when its plaintext body is the stored envelope's body. A matching record that is unsigned, badly signed, signed by anyone else, addressed to anyone else, or presenting a body or recipient its stored envelope does not carry never acks. The metadata receipt now carries the signed reply it attests (signedReply), 0600 in the replying agent's own obligation store; one written before this change carries none and is not evidence (its obligation resolves at its deadline). A local reply now writes a metadata receipt too, like the wire and the bridge: its delivered record lives in the recipient's maildir, which the recipient consumes (promote() moves it, the ack deletes it, gc purges it), so once the recipient had acked it, a later scan — the deadline's, or restart recovery's — found no evidence and the committed reply ended unconfirmed. The outbox route still has none: its record stays in this host's outbox and the drain quarantining it is a verdict the scan must see. A verification that cannot run (Flair unreachable) is logged receipt-verify-unavailable and is not evidence.

pi-tps-mail watcher.

• The inbound is verified before any field is used: each check runs tps mail check <agent> --json as the agent — the CLI's promotion path — and the watcher dispatches only the records it returns. An unsigned or forged inbound is dead-lettered by the CLI and never answered; the sender, the body the launcher sees and the thread come from the verified envelope.
• The reply goes out on stdin with --reply-to the inbound's verified envelope id and --message-id from a reply journal (<mail>/<agent>/.pi-tps-mail/replies/<id>.json, 0600) written before the first send. A send whose outcome is unknown (a non-zero exit or a timeout) is re-sent after a backoff as the same message — same text, thread and messageId — so if the first attempt had been delivered, the recipient's replay gate dead-letters the copy. A failed ack is retried on the next check without re-sending; a restart finishes the journal (re-ack or re-send). What the journal cannot cover: a crash while the launcher runs leaves the inbound unacked in cur/, and the CLI re-presents it when its 30-minute lease expires (the watcher re-runs its verified check at least every rescanIntervalMs), so the launcher runs again — at-least-once.

What this does not do (#433)

Signing today: tps mail send (all four routes), the openclaw-tps-mail plugin's dispatcher replies and nacks, and the codex/gemini runtimes' replies (runtime mail). These producers do not sign bodies themselves: pulse, topic fan-out and catch-up, hire onboarding, roster invites, bootstrap, branch handler replies, the plugin's outbound adapter (sendText, which also carries an unsigned wrapper replyToId), and the channel bridge — tracked in #433 — and, not yet listed there, the @tpsdev-ai/agent runtime's MailClient.sendMail (it writes {to, body, sentAt} to its outbox as given). A verifying recipient dead-letters an unsigned body; a writer that passes a supplied body through (a relay, a branch forward) can preserve an envelope that was already signed. docs/commands.md and the changelog fragment say the same; the help text describes only tps mail send.

Exact CLI usage

tps mail send <to> --stdin
tps mail send <to> --stdin --reply-to <messageId>
tps mail send <to> --stdin --reply-to <messageId> --message-id <id> --json
printf 'body' | tps mail send <to> --stdin --reply-to <messageId>

Callers

• packages/pi-tps-mail/src/watcher.ts sends through tps mail send <to> --stdin --reply-to <envelopeId> --message-id <journal id> as the agent; with no usable key the send fails loudly and the reply stays journaled until a key exists.
• packages/cli/test/mail.test.ts's branch-outbox test provisions a signing key (its subject is outbox routing, not signing).
• tpsdev-ai/bob (bob#203) is the consumer this unblocks: tps mail send <to> --stdin --reply-to <messageId> as the agent, with the PEM key bob onboard writes.

Tests

Every control below fails without the change it guards (mutation list below). CLI spawns run with HOME inside the test's temp root — including the fd-0 harness probe in mail-send-stdin-reply.test.ts, which now gets the same isolated environment as the sends. The pi watcher tests drive the real tps CLI against a stub Flair inside a throwaway root.

• packages/cli/test/mail-send-routes.test.ts (10 → 23): --stdin --json prints metadata only — the stdin body is on neither stdout nor stderr — on the local, bridge, outbox and remote-branch routes (the latter against a branch stand-in that completes the Noise handshake and ACKs), on a failing wire and on a refused send; the JSON's messageId matches the envelope actually delivered. A ~65,000-byte body (under 64 KiB as plaintext, over it once signed) is refused by name on the local, bridge, outbox and remote-branch routes, with and without --json: nothing written, no connection to the wire, the body never echoed; a 60,000-byte body is sent (control). A tps agent create identity key plus a DIFFERENT valid ~/.flair/keys key is refused naming both paths and nothing is written; with the same key in both files the send signs and verifies against the registered key.
• packages/cli/test/mail-receipt-thread.test.ts (12 → 18): forged thread headers (X-TPS-InReplyTo, X-TPS-Obligation, X-TPS-Nack, In-Reply-To) and extra thread fields on a new/, dlq/ and non-re-verifying cur/ record are withheld in mail list and mail read, text and JSON; a verified record keeps its headers (control). mail log shows a verified reply's thread in text and JSON, and an unverified thread claim never reaches the log.
• packages/cli/test/mail-send-stdin-reply.test.ts (18 → 20): --message-id produces the same envelope id on two sends (both verify); an invalid --message-id is refused by name.
• packages/cli/test/agent-keys.test.ts (23 → 25): the test that expected the Flair key to win silently is replaced — two different valid keys are refused with both paths and the remedy and no key material; the same key in two formats is accepted; a malformed second file is named.
• plugins/openclaw-tps-mail/test/receipt-scan.test.ts (29 → 56): the positive signed fixtures carry real Ed25519 signatures (the old "signed" fixture had none); the negative fixtures are deliberately unsigned, badly signed, foreign-signed, misaddressed or plaintext. For each receipt form — posted record, bridge sandbox record, metadata receipt — an unsigned reply, a signature broken after signing, a reply signed with another key while claiming the agent, another agent's genuine reply, and a plaintext body are all rejected. A recipient-promoted record (plaintext body, signed envelope stored beside it) is accepted; the same record with an unsigned stored envelope, with a VALID stored envelope beside altered plaintext, or with a valid stored envelope beside an altered record recipient is rejected (posted and bridge forms). A GENUINE signature addressed to the wrong recipient is rejected on every form (posted, promoted posted, bridge, metadata). A pre-mail send: stdin body, --reply-to threading, PEM PKCS8 keys, and refuse to send unsigned #429 metadata receipt with no signed reply is rejected; a signature check that throws is not evidence. Signed-thread mode is checked with real signatures, including a thread changed after signing.
• plugins/openclaw-tps-mail/test/locality.test.ts (34 → 44): on the local and remote-branch routes, a delivered reply whose signature Flair does not verify leaves the obligation posted with its deadline armed — not acked, not failed, not nacked. The remote-branch receipt test asserts the receipt's signedReply is the exact body that went on the wire and verifies. Integration (local and bridge): the obligation is left open after delivery, the recipient's REAL promote() runs on the delivered reply — the promoted record keeps the obligation metadata (marker, account and thread; or the bridge record's obligation ids) and the posted-record scan alone finds it — and then the restart scan and the deadline scan each ack the obligation; and after the recipient also ACKS (deletes) the reply, the restart and deadline scans still ack it (on the local route this failed before this change: posted / unconfirmed).
• plugins/openclaw-tps-mail/test/final-selection.test.ts (b4) and reply-obligation.test.ts (R8-c): both simulate a committed local reply with NO evidence by making the recipient's maildir unlistable; a local reply now also has a metadata receipt, so each also makes that receipt unwritable — the premise (no evidence) and the assertions are unchanged; counts unchanged.
• plugins/openclaw-tps-mail/test/startup.test.ts: the crash-recovery fixture registers the agent's key with the mocked Flair (the ack now needs a verified receipt); count unchanged.
• packages/pi-tps-mail/test/reply-send.test.ts (3 → 12): a genuine inbound is answered (verified body to the launcher; reply signed, on stdin, threaded, journaled messageId; ack after send); an unsigned and a forged inbound are dead-lettered and never dispatched, answered or acked; no key → no ack, then the same message once a key exists; a send that exits non-zero after delivering and one that times out after delivering are each re-sent as the same message, and the recipient's mail check presents one and dead-letters the copy as replay; a failed ack is retried without re-sending; restart with a sent entry → ack only; restart with a prepared entry → the same message; a lease-expired inbound with no journal entry is re-presented and answered; one with a journaled reply is left to the journal (no second launcher run); an unexpired lease is left alone.

Mutations: 33, each break → red, restore by copy (sha256-identical) → green. Round 7: the signed-size check removed; the local route writing no metadata receipt (the previous head's behaviour); the reply record written without its accountId; a promoted record never read as a receipt (the pre-round-5 behaviour). Receipt binding (round 6): a promoted record's plaintext no longer compared with its stored envelope's body; a record's to no longer compared with its envelope's; the signed recipient no longer required to be the inbound's sender; the plugin passing the replying agent as the expected recipient. Receipts: signature check skipped; signer not required to be the agent; signed thread not compared; metadata / posted / bridge candidates accepted unverified; the plugin's Flair check wired open; receipt written without signedReply. Redaction: headers allowlisted; the previous blocklist restored. mail log: thread not recorded; thread not printed. --json: local route prints the record; bridge JSON carries the body. Watcher: --message-id dropped by the CLI; the watcher reads new/ itself; a fresh id per attempt; a timeout counted as sent; a failed ack drops the journal; the journal never re-read; no rescan of cur/; journal skip removed. Keys: first key wins; second file unread; identical keys refused.

Counts (isolated HOME/TMPDIR, env -i; bun install --frozen-lockfile && bun run build clean on every head; plugin via npm ci --ignore-scripts && npm run build && bun run test; the test-file coverage guard passes on every head). 3f06d658 is the head before round 5, a5c39901 round 5, 5503cd0b round 6 (the receipt binding), and this head adds the signed-size check and the local receipt:

The 10 macOS cli failures are the same 10 tests on every head, in files this patch does not touch (facts-commands, facts-verify, launch-attestation, launch-attestation-real-nono, nono, office-supervision) — host-specific to that Mac; on Linux (no nono, as on CI) there are none.

Closes #429.
Refs #433, tpsdev-ai/bob#200.

🤖 Generated with Claude Code