Persist run and task checkpoints for reliable continuation after compaction or interruption #48

Area

Orchestrator / workflow state / memory / resume

Problem

The orchestrator reads the memory index, role logs, decisions, and stage artifacts at session start. This supplies useful context, but there is no explicit durable run/task manifest establishing which invocation started, what finished, what is still running/interrupted, or which artifact was approved.

OpenCode session compaction and session resumption help preserve conversation continuity, but a summary alone is not a reliable task completion record. A context transition, restart, or interrupted tool result can leave the orchestrator reconstructing state from prose and artifacts, potentially repeating completed work or skipping unfinished work.

Proposal

Persist a lightweight checkpoint before each task starts and after each task finishes. On continuation, read and validate that checkpoint before planning or dispatching work.

For example, keep a run-scoped state under .team/runs/<run_id>/ containing:

• Unique run/task identity, stage, agent, attempt, and parent/child OpenCode session IDs when available.
• Explicit status, such as pending, running, awaiting approval, completed, failed, or interrupted.
• Input/output artifact references and the next pending action.
• Completion evidence and a separate human approval record tied to the relevant stage/artifact revision.

The exact file/schema and integration points are design choices. Keep state machine-readable and compact; do not store credentials or full transcripts.

Acceptance criteria

• Each run and task attempt has a durable unique identity, distinct from reusable stage names such as build.
• Record the task before dispatch and its terminal outcome after execution.
• Startup/resume reads checkpoints before dispatching; after compaction, reload them through an appropriate supported integration point.
• Completed tasks are not rerun merely because conversational context was shortened.
• Uncertain/running tasks are reconciled against available runtime/artifact evidence; do not blindly mark them completed or automatically repeat side effects.
• Failed/interrupted tasks can be resumed or retried explicitly, with attempt history and a clear next action.
• Persist and preserve human approval requirements; an artifact existing on disk does not itself prove approval.
• Checkpoint updates cannot expose partial state; define concurrency handling for multiple invocations.
• Existing projects without a checkpoint initialize safely without treating old work as newly approved.
• Test continuation after context compaction, process interruption between start/finish writes, completed-task recovery, and failed-task retry.
• Document the limits: checkpoints support reliable continuation but do not automatically restart a stopped OpenCode process or guarantee exactly-once external side effects.

Alternatives considered

Use only conversation summaries or infer progress from artifact existence. These remain useful evidence but cannot uniquely identify a task attempt or distinguish draft output from a completed, approved stage.

Compatibility

Preserve project-local memory and current approval gates. Prefer the smallest durable state mechanism compatible with the project's file-based approach, and account for the selected OpenCode v1/v2 support policy.