feat(telegram): add monitor service wrapper

[artemgetmann]

Review Fast Path

• User path fixed: durable Telegram-as-me waits now have an opt-in supervised monitor-poll --watch service path after foreground polling is proven.
• Proof: 17-file targeted suite, tsgo, format:check, git diff --check, build, built CLI smoke, and codex review --base origin/main all passed.
• Shared-state footgun removed: service identity is profile-scoped and does not reuse the gateway LaunchAgent/systemd unit; status JSON redacts OPENCLAW_GATEWAY_TOKEN.
• Still hurts: no Windows service wrapper and no live Telegram traffic proof in this slice.

Summary

• Problem: foreground telegram-user monitor-poll --watch worked, but durable waits had no repo-owned supervised service wrapper.
• Why it matters: event-driven Telegram-as-me waits need a resident local watcher path without mutating the shared/default gateway runtime.
• What changed: added openclaw telegram-user monitor-service status|install|restart|stop|uninstall for macOS launchd and Linux systemd.
• What did NOT change (scope boundary): no new monitor creation semantics, no gateway ownership change, no cron/cursor ownership rewrite, no Windows service install, no live sends.

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

• Related feat(telegram): emit monitor events for user listener #1100
• Related feat(telegram): add durable monitor listener cursors #1101
• Related feat(telegram): add monitor poll watch mode #1103

User-visible / Behavior Changes

Adds:

• openclaw telegram-user monitor-service status
• openclaw telegram-user monitor-service install
• openclaw telegram-user monitor-service restart
• openclaw telegram-user monitor-service stop
• openclaw telegram-user monitor-service uninstall

The service runs the existing telegram-user monitor-poll --watch path. It is opt-in and profile-scoped.

Security Impact (required)

• New permissions/capabilities? (Yes) Installs a per-user launchd/systemd service only when explicitly requested.
• Secrets/tokens handling changed? (Yes) OPENCLAW_GATEWAY_TOKEN can be persisted in the service environment instead of command args; status JSON redacts it.
• New/changed network calls? (No) Uses the existing local hook dispatch path.
• Command/tool execution surface changed? (Yes) Adds lifecycle CLI commands for the Telegram monitor service.
• Data access scope changed? (No) Reuses existing Telegram monitor-poll stores and Telegram read path.
• If any Yes, explain risk + mitigation: hook URLs are validated as local and target /telegram-user-monitor-event; service identities are profile-scoped; no valid service install was run in this lane.

Repro + Verification

Environment

• OS: macOS local worktree lane
• Runtime/container: Node/pnpm repo build
• Model/provider: N/A
• Integration/channel (if any): Telegram-as-me monitor poller, no live Telegram traffic
• Relevant config (redacted): local config produced pre-existing plugins.entries.voice-call warnings during CLI smoke

Steps

1. Run focused monitor/gateway/goal/Telegram tests.
2. Run typecheck, format check, diff check, and build.
3. Run built CLI smoke for help/status/profile hook defaults and invalid install inputs.
4. Run codex review --base origin/main.

Expected

• Service wrapper is available and profile-scoped.
• Invalid local service inputs fail before writing a service.
• Existing monitor event ingress, goal binding, Gmail routing, and Telegram poller tests stay green.

Actual

• All validation passed.

Evidence

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

Human Verification (required)

• Verified scenarios:
  • npx -y pnpm@10.23.0 vitest run src/cli/telegram-user-monitor-service.test.ts src/daemon/telegram-monitor-service.test.ts src/daemon/service-env.test.ts src/daemon/launchd.test.ts src/daemon/systemd.test.ts src/cli/telegram-user-cli.test.ts src/cli/node-cli/register.test.ts src/cli/daemon-cli/lifecycle-core.test.ts src/commands/telegram-user.test.ts src/commands/telegram-monitor-service-install-helpers.test.ts src/telegram-user/monitor-listener.test.ts src/telegram-user/monitor-event.test.ts src/monitor/event-router.test.ts src/gateway/server.hooks.test.ts src/gateway/server-methods/monitor.test.ts src/agents/tools/monitor-tool.test.ts src/agents/tools/goal-tools.test.ts src/config/sessions/goals.test.ts
  • npx -y pnpm@10.23.0 tsgo
  • npx -y pnpm@10.23.0 format:check
  • git diff --check
  • npx -y pnpm@10.23.0 build
  • Built CLI smoke for monitor-service --help, parent help, default/profile status JSON, invalid poll interval, invalid remote hook URL, and token redaction.
  • codex review --base origin/main passed after fixing a status/config-port drift finding.
• Edge cases checked: profile-scoped launchd/systemd names, config-derived gateway port, local-hook validation, no start command, token not in command args/status JSON, non-gateway launchd restart skips gateway stale-pid cleanup.
• What you did not verify: no valid service install/start/restart was executed; no live Telegram reply was sent or observed; Windows service install remains out of scope.

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? (Yes) Service install may persist OPENCLAW_GATEWAY_TOKEN; OPENCLAW_NO_RESPAWN=1 is set for the monitor service.
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: run openclaw telegram-user monitor-service stop or openclaw telegram-user monitor-service uninstall; revert this commit if the CLI surface itself is bad.
• Files/config to restore: launchd plist or systemd user unit for the profile-scoped Telegram monitor service.
• Known bad symptoms reviewers should watch for: service points at wrong gateway port, token appears in status JSON, profile service collides with default gateway service.

Risks and Mitigations

• Risk: managed service could target the wrong hook URL.
  • Mitigation: config-aware default hook tests plus local-hook validation before install.
• Risk: service token leaks through status or process arguments.
  • Mitigation: token is stored in environment, omitted from program args, and status JSON uses filterDaemonEnv.

AI Assistance

• AI-assisted
• Testing degree: targeted