Summary

What problem does this PR solve?

• Fixes Telegram outbound target resolution for provider-reserved words such as current, self, this, and me.
• A reserved word that is also a real configured Telegram group/channel target now resolves through the directory first, instead of being rejected before lookup.
• A reserved word with no directory match still fails closed before plugin/default fallback.
• Target validation and route-miss paths now keep only validated directory targets, so downstream delivery code cannot accidentally keep using the original unsafe input next to targetResolutionError or after route canonicalization misses.
• Isolated cron delivery now uses the same directory-first reserved-literal behavior before returning a reserved-target error.

Why does this matter now?

• The previous PR shape protected session-reference words, but it could break existing Telegram routes if a real configured group/channel was named or handled as one of those words.
• It also left delivery-path footguns: callers that did not check targetResolutionError first could still see the original unresolved target in resolvedTo, and isolated cron delivery could return the reserved-target error before the directory-aware resolver ran.
• The practical user impact is message-delivery correctness: real Telegram directory entries should remain routable, while missing reserved literals should not be treated as literal Telegram destinations.

What is the intended outcome?

• current resolves to a configured Telegram directory entry when that entry exists.
• telegram:current follows the same directory-first behavior as bare current.
• current fails closed with a reserved-target error when there is no matching Telegram directory entry.
• Gateway delivery planning uses the same directory-aware target result, failed target validation removes resolvedTo, and isolated cron delivery gives configured directory entries the same reserved-literal preservation before failing closed on misses.

What is intentionally out of scope?

• No Telegram schema, migration, permission, auth, or live-send behavior changes.
• No new public target syntax beyond using the already introduced plugin reserved-literal contract.
• No attempt to make bare reserved words literal Telegram usernames after a directory miss; users must use explicit handle/id syntax for literal destinations.
• No live Telegram network send in this proof environment.

What does success look like?

• Directory-backed Telegram targets named/handled as current keep working.
• Reserved words that are not directory entries remain blocked before fallback normalization.
• Delivery-plan error paths do not expose unsafe original inputs as resolved destinations.
• Focused regression tests and production-path resolver/gateway proof both pass on the current head.

What should reviewers focus on?

• The routing order in resolveMessagingTarget: directory matches are preserved before reserved-literal rejection, and reserved literals cannot continue to plugin/default fallback after a miss.
• The session-route preparation path in resolveAgentDeliveryPlanWithSessionRoute: it now uses the directory-aware resolver and clears resolvedTo on target-resolution errors.
• The compatibility boundary for Telegram users with literal reserved-word usernames: explicit handle/id syntax remains the intended path when there is no directory match.

Fix classification: root-cause compatibility and safety fix for Telegram outbound target resolution.

Root cause: reserved-literal rejection and session-route planning were split across sync outbound validation, the directory-aware resolver, gateway delivery planning, and isolated cron delivery. Core could not consistently distinguish a real Telegram directory entry named current from an unsafe session-reference literal, and route/error paths could keep raw reserved input after validation failed or route canonicalization missed.

Why this is the root cause: the resolver must first identify whether the input is a configured destination, then apply provider-reserved literal safety before plugin/default resolution; delivery planning and cron delivery must only expose destinations that have passed the directory-aware target owner.

Related PR scan: this is a repair/update to the existing PR #94107 for #91372. I did not open a competing PR; the remaining public-contract questions are disclosed below for maintainer review.

