Long-Running Agent Harnesses: Sessions, Memory, and Incremental Progress

Multi-day agent projects fail when each context window starts cold—initializer vs coding sessions, feature JSON on disk, and E2E verify before passes flip beat bigger windows…

Watch

Watch on YouTube

Also on our YouTube channel.

Executive Summary

Multi-day agent projects fail when each context window starts cold—initializer vs coding sessions, feature JSON on disk, and E2E verify before passes flip beat bigger windows alone.

---

At a Glance

Who this is for: Teams whose agent work outlives a single context window—multi-day refactors, greenfield apps, migration backlogs—not engineers optimizing one IDE session.

If you already ship verify-first gates in the coding harness, this is the next failure mode: amnesia. Each fresh session starts cold. The model one-shots until context overflows, declares victory on half-finished work, or marks features "done" after unit tests while the UI is broken [1].

Anthropic's answer is not a bigger window alone—it is a harness pattern that externalizes memory: initializer vs coding sessions, progress artifacts on disk, JSON feature truth, and browser E2E before passes: true [1][2]. This playbook maps that pattern to Monday-morning operator rituals and production parallels (LangGraph checkpoints, Decision Ledger fields).

Figure 1: Same harness, two session entry prompts

Initializer seeds artifacts once; every coding session replays the getting-up-to-speed ritual.

---

The Amnesiac Agent Problem

Long-running agents fail in predictable ways when progress lives only in the model's context [1][10]:

• Failure mode: One-shotting · What goes wrong: Agent tackles the whole backlog in one session; context overflows mid-implementation · Operator signal: Giant diffs, incomplete branches, no commit boundary

• Failure mode: Premature victory · What goes wrong: New session reads partial progress and concludes the project is finished · Operator signal: "Done" messages while features.json still has passes: false

• Failure mode: Localized-only testing · What goes wrong: Unit tests or dev-server checks pass; integration/UI fails · Operator signal: Green CI, broken demo in browser

• Failure mode: Messy handoff · What goes wrong: Undocumented state, conflicting files, no progress log · Operator signal: Next session cannot replay from git + logs

Composite vignette: A platform team ran Claude Code across a five-day auth refactor. Session three restarted after a laptop sleep; the agent summarized two merged PRs as "project complete" and skipped OAuth callback wiring. Session four rediscovered the gap only when a Puppeteer smoke test failed—after twelve hours of false confidence. Illustrative composite patterned on Anthropic failure-mode taxonomy [1].

These are assurance failures, not model IQ failures. They respond to structure before bigger models. The pattern mirrors distributed systems: stateless workers need an external store. Agent sessions are stateless; the repo is the store.

---

Initializer vs Coding Sessions

Anthropic uses two labels—initializer agent and coding agent—but the harness is identical: same system prompt, tools, and policy. Only the first user message changes [1]. Anthropic notes these are separate "agents" in documentation only because the entry prompt differs—the system prompt, tool surface, and overall harness stay the same [1].

• Session type: Initializer · When: Once, at project start · First-turn intent: Bootstrap environment, feature backlog, progress log

• Session type: Coding · When: Every session after · First-turn intent: Replay state, pick one feature, increment, hand off cleanly

Initializer must produce:

• Artifact: init.sh · Role: One-command environment bootstrap (deps, dev server)

• Artifact: claude-progress.txt · Role: Human-readable session log—what happened, what's next

• Artifact: features.json · Role: Priority-ordered backlog; each item has passes: true/false

The coding agent never re-scopes the whole project. It inherits the contract the initializer wrote to disk [1][3].

Starter `features.json` shape (schematic—adapt ids to your repo):

{
 "features": [
 { "id": "auth-oauth", "priority": 1, "passes": false, "notes": "OAuth provider wiring" },
 { "id": "auth-callback", "priority": 2, "passes": false, "notes": "Callback route + session" },
 { "id": "dashboard-shell", "priority": 3, "passes": false, "notes": "Layout + nav only" }
 ]
}

