Add `dotagent why <agent>` — explain why an agent is (not) running now
- Dominant language
- Rust
- Stars
- 3
- Forks
- 1
- Avg merge
- 4h 50m
- Merged PRs (30d)
- 1
Description
When an agent is not behaving as expected — "I expected this to run at 10:00 but it's 10:30 and nothing happened" — the user has to inspect the manifest, compute the next fire time mentally, and check the window state. There is no single command that answers "why isn't this running right now?".
## Proposal
A new subcommand that explains the scheduler's state for one agent:
```
dotagent why
dotagent why /
```
Sample output:
```
hello-fish/manual
schedule: interval(every 10080 minutes = 7 days)
last fired: 2026-05-13 10:00:00 (success)
next fire: 2026-05-20 10:00:00 (in 4h 22m)
window state: ok
current state: waiting for window
```
Or a failure case:
```
databricks-cost-daily/morning
schedule: cron(weekday=mon-fri 10:15)
last fired: 2026-05-19 10:15:00 (exit 1, given up after 3 attempts)
next fire: 2026-05-20 10:15:00 (in 6h)
window state: failing
current state: retry budget exhausted; will try again at next scheduled fire
see: dotagent history databricks-cost-daily --failed
```
## Acceptance criteria
- [ ] One-screen output, no scrolling.
- [ ] Covers all four health states (`ok` / `degraded` / `failing` / `stale`) and explains each transition.
- [ ] Calls out preflight aborts distinctly from agent failures.
- [ ] When a manifest exists but the agent has never run, says "never run — try `dotagent bootstrap` or wait for the first fire at
## Where to start
- `crates/dotagent-scheduler/src/lib.rs` — next-fire computation.
- `crates/dotagent-state/src/lib.rs` — window state and heartbeat reads.
- `crates/dotagent/src/commands/utility.rs::inspect` — close cousin, may share helpers.
## Non-goals
- Modifying any state. Pure read.
- Replacing `dotagent status`. `status` is the dashboard; `why` is the deep-dive on one agent.
Contributor guide
Research direction
Start with crates/dotagent-scheduler/src/lib.rs for next-fire computation, then read crates/dotagent-state/src/lib.rs for window and heartbeat state. Compare the command structure and reusable helpers around crates/dotagent/src/commands/utility.rs::inspect. Done means a read-only, one-screen why command supports both agent forms, all four health states, preflight aborts, never-run agents, and --json.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100