• Fix classification: Root-cause compatibility and safety fix for Telegram outbound target resolution.
• Root cause: Reserved-literal safety and delivery planning were split around the directory-aware resolver, so a configured Telegram destination named current could be rejected before lookup while directory misses or route misses could still leak raw reserved input across gateway or cron delivery paths.
• Why this is root-cause fix: resolveMessagingTarget is kept as the source of truth for configured destinations and reserved-literal misses. Directory lookup owns real destinations, reserved-literal rejection owns misses before plugin/default resolution, and gateway/cron delivery only keep validated targets after successful directory-aware resolution.
• Maintainer-ready confidence: High after sync-main, focused resolver/outbound validation, cron delivery validation, raw-channel-fetch boundary lint, and ClawSweeper commit review all passed on the current repair branch.
• What did NOT change: This PR does not change schema, migration, permission, auth, token, live-send, provider setup, public target syntax, or non-Telegram routing behavior.
• Architecture / source-of-truth check: Core target resolution remains the source-of-truth in resolveMessagingTarget; Telegram only declares its reserved literals/capabilities, and gateway/session-route delivery consumes the resolver result instead of duplicating destination ownership.
• Patch quality notes: Patch-quality warnings are test/body-risk guardrails, not runtime fallbacks: the expect.any(Function) shape assertion is confined to test fixtures, explicit return undefined keeps non-matching normalization branches clear, and fallback wording describes the old path being blocked rather than a new fallback being added.
• Related open PR scan: This updates my existing open PR fix(outbound): reject reserved Telegram targets before directory/default fallback #94107 for Gateway session resolver should reject literal target="current" strings #91372 rather than opening a competing PR; the optional plugin reservedLiterals contract remains explicitly disclosed for maintainer review.
• Risk labels considered: message-delivery, session-state, and public plugin SDK contract.
• Risk explanation: The risky boundary is Telegram target routing order for provider-reserved words that may also be real configured directory destinations.
• Why acceptable: The change allows reserved words only after a concrete directory match; missing directory entries still fail closed before fallback/session-route handling, and focused resolver, outbound, Telegram target, and boundary lint checks pass.

Linked context

Closes #91372

Related #94107

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Telegram reserved targets like current should route to a real configured Telegram group/channel named or handled as current, but still fail closed when no directory entry exists.
• Real environment tested: production OpenClaw modules with the real Telegram plugin, config-backed Telegram groups, the production target resolver, and the gateway delivery-plan/session-route path.
• Exact steps or command run after this patch:

pnpm exec tsx <production-path proof script>

• Evidence after fix:

{
  "proof": "telegram-current-directory-vs-reserved-miss",
  "registry": {
    "pluginId": "telegram",
    "channelId": "telegram",
    "source": "proof",
    "hasDirectory": true,
    "hasSessionRoute": true,
    "reservedLiterals": ["current", "self", "this", "me"]
  },
  "directoryHit": {
    "ok": true,
    "target": {
      "to": "telegram:@current",
      "kind": "group",
      "display": "current",
      "source": "directory",
      "resolutionSource": "directory"
    }
  },
  "prefixedHit": {
    "ok": true,
    "target": {
      "to": "telegram:@current",
      "kind": "group",
      "display": "current",
      "source": "directory",
      "resolutionSource": "directory"
    }
  },
  "reservedMiss": {
    "ok": false,
    "error": "Reserved target \"current\" for Telegram cannot be used as a literal destination. Provide an explicit id or handle. Hint: <chatId>"
  },
  "gatewayPlan": {
    "resolvedChannel": "telegram",
    "resolvedTo": "telegram:@current",
    "deliveryTargetMode": "explicit",
    "targetResolutionError": null
  },
  "heartbeatReservedMiss": {
    "channel": "none",
    "reason": "no-target"
  },
  "checks": {
    "directoryHitOk": true,
    "prefixedHitOk": true,
    "directoryMissFailClosed": true,
    "gatewayResolvedFromDirectory": true,
    "heartbeatReservedMissFailClosed": true
  }
}

• Observed result after fix: bare current and prefixed telegram:current both resolve through the Telegram directory when a config-backed directory entry exists; the same resolved target flows into gateway delivery planning as telegram:@current; a missing directory entry returns the reserved-target error instead of normalizing to an unintended literal destination; heartbeat delivery with missing current returns channel: "none" / reason: "no-target" before Telegram session-route canonicalization.
• What was not tested: no outbound Telegram message was sent to the public Telegram network.
• Proof limitations or environment constraints: this proof exercises the production Telegram plugin and OpenClaw resolver/delivery-plan path with config-backed directory data; it does not require or use a Telegram bot token.
• Before evidence: the production-path proof showed current being normalized as telegram:@current before directory/miss handling; after the resolver change, reserved literals stay on the directory-first path and fail closed only after a directory miss.

