Lesson 13 — Build the programmable fake agent

Outcome

Run a deterministic fake agent against a real Task worktree through the real orchestration boundaries.

Why this comes now

A reliable fake gives us end-to-end confidence without model API cost, network variability, or provider changes. It also becomes the reference for every later adapter contract.

Understand

The fake should be programmable. It is not merely return success. A script can emit events, write a file, ask a Decision later, crash, delay, duplicate an event, or finish. This allows deterministic tests for timing and failure paths that are hard to force from a live model.

Build the real project

1. Define the smallest Adapter Strategy interface required to start/drive/stop the fake.
2. Implement a registry lookup by Strategy ID.
3. Create Fake Adapter scripts/steps such as EmitMessage, EmitToolEvent, WriteFile, Sleep/Wait, Fail, Complete.
4. Compose Task + Operation + LocalWorktreeEnvironment + Fake Adapter in the application/orchestrator.
5. Have the fake edit a real file in the test worktree.
6. Add contract tests for normal completion, cancellation, crash, and multiple Turns.
7. Keep the fake deterministic by default—no random sleeps.

Completion gate

One integration test starts a Task, prepares its worktree, runs Fake Adapter, changes a file, records Run/Turn outcome, and leaves the Task in a sensible post-work state without any real provider.

Pitfalls to avoid

Do not let the fake bypass the same interfaces real adapters will use. Do not write tests that depend on timing sleeps when a deterministic gate/channel works.

References

TESTING.md, Go testing: https://pkg.go.dev/testing

Checkpoint

M4 is complete when the fake can reproduce failure modes you expect from a real provider.