Add `dotagent history <agent>` — list recent runs from the audit log
- Dominant language
- Rust
- Stars
- 3
- Forks
- 1
- Avg merge
- 4h 50m
- Merged PRs (30d)
- 1
Description
Heartbeat files at `~/.config/dotagent/state/agents//.heartbeat.json` capture the last run's exit code, duration, and timestamps — but only the last one. Window state files capture per-window outcomes but get cleaned up by retention. The audit log (`~/.config/dotagent/state/audit.log` JSON Lines) has the full history but is not user-friendly.
`dotagent inspect` shows the single most recent heartbeat. There is no way to ask "show me the last 20 runs for this agent" without reading raw JSON lines yourself.
## Proposal
A new subcommand:
```
dotagent history # last 20 runs across all schedules
dotagent history --schedule X # filter to one schedule
dotagent history -n 100 # last 100 runs
dotagent history --since 7d # time window
dotagent history --failed # only failures
dotagent history --json # machine-readable
```
Output as a table:
```
when schedule exit duration notes
2026-05-20 10:15:02 morning 0 12s
2026-05-20 09:15:01 morning 1 12s failed → notified slack
2026-05-19 10:15:00 morning 0 11s
```
## Acceptance criteria
- [ ] Reads from the audit log (authoritative source) and falls back to heartbeat for the most recent run.
- [ ] Default limit is 20 rows. `--since` and `-n` compose.
- [ ] `--failed` shows only non-zero exits and preflight aborts.
- [ ] `--json` emits one record per line (NDJSON), matching the audit log shape.
- [ ] Empty history shows a clear message ("no runs recorded yet — has the daemon started?").
## Where to start
- `crates/dotagent-state/src/audit.rs` — the audit log format.
- `crates/dotagent/src/commands/utility.rs::inspect` — the existing single-snapshot inspector.
- `crates/dotagent/src/commands/output.rs` — shared renderer.
## Non-goals
- Re-running historical runs. Read-only.
- Cross-agent history. Per-agent only.
Contributor guide
Research direction
Start by reading crates/dotagent-state/src/audit.rs for the audit log format, then inspect crates/dotagent/src/commands/utility.rs::inspect and the shared renderer in crates/dotagent/src/commands/output.rs. The work is done when the per-agent history command supports the stated filters, limits, fallback, empty-state message, table output, and NDJSON output without modifying historical runs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100