Tests and validation

Which commands did you run?

pnpm exec vitest run --config test/vitest/vitest.infra.config.ts src/infra/outbound/target-resolver.test.ts
pnpm exec vitest run --config test/vitest/vitest.infra.config.ts src/infra/outbound/target-resolver.test.ts src/infra/outbound/agent-delivery.test.ts src/infra/outbound/targets.test.ts src/infra/outbound/targets.shared-test.ts extensions/telegram/src/targets.test.ts
pnpm exec vitest run --config test/vitest/vitest.cron.config.ts src/cron/isolated-agent/delivery-target.test.ts
pnpm run lint:tmp:no-raw-channel-fetch

Result:

Validation target-resolver-reserved-exact-only: pass
Test Files  1 passed (1)
Tests       13 passed (13)

Validation focused-outbound-cron-reserved-exact-only: pass
Test Files  4 passed (4)
Tests       113 passed (113)

Validation cron-delivery-reserved-exact-only: pass
Test Files  1 passed (1)
Tests       54 passed (54)

Validation no-raw-channel-fetch-reserved-exact-only: pass
$ node scripts/check-no-raw-channel-fetch.mjs

What regression coverage was added or updated?

• target-resolver.test.ts now covers directory-first resolution for both current and telegram:current, fail-closed behavior after a directory miss, and exact-only reserved-literal directory preservation so me does not match a substring-only directory entry such as memes.
• agent-delivery.test.ts now covers clearing resolvedTo when route preparation/target validation fails, preserving the stored target error, and preserving the directory-resolved target when session-route canonicalization itself cannot produce a route.
• delivery-target.test.ts now covers isolated cron delivery resolving a reserved explicit Telegram target through a configured directory entry before returning any reserved-target error.
• targets.test.ts now covers heartbeat delivery preserving directory hits for reserved literals and failing closed when a heartbeat reserved literal misses the directory.
• The shared direct outbound target tests stayed green, confirming direct fallback still rejects bare Telegram reserved literals instead of treating them as normal literal targets.

What failed before this fix, if known?

• current returned a reserved-target error before the resolver checked configured Telegram directory entries.
• A session-route target validation error could leave the original unsafe resolvedTo value visible next to targetResolutionError.
• Isolated cron delivery could return the sync reserved-target error before the directory-capable resolver preserved a configured Telegram directory entry named current.
• Reserved-literal directory preservation used the normal fuzzy directory match, so a reserved word like me could match a substring-only entry such as memes before the fail-closed reserved check ran.

If no test was added, why not?

• Tests were added/updated for the directory-first behavior, directory-miss fail-closed behavior, and delivery-plan error path.

Test guardrail rationale:

• The resolver tests protect both sides of the compatibility boundary: existing real Telegram directory entries keep routing, while missing reserved literals still stop before fallback.
• The delivery tests protect the safety boundary: failed target validation and route misses cannot leave a destination-shaped raw reserved literal for downstream code to reuse.
• The cron delivery test protects the scheduled/isolated delivery surface so it follows the same directory-first behavior as gateway delivery.
• The shared target tests protect direct outbound behavior so this repair does not accidentally re-enable reserved words as literal plugin/default destinations.

Risk checklist

Did user-visible behavior change? (Yes/No)

Yes. A real Telegram directory entry named/handled as current, self, this, or me can now be reached instead of being rejected before lookup; missing entries still fail closed.

Did config, environment, or migration behavior change? (Yes/No)

No.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

No new network/auth/tool execution behavior. The safety posture is preserved for directory misses and strengthened on validation errors by clearing resolvedTo.

What is the highest-risk area?

