Lesson 12 — Task vs Run vs Turn vs process

Outcome

Add AgentRun and AgentTurn domain/storage models and make their lifetimes explicit before the fake adapter starts doing work.

Why this comes now

Without this separation, later features such as resume, review follow-ups, long-lived provider servers, and crash recovery all become awkward or misleading.

Understand

A Task can outlive every provider execution. A Run is one supervised provider/session lifetime attached to the Task. A Turn is one input → work cycle within a Run. An OS process is merely how one adapter strategy may implement a Run or Turn.

Provider completion is also not the same as Task readiness for Review: revision capture and other follow-up Operations may still be pending.

Build the real project

1. Implement AgentRun with selected Agent Instance/Strategy, Execution Environment reference, status, stopped reason, external session ID, capability snapshot, and policy snapshot placeholder.
2. Implement AgentTurn sequence/status/timestamps.
3. Persist them.
4. Add domain/application APIs that can create a Run/Turn without exposing PID as identity.
5. Add explicit stopped-reason classification type.
6. Write timeline tests with multiple Turns in one Run and multiple Runs for one Task.

Completion gate

Tests show Task ID, Run ID, Turn ID are independent. A Run can obtain external session ID after creation. Stopping a Run does not itself mark the Task Done.

Pitfalls to avoid

Do not put exit_code on Task. Do not assume every Run has one PID. Do not call a provider Turn “Task completed.”

References

AGENT_SYSTEM.md, T3 turn-completion notes: https://github.com/pingdotgg/t3code/blob/main/docs/internals/overview.md

Checkpoint

Update your vocabulary in code/comments if you catch yourself using “session” where Run or Turn is meant.