Preserve legacy watch resume semantics for GUID-linked URL previews

[omarshahine]

Problem

PR #181 reproduced a Messages.app URL-preview variant where one composition creates a text row and a GUID-linked preview row, but imsg watch emits two logical events. The repaired head, 5d86702043da, passed maintainer review and CI. The PR closed without merging because its watcher hardening changed the documented resume contract.

Peter summarized the remaining work in his closing comment:

Closing after binary maintainer review. The bug is real and the repaired head is CI-clean, but it changes the documented watch resume contract from id to a new physical cursor. Exact-head delayed-preview reconnect proof for both legacy id and cursor is also unavailable because the signed CLI is blocked in this host's Contacts/TCC preflight.

Landing therefore requires an owner decision on legacy id compatibility plus exact-head resume proof. We do not leave contributor PRs in a change-request limbo; the decision brief and repair SHA are preserved for a future focused implementation.

Existing consumers persist a watch event's id and pass it back through --since-rowid. A folded URL-preview event can span the text row and a later physical preview row, so resuming from the logical text-row id must not replay the preview or create a second delivery.

Proposed plan

1. Start from the reviewed repair at 5d86702043da and retain its structurally constrained GUID-linked URL-preview coalescing.
2. Preserve id as a backward-compatible --since-rowid input. Resolve a folded event's physical completion boundary inside the watcher so legacy clients neither replay the preview row nor skip the next logical message.
3. Keep cursor additive and preferred for new clients only if both resume paths can share clear at-least-once semantics. Otherwise defer the public cursor field and keep the completion boundary internal.
4. Add reconnect regressions for legacy id and physical cursor, including delayed preview arrival, interruption between the two physical rows, an unlinked preview negative control, and the next-message boundary.
5. Capture redacted exact-head proof on a macOS host with Messages and Contacts permissions: one linked-preview composition, one watch event, no delayed duplicate, then reconnect once with id and once with cursor without replay or loss.
6. Merge the focused fix without a functional-PR changelog edit, then publish it in the next imsg release.

Acceptance criteria

• GUID-linked text and URL-preview rows produce one logical event with the URL retained.
• Resuming from the emitted id produces no replay, duplicate, or skipped next message.
• Resuming from cursor, if shipped, has the same observable delivery boundary.
• History, search, stats, unread counts, and watch output retain the regression coverage from PR fix: coalesce GUID-linked URL previews #181.
• macOS and Linux CI pass on the exact merge head.
• Redacted exact-head live output covers delayed preview delivery and both supported reconnect tokens.

Downstream dependency

openclaw/openclaw#91243 remains open pending an imsg release that owns URL-preview coalescing. Draft openclaw/openclaw#108436 removes OpenClaw's fallback and currently names imsg 0.13.1, but that release does not contain PR #181. The downstream PR must remain draft and target the eventual release containing this fix.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 18, 2026, 7:31 PM ET / 23:31 UTC.

Summary
This remains necessary: the prior coalescing repair was closed unmerged because it changed the documented legacy resume boundary, and the remaining work needs an explicit compatibility decision plus exact-head reconnect proof.

Reproducibility: yes. a high-confidence macOS reproduction path is described: send a text-plus-URL composition that creates GUID-linked text and preview rows, then reconnect around delayed preview delivery. This review did not execute that permission-gated live path on current main.

Root-cause cluster
Relationship: canonical
Canonical: #184
Summary: This issue is the canonical remaining compatibility decision after the earlier coalescing repair closed unmerged.

Members:

• partial_overlap: fix: coalesce GUID-linked URL previews #181 - The closed branch contains the coalescing approach, but it did not resolve or obtain approval for the legacy id resume contract required here.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
An owner must settle the legacy resume contract before a focused repair can safely implement and prove it.

Maintainer decision needed

• Question: Should folded watch events preserve legacy --since-rowid semantics through an internal completion boundary and defer a public cursor unless both tokens have equivalent proven reconnect behavior?
• Rationale: The prior implementation was intentionally closed because this is a public compatibility-contract choice, not a mechanical coalescing fix alone.
• Likely owner: Peter — The prior closure identifies this person as the reviewer who surfaced the unresolved resume-contract decision.
• Options:
  • Preserve legacy id; defer public cursor (recommended): Keep the physical completion boundary internal so existing consumers resume safely, and introduce no new public token until its semantics are independently justified.
  • Ship an additive cursor contract: Expose cursor only while retaining legacy id mapping and adding explicit documentation plus reconnect tests for both tokens.

Review details

Best possible solution:

Implement GUID-linked preview coalescing with an internal physical completion boundary that preserves legacy id reconnect behavior; expose cursor only if maintainers approve a documented additive contract backed by delayed-preview proof.

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

Yes, a high-confidence macOS reproduction path is described: send a text-plus-URL composition that creates GUID-linked text and preview rows, then reconnect around delayed preview delivery. This review did not execute that permission-gated live path on current main.

Is this the best way to solve the issue?

Unclear until maintainers choose the public resume contract. Preserving legacy id through an internal completion boundary is the narrowest compatible path; a public cursor should remain optional and require equivalent proof.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Changing folded-event resume behavior without mapping legacy id to the physical completion boundary can replay a delayed preview or skip the next logical message.
• Shipping a public cursor alongside legacy id without clear, tested delivery semantics would create two conflicting resume contracts for consumers.

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

Label changes

Label changes:

• add P1: A single incoming Messages composition can be delivered as two watch events and trigger duplicate downstream work for existing consumers.
• add impact:message-loss: The report concerns duplicate logical message delivery and reconnect boundaries that can replay or skip messages.
• add issue-rating: 🦪 silver shellfish: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P1: A single incoming Messages composition can be delivered as two watch events and trigger duplicate downstream work for existing consumers.
• impact:message-loss: The report concerns duplicate logical message delivery and reconnect boundaries that can replay or skip messages.

Evidence reviewed

What I checked:

• Unmerged repair establishes the remaining gap: The supplied discussion identifies a reviewed repair at 5d86702043daae2ccf65ab8ce9a79039eab45313, but its pull request was closed without merge because changing legacy id resume semantics to a physical cursor was not accepted. (5d86702043da)
• Concrete affected behavior: The report documents a Messages composition with a text row and GUID-linked URL-preview row that yields two logical watch events; consumers persist the emitted id, so folding must preserve a safe reconnect boundary.
• Related repair is not a safe superseding implementation: fix: coalesce GUID-linked URL previews #181 is closed and unmerged, so it is useful implementation evidence but cannot close this issue as already fixed. (5d86702043da)
• Downstream remains blocked: The issue body identifies Remove client-side iMessage split-send coalescing once imsg coalesces upstream openclaw#91243 as still awaiting an imsg release that owns URL-preview coalescing; the cited downstream removal pull request remains draft.

Likely related people:

• Peter: The supplied closing rationale for the prior repair records Peter as the person who identified the unresolved legacy id contract and required reconnect proof. (role: prior repair reviewer and likely compatibility decision owner; confidence: medium; commits: 5d86702043da)

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.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this issue: Preserve legacy watch resume semantics for GUID-linked URL previews This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.