The long-running agent problem

AI coding agents are now good enough to do real engineering work. They are not yet good at doing a lot of it in a row. A real project, or one large epic, is hundreds of hours of agent work spread over many separate contexts. Over that distance three things fall apart at once: the quality of the agent's reasoning, the faithfulness to what the human actually wanted, and the budget. This page is about that problem, what the field has tried, why it breaks, and a design we built and partly tested to get around it.

Context: we build a real product (a published mobile app) with Claude Code on a flat-rate Claude Max plan, plus OpenAI's Codex as a second reviewer. Everything here is grounded in public research, our own measured runs, and live tests. Estimates are labelled as estimates.

The shape of the problem

An agent does all its thinking inside a context window: the instructions, every file it read, every command output, and its own reasoning, all re-sent to the model on every single step. That window is the agent's working memory, and it behaves badly in three ways that compound:

On top of the memory problem sit two more: verification (an agent's own "done" is not reliable) and coordination (splitting work across many agents creates new failure modes and multiplies cost). Finally there is the human: someone has to define "right" and judge the parts no test can.

What the evidence says

What others have tried, and where each breaks

What is wrong with the usual logic

Measuring a real run

We ran one real epic (adding multiple languages to our app) with one lead chat handing work to helpers, then read every transcript from disk: 44 helpers and about 5,700 model calls over about 21 hours. Cost is in input-token equivalents at the API's price ratios (cache read 0.1x, cache write 1.25x, output 5x).

• Long-lived helpers were the cost, not startup: they ended at a median 316k and up to 816k tokens, after 200-375 steps each.
• Short cache lifetimes were the second cost. Helper caches expired after 5 idle minutes; a long test run or a manager waiting on its builders meant re-writing the whole context. We moved helpers to a 1-hour cache.
• The middle layer was the most expensive agent, because it did hands-on work, held 700-800k, and paid rewrites while waiting.

Replaying the real traces

The obvious fix, "cap each helper's context and restart fresh", seemed sound. We replayed all 26 builders' step-by-step histories under different rules before trusting it:

Fresh restarts lose because getting up to speed is expensive (about 71k at startup, 65k of command and file output, the rest reasoning). Forks win because they start up to speed and read that knowledge from cache at a tenth of the price. That is what pointed us at forking a shared, primed knowledge base.

What we proved about forks

How the design emerged

The solution: knowledge in a seed, work in forks, truth outside

Three layers: an orchestrator keeps the epic moving; an architect owns each wave; workers carry out the assignments it chooses. The architect can prepare a shared seed and fork workers from it, saving repeated codebase exploration, or start fresh specialists where they fit better. GitHub issues already define the agreed end-state in their Completed sections. The architect verifies the result against those criteria and the epic's goal.

Principles

The architecture

flowchart TD
  H["Human owner
agrees the issue end-states
answers parked decisions, walks the result, says push"]
  O["Orchestrator chat
scheduler for the whole epic
never reads or writes code"]
  A["Architect, one per wave
plans, dispatches, verifies,
refreshes the seed. Never codes"]
  GH[("Issue tracker + repo
Completed criteria, decisions, reports,
canonical docs, locked tests, code")]
  S[("Seed session
the wave's codebase knowledge
shared preparation at a known commit")]
  subgraph F["Workers chosen by the architect: example roles"]
    direction LR
    SW["Spec writer
docs + tests"] --> TR["Test review"] --> CW["Coder
passes locked tests"] --> AR["Adversarial review
+ Codex"]
  end
  H --> O
  O -->|"one per wave"| A
  A -->|"creates, refreshes"| S
  A -->|"chooses agents and models"| F
  S -. "fork when useful" .-> F
  F -->|"commits, comments"| GH
  A -->|"reads, files issues"| GH

Who does what

How a seed lives

A seed is an ordinary agent session that gets acquainted with the wave before implementation starts: its issues, architecture, conventions and relevant code. Save that session, then fork workers from it when they need the same foundation. For ten workers sharing that ground, the aim is one preparation pass instead of ten. Each worker still does its own task-specific investigation and work; the inherited input is read at the cached rate when the cache hits. The architect can also start fresh agents, including a test-writing specialist or an adversarial reviewer on another model.

flowchart LR
  P["Prime
read epic, issues, docs, files"] --> S1[("Seed v1
commit A")]
  S1 -. fork .-> W1["Issue 1 agents"]
  S1 -. fork .-> W2["Issue 2 agents"]
  S1 -->|"fork + catch up:
git diff A..B, reports"| S2[("Seed v2
commit B")]
  S2 -. fork .-> W3["Issue 3 agents"]
  S2 -. fork .-> W4["Issue 4 agents"]
  S2 -->|"wave ends"| X["Retire.
Next wave primes a clean seed"]

When the architect refreshes the seed

• When shared facts change: a contract, convention or implementation has moved enough that later workers would otherwise repeat the same catch-up work.
• When a worker reports that the seed misled it, for example a function the seed remembers was renamed.
• When knowledge should be inherited: a research or design report from any model (a Fable brainstorm, a Sonnet investigation) is taught to the seed once, and every later agent inherits it.
• Before splitting into parallel lanes, so every lane starts from the same current understanding.

Why refreshes are not forever

A refresh adds the news on top of the old knowledge; the old view of changed files stays in the seed. When outdated material becomes confusing, or a new wave needs different groundwork, the architect primes a clean seed from current code. Refresh when useful, rather than after a fixed number of issues.

The quality pipeline: docs, tests, code, adversarial review

The issue's Completed section is the contract. The architect chooses a suitable team and sequence of assignments to satisfy it, including dedicated spec or test writers when useful. The diagram shows a full test-first example, not a requirement to create a separate agent for every box. The quality floor stays: evidence of the agreed behavior, protected existing tests, the project gate and independent review.

flowchart TD
  DW(["Issue Completed criteria, already agreed"]) --> SPEC["1. Docs and tests:
update the canonical docs,
write tests proving each completion criterion"]
  SPEC --> TREV(["2. Test review: do docs + tests
prove each completion criterion?"])
  TREV -->|"gaps"| SPEC
  TREV -->|"yes"| LOCK["3. Lock: commit spec(#n),
docs + locked tests"]
  LOCK --> CODE["4. Implementation:
make the locked tests pass,
full project gate green"]
  CODE --> AREV(["5. Adversarial review:
independent reviewer + Codex on evidence"])
  AREV -->|"real findings"| CODE
  AREV -->|"pass"| CHECK(["6. Architect verifies: criteria met,
test integrity and review evidence"])
  CHECK -->|"ok"| DONE["Issue done, comment on the issue"]
  CHECK -->|"gap, first time"| CODE
  CHECK -->|"second failure"| PARK["Parked for the human"]

When a separate spec writer helps

A separate spec writer can concentrate on the agreed behavior while the coder concentrates on implementing it. A shared seed avoids repeating their common codebase exploration, but each role still does real work. The architect decides whether that separation pays off for the assignment. Whoever writes the tests, review them against the issue's Completed criteria and preserve them during implementation. A test that is genuinely wrong needs an explicit, reviewed correction.

How deep the final review goes (the architect decides, above a floor)

How the architect orchestrates

• Sequence by default. One issue at a time, each to 100%, following the epic's dependency graph (an issue starts when its blockers are done).
• Parallel when it pays. Independent issues can run in separate worktrees; check shared contracts as well as file overlap. Each lane can have its own seed. Integration follows the owner's merge permissions.
• Choose the right agents. Fork prepared workers, resume related work or start fresh specialists on a suitable model. Feed useful shared findings into the next seed.
• Own the result. Verify the issue end-states and the combined behavior specified by the epic or integration issue. This is part of the architect's existing job.

How cost stays under control

What stays with the human

• Before: the epic and issues' agreed Completed criteria, taste calls and consequential design choices. These give the architect a clear outcome to pursue while the owner is away.
• During: only parked decisions that are truly irreversible, or truly about taste, money or scope.
• After: walking the result on a real device, and the go to push.

This is the real ceiling of the whole approach: not run length, but the share of work only a human can call "done", and how late they see it.

Running it for real

Example briefs and command sketches for the pilot, using off-the-shelf tools: Claude Code 2.1.289 on a Claude Max plan (desktop app plus the claude command line), GitHub, and the Codex CLI as the second-family reviewer. No new software.

The graph we are building

An epic is a graph of issues with "blocked by" edges. The orchestrator walks waves; inside a wave the architect walks issues whose blockers are done; inside an issue the architect chooses the assignments. Each node is checked against its agreed Completed criteria.

flowchart TD
  w1["Wave 1 done"] --> w2["Wave 2: its architect takes over"] --> w3["Wave 3 next"]
  w2 --> s1[("Seed v1")]
  s1 --> na["Issue A"]
  s1 --> nb["Issue B"]
  na --> nc["Issue C, blocked by A"]
  s2[("Seed v2, refreshed after A and B")] --> nc
  nb --> nd["Issue D, new, surfaced in B"]
  nc --> p1["Docs + tests"] --> p2["Test review"] --> p3["Lock"] --> p4["Code"] --> p5["Adversarial review"] --> p6["Architect verifies"]

Before you start

Keeping headless workers out of the memory system

Many long-running setups pair agents with a persistent memory: a hook that captures every finished session and summarizes it into searchable notes. Ours, cc-memory-bridge, captures sessions on Claude Code's SessionEnd hook. That is exactly right for human conversations and exactly wrong for workers: a wave of ten workers plus a seed would leave eleven junk summaries, and over an epic it would drown the real ones.

Headless workers still need the user's settings (the cache setting, permissions, tools), so the hooks cannot simply be turned off. The fix already existed: the bridge's capture step exits silently when CC_MEMORY_BRIDGE_SUBPROCESS=1 is set. It was built so the summarizer's own claude -p calls do not capture themselves; every seed and worker command sets it too. The first trial must confirm that these workers are not captured. Any memory or logging layer used with this design needs the same kind of switch.

Step 0: the human and the agent, together

Use the existing GitHub issues: their Completed sections already describe the end-states discussed with the owner. Check that they and the epic cover the combined behavior, settle any remaining owner decisions, then work against those criteria. There is no extra completion document or approval layer. New necessary work inherits the approved goal; new product scope goes back to the owner.

## Completed (agreed end-state)
1. [test] ... a behaviour a test can prove ...
2. [test] ... another one ...
3. [docs] ARCHITECTURE.md describes the new behaviour.
4. [human] (only if it truly needs the owner's eyes) ...

Step 1: the orchestrator prompt

Pasted into a new desktop chat (Opus, high effort). It carries the architect brief, so the architect never depends on the orchestrator's paraphrase.

You're the ORCHESTRATOR for epic <org>/<repo>#<epic>. Read the epic's "Status + start here" block and its latest comment first.

You are a scheduler, not a builder: you never read code, never write it, never run the test suite. You keep the lights on for the whole epic, so keep your own context small - the wave list, which architect is running, and one paragraph per finished wave.

For each wave, in order: start ONE architect (a helper agent, Opus, high effort) and give it the ARCHITECT BRIEF below word for word, with the wave, its issues and the folder filled in. Wait for its WAVE DONE / WAVE BLOCKED report, post one line here, update the epic's latest comment (done, verified, next), then start the next unblocked wave's architect. Keep the epic sufficient for a replacement orchestrator to resume after an interruption.

I'm away: decide like the owner. Write each decision and its reason on the issue. Only stop for something truly irreversible or that truly needs my call - park it as a needs-decision issue and keep going with everything that can move.

Nothing is pushed, merged or deployed until I say so.

[ARCHITECT BRIEF]
[SPEC WRITER BRIEF] [CODER BRIEF] [REVIEWER BRIEF]
[the owner's "How we work" rules, word for word]

Step 2: the architect brief

You are the ARCHITECT for Wave <N> of epic <org>/<repo>#<epic>: issues <list>. Folder: <path>, branch <branch>. You own a working, coherent wave. Delegate implementation and keep your context focused on reports, issue state and decisions; inspect specific code when a decision needs it.

1. START FROM THE OUTCOME. Read the issues' Completed sections and the epic's agreed goal. Work in dependency order, normally one issue at a time. Keep work that depends on a parked decision blocked.
2. CHOOSE THE TEAM. Prepare a seed for shared groundwork (SEED command); record its session id and commit on the epic. Fork workers when that preparation helps. Use fresh specialists on suitable models, or resume related work, when that fits better. Separate worktrees for genuinely independent parallel work; respect the owner's merge permissions.
3. BUILD AND VERIFY. Choose the assignments: for example docs and tests, test review, implementation, adversarial review. A dedicated test writer may cover an issue or a wave. Preserve locked tests and the agreed spec; require the project gate and a Codex review, with full adversarial review for contracts, schema, security, auth, money, user-facing flows, large changes and retries. Verify evidence against the Completed criteria, not just the worker's report. Added tests are welcome; weakened assertions or skipped checks are not. If a test is genuinely wrong, have its correction reviewed explicitly.
4. KEEP THE SEED CURRENT. When shared facts change, fork the seed and have it review the relevant developments (REFRESH command). Its updated session becomes the next seed. Rebuild from current code when obsolete history becomes confusing. Keep worker-specific debugging out of the seed.
5. OWN WHAT SURFACES. File and handle missing work needed for the agreed goal. Park new product scope or decisions that truly need the owner. A failed assignment gets one informed retry; a second failure is parked with evidence. Confirm the previous worker has stopped before starting a replacement.
6. WAVE DONE. Verify the combined result against the epic or integration issue as well as the individual issue criteria. Report in at most 5 lines: WAVE DONE or WAVE BLOCKED, issues done and parked, new issues, commits and verification evidence. Keep the details on the issues.

Step 3: the commands

These commands illustrate the seed-and-fork path; fresh agents use the architect's chosen model and brief. Run a fork chain in the same folder on the same model for cache reuse. CC_MEMORY_BRIDGE_SUBPROCESS=1 opts these sessions out of memory capture. Launch long workers with the tool's background mode and keep its task handle; the shell command below does not background itself.

SEED (prime once per wave)

cd "<wave folder>" && mkdir -p runs
export CC_MEMORY_BRIDGE_SUBPROCESS=1
SEED=$(claude -p --model opus --permission-mode bypassPermissions --output-format json \
  "You are the SEED for Wave <N> of epic <org>/<repo>#<epic>. Read, and change nothing: the epic and its latest comment (gh issue view <epic> --comments), the wave's issues <list>, docs/ARCHITECTURE.md, the area guide, and the relevant code shared by the planned assignments. Learn the conventions and the primitives. Reply only: READY at $(git rev-parse --short HEAD)." \
  < /dev/null | python -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
echo "$SEED"

WORKER (spec writer, coder or seed-fork reviewer: one command, a different brief)

cd "<wave folder>" && CC_MEMORY_BRIDGE_SUBPROCESS=1 claude -p \
  --resume "<seed id>" --fork-session --model opus \
  --permission-mode bypassPermissions --output-format json \
  "$(cat runs/brief-<n>-<role>.md)" < /dev/null > runs/<n>-<role>.json 2> runs/<n>-<role>.err

WAIT

Wait for the background task to finish, then check its exit status and parse its result for success or error. A nonempty output file is not proof of completion. If a wait times out, check the existing task before retrying; never start a second writer while the first may still be running.

REFRESH (fork the seed, let it catch itself up, use it as the new seed)

cd "<wave folder>" && NEW=$(CC_MEMORY_BRIDGE_SUBPROCESS=1 claude -p \
  --resume "<seed id>" --fork-session --model opus --permission-mode bypassPermissions --output-format json \
  "You are being refreshed into the new seed. Run git diff <seed commit>..HEAD --stat, read the changed files that matter, and read these reports: <issue numbers or files>. Change nothing. Reply only: READY at $(git rev-parse --short HEAD)." \
  < /dev/null | python -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
echo "$NEW"   # from now on, fork this id instead of the old one

A refresh reuses the earlier preparation and adds the relevant changes. After checking its result, record the new seed id and commit for later forks. The old seed stays untouched. Cached input still has a read cost; the saving comes from avoiding repeated exploration and reconstruction of the same groundwork.

Step 4: example role briefs

Use these when the architect chooses separate roles. Scope a brief to the issue or wave it owns. For a fresh agent, replace the seed-commit instruction with targeted onboarding; every agent still reads its current issue criteria and relevant changes.

SPEC WRITER

You are the SPEC WRITER for issue <org>/<repo>#<n>. Your view of the code is from commit <seed commit> - first run git diff <seed commit>..HEAD --stat and read what changed that touches this issue. Read the issue and its comments: its Completed section is the contract.

1. Docs first: update the canonical docs so they describe the behaviour this issue must have.
2. Tests: write tests that prove each completion criterion against those docs. For missing behavior, demonstrate a failure for the intended reason before implementation; preserve checks for behavior that already works.
3. Do not write implementation code.
4. Reply in at most 200 words: the docs changed, the tests added, which completion criterion each test proves, anything unclear you decided and why.

CODER

You are the CODER for issue <org>/<repo>#<n>. Your view of the code is from commit <seed commit> - first run git diff <seed commit>..HEAD --stat and read the relevant changes, current docs and tests. The spec is locked at commit <lock commit>: the docs and tests there define done.

1. Make the locked tests pass and the full project gate green. You may ADD tests; you may not weaken or edit a locked test or the spec docs. If one is truly wrong, stop and say why in your report.
2. Clean, DRY, reuse and grow existing primitives - never a one-off. Use helpers as you see fit (any model) for research or grunt reading.
3. Commit. Post a comment on the issue: what changed, the commits, the test numbers.
4. Reply in at most 300 words: DONE / BLOCKED / FAILED, the final commit, the issue comment link, new issues worth filing, anything the seed got wrong.

REVIEWER (seed fork or fresh; Codex gets the same request)

You are an adversarial reviewer for issue <org>/<repo>#<n>. You change nothing and start no agents. You are given the issue completion criteria, the locked spec (docs + tests at <lock commit>) and git diff <lock commit>..HEAD.
Check the agreed end-state against the current implementation and evidence: PASS or FAIL per line with evidence (file:line, test name or command output). Then list any other real problem with its severity: correctness, security, duplication of an existing primitive, docs out of step with code. Resolve findings through evidence, never unsupported reassurance. Check the running behavior when the criteria require it.

What the human sees

• In the orchestrator chat: one line per finished wave, then a final report: issues done, issues parked, new issues filed, the branch, nothing pushed.
• In the issue tracker: the epic's latest comment (done, verified, next), each issue's spec and coder comments, a short needs-decision list.
• Their part: answer the parked decisions, walk the result, say "push".

The real limits

The trial

1. When: after the current epic run finishes (nothing about a running epic changes mid-run).
2. What: one wave of the next epic, the issue completion criteria already agreed.
3. First checks: background workers and the wait work from inside an architect; forks read the seed from cache; nothing lands in the memory system.
4. Measure: total usage per accepted issue against our baseline, time spent catching up, the leads' context sizes, review findings and human repair time. Confirm the final result satisfies the issue and epic criteria.
5. If it holds: try a larger run before making it the default for large epics.

For reviewers: attack this

We want this design taken apart before we rely on it. Below: what is measured versus assumed, the weak spots we already see, and the specific questions we most want challenged. Where you think we are wrong, say why, and point at evidence if you have it.

Measured, tested, or assumed

Weak spots we already see

Questions we most want challenged

1. Static seed versus a living expert. For workers sharing groundwork, how much repeated exploration does a prepared seed avoid? When should the architect choose a fresh agent or resume an existing one instead?
2. Is the architect a middle layer in disguise? The evidence says middle layers cost the most and help the least. We kept one per wave because without it the scheduler drowns in detail. Is there a better split?
3. Spec writer separate from coder: for which assignments does the separation improve results enough to justify the extra work?
4. Reviewer independence: is a fork of the same seed independent enough to be an adversarial reviewer, or must the judge always start fresh?
5. Refresh cadence: what signal should trigger a refresh, and when does a refreshed seed become worse than a clean one?
6. Parallelism: we default to one issue at a time. Where would you parallelize, and how would you handle merges without a costly integrator agent?
7. Measuring "green but wrong": what metric would show that the pipeline catches work that passes tests but misses intent?
8. Failure modes we have not imagined: what breaks first at 50 issues? At 200?

Sources

• Chroma, "Context Rot" (2025). Du et al., EMNLP Findings 2025, arXiv 2510.05381. Laban et al., arXiv 2505.06120.
• Factory, "Evaluating context compression" (Dec 2025). Codex GitHub issues on post-compaction loss.
• METR time-horizon data (2026); METR, "Towards reconciling slowdown with time horizons" (Aug 2025).
• ImpossibleBench, arXiv 2510.20270. TDFlow, arXiv 2510.23761.
• MAST, "Why Do Multi-Agent LLM Systems Fail?", arXiv 2503.13657. Google/MIT on agent scaling, arXiv 2512.08296.
• Anthropic engineering: multi-agent research system; effective harnesses for long-running agents; harness design for long-running apps; building a C compiler with agents. Cursor, "Scaling long-running autonomous coding" (Jan 2026). Cognition, "Don't build multi-agents" and "Multi-agents: what's actually working" (2026). OpenAI, long-horizon Codex runs. Geoffrey Huntley on Ralph; RepoMirror; DoltHub on Gas Town.
• Claude Code documentation: sub-agents and forks, prompt caching, agent teams, desktop scheduled tasks.
• Our own figures: transcripts of one epic run, 12 Oct 2026, analysed with our scripts.