watchdog-discord-route/SKILL.md

---
name: watchdog-discord-route
description: Install, reset, verify, or operate the OpenClaw watchdog-b owner-facing Discord route. Use when setting up or repairing watchdog-b -> owner-report -> Discord delivery, cleaning old watchdog test residue, enabling the systemd --user timer, running end-to-end verification, or adjusting the Discord-facing notification path/target/template.
---

# Watchdog Discord Route

Use this skill when the task is about the **watchdog-b owner-facing notification path to Discord**.

This skill covers four recurring jobs:

1. **Reset / clean** old watchdog test residue without deleting live audit assets.
2. **Verify** the end-to-end path from watchdog-b to Discord.
3. **Install / enable** the live watchdog schedule.
4. **Repair / adjust** the Discord-facing route, target, or message format.

## What the current canonical path is

Preferred owner-facing path:

`watchdog-b -> notify_watchdog_b.py -> owner_report_producer.py -> owner_report_driver.py -> OpenClaw Discord send -> sent archive`

For watchdog-b single-shot owner-facing delivery, prefer the **direct Discord driver path** over relying on the generic wrapper watchdog destination semantics.

Current default Discord target in this workspace is a validated example, but the portable skill should treat target as host-local configuration.

For portable installs, set:

- `WATCHDOG_B_OWNER_REPORT_TARGET=channel:REPLACE_ME`

## Bundled skill resources

This skill now carries a portable bundle under its own directory.
Prefer these bundled files first when adapting or reusing on another host:

### scripts/
- `scripts/check_openclaw_state.sh`
- `scripts/notify_watchdog_b.py`
- `scripts/run_watchdog_b.sh`
- `scripts/verify_watchdog_b_e2e.sh`
- `scripts/owner_report_consumer.py`
- `scripts/owner_report_producer.py`
- `scripts/owner_report_driver.py`
- `scripts/install_watchdog_bundle.sh`
- `scripts/bootstrap_watchdog_bundle.sh`
- `scripts/openclaw-watchdog-b.service`
- `scripts/openclaw-watchdog-b.timer`
- `scripts/openclaw_runtime_probe.py`
- `scripts/watchdog-b.env.example`

### references/
- `references/watchdog-b-readme.md`
- `references/owner-reporting-system.md`
- `references/owner-report-operator-manual.md`

If working in this workspace, you may still inspect the live workspace files too, but the bundled skill files are the portable baseline.

## When resetting / cleaning

Before touching anything, inventory:

- `state/watchdog-b/`
- `state/watchdog-b-test-*`
- `state/watchdog-b-verify-e2e/`
- `state/archive/`
- `~/.clawteam/owner-reports/pending/`
- `~/.clawteam/owner-reports/sent/`
- user crontab entries related to owner-report/watchdog
- `~/.config/systemd/user/openclaw-watchdog-b.*`

Rules:

- **Do not delete** `~/.clawteam/owner-reports/sent/` history unless explicitly asked.
- **Do not delete** live `state/watchdog-b/notify-state.json` unless the user explicitly wants a hard reset.
- Prefer **archiving** old `state/watchdog-b-test-*` into `state/archive/<timestamp>/`.
- Distinguish clearly between:
  - live state
  - old test residue
  - repo templates
  - live installed units

## When doing end-to-end verification

Default verification script:

- bundled: `scripts/verify_watchdog_b_e2e.sh`
- workspace live path: `scripts/watchdog-b/verify_watchdog_b_e2e.sh`

This should be treated as the **single-source verification path** unless there is a specific reason to bypass it.

Minimum success evidence:

- Discord send success with a new message id
- pending report created then moved to sent
- sent file exists under `~/.clawteam/owner-reports/sent/`
- verification artifacts under `state/watchdog-b-verify-e2e/<run-id>/`

Useful artifacts:

- `verify.log`
- `run-output.txt`
- `queue-before.txt`
- `queue-after.txt`
- `sent-head.txt`
- `state/notify-state.json`

Do not claim human-visible success unless either:

- the user confirms visibility, or
- you can read back the message from the exact Discord channel and match the message id/content.

## When installing the live schedule

Preferred scheduler: **systemd --user timer**.

Before claiming a host is ready, prefer to run the bundled bootstrap checker first:

- `scripts/bootstrap_watchdog_bundle.sh`

When installing or refreshing the portable bundle into live paths, prefer the bundled installer:

- `scripts/install_watchdog_bundle.sh --install-env-example`

Use bootstrap when you need a quick host-readiness answer without changing the host.
Use install when you need to copy the bundled scripts/service/timer/env example into the live workspace and user config paths.

Use it when:

- `systemd --user` is available
- linger/user services are supported
- you want journal/status/list-timers visibility

Live install paths:

- `~/.config/systemd/user/openclaw-watchdog-b.service`
- `~/.config/systemd/user/openclaw-watchdog-b.timer`
- `~/.config/openclaw/watchdog-b.env`

Portable install sources carried by this skill:

- `scripts/check_openclaw_state.sh`
- `scripts/run_watchdog_b.sh`
- `scripts/notify_watchdog_b.py`
- `scripts/owner_report_consumer.py`
- `scripts/owner_report_producer.py`
- `scripts/owner_report_driver.py`
- `scripts/install_watchdog_bundle.sh`
- `scripts/bootstrap_watchdog_bundle.sh`
- `scripts/openclaw-watchdog-b.service`
- `scripts/openclaw-watchdog-b.timer`
- `scripts/openclaw_runtime_probe.py`
- `scripts/watchdog-b.env.example`

