`dotagent record` + `dotagent replay` — deterministic debug
- Dominant language
- Rust
- Stars
- 3
- Forks
- 1
- Avg merge
- 4h 50m
- Merged PRs (30d)
- 1
Description
When an agent fails in a way that does not reproduce locally, the operator has to guess at what environment / inputs / external state caused the failure. There is no way to capture an execution completely and replay it later.
This is a power feature, not v1 territory, but it solves a real recurring debug pain.
## Proposal
Two new subcommands:
```
dotagent record [--schedule ]
dotagent replay
```
`record` runs the agent like `run-now` but also serializes:
- Environment variables (with secrets redacted by an allow-list).
- The full stdout/stderr.
- The exit code, timing, heartbeat lifecycle.
- The manifest hash and resolved plugin paths.
into a single tarball at `~/.config/dotagent/recordings//.tar.zst`.
`replay ` reconstructs the execution: same env, same args, same working dir. The agent runs in a sandbox so it does not double-write to external state (or the user opts in with `--write`).
## Acceptance criteria
- [ ] `dotagent record hello-fish` produces a single archive.
- [ ] `dotagent replay ` re-runs and reports if the outcome diverged from the recorded one.
- [ ] Secret redaction has a configurable allow-list of env vars to NOT capture.
- [ ] Recordings have a retention policy (default: keep 10 per agent).
- [ ] [`agent-spec.md`](docs/reference/agent-spec.md) or a new doc explains the workflow.
## Where to start
- `crates/dotagent-runner/src/lib.rs` — instrument the existing run path.
- `tar` + `zstd` crates for the archive.
## Non-goals
- Time-travel of external services. If the agent hit GitHub's API on 2026-05-01, replay calls today's GitHub. Pure capture/replay of inputs; effects are real.
- Deterministic replay across machines. Pin to the recording machine for v1.
Contributor guide
Research direction
Start by reading crates/dotagent-runner/src/lib.rs and tracing the existing run-now path. Check how the tar and zstd crates can support the proposed recording archive, then define the CLI flow for record and replay. Done means the stated acceptance criteria are covered, including archive creation, divergence reporting, redaction, retention, and the agent-spec.md documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100