watchdog-discord-route/README.md

# watchdog-discord-route

Portable OpenClaw skill bundle for the **watchdog-b owner-facing Discord route**.

This repo packages the scripts, env example, systemd user units, and skill documentation needed to install, verify, and repair the path:

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

## Quick install (shortest path)

Run from inside this repo:

```bash
./scripts/install_watchdog_bundle.sh --install-env-example
mkdir -p ~/.config/openclaw && cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
sed -i 's#^WATCHDOG_B_OWNER_REPORT_TARGET=.*#WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID#' ~/.config/openclaw/watchdog-b.env
./scripts/bootstrap_watchdog_bundle.sh && systemctl --user daemon-reload && systemctl --user enable --now openclaw-watchdog-b.timer
```

Replace `YOUR_DISCORD_CHANNEL_ID` with the real target before enabling the timer.

## Install flow

```mermaid
flowchart TD
    A[Clone or unpack watchdog-discord-route] --> B[Run install_watchdog_bundle.sh --install-env-example]
    B --> C[Create ~/.config/openclaw/watchdog-b.env from example]
    C --> D[Set WATCHDOG_B_OWNER_REPORT_TARGET]
    D --> E[Run bootstrap_watchdog_bundle.sh]
    E --> F{Bootstrap passes?}
    F -- no --> G[Fix config/runtime/path issues and rerun bootstrap]
    G --> E
    F -- yes --> H[systemctl --user daemon-reload]
    H --> I[Enable/start openclaw-watchdog-b.timer]
    I --> J[Optional: run verify_watchdog_b_e2e.sh]
```

## What this is for

Use this bundle when you need to:

- install watchdog-b on another OpenClaw host
- verify end-to-end owner-facing Discord delivery
- repair broken `owner_report_*` routing
- refresh the live bundle under `scripts/watchdog-b/`
- enable the `systemd --user` timer for watchdog-b

## What is included

### Skill docs
- `SKILL.md`

### Scripts
- `scripts/check_openclaw_state.sh`
- `scripts/run_watchdog_b.sh`
- `scripts/notify_watchdog_b.py`
- `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_runtime_probe.py`
- `scripts/watchdog-b.env.example`

### systemd --user units
- `scripts/openclaw-watchdog-b.service`
- `scripts/openclaw-watchdog-b.timer`

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

## Recommended install order

Run from inside this repo:

```bash
./scripts/install_watchdog_bundle.sh --install-env-example
mkdir -p ~/.config/openclaw
cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
```

Then edit at least:

```bash
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
```

Then validate:

```bash
./scripts/bootstrap_watchdog_bundle.sh
```

Only after bootstrap passes:

```bash
systemctl --user daemon-reload
systemctl --user enable --now openclaw-watchdog-b.timer
```

## Quick update / refresh on a host

If you already have the repo or bundle and just want to refresh the live install:

```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force
./scripts/bootstrap_watchdog_bundle.sh
```

## End-to-end verification

Run:

```bash
cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh
```

Minimum success evidence:

- pending owner report created
- report moved to `~/.clawteam/owner-reports/sent/`
- Discord send returns success / message id
- artifacts written under `state/watchdog-b-verify-e2e/<run-id>/`

Useful verification files:

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

## Important config

Expected live config lives in:

- `~/.config/openclaw/watchdog-b.env`

Typical minimum values:

```bash
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:YOUR_DISCORD_CHANNEL_ID
```

Optional if the host really has a valid OpenClaw agent id:

```bash
WATCHDOG_B_MAIN_AGENT_ID=backend
```

If this is unset, stalled/idle paths skip main-agent nudge instead of failing on `Unknown agent id`.

## Known pitfalls fixed in this bundle

This bundle already includes fixes for these previously observed issues:

1. **Wrong producer path**
   - bad: `.../workspace/scripts/scripts/owner_report_producer.py`
   - fixed: `.../workspace/scripts/watchdog-b/owner_report_producer.py`

