Related lectures: Lecture 05. Keep context alive across sessions · Lecture 06. Initialize before every agent session Starter kit (task prompt, this project's real feature list, and the restart/handoff harness files, no application source) included in the course Template Pack. Download it from your account page.

Project 03. Keep the Agent Working Across Session Restarts

Illustrative composite. A logistics-dashboard team hit this twice in one quarter. An agent session ended with the chunking feature half-built, marked active only in the agent's own reasoning — no file said so. The next session had no memory of any of it: it re-profiled data that had already been profiled and rebuilt a chunking approach the first session had already tried and rejected, burning roughly ninety minutes redoing work that existed, unfinished, in the working tree the whole time. The second time it happened, the redone version diverged just enough from the first attempt that reconciling the two cost more than either session's actual coding did.

Decide now: what needed to survive that restart, and where should it have lived?

What You Do

Add scope control and verification gates to the agent. Implement document chunking, metadata extraction, indexing progress display, and citation-based Q&A flow. Use feature_list.json to track feature status: one feature at a time, no marking as "pass" without verification evidence.

You compare the checked-in starter and solution: the starter has only the early tracking surface, while the solution adds the stricter restart and handoff artifacts around the same feature list.

Tools

• Claude Code or Codex
• Git
• Node.js + Electron

Harness Mechanism

Progress log + session handoff + multi-session continuity + one-feature-at-a-time verification

Use the Checked-In Project

Suggested workspace: projects/project-03/ in your own practice repo. Build the layout below as you work.

Directory	What it contains	What to compare
starter/	Project 02 code with indexing and grounded QA still unfinished. It has a starter feature_list.json, but lacks the final restart/handoff artifacts.	Whether the agent drifts across multiple features or loses state after a restart.
solution/	Completed chunking, metadata, index status, and citation-based QA, plus init.sh, session-handoff.md, claude-progress.md, and clean-state-checklist.md.	Whether each feature has concrete verification evidence before it is marked passing.

This project is not a generic "multi-session" exercise. The checked-in solution maps to four specific product features: document chunking, metadata extraction, indexing status UI, and grounded Q&A with citations.

Brief

The starter workspace (starter/) is Project 02's app with indexing and grounded QA still unfinished, and only a starter feature_list.json; the solution workspace adds init.sh, session-handoff.md, claude-progress.md, and clean-state-checklist.md around the same four features.

Run one continuous task across three real session restarts, held to Lecture 05's continuity rule and Lecture 06's clock-in/clock-out routine. Concretely: pick one feature at a time from the list, never two active at once, work it until you would naturally stop, deliberately end the session there — close the terminal, don't just pause — and force the next session to run the full clock-in routine before touching code.

Full inputs given: the four features above, the starter feature_list.json's four rows (one per feature, initially not_started), and the restart trigger you must use exactly: restart after a feature reaches active status but before it reaches passing, an interruption you engineer on purpose, not one you wait to stumble into.

diagramsource

drawing

The Rule This Lab Tests

Use the full clock-out ritual — update feature_list.json, write session-handoff.md, commit — whenever a feature will still be active, not passing, when the session ends. Skip the ceremony only when a feature starts and finishes inside a single sitting; there is no state to hand off if nothing was left open. The matching clock-in half (read both files before touching code) is unconditional: it costs seconds, and the one time you skip it is the time a restart lands mid-feature.

Session outcome	Protocol needed	What happens without it
Feature reaches passing before you stop	A commit is enough; nothing to hand off	Nothing — there's no open state to lose
Feature still active when you stop	Full clock-out: update the feature row, write the handoff note, commit	Next session re-derives the missing context, or repeats work already done
Restart lands mid-active-feature	Full clock-in: read both files before any code changes	Two features end up active at once, or finished work gets redone from scratch

Steps

1. Run session 1 against starter/. Pick document chunking as the active feature. Work until it is roughly half-built, then stop deliberately — do not finish it. Output: a working tree with chunking half-implemented, feature_list.json's chunking row still active.

2. Restart cold, no briefing, and run the clock-in routine. Before touching any code, decide: does chunking sitting active and half-built mean the new session should resume the existing code, or discard it and start clean?

   Read feature_list.json for current state, run whatever check command exists, and continue only from what the repo says. Output: session 2 either finishes chunking or doesn't — record which, and why.

3. Clock out deliberately before session 2 ends. Update feature_list.json's state, write what's done and what's next into claude-progress.md, and commit. Output: a real clock-out artifact, not a session that just runs out of turns.

4. Restart a second time and move to metadata extraction and indexing status. Same clock-in discipline: read state, verify, continue. Output: two more feature_list.json rows moved from not_started toward passing, one feature at a time.

5. Restart a third time for citation-based Q&A, the feature most likely to reveal a lost decision (why citations are attached the way they are). Output: the fourth row moved to passing, with session-handoff.md updated at every restart boundary in between.

6. Write the continuity log. For each of the three restarts: what the new session correctly resumed, what it had to re-derive, and how long re-deriving took. Output: harness/p03-continuity-log.md.

7. Stretch goal — run it once on your own repository. Pick a real feature you're currently building outside this course, not the checked-in starter or solution. Engineer one restart mid-feature against your own tracking file (add a minimal one if you don't have one yet), and run the same clock-in/clock-out discipline. No checked-in reference this time; your own continuity-log entry is the only evidence it worked.

Acceptance

• Exactly one feature_list.json row is active at any time; never two.
• Three real session restarts happened — new conversations, not one long conversation with pauses.
• Each restart's clock-in read feature_list.json and session-handoff.md before any code was touched.
• Each restart's clock-out updated both files and left a git commit before the session ended.
• harness/p03-continuity-log.md records, per restart, what was correctly resumed and what had to be re-derived.
• No feature is marked passing in feature_list.json without the verification evidence that earned it.

Rubric

Criterion	Weak	Strong
Restart discipline	"Restarts" are pauses in one long conversation	Three genuinely separate agent sessions, each clocking in and out
State handling	feature_list.json shows two features active at once, or a passing row with no evidence	One active feature at a time; every passing row backed by a recorded check
Continuity log quality	"Session 2 picked up fine," no specifics	Names exactly what was re-derived versus resumed, per restart
Handoff completeness	session-handoff.md updated once, at the end	Updated at every clock-out, distinguishing completed from broken/unverified work

Key Takeaways

• Hold exactly one feature active at a time across all three restarts.
• Force a real clock-in read before touching any code, every restart.
• Clock out deliberately: update state files and commit before the session ends.
• Never mark a feature passing without the verification that earned it.
• Log what each restart correctly resumed versus what it had to re-derive.

What You Have Now

One task carried across three deliberate session restarts without losing state. harness/p03-continuity-log.md sits beside harness/continuity.md and harness/init.sh from the two lectures behind it, and is the first proof that the clock-in/clock-out routine survives more than one boundary, not just the single restart it was designed against. It sets up the runtime-observability project next, which assumes state already survives restarts before it adds logs on top.