hoangsonww / hoangsonww/Forge-Agentic-Coding-CLI

Feature: Task Replay and Checkpoint System for Deterministic Resume, Diff, and Audit

Open
#7 0 comments 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
bug documentation enhancement feature help wanted question
Dominant language
TypeScript
Stars
23
Forks
9
PR merge metrics
No merged PRs in 30d

Description

## Summary

Build a task replay and checkpoint system that can reconstruct a Forge task from persisted events, compare planned vs actual execution, and resume from explicit checkpoints with clear auditability.

## Problem / Opportunity

Forge already persists tasks, sessions, conversations, and events, and its architecture emphasizes inspectability and replayability. Today that inspectability is distributed across JSON, JSONL, SQLite indexes, and dashboard views. Users need a cohesive workflow for:

- Replaying a completed or failed task timeline.
- Understanding how a plan changed during validation retries or reviewer bounce-backs.
- Resuming from a known checkpoint rather than restarting from draft.
- Producing an audit bundle for a task without exposing secrets.
- Comparing two runs of the same prompt or plan.

This is especially important for local-first agentic coding where users want confidence that actions were bounded, explainable, and recoverable.

## Proposed Feature

Add replay/checkpoint support across CLI and UI:

- `forge task replay ` to render a normalized timeline from events, session turns, tool calls, validation results, and reviewer outcomes.
- Explicit checkpoints at major state transitions and before/after mutating tool batches.
- `forge task diff ` to compare plan, files changed, tool outcomes, validation, and cost.
- `forge resume --from-checkpoint ` for supported checkpoint boundaries.
- Redacted export bundles for sharing task audits.
- Dashboard timeline and checkpoint browser.

## Scope

Expected implementation areas:

- `src/persistence/tasks.ts`, `src/persistence/events.ts`, `src/persistence/sessions.ts`, and `src/persistence/conversation-store.ts`.
- `src/core/loop.ts`, `src/agents/executor.ts`, and `src/core/validation.ts` for checkpoint emission.
- `src/cli/commands/task.ts` and `src/cli/commands/resume.ts` for replay, diff, export, and checkpoint resume.
- `src/ui/server.ts` and `src/ui/public/` for timeline visualization.
- `src/security/redact.ts` for export safety.
- Architecture and CLI documentation updates.

## Acceptance Criteria

- [ ] Every task can render a chronological replay from persisted data without requiring the original process to be alive.
- [ ] Checkpoints are emitted at state transitions and before/after mutating tool batches.
- [ ] Replay output includes plan steps, state transitions, tool actions, permission decisions where available, validation results, reviewer decisions, files changed, provider/model decisions, and cost.
- [ ] Redacted export bundles exclude credentials, sensitive paths, and raw secrets.
- [ ] Supported checkpoint resumes are explicit and refuse unsupported unsafe boundaries with a clear error.
- [ ] Task diff can compare two runs and highlight changed plans, changed files, failed steps, validation deltas, and model/provider deltas.
- [ ] Unit tests cover replay reconstruction from fixture JSON/JSONL data and checkpoint validation.
- [ ] Documentation explains which parts of replay are deterministic and which depend on external model/tool behavior.

## Non-Goals

- Bit-for-bit deterministic re-execution of arbitrary shell commands.
- Rewriting Git history or restoring files automatically without user confirmation.
- Uploading audit bundles to a hosted service.
- Supporting checkpoint resume from every possible internal executor turn in the first version.

## Dependencies / Risks

- Event schemas need versioning so older task records remain readable.
- Replay must not accidentally expose raw model prompts or secrets in default output.
- Resume from checkpoints must respect the existing task state machine and validation gate.
- Diff output can become noisy unless normalized around meaningful task concepts.

## Open Questions

- Should checkpoint snapshots include file hashes only, or optional file content patches?
- Should replay default to concise output with a `--verbose` mode for raw detail?
- How should checkpoint resume interact with `completed`, `failed`, `blocked`, and `cancelled` terminal states?
- Should exported audit bundles include local model names by default?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.