feat: add sticker sends

[omarshahine]

Summary

• add one public surface: imsg send-sticker and JSON-RPC send.sticker
• support standalone stickers and exact message-part attachment through the injected IMCore bridge
• validate and privately stage PNG/APNG, GIF, and JPEG assets before Messages sees them
• expose fail-closed stickerSend / stickerAttach selector capabilities

Maintainer rewrite

This branch keeps Omar's native reverse-engineering and runtime findings, but rewrites the public contract and trust boundaries:

• removed the unshipped sticker, attachments.sendSticker, and sticker.send aliases
• strict RPC object/type/key/chat-selector validation
• iMessage/iMessageLite only; shared identifiers prefer an iMessage chat
• exact target normalization and live-chat membership checks before transfer allocation
• single-read, component-safe openat validation; 500 KiB, 618x618, 100-frame, and 25-million-decoded-pixel caps
• full-frame decode plus truncated PNG/GIF/JPEG rejection
• neutral Sticker accessibility metadata; local source basenames are not transmitted
• SHA-256 byte-integrity checks; native-compatible MD5 sticker hash and canonical staged filename ID
• two-phase transfer preparation/registration and fail-closed attachment/association initializers
• release/notarization builds isolate SwiftPM products per architecture, preventing stale slices from entering universal artifacts
• status, RPC docs, skill guidance, and regression coverage

Redacted exact-head proof

Recipient-visible screenshot artifact:

The screenshot shows the recipient-side Messages transcript with the PR164 proof text and a rendered sticker attached over the target message bubble. It contains no phone numbers or handles beyond the test chat display name.

Proof was collected on refreshed branch head 0f1924c in the real Lobster Test Group iMessage group, with private handles and local paths redacted in the summary below.

Runtime capability after relaunching the branch helper:

{
  "bridge_version": 2,
  "v2_ready": true,
  "selectors": {
    "stickerSend": true,
    "stickerAttach": true,
    "stickerAssociatedMessage": true,
    "stickerAttachmentMessage": true,
    "stickerReplyTo": false
  },
  "rpc_methods": ["send.sticker"]
}

Standalone sticker send returned:

{
  "messageGuid": "B73CDFAE-0423-49B8-A594-0391EDCC9521",
  "transferGuid": "DAB8D310-8BB6-42D5-B327-6ECC47FADEA3",
  "selectedMessageGuid": "",
  "targetPartIndex": 0
}

Exact-part attached sticker send to that standalone sticker message returned:

{
  "messageGuid": "48C121B6-C87D-4B1D-8487-C4DBE97950E5",
  "transferGuid": "5A736866-8E7E-4D14-8DDE-9B059B6883C4",
  "selectedMessageGuid": "B73CDFAE-0423-49B8-A594-0391EDCC9521",
  "targetPartIndex": 0
}

Redacted DB proof for the attached row:

{
  "ROWID": 6893,
  "guid": "48C121B6-C87D-4B1D-8487-C4DBE97950E5",
  "is_from_me": 1,
  "associated_message_guid": "p:0/B73CDFAE-0423-49B8-A594-0391EDCC9521",
  "associated_message_type": 1000,
  "cache_has_attachments": 1,
  "chat_guid": "any;+;<redacted-group-id>"
}

Redacted attachment join proof:

{
  "message_guid": "48C121B6-C87D-4B1D-8487-C4DBE97950E5",
  "attachment_guid": "5A736866-8E7E-4D14-8DDE-9B059B6883C4",
  "filename": "~/Library/Messages/Attachments/imsg/stickers/<redacted>/13285d97dc50e851dff55277f6a87527baae1bcb194f0e98431d89494696b48a.png",
  "mime_type": "image/png",
  "uti": "public.png",
  "total_bytes": 6902,
  "is_sticker": 1,
  "hide_attachment": 0
}

imsg history --attachments decoded both rows as sticker attachments and resolved the attached row back to the exact parent:

{
  "id": 6893,
  "guid": "48C121B6-C87D-4B1D-8487-C4DBE97950E5",
  "reply_to_guid": "B73CDFAE-0423-49B8-A594-0391EDCC9521",
  "attachments": [{ "is_sticker": true, "mime_type": "image/png", "uti": "public.png", "total_bytes": 6902 }]
}

This proof also found and fixed two exact-head issues before the final run:

• sticker staging had the same macOS home-path O_NOFOLLOW problem as rich links; it now anchors below the trusted imsg sticker root and walks only descendants with openat(... O_NOFOLLOW)
• exact attachment no longer depends on the unavailable setReplyToGUID: selector; the associated-message initializer path is sufficient and is what produced the attached sticker row above

Verification

• make build - passed; universal release artifacts built (imsg: arm64 + x86_64; helper: arm64e + arm64 + x86_64)
• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer make lint - passed; 9 existing SwiftLint warnings, 0 serious
• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer make test - passed; 432 tests
• git diff --check - passed

Apple's public sticker constraints are documented in MSSticker.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 11, 2026, 2:17 PM ET / 18:17 UTC.