Expected environment for live route:

- `WATCHDOG_B_NOTIFY_DRY_RUN=0`
- `WATCHDOG_B_RUNNING_REPORT_MODE=enqueue-and-drain`
- `WATCHDOG_B_OWNER_DELIVERY_MODE=direct-discord`
- `WATCHDOG_B_OWNER_REPORT_CHANNEL=discord`
- `WATCHDOG_B_OWNER_REPORT_TARGET=channel:REPLACE_ME`
- optional: `WATCHDOG_B_MAIN_AGENT_ID=<valid-agent-id-on-that-host>`

Minimum installation verification:

- `systemctl --user daemon-reload`
- `systemctl --user enable --now openclaw-watchdog-b.timer`
- `systemctl --user start openclaw-watchdog-b.service`
- `systemctl --user status openclaw-watchdog-b.timer --no-pager`
- `systemctl --user status openclaw-watchdog-b.service --no-pager`
- `systemctl --user list-timers --all | rg openclaw-watchdog-b`
- `journalctl --user -u openclaw-watchdog-b.service -n 50 --no-pager`

## When repairing Discord delivery

Check these in order:

1. Is the target channel correct?
   - Validate the host-local configured form such as `channel:<discord_channel_id>`
2. Is the send path using direct driver delivery or the generic wrapper?
   - For watchdog-b owner-facing single-shot delivery, prefer direct driver delivery.
3. If stalled/idle tries to nudge a main agent, is `WATCHDOG_B_MAIN_AGENT_ID` set to a valid agent id on that host?
   - If not, leave it unset so main-agent nudge is skipped instead of failing on `Unknown agent id`.
4. Does the message actually appear in channel readback?
5. Is the message merely transport-accepted, or human-visible?

Be precise in language:

- "transport accepted" = send returned success / message id
- "channel-readable" = message appears in channel readback
- "human-confirmed" = Eric says he saw it

Do not collapse these into one claim.

## Message formatting preference

Eric reported that visible does not necessarily mean prominent.

When adjusting Discord-facing watchdog messages, prefer:

- short first line
- conclusion first
- minimize raw diagnostic fields in the user-facing body
- keep machine/audit detail in artifacts, not in the first visible lines

Preferred shape:

- `🔔 WATCHDOG｜<結論>`
- `任務：...`
- `結論：...`
- `你現在不用做事` or `需要你介入：...`

## Suggested execution pattern

For most tasks in this skill:

1. Inventory live state and installed schedule.
2. Decide whether the task is:
   - reset/cleanup
   - route repair
   - schedule install
   - e2e verify
   - portability / migration
3. Preserve audit assets.
4. Prefer the bundled skill scripts as the reusable baseline.
5. Use direct driver Discord route for owner-facing verification.
6. Attach evidence paths and exact commands before claiming success.

## Portability note

This skill is now suitable to copy to another OpenClaw workspace, but portability still depends on the target host having:

- a working OpenClaw install
- Discord routing available
- a valid destination channel/target configured in `watchdog-b.env`
- systemd --user if live scheduling is desired

When moving to another host, recommended order is:

1. Run `scripts/install_watchdog_bundle.sh --install-env-example` to populate live paths from the bundled copies.
2. If `~/.config/openclaw/watchdog-b.env` does not exist, create it from the example:
   - `mkdir -p ~/.config/openclaw`
   - `cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env`
3. Edit `~/.config/openclaw/watchdog-b.env` and set at least:
   - `WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID`
4. Run `scripts/bootstrap_watchdog_bundle.sh`.
5. Bootstrap should now validate the installed live bundle under `scripts/watchdog-b/` and should not require a separate `owner-reporting-system/` live tree.
6. Re-run bootstrap until it passes, then enable/start systemd --user units.

When moving to another host, runtime detection now follows this order:

1. explicit env overrides: `WATCHDOG_B_NODE_BIN`, `WATCHDOG_B_OPENCLAW_MJS`, `WATCHDOG_B_OPENCLAW_ENTRY`
2. PATH discovery: `node`, then `openclaw`-adjacent install roots
3. common install roots scan: nvm, pnpm global, npm-global, `/usr/local`, `/usr`, and Volta-style locations
4. hard failure with a message telling the operator which env vars to set manually

So on most hosts you should only need to update:

- `WATCHDOG_B_OWNER_REPORT_TARGET`
- `WATCHDOG_B_WORKSPACE` if the workspace is not the default `~/.openclaw/workspace`

Only set `WATCHDOG_B_NODE_BIN` / `WATCHDOG_B_OPENCLAW_ENTRY` / `WATCHDOG_B_OPENCLAW_MJS` when auto-detection fails or you intentionally want to pin a non-default runtime.

If another agent reports that `~/.config/openclaw/watchdog-b.env` does not exist, the correct response is to create it from `watchdog-b.env.example` before expecting bootstrap to pass.

## Success checklist

Do not say done unless you have all applicable evidence:

- changed file paths
- exact command(s) run
- status output or send result
- sent archive path when queue/driver is involved
- channel/message evidence when claiming delivery
- rollback instructions when you changed live scheduling