Telegram target routing order for provider-reserved literals, especially compatibility between real directory entries and fail-closed reserved words.

How is that risk mitigated?

The resolver and delivery paths only allow reserved literals after an exact concrete directory match on id/name/handle after prefix stripping. If the directory does not contain an exact matching Telegram group/channel, the reserved literal still fails closed before plugin/default resolution. Gateway and cron delivery paths no longer expose the original unsafe target after validation failure or route canonicalization miss.

Scope boundary and patch quality notes:

• The word "fallback" in this PR refers to the existing plugin/default target-resolution stages, not to a silent mitigation path.
• The larger diff size comes from the existing PR's SDK contract/tests plus this repair's resolver/delivery regression coverage; this update stays within the existing PR scope and does not add a second feature.
• The public contract risk is the existing optional plugin reserved-literal field. This update narrows the behavior by preserving directory compatibility before applying that reserved-literal guard.

Current review state

What is the next action?

Ready for maintainer review after the PR branch/body update and fresh checks.

What is still waiting on author, maintainer, CI, or external proof?

No known author-side code or test follow-up remains. The only proof limitation is that the production-path Telegram proof does not send a live Telegram network message. Maintainers still need to accept the existing SDK contract and compatibility choice for reserved Telegram literals.

Which bot or reviewer comments were addressed?

• RF-001 triage: mock-only-proof: addressed with production-path proof using the real Telegram plugin, production resolver, and gateway delivery-plan path; live Telegram network send remains disclosed as not tested.
• RF-002 real gateway/message-action or Telegram proof for target: "current": addressed with current-head production-path proof showing directory hit for current and a fail-closed reserved error on directory miss.
• RF-003 real behavior proof request: addressed by replacing mock-only proof with production module proof and copied runtime output in this PR body.
• RF-004 new optional SDK field requires maintainer acceptance: disclosed as a maintainer contract decision; this repair does not expand that API further.
• RF-005 compatibility risk for bare Telegram reserved targets: addressed by preserving real directory matches before fail-closed rejection, and disclosed that literal non-directory destinations still need explicit handle/id syntax.
• RF-006 proof still helper/mock based: addressed with production Telegram plugin + resolver + gateway delivery-plan proof after the patch.
• RF-007 maintainer review needed for SDK field and compatibility choice: disclosed; author-side code/test/proof updates are complete, maintainer contract review remains.
• RF-008 explicit reserved targets reaching Telegram session routing: addressed by resolving reserved explicit targets through directory-capable target resolution before session-route planning, preserving a target-resolution error after directory miss instead of handing raw current to Telegram route parsing.
• RF-009 heartbeat reserved-target misses: addressed by making heartbeat session-route refinement stop delivery when directory-capable target resolution returns the reserved-target error after a directory miss.
• RF-010 src/infra/outbound/targets.test.ts: addressed with focused heartbeat coverage for both directory-hit routing and directory-miss fail-closed behavior.
• RF-011 resolver/agent-delivery/Telegram target tests: addressed by the current-head focused outbound and Telegram suite covering resolver, gateway delivery, direct outbound target fallback, and Telegram target behavior.
• RF-012 after-fix heartbeat proof: addressed with production-path Telegram proof showing heartbeatReservedMiss returns channel: "none" and reason: "no-target" for missing current.
• RF-013 latest proof/status signal: addressed by updating this PR body with current-head validation and the latest delivery-path, cron, and exact-match review fixes; proof remains proof: sufficient, while live Telegram Desktop proof is disclosed as optional maintainer-requested transport evidence.
• Latest delivery-path review finding: addressed by preserving a directory-resolved reserved target when session-route canonicalization misses, instead of returning raw current.
• Latest isolated cron review finding: addressed by letting cron delivery run directory-capable target resolution for reserved literals before returning a reserved-target error.
• Latest exact-match review finding: addressed by requiring reserved-literal directory preservation to match exact id/name/handle after prefix stripping, with regression coverage for me not matching memes.