System Diagnostics

System Diagnostics

Use these to detect and surface problems before they become crises.

Stale Task Detection

Find tasks that have been in-progress too long or pending without action:

cortextos bus check-stale-tasks

Flags:

• in_progress for more than 2 hours
• pending for more than 24 hours
• Human tasks with no update in 48 hours
• Tasks past their due date

When to run: Every heartbeat (orchestrator), on suspicion of stuck work (all agents).

Goal Staleness Check

Detect agents whose GOALS.md hasn't been updated recently:

# Default threshold (7 days)
cortextos bus check-goal-staleness

# Custom threshold
cortextos bus check-goal-staleness --threshold 3

# JSON output for parsing
cortextos bus check-goal-staleness --json

When to run: Weekly, or when an agent seems directionless.

Human Task Monitoring

Check for human-assigned tasks that are waiting too long:

cortextos bus check-human-tasks

Sends reminders for overdue human tasks. Run daily (orchestrator) or when blocked waiting on a human.

Fleet Health Summary

Read all agent heartbeats at once:

cortextos bus read-all-heartbeats

# JSON for parsing
cortextos bus read-all-heartbeats --format json

Stale threshold: agent hasn't updated in >6h = investigate.

Metrics Collection

Collect and record system metrics snapshot:

cortextos bus collect-metrics

Run nightly (analyst cron). Captures task counts, completion rates, agent activity.

Full Health Check Sequence

Run this during morning review or when something feels off:

echo "=== Fleet Heartbeats ==="
cortextos bus read-all-heartbeats

echo "=== Stale Tasks ==="
cortextos bus check-stale-tasks

echo "=== Stale Goals ==="
cortextos bus check-goal-staleness

echo "=== Human Tasks ==="
cortextos bus check-human-tasks

Surface any findings to the user via Telegram if critical.