avelino / avelino/dotagent

Add `dotagent why <agent>` — explain why an agent is (not) running now

Open
#10 3 comments 0 reactions 0 assignees View on GitHub
area: cli area: scheduler type: feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.