Treat priority as immutable unless a human reprioritizes. Backlog truth lives in JSON—not in chat memory.

Prompt templates (operator starting points):

• Initializer: "You are the initializer session. Create init.sh, claude-progress.txt, and features.json covering the full project scope. Do not implement features yet—only scaffold and document the backlog."

• Coding: "You are a coding session. Run the getting-up-to-speed ritual, implement exactly one highest-priority feature where passes is false, run verify scripts, update logs, commit, and leave a clean tree."

Store templates in .cursor/rules, Claude Agent SDK config, or your harness repo—version them as policy_version [3][9].

Figure 2: Externalized backlog beats in-context task lists

No feature flips to `passes: true` without your verify gate—see next section.

---

Environment Management: One Feature Per Session

Incremental progress is a discipline, not a suggestion. Anthropic's coding prompt encodes a ritual—getting up to speed—before any edits [1]:

1. Run pwd; confirm directory boundary (agents edit only what they should).

2. Read git log and claude-progress.txt.

3. Open features.json; select the highest-priority item where passes is false.

4. Implement that feature only; commit with a message that references the feature id.

5. Update claude-progress.txt before session end.

This pairs naturally with context engineering for operators: compaction and subagents manage within-session budget; feature JSON manages across-session scope [8].

Operator rule: If a session closes without a git commit and progress-line entry, treat the next session as contaminated—replay from last known good commit before continuing.

Git as session memory

Git is not optional decoration—it is the diffable audit trail between amnesiac sessions [1]. Minimum bar:

• Git practice: One feature per branch or atomic commits on main · Why it matters: Bisect when a session introduces regressions

• Git practice: Commit message references feature id · Why it matters: Progress log + git log --grep become searchable

• Git practice: No force-push on shared agent branches · Why it matters: Replay and rollback stay trustworthy

• Git practice: Tag initializer commit · Why it matters: git diff initializer..HEAD shows total agent scope

Pair with context engineering for operators: when a single session still grows large, compact within the session—but never substitute compaction for writing progress to disk [8].

---

Verify Across Sessions: Rules Before Self-Report

Per-turn verify belongs in the verify-first coding harness. Long-running work adds a session-boundary verify layer [1][2][6]:

• Verify layer: Unit / lint · What it checks: Fast feedback inside the feature

• Verify layer: Browser E2E (Puppeteer, Playwright) · What it checks: UI flows end-to-end—catches "localized-only" false greens

• Verify layer: Feature JSON gate · What it checks: passes: true only after E2E script exits 0

• Verify layer: Git + progress log · What it checks: Next session can reconstruct intent

Anthropic observes agents mark work complete after unit tests or direct server calls while the full user journey still fails [1]. Browser automation is slower—but it is rules-based verify, aligned with the hierarchy in Building effective agents: schema and environment truth before LLM self-report [2][6].

Wire E2E into CI when the feature list stabilizes; until then, a single e2e.sh the agent must run before flipping passes is enough for pilot teams.

Puppeteer and browser verify

Anthropic's reference harness uses browser automation so agents see what users see—not only what unit tests assert [1]. Practical rollout:

1. One golden path per feature (login → action → confirmation).

2. Headless in CI, headed locally when debugging agent confusion.

3. Screenshot on failure checked into claude-progress.txt or CI artifacts—not into chat alone.

4. Fail closed: script non-zero exit blocks passes: true in features.json.

This is the session-boundary cousin of verify-first rules inside the IDE loop [7]. Together they form a defense in depth: per-turn gates for tool writes, session gates for "done" claims.

---

Production Parallels: Checkpoints and Ledger

The filesystem pattern is a poor person's checkpoint store. In production graphs, use the same semantics with durable IDs [4][5][9]:

• Harness artifact: features.json · Production analog: Workflow backlog / state machine nodes

• Harness artifact: claude-progress.txt · Production analog: Decision Ledger narrative per transition

• Harness artifact: thread_id · Production analog: LangGraph thread_id with PostgresSaver—not MemorySaver [4]

• Harness artifact: policy_version · Production analog: Bundle version on promote/hold gates