Summary
The PR adds imsg send-sticker and JSON-RPC send.sticker for standalone and exact-message-part iMessage stickers, including bounded image validation, secure staging, private bridge construction, capability reporting, documentation, and regression tests.

Reproducibility: not applicable. This PR introduces a new capability rather than repairing established behavior. The earlier proof head is convincingly demonstrated, but equivalent validation is still needed for the current integrated head.

Review metrics: 4 noteworthy metrics.

• Change surface: 28 files; +2,565/-89. The feature spans public API, native runtime construction, filesystem and image validation, documentation, and tests.
• Unproven delta: 4 functional commits. Chat aliasing, transfer staging, and failure cleanup changed after the documented real-device proof.
• Merge conflicts: 3 files. The conflicts include the central injected helper, where incorrect resolution could alter several bridge features.
• Live evidence: 1 recipient artifact plus 4 runtime/DB outputs. The earlier-head evidence convincingly covers visible rendering, both send modes, persisted association, and attachment metadata.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Resolve current-main conflicts without dropping existing bridge behavior or sticker hardening.
• Remove the release-owned CHANGELOG.md entry.
• Post redacted final-head proof for standalone and exact-message-part sticker sends.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The recipient artifact and runtime/database outputs prove head 0f1924c, not current head 739ed60, which later changes sticker routing, staging, and cleanup; after resolving conflicts, rerun both modes with redacted screenshot and terminal/database output, update the PR body, and ask a maintainer for @clawsweeper re-review if the automatic review does not run.

Risk before merge

• [P1] The central native-helper conflict could accidentally drop either current-main bridge behavior or sticker-specific hardening during resolution.
• [P1] The supplied real-device evidence does not validate the current head's later staging, alias, and cleanup changes.
• [P1] Merging establishes a maintained CLI/RPC promise over undocumented IMCore selectors and initializer behavior that may vary across macOS releases.

Maintainer options:

1. Refresh, clean, and re-prove (recommended)
   Resolve the current-main conflicts, drop the changelog entry, and repeat the redacted standalone and attached sticker flow on the resulting head.
2. Accept private-framework ownership
   After final-head proof, merge with explicit responsibility for future selector and initializer drift across macOS releases.
3. Decline the support contract
   Close the PR if native sticker automation does not justify its continuing private-IMCore maintenance cost.

Next step before merge

• [P1] The contributor must reconcile and re-prove the exact head, after which the likely feature owner must accept or decline the permanent private-IMCore compatibility contract.

Maintainer decision needed

• Question: After current-main integration and exact-head runtime proof, should imsg maintain send-sticker and send.sticker as a public advanced-bridge contract?
• Rationale: The implementation can be technically validated, but only repository owners can accept the ongoing support obligation for reverse-engineered private IMCore selectors and transfer initialization behavior.
• Likely owner: steipete — They authored the maintainer rewrite and most compatibility, security, integration, and cleanup work on the branch.
• Options:
  • Adopt guarded sticker API (recommended): Maintain the single strict, capability-gated surface after final-head validation and conflict resolution.
  • Require wider macOS proof: Keep the PR open until the integrated head is demonstrated on additional supported macOS versions.
  • Decline private stickers: Close the PR if the permanent undocumented-framework compatibility burden is outside imsg's intended boundary.

Security
Cleared: No concrete security or supply-chain defect was found; the patch bounds image resources, rejects symlink traversal, privately stages and integrity-checks bytes, cleans failed transfers, and adds no third-party execution source.

Review findings

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:24

Review details

Best possible solution:

Integrate the strict, fail-closed sticker surface with current main without losing either side's bridge behavior, remove the release-owned changelog edit, and validate both standalone and attached sends on the resulting exact head before adoption.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR introduces a new capability rather than repairing established behavior. The earlier proof head is convincingly demonstrated, but equivalent validation is still needed for the current integrated head.

Is this the best way to solve the issue?

Yes, conditionally: one strictly validated and capability-gated CLI/RPC surface is narrower and more maintainable than aliases or semantic fallbacks, provided conflict resolution preserves its trust boundaries and the final head is re-proven.

Full review comments:

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:24
CHANGELOG.md is reserved for release work, so this feature PR should not add its own unreleased note. Keep the user-visible context in the PR body or commit message instead.
  Confidence: 0.99

Overall correctness: patch is correct
Overall confidence: 0.94

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 0b5dea7efdca.

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The recipient artifact and runtime/database outputs prove head 0f1924c, not current head 739ed60, which later changes sticker routing, staging, and cleanup; after resolving conflicts, rerun both modes with redacted screenshot and terminal/database output, update the PR body, and ask a maintainer for @clawsweeper re-review if the automatic review does not run.
• remove proof: sufficient: Current real behavior proof status is insufficient, not sufficient.
• remove status: 👀 ready for maintainer look: Current PR status label is status: 📣 needs proof.
• remove rating: 🦀 challenger crab: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P3: This is an optional advanced-bridge capability rather than a regression affecting existing workflows.
• merge-risk: 🚨 compatibility: The new maintained CLI/RPC contract relies on undocumented IMCore classes, selectors, and initializers that may drift by macOS version.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. Native standalone and exact-bubble sticker automation unlocks an unusually distinctive, recipient-visible advanced messaging workflow.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The recipient artifact and runtime/database outputs prove head 0f1924c, not current head 739ed60, which later changes sticker routing, staging, and cleanup; after resolving conflicts, rerun both modes with redacted screenshot and terminal/database output, update the PR body, and ask a maintainer for @clawsweeper re-review if the automatic review does not run.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The recipient artifact and runtime/database outputs prove head 0f1924c, not current head 739ed60, which later changes sticker routing, staging, and cleanup; after resolving conflicts, rerun both modes with redacted screenshot and terminal/database output, update the PR body, and ask a maintainer for @clawsweeper re-review if the automatic review does not run.