2. **Missing consumer in portable bundle**
   - `owner_report_consumer.py` is included and installed to the live bundle

3. **Bootstrap wrongly required old live owner-reporting-system tree**
   - bootstrap now validates the installed live bundle under `scripts/watchdog-b/`

4. **Invalid hard-coded `main` agent nudge**
   - nudge now uses `WATCHDOG_B_MAIN_AGENT_ID` only when configured

## Evidence standard

When claiming success, distinguish these clearly:

- **transport accepted**: send returned success / message id
- **channel-readable**: message can be read back from the target Discord channel
- **human-confirmed**: the user confirms they saw it

Do not collapse them into one claim.

## Known troubleshooting FAQ

### 1. `bootstrap_watchdog_bundle.sh` says `owner-reporting-system root missing`

Cause:
- an older bundle / script still expects the old live tree
- or the host has not refreshed to the fixed portable bundle yet

Fix:
- refresh the live bundle:

```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force
./scripts/bootstrap_watchdog_bundle.sh
```

Expected fixed behavior:
- bootstrap should validate the installed live bundle under `scripts/watchdog-b/`
- it should **not** require a separate `owner-reporting-system/` live directory

### 2. `can't open file .../scripts/scripts/owner_report_producer.py`

Cause:
- notifier is using the wrong base path for `owner_report_producer.py`

Bad path:
- `.../workspace/scripts/scripts/owner_report_producer.py`

Correct path:
- `.../workspace/scripts/watchdog-b/owner_report_producer.py`

Fix:
- update to a bundle that uses the live script directory correctly
- then rerun:

```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force
cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh
```

### 3. `Unknown agent id "main"`

Cause:
- stalled / idle path tried to nudge a hard-coded `main` agent id that does not exist on that host

Fix:
- either leave `WATCHDOG_B_MAIN_AGENT_ID` unset
- or set it to a real host-local agent id

Example:

```bash
WATCHDOG_B_MAIN_AGENT_ID=backend
```

If unset, the fixed bundle skips main-agent nudge instead of failing.

### 4. `~/.config/openclaw/watchdog-b.env` does not exist

Cause:
- install copied the example, but the live env was never created

Fix:

```bash
mkdir -p ~/.config/openclaw
cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
```

Then edit at least:

```bash
WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
```

### 5. Bootstrap passes, but Discord delivery still fails

Check these in order:

1. `WATCHDOG_B_OWNER_REPORT_TARGET` is real, not placeholder
2. Discord routing actually works on that host
3. the send was only transport-accepted vs actually channel-readable
4. `~/.clawteam/owner-reports/pending/` and `sent/` show the expected file movement
5. `state/watchdog-b-verify-e2e/<run-id>/` contains the expected verification artifacts

### 6. Timer is active, but owner-facing route still did not work

This means:
- `systemd --user` scheduling is alive
- but the notification chain may still be broken

Do not stop at `timer active` / `service success`.
You still need to verify:
- pending owner report creation
- sent archive movement
- Discord send success / message id
- readback or human-visible evidence if claiming visible delivery

### 7. How do I know whether I should rerun install or just rerun verify?

Use this rule:

- rerun **install** when scripts / env example / units may be stale or incomplete
- rerun **bootstrap** when you need host-readiness validation
- rerun **verify** when install is already in place and you need fresh E2E evidence

Practical order:

```bash
./scripts/install_watchdog_bundle.sh --install-env-example --force
./scripts/bootstrap_watchdog_bundle.sh
cd ~/.openclaw/workspace/scripts/watchdog-b
./verify_watchdog_b_e2e.sh
```

## Safety / cleanup rules

- Do **not** delete `~/.clawteam/owner-reports/sent/` history unless explicitly asked
- Do **not** delete live `state/watchdog-b/notify-state.json` unless explicitly doing a hard reset
- Prefer archiving old test residue under `state/archive/<timestamp>/`

## Repo purpose

This repo is meant to be a reusable, host-portable source of truth for the watchdog-b Discord delivery path, not just a local one-off workspace patch.