The production loop agents and ML share already maps gather → act → verify → repeat across vendors. Long-running harnesses are that loop with explicit memory between iterations—whether files in a repo or checkpoints in Postgres [5][9].

When to graduate from files to PostgresSaver

• Stage: Pilot · Memory model: features.json + progress log in repo · Good for: Single team, single app, <2 week agent projects

• Stage: Team scale · Memory model: LangGraph thread_id + PostgresSaver [4] · Good for: Multiple operators, regulated promote/hold

• Stage: Platform · Memory model: Decision Ledger + segment gates [9] · Good for: Cross-service agent workflows, FinOps attribution

LangGraph persistence docs emphasize that in-memory savers are for development only—production requires durable checkpoints keyed by thread_id [4]. Map each coding session to a graph step or sub-graph invocation; the feature list becomes nodes, E2E verify becomes an edge guard.

Composite vignette: A neobank platform team ran file-based harnesses for three sprints, then promoted to PostgresSaver when two engineers concurrently drove the same thread_id through different features. Checkpoint conflicts dropped to zero after serializing "one active feature per thread" in graph routing—mirroring the JSON backlog rule on disk. Illustrative composite.

---

Learn Next

1. Prerequisite: Coding with Agents: The Verify-First Harness — per-turn gates before multi-session scale.

2. Platform scale: The production loop agents and ML share — PostgresSaver, segment gates, FinOps.

3. Practice path: Agentic AI in Production — red-teaming lab after agent-assisted changes.

---

Key Takeaways

• Bigger context ≠ memory — externalize backlog, progress, and verify state to disk or checkpoints.

• Initializer once, coding many — same harness; different first user prompt.

• One feature per session — defeats one-shotting and premature victory.

• E2E before `passes: true` — unit tests alone invite false greens.

• Git + progress log — every session must leave a replayable handoff.

• Production mapping — thread_id, PostgresSaver, policy_version on the Decision Ledger.

---

References

1. Anthropic. (2025). Effective harnesses for long-running agents. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

2. Anthropic. (2024). Building effective agents. https://www.anthropic.com/research/building-effective-agents

3. Anthropic. (2025). Building agents with the Claude Agent SDK. https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk

4. LangChain. (2025). LangGraph persistence. https://langchain-ai.github.io/langgraph/concepts/persistence/

5. The AI Operator. Agent orchestration stack. https://www.theaioperator.net/articles/operator-production-loop-agents-ml

6. The AI Operator. Anthropic agent loop (reference). https://www.anthropic.com/research/building-effective-agents

7. The AI Operator. Coding with Agents: The Verify-First Harness. https://www.theaioperator.net/articles/coding-with-agents-verify-first

8. The AI Operator. Context Engineering for Operators. https://www.theaioperator.net/articles/context-engineering-memo

9. The AI Operator. The production loop agents and ML share. https://www.theaioperator.net/articles/operator-production-loop-agents-ml

10. Google NotebookLM. Effective Harnesses for Long-Running Agents. https://notebooklm.google.com/notebook/3c33ff8f-b6a9-4d68-ad34-bd9263a2aef1

---

Monday Morning Checklist

• [ ] Add `features.json` to your next multi-day agent pilot—every item starts passes: false.

• [ ] Split prompts — initializer template vs coding template; do not reuse one generic "build the app" message.

• [ ] Mandate the ritual — pwd, git log, progress file, pick one feature—before any edit in coding sessions.

• [ ] Block `passes: true` until a browser E2E script exits clean (Puppeteer/Playwright).

• [ ] Log `policy_version` on harness changes; pair filesystem handoffs with Decision Ledger rows for audit replay [9].

---

Editorial transparency. Essays at The AI Operator may use AI-assisted research, drafting, and editing tools under staff editorial review. Facts, figures, and recommendations are checked before publication; we correct the record when evidence changes. Questions: hello@theaioperator.net.

---

Published on [Substack](https://theaioperator2.substack.com/p/long-running-agent-harnesses).