Summary

The Weixin adapter's session-expired fallback only recognizes errcode=-14 as a stale-session signal. In practice, iLink also returns ret=-2 errmsg="unknown error" for what appears to be the same underlying condition — typically when a cron job tries to push a message to a chat that hasn't had user activity for many hours. The adapter treats ret=-2 as a generic failure, exhausts its retries with the same stale context_token, and the push is dropped.

Impact

Cron jobs with deliver: "feishu,weixin" (or single deliver: "weixin") silently fail on the Weixin leg if the target chat hasn't been active recently. Feishu delivery works; Weixin delivery loses the message.

Secondary effect: once the first attempt raises, subsequent retries in the same send cycle surface a misleading Timeout context manager should be used inside a task error (likely aiohttp session left in a bad state after the RuntimeError), which obscures the root cause in last_delivery_error.

Reproduction

1. Configure a cron job that delivers to Weixin on a schedule (e.g. 0 8 * * *).
2. Make sure no user message is sent to the bot for several hours before the cron fires.
3. Observe cron triggers → adapter logs:

[Weixin] send chunk failed ... attempt=1/3, retrying in 1.00s: iLink sendmessage error: ret=-2 errcode=None errmsg=unknown error
[Weixin] send chunk failed ... attempt=2/3, retrying in 2.00s: iLink sendmessage error: ret=-2 errcode=None errmsg=unknown error
[Weixin] send failed ...: iLink sendmessage error: ret=-2 errcode=None errmsg=unknown error
[Weixin] send chunk failed ... attempt=1/3, retrying in 1.00s: Timeout context manager should be used inside a task
...

1. Send any message from the user to the bot (refreshing the server-side session), then trigger the same cron job — it succeeds.

Evidence

In my setup, three cron deliveries failed on 2026-04-29 at 08:06, 08:17, 09:04 (all with ret=-2). After interactive replies at 09:24 / 09:28 refreshed the session, the 09:30 cron delivery succeeded without any code change.

Root cause (adapter side)

In gateway/platforms/weixin.py, _send_chunk_with_retry (~L1502–1556):

is_session_expired = (
    ret == SESSION_EXPIRED_ERRCODE           # -14
    or errcode == SESSION_EXPIRED_ERRCODE
)

Only -14 triggers the tokenless-fallback path that the docstring explicitly designed for cron push:

On session-expired errors (errcode -14), automatically retries without context_token — iLink accepts tokenless sends as a degraded fallback, which keeps cron-initiated push messages working even when no user message has refreshed the session recently.

When iLink returns ret=-2 (which empirically correlates with the same stale-token condition), the adapter doesn't strip the token, so all 3 retries reuse the bad token and the send is dropped.

Underlying issue

The real problem is on the iLink side: ret=-2 errmsg="unknown error" is semantically ambiguous. It would be better for iLink to return a specific error code for stale sessions, rather than forcing clients to heuristically map ret=-2 to "probably session expired". Until that's clarified, the adapter could either:

Option A — pragmatic fix: extend is_session_expired to also match ret=-2 and try the tokenless fallback. Downside: if ret=-2 ever means something else, we mask that error behind a tokenless retry.

Option B — defensive fix: on any retriable error, invalidate the cached context_token after the first failed attempt and retry tokenless. Clearer semantics, but mildly more aggressive.

Option C — upstream: raise this with iLink to get a distinct error code for session expiry, so adapters don't have to guess.

Environment

• hermes-agent commit: 3ff3dfb5 (fix(telegram): accept /cmd@botname from bot menu in groups)
• OS: Ubuntu 22.04
• Delivery mode: cron native deliver: "feishu,weixin" (comma-separated multi-target — which by the way isn't documented, only shown in _resolve_delivery_targets)

Side note

website/docs/user-guide/features/cron.md doesn't document the comma-separated multi-target deliver syntax that cron/scheduler.py::_resolve_delivery_targets supports. Worth adding — right now users are told to use send_message for the second target, which on Weixin hits a separate aiohttp event-loop issue.