Evidence reviewed

What I checked:

• Capability remains absent from main: Current main exposes sticker metadata when reading attachments but has no sticker-send command, RPC route, bridge action, or native send handler. (Sources/imsg/CommandRouter.swift:20, 0b5dea7efdca)
• Current-head proof gap: The PR body identifies 0f1924c as the proven runtime head, but four subsequent commits alter chat alias resolution, native sticker staging, and failed-transfer cleanup before current head 739ed60. (Sources/IMsgHelper/IMsgInjected.m:5066, 739ed60dbee3)
• Current-main merge conflicts: A three-way merge calculation reports conflicts in CHANGELOG.md, the central injected helper, and its bridge registration tests. (Sources/IMsgHelper/IMsgInjected.m:430, 739ed60dbee3)
• Real behavior evidence: The inspected recipient artifact shows a rendered sticker attached over the target Messages bubble, while the PR body supplies redacted standalone/attached bridge responses and persisted database records for the earlier proof head. (0f1924c1ff15)
• Security design: The branch bounds image size, dimensions, frames, and decoded pixels; rejects symlink traversal; privately stages snapshots; rechecks content integrity; and cleans failed native transfers. (Sources/IMsgCore/StickerAsset.swift:1, 739ed60dbee3)
• Feature ownership history: Current-main history and the PR commits connect steipete to the central transfer implementation and sticker hardening, while omarshahine introduced the sticker work and owns recently merged adjacent bridge features. (Sources/IMsgHelper/IMsgInjected.m:4094, 0b5dea7efdca)

Likely related people:

• steipete: Authored most sticker portability, security, staging, alias, cleanup, and main-synchronization commits, plus recent current-main bridge hardening. (role: feature hardening and integration owner; confidence: high; commits: 5b0e907b393f, 5a5612d4d43f, 2e312b932c1b; files: Sources/IMsgHelper/IMsgInjected.m, Sources/IMsgCore/StickerAsset.swift, Sources/imsg/RPCServer+StickerHandlers.swift)
• omarshahine: Introduced and runtime-proved the sticker feature and authored adjacent rich-link and poll bridge capabilities now present on current main. (role: feature introducer and adjacent bridge owner; confidence: high; commits: e2b5c7133154, 11e7b3dcee1e, 0f1924c1ff15; files: Sources/IMsgHelper/IMsgInjected.m, Sources/imsg/Commands/StickerCommand.swift, Sources/imsg/RPCServer+StickerHandlers.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (13 earlier review cycles; latest 8 shown)

• reviewed 2026-07-09T20:16:05.210Z sha 3744d19 :: needs maintainer review before merge. :: none
• reviewed 2026-07-09T20:21:32.201Z sha 3744d19 :: needs maintainer review before merge. :: none
• reviewed 2026-07-09T20:27:28.124Z sha 3744d19 :: needs maintainer review before merge. :: none
• reviewed 2026-07-10T08:58:09.147Z sha d0d81ab :: needs real behavior proof before merge. :: [P3] Remove the release-owned changelog entry
• reviewed 2026-07-10T18:51:21.927Z sha 0f1924c :: needs real behavior proof before merge. :: none
• reviewed 2026-07-10T18:58:49.585Z sha 0f1924c :: needs real behavior proof before merge. :: none
• reviewed 2026-07-10T19:08:22.833Z sha 0f1924c :: needs maintainer review before merge. :: none
• reviewed 2026-07-10T19:15:28.461Z sha 0f1924c :: needs maintainer review before merge. :: none

[omarshahine]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[omarshahine]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[omarshahine]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[omarshahine]

@clawsweeper re-review

[steipete]

Merged via 10c91b10924ef0cbbb62c1fa4ed0ac363d794118 from exact contributor head bf3769ae235c4e5d1be6ee9c20888743b110dcf0.

Final proof:

• make test: 465 tests passed.
• make lint: 0 serious violations.
• make build: universal CLI (arm64, x86_64) and helper (arm64e, arm64, x86_64) passed.
• Autoreview: clean; no accepted/actionable findings.
• Exact-head CI: macOS and Linux read-core passed in run 29163701301.
• End-to-end standalone and message-attached sticker delivery proof is recorded in the PR body. The final follow-up changes hardened staging/cleanup, preserved direct-chat service selection, and synced current main; live delivery could not be repeated on the final head because the SIP-disabled Lobster test host was unavailable from the current network.

Thanks @omarshahine!