Summary

• Problem: the iMessage monitor subscribed live-only after Gateway restart, so messages written to chat.db while OpenClaw was down were not replayed.
• Why it matters: operators could miss inbound iMessage/SMS requests after sleep, restarts, or offline windows.
• What changed: OpenClaw now stores the last successfully processed imsg rowid per iMessage account and passes a bounded since_rowid + start cursor to watch.subscribe on restart.
• What did NOT change (scope boundary): first-run subscriptions remain live-only; access control, echo-dedupe, mention gating, and reply dispatch still use the existing inbound pipeline.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes iMessage: catchup missed inbound messages received while gateway was down #78649
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: iMessage restart catchup now resumes imsg rpc watch.subscribe from a persisted, exclusive rowid cursor instead of launching live-only after every Gateway restart.
• Real environment tested: local OpenClaw repo checkout on Linux, running the actual changed cursor builder module with Node/tsx; dependency contract verified against current imsg JSON-RPC docs for watch.subscribe params (since_rowid, start, attachments).
• Exact steps or command run after this patch: node --import tsx - <<'EOF' ... buildIMessageWatchSubscribeParams(...) ... EOF
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): copied console output from the real changed OpenClaw module:

$ node --import tsx - <<'EOF'
import { buildIMessageWatchSubscribeParams } from './extensions/imessage/src/monitor/catchup-cursor.ts';
const firstRun = buildIMessageWatchSubscribeParams({ attachments: false, cursor: null });
const restart = buildIMessageWatchSubscribeParams({
  attachments: false,
  cursor: { lastSeenRowid: 9000, updatedAt: '2026-05-07T00:00:00.000Z' },
  catchup: { maxAgeMinutes: 30 },
  now: new Date('2026-05-07T12:00:00.000Z'),
});
console.log(JSON.stringify({ firstRun, restart }, null, 2));
EOF
{
  "firstRun": {
    "attachments": false
  },
  "restart": {
    "attachments": false,
    "since_rowid": 9000,
    "start": "2026-05-07T11:30:00.000Z"
  }
}

• Observed result after fix: first-run watch params stay live-only, while restart params include since_rowid: 9000 plus a 30-minute bounded ISO start, which is the documented imsg rpc replay cursor contract.
• What was not tested: live macOS Messages.app replay against a real chat.db was not run from this Linux workspace.
• Before evidence (optional but encouraged): existing code always called watch.subscribe with only attachments, so imsg started at the newest message and skipped rows written before launch.

Root Cause (if applicable)

• Root cause: OpenClaw treated imsg watch.subscribe as a live-only stream and did not persist or pass the last processed message rowid across monitor restarts.
• Missing detection / guardrail: no monitor test asserted restart subscribe params when a previous rowid exists.
• Contributing context (if known): imsg starts at newest message when since_rowid is omitted, by design.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/imessage/src/monitor/catchup-cursor.test.ts, extensions/imessage/src/monitor.watch-subscribe-retry.test.ts, extensions/imessage/src/config-schema.test.ts
• Scenario the test should lock in: persist the largest processed rowid per account; build bounded resume params; pass the persisted cursor to watch.subscribe; validate catchup.maxAgeMinutes schema bounds.
• Why this is the smallest reliable guardrail: it proves OpenClaw uses the documented imsg RPC cursor contract without needing a real macOS Messages database in unit CI.
• Existing test that already covers this (if any): none.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• iMessage accounts now create $OPENCLAW_STATE_DIR/imessage/catchup-cursors.json after processing live messages.
• After a cursor exists, Gateway restart replays missed iMessage rows through the existing pipeline for a bounded window.
• New optional config: channels.imessage.catchup.enabled and channels.imessage.catchup.maxAgeMinutes (default enabled, 24 hours).

Diagram (if applicable)

Before:
Gateway restart -> watch.subscribe({ attachments }) -> imsg starts at newest row -> missed offline rows stay missed

After:
processed row -> persist rowid -> Gateway restart -> watch.subscribe({ since_rowid, start, attachments }) -> missed bounded rows replay

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A.

Repro + Verification

Environment

• OS: Linux validation workspace
• Runtime/container: Node via repo pnpm scripts
• Model/provider: N/A
• Integration/channel (if any): iMessage / imsg rpc
• Relevant config (redacted): channels.imessage.catchup.maxAgeMinutes=30 in unit coverage

Steps

1. Seed an iMessage catchup cursor for account main with rowid 9000.
2. Start the iMessage monitor with mocked imsg rpc client.
3. Inspect the watch.subscribe params.

Expected

• Subscribe includes since_rowid: 9000, a bounded ISO start, and the existing attachments flag.

Actual

• Matches expected in extensions/imessage/src/monitor.watch-subscribe-retry.test.ts and the real module console output above.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Validation run:

pnpm test extensions/imessage/src/monitor/catchup-cursor.test.ts extensions/imessage/src/monitor.watch-subscribe-retry.test.ts extensions/imessage/src/config-schema.test.ts
# Test Files 3 passed (3); Tests 19 passed (19)

pnpm config:docs:check
# OK docs/.generated/config-baseline.sha256

pnpm config:channels:check
# passed

pnpm exec oxfmt --check --threads=1 CHANGELOG.md docs/channels/imessage.md extensions/imessage/src/accounts.ts extensions/imessage/src/config-schema.test.ts extensions/imessage/src/monitor.watch-subscribe-retry.test.ts extensions/imessage/src/monitor/catchup-cursor.ts extensions/imessage/src/monitor/catchup-cursor.test.ts extensions/imessage/src/monitor/monitor-provider.ts src/config/types.imessage.ts src/config/zod-schema.providers-core.ts src/config/bundled-channel-config-metadata.generated.ts
# All matched files use the correct format.

git diff --check
# passed

pnpm lint:extensions -- extensions/imessage/src/monitor/catchup-cursor.ts extensions/imessage/src/monitor/monitor-provider.ts extensions/imessage/src/accounts.ts extensions/imessage/src/monitor/catchup-cursor.test.ts extensions/imessage/src/monitor.watch-subscribe-retry.test.ts extensions/imessage/src/config-schema.test.ts
# Found 0 warnings and 0 errors.

pnpm tsgo:core && pnpm tsgo:extensions && pnpm tsgo:extensions:test
# passed

Additional note:

pnpm tsgo:core:test
# still fails on pre-existing OpenAI fixture type errors in:
# src/agents/openai-transport-stream.test.ts
# src/agents/pi-embedded-runner/openai-stream-wrappers.test.ts

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: first-run live-only params; persisted cursor resume params; per-account cursor max rowid; catchup config validation; generated config metadata/docs baseline.
• Edge cases checked: disabled/missing cursor does not replay; invalid maxAgeMinutes: 0 is rejected; lower rowid does not move the cursor backward.
• What you did not verify: live macOS Messages.app replay with a real chat.db from this Linux workspace.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes)
• Migration needed? (No)
• If yes, exact upgrade steps: no required migration; optional tuning via channels.imessage.catchup.enabled / maxAgeMinutes.

Risks and Mitigations

• Risk: replay after restart could process stale old rows if a gateway was down for a long period.
  • Mitigation: replay is bounded by catchup.maxAgeMinutes and defaults to 24 hours; first run stays live-only until OpenClaw has processed and persisted a cursor.