clawdie-ai/docs/MONITORING.md

Monitoring Model

Clawdie monitoring is split into distinct layers so "process is running" is not confused with "system is healthy".

Current Design

Clawdie writes runtime health state into:

• data/health/host.json
• data/health/pipeline.json
• data/health/jail.json

These files are updated by the running process and inspected by:

npm run doctor

Monitoring Layers

1. Host Health

Tracks:

• process startup
• database initialization
• channel connection startup
• IPC watcher startup
• message loop heartbeat
• scheduler heartbeat

This answers: is the main process alive and making progress?

2. Pipeline Health

Tracks:

• Telegram connected
• last inbound message received
• last inbound message persisted
• last message routed
• last jailed run started
• last jailed run finished
• last reply sent
• last pipeline failure

This answers: are messages actually flowing through the system?

3. Warden Health

Tracks:

• last jail run started
• last jail run finished
• last jail success
• last jail failure
• last failure code and message
• last duration

This answers: is the isolated executor actually working?

Why This Exists

Without this split, a running PID can hide real failures such as:

• Telegram intake dead
• scheduler stalled
• jail execution failing
• replies not being delivered

Doctor Command

Run:

npm run doctor

It reports:

• overall status
• latest host heartbeats
• latest Telegram connection state
• latest pipeline activity
• latest Warden success or failure
• split-brain DB availability
• built-in knowledge artifact readiness and version
• runtime skills lookup presence
• memory and built-in knowledge row counts

User-facing timestamps are printed in European format.

Bastille's Role

Bastille monitoring is still useful later, but it solves a different problem.

• Bastille monitor: jail service watchdog
• Clawdie doctor: application and pipeline health

Use both, but do not confuse them.

Next Layer to Add Later

Current doctor output still does not include:

• persistent execution history for all interactive runs
• admin alerting to Telegram
• Healthchecks.io integration
• Bastille monitor integration

Those are the next logical additions after the basic health state is stable.