feat(telegram-e2e): add repo-local telegram user CLI

[artemgetmann]

Summary

• Problem: Telegram user-side E2E still had multiple public entrypoints, including brittle repo-specific shell/Python helpers.
• Why it matters: failed Telegram smoke checks were too easy to misread because the harness path diverged from the real operator path.
• What changed: added the repo-local telegram-user CLI, routed legacy wrappers through it, and kept Python as an internal Telethon transport instead of a first-class UX.
• What did NOT change (scope boundary): this does not replace Telegram runtime bot handling; it only tightens the user-account E2E tooling flow.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 #
• Related feat(telegram-e2e): add repo-local telegram user CLI #108

User-visible / Behavior Changes

• New repo-local Telegram user CLI: openclaw telegram-user precheck|send|read|wait
• scripts/telegram-e2e/userbot-send-live.sh is now a compatibility shim over the CLI instead of a separate Python path
• scripts/telegram-e2e/run-consumer-first-reply-smoke.sh and run-model-inheritance-e2e.sh use the CLI surface
• Docs now describe Python as an internal backend, not the recommended operator path

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (Yes)
• New/changed network calls? (No)
• Command/tool execution surface changed? (Yes)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:
  • Token handling now prefers reusing this worktree's existing .env.local claim during scripts/telegram-live-runtime.sh ensure, which avoids false pool-exhaustion failures. The script still reports token_claim_count and fails loudly when the same token appears claimed by more than one worktree.
  • The command surface is narrower because old wrappers now funnel into one CLI path instead of maintaining separate shell/Python behavior.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Node 22 + Telethon backend
• Model/provider: n/a
• Integration/channel (if any): Telegram
• Relevant config (redacted): worktree-local .env.local, scripts/telegram-e2e/.env.local, existing user session file

Steps

1. bash scripts/telegram-live-runtime.sh ensure
2. pnpm test -- src/telegram-user/match.test.ts src/commands/telegram-user.test.ts src/cli/program/register.subclis.test.ts
3. scripts/telegram-e2e/userbot-send-live.sh --chat @jarvis_tester_1_bot --text "main branch wrapper smoke $(date +%s)"
4. pnpm openclaw:local telegram-user wait --chat @jarvis_tester_1_bot --after-id 41087 --sender-id 8475294213 --timeout-ms 60000 --json

Expected

• ensure keeps the current worktree token claim instead of failing when the pool is full
• wrapper send goes through the repo-local CLI
• bot reply is matched with raw Telegram metadata

Actual

• ensure reported runtime_ownership=ok, runtime_health=ok, token_claim_count=1
• wrapper send succeeded with message_id=41087
• CLI wait matched bot reply message_id=41088 with matched_by=no_thread_filter

Evidence

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

Human Verification (required)

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

• Verified scenarios:
  • telegram-user precheck/send/read/wait flow works against @jarvis_tester_1_bot
  • userbot-send-live.sh now routes through the repo-local CLI and still sends successfully
  • scripts/telegram-live-runtime.sh ensure on this branch reuses the current worktree token claim without duplicating claims
• Edge cases checked:
  • duplicate token claims still fail loudly via token_claim_count > 1
  • CLI JSON extraction still works when config warnings precede JSON output
• What you did not verify:
  • full pnpm build && pnpm check && pnpm test
  • full legacy interactive Python auth bootstrap flow

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.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert commits 6ed0152f7d and afe65fa2f1
• Files/config to restore: scripts/telegram-e2e/userbot-send-live.sh, scripts/telegram-e2e/run-model-inheritance-e2e.sh, scripts/telegram-e2e/userbot-common.sh, Telegram E2E docs
• Known bad symptoms reviewers should watch for:
  • wrapper scripts no longer send messages
  • run-model-inheritance-e2e.sh fails before polling because CLI precheck/send/wait wiring is broken

Risks and Mitigations

• Risk: older local workflows may have been shelling directly into removed helper internals.
  • Mitigation: keep the wrapper filename and arg shape stable while routing into the CLI.
• Risk: config warnings before JSON can break brittle shell parsing.
  • Mitigation: affected scripts explicitly extract the JSON payload from mixed stdout.

AI Assistance

• AI-assisted PR
• Testing: fully tested for the targeted Telegram user CLI flow and wrapper path; not fully repo-wide tested