Support inbound iMessage image attachments

[owainlewis]

Outcome

An accepted iMessage can include supported local image attachments, which Push forwards through the shared image pipeline to Codex, Pi, or Claude.

Dependencies

• Depends on Support inbound Telegram images through Codex #185, Support Telegram images through Pi #186, and Support Telegram images through Claude Code #187.

Constraints

• Read attachment metadata through the Messages database without reading image bytes during polling.
• Join attachments to their message while preserving one inbound message per Messages row.
• Read attachment bytes only inside the accepted worker.
• Canonicalize and verify each path under the Messages attachment directory before opening it.
• Reject missing files, directories, escaping symlinks, and unsupported types.
• Support JPEG, PNG, and WebP directly.
• Convert HEIC and HEIF to a private temporary JPEG using macOS system image tooling, then apply the shared size limit to the result.
• Preserve text decoding, reply-marker filtering, group rejection, cursors, and sender allowlists.
• Document the added Full Disk Access implications and local conversion behavior.

Acceptance criteria

• Image-only iMessages from accepted conversations are processed.
• Text plus image messages preserve both inputs.
• Several supported attachments preserve database order up to the shared limit.
• Polling does not load attachment bytes.
• Paths outside the Messages attachment directory are rejected.
• Missing and unsupported attachments receive an actionable reply without invoking the backend.
• HEIC input is converted to JPEG and all temporary files are removed after the turn.
• Existing iMessage text behavior and cursor tests pass.
• Codex, Pi, and Claude receive the prepared images.
• Documentation covers formats, limits, privacy, and macOS permissions.

Checks

cargo test --locked imessage
cargo test --locked gateway
cargo fmt --all --check
cargo clippy --locked --all-targets -- -D warnings
cargo build --locked
cargo test --locked
mkdocs build --strict

Manually send a JPEG screenshot and an iPhone HEIC photo through iMessage. Confirm both are understood and no converted files remain.

Out of scope

• iMessage image replies
• Videos, Live Photo video components, stickers, PDFs, and other documents
• Group chats
• Durable storage of image bytes

[owainlewis]

Implemented in commit 6cb0428 and PR #195.

Verification: 26 iMessage tests, 76 gateway tests, 438 full unit tests plus all integration suites, strict Clippy, formatting, build, strict MkDocs, and a real macOS sips HEIC round-trip all pass. Independent review approved after deterministic attachment-path and root-parent race tests were added. Manual Messages delivery remains unverified.

[owainlewis]

Automated review follow-up: commit f58c140 adds a 32 MiB bounded HEIC/HEIF staging copy, regression coverage, and documentation. The review thread is resolved. Updated verification: 7 focused attachment tests, 76 gateway tests, 439 full tests plus integration suites, strict Clippy, formatting, build, and strict MkDocs pass.

[owainlewis]

Second automated review follow-up: commit bcce443 adds bounded pending-filename deferral so an in-progress attachment is not lost and an abandoned transfer cannot block later messages forever. The review thread is resolved. Updated verification: 28 iMessage tests, 76 gateway tests, 441 full tests plus integration suites, strict Clippy, formatting, build, and strict MkDocs pass.

[owainlewis]

Final review feedback is addressed in 639892c and PR #195. Filename deferral now happens only after iMessage acceptance, its cursor barrier survives history/queue/pre-worker failures, and vanished rows are reconciled only from a complete iMessage snapshot. Verified with 32 iMessage tests, 79 gateway tests, 444 full unit tests plus all integration suites, strict clippy, build, and strict MkDocs. Fresh independent review approved.

[owainlewis]

Final automated review finding fixed in d83e8c9 on PR #195. Later completed rows now survive restart through durable completion markers; marker-write failures hold a retryable cursor barrier; markers are consumed only from complete iMessage snapshots and pruned transactionally with cursor advancement. Verified with 447 unit tests plus all integration suites, 81 gateway tests, strict clippy, build, strict MkDocs, and a fresh independent review.

[owainlewis]

Latest automated review finding fixed in f99ef04 on PR #195. The three-poll filename grace is now durable across restarts, stays exhausted after the third deferral, clears when the filename becomes ready, and is pruned atomically when the cursor advances. A four-process restart regression proves fallback occurs on the fourth observation without rerunning the later completed row. Full tests, focused tests, strict clippy, build, docs, and fresh independent review are green.