Stateful Message Processing

Stateful message processing

Use this playbook with the repository contracts in AGENTS.md. Preserve account isolation, legacy state, polling progress, the approval lane, abort behavior, and privacy while changing stateful code.

Define states and ownership first

Before editing, write down the observable regression and complete this model for each acquired claim, lock, file, or database handle:

Keep states with different retry behavior distinct. In particular, do not reduce claimed, inflight, committed, released, and aborted to a duplicate boolean.

Ownership starts when the resource is acquired. Put the first subsequent operation that can throw inside the complete commit/release or close/finally boundary, including logging, status updates, config lookup, payload inspection, and preprocessing.

Design collision-safe identity

• Prefer stable transport message IDs, then canonical item-level IDs.
• Use a canonical digest only when all inputs are message-specific and stable.
• Include account scope in persistent namespaces; never introduce a global fallback.
• Prove two distinct valid messages or accounts remain distinct.
• If no collision-safe message identity exists, skip dedupe instead of using a sender-only or empty-body key.
• Treat full keys and fingerprints as sensitive when they embed account, sender, message, token, body, or CDN data. Log only a non-sensitive identity kind and outcome.

Preserve progress and retry

Test outcomes rather than prescribing one implementation:

• An accepted ordinary turn must not stop polling or block a later unrelated message.
• Plugin approval work must retain its independent lane.
• An inflight replay must not hold an admission lane while its owner runs.
• Owner commit drops the replay exactly once.
• Owner release or failure leaves one delivery able to retry.
• Abort stops the in-flight long poll and does not strand owned state.

If a fix for one outcome changes scheduling, rerun the complete state matrix. Do not patch review findings one transition at a time.

Use deterministic harnesses

• Reuse createDeferred from test/helpers/deferred.ts to control ownership and ordering explicitly.
• Reuse makeTextMessage and createChannelRuntimeHarness where applicable.
• Prefer fake timers over sleeps.
• Keep tests safe under Vitest's default parallelism.
• Do not call the live backend, perform QR login, or use developer state.

Cover every applicable scenario:

Test persistence and cleanup

• Isolate both OPENCLAW_STATE_DIR and the higher-precedence OPENCLAW_OAUTH_DIR; clear the latter or point it to its own temporary directory.
• Cover write/read, account isolation, case normalization, supported legacy formats, and module or process restart.
• Close database, file, and lock handles before deleting temporary directories.
• Restore environment variables, timers, modules, and mocks.
• Do not swallow cleanup failures or turn them into success-shaped fallbacks.

Completion evidence

• The focused test fails for the original state or ordering reason without the fix.
• Every affected state transition and error exit has an observable assertion.
• Logs omit raw identifiers and full keys.
• npm run check passes after the focused suites.