# Autonomous Run Completion Design

audience: AI coding agents first.

## Goal

MUST finish `delivery-controller-receipts` and `throughput-seams` without manual intervention. Success requires every task committed and landed, zero quarantined/skipped tasks, green gates, and runner exit 0.

## Architecture

Use SQLite state journal as sole run-lifecycle authority. Every runner invocation opens one attempt before work and closes same attempt with an explicit outcome. Daemon monitors latest open attempt only; historical terminal records MUST NOT suppress recovery.

Treat Cursor stream terminal record as transport completion only. Reap a lingering Cursor process after bounded grace, preserve terminal payload, then apply existing repository evidence rules: diff or explicit no-op, scope guard, gates, commit, merge.

Route recoverable task failures through repair policy. `agent-idle` MUST execute `resume`, then `redo-task`, then quarantine; it MUST NOT fall through to `repair-unavailable`.

## Attempt Lifecycle

Events:

- `run.start`: append to SQLite and run log before preflight; include `attemptId`, owner PID/PGID/start time, and launch reason.
- `run.done`: append only after scheduler completes; include `attemptId`, outcome `succeeded|failed`, and summary.
- `run.crashed`: append from crash reconciliation; include `attemptId`, signal/reason, and owner.
- `run.restarted`: daemon decision; next runner emits new `run.start` with new `attemptId`.
- `run.killed`: intentional terminal outcome; daemon MUST NOT restart same attempt.

Latest attempt owns lifecycle state. Historical terminal records remain immutable evidence.

## Cursor Terminal Contract

Recognize only parsed top-level stream records with `type:"result"` and terminal subtype. Assistant prose never terminates transport.

- `subtype:"success"`: wait short grace for normal exit. If still alive, reap process group and return captured terminal result as adapter completion.
- Error terminal: reap lingering process and return adapter failure.
- Missing terminal: existing watchdog semantics apply.
- Transport success never implies task success. Existing zero-diff/no-op and gate contracts remain mandatory.

## Resolver Contract

Task recovery executes resolver decision, records decision, and applies action:

1. `resume`: recover existing task worktree evidence and rerun task state machine.
2. `redo-task`: reset task workspace from integration head and rerun.
3. Quarantine only after retry budget is exhausted.

## Status and Audit

Status cache MUST expose `running|recovering|paused|succeeded|failed|killed|crashed`; never collapse terminal outcomes to `done`. Scheduler and daemon action records MUST share existing SQLite run journal so postmortems can attribute attempts, restarts, and signals.

## Testing

- Real scheduler writes `run.start` before work and attempt-scoped terminal outcome after work.
- Prior `run.done`/`run.killed` does not hide a later open attempt.
- Cursor fixture emits successful terminal record then sleeps; wrapper returns completion and evidence gates still decide task result.
- Successful terminal with zero diff and no explicit no-op remains `zero-diff`.
- `agent-idle` follows resolver retry ladder.
- Final acceptance runs both failed plans foreground and requires exit 0 plus all tasks committed/landed.

## Architecture Decisions

- Keep lifecycle in existing journal; deleting a separate attempt store avoids split authority.
- Keep task evidence validation in ship/gates; adapter terminal handling MUST NOT duplicate business completion rules.
- Extend existing resolver/repair seam; no second recovery engine.