--email sends a Run notification whenever a Run ends #114

Parent

#109

What to build

email / --email, optionally followed by an address, makes a Run send exactly one Run notification when it ends, whatever the outcome. The flag may appear before or after the Issue URL and merge.

Choosing the address. The token after the flag is taken as the address only if it contains @ and doesn't start with https://. Otherwise the address is email.to from the User config. Repeating the flag is an argument error.

Preflight. The notification checks run before any other work, and are the same local checks email-test uses: an address is known, and RESEND_API_KEY is set and not empty. If either fails, the Run stops, sends nothing, and names what's missing.

When it's sent. Once those checks pass, every way the Run ends sends exactly one Run notification:

• ready for review
• merged (a Merge run)
• Failed run, including later preflight failures such as an Origin match mismatch
• interrupted (Ctrl-C, SIGTERM, a closed terminal)

It is sent after the outcome is final and cleanup is done, through the same sending code as email-test.

Content.

• Subject: [thirdshift] <owner>/<repo>#<n> <issue title>: <outcome>, where the outcome is ready for review, merged, failed or interrupted. The title is left out if it isn't known.
• Plain-text body: the pull request URL (if any), the failure cause (if failed), the session log path (if any), the hostname and how long the Run took.

A failed send is a warning on stderr that includes Resend's error. It never changes the Run's outcome, stdout or exit code.

Help and README document --email.

Acceptance criteria

• A Run ready for review with --email me@example.com sends one notification to that address, with subject [thirdshift] acme/widgets#<n> <title>: ready for review and a body containing the PR URL, log path, hostname and duration
• A Merge run with email sends one notification with outcome merged
• A Failed run with --email sends one notification with outcome failed and the failure cause in the body
• An interrupted Run with --email sends one notification with outcome interrupted
• A bare --email sends to email.to, and an address after the flag wins over email.to
• --email and email work before and after the Issue URL and alongside merge, and the Issue URL is never mistaken for the address
• With no address known, or RESEND_API_KEY unset, the Run stops before any claude session or changing gh call, and the stand-in receives nothing
• A Run without the flag sends nothing
• When the stand-in replies 401 or 500, the Run's exit code and stdout are unchanged and stderr has a warning with Resend's error
• Help text and README document --email

Blocked by

• thirdshift email-test through Resend #113