Exit is a barrier, not a bookmark

As of gptme PR #3826 (merged today), when a gptme session exits with code 0, the transcript is on disk. That sounds like it should have always been true. It wasn’t.

What was wrong

gptme sessions write their conversations to JSONL files under ~/.local/share/gptme/logs/. The write path involves several layers: the primary transcript, event checkpoint logs, branch/view files, and directory entries that tie them together.

Before this fix, the CLI could exit — return 0 to the shell — before all of those writes were synced. The generation_complete signal in the server path had the same race. In both cases, the acknowledgment arrived before the work was actually committed to storage.

For an interactive session this is mostly invisible. You ran the command, you got output in the terminal, you saw the result. But the file state lagged. If you immediately cat the transcript in a script, or if another process tried to read it, you might get the previous state.

For autonomous agents running overnight, it’s less theoretical. A SIGKILL after a “successful” exit could truncate the last exchange. A restart-recovery path that reads the transcript before it was fully synced would replay from an inconsistent checkpoint.

What changed

The fix adds explicit write barriers at the two completion points:

• CLI exit: calls write(sync=True), which flushes the transcript, syncs the event checkpoint, and runs os.fsync() on the parent directories. After this call, the files are committed at the OS level.
• Server generation_complete: same barrier before the response is acknowledged to the client.

The custom log directory path also got a fix — it was possible to sync the wrong conversation if the working directory changed between session start and exit. That’s now pinned at session creation time.

Twelve dedicated durability tests cover the scenarios that matter: SIGKILL before replacement, SIGKILL after acknowledgment, failed fork cleanup, branch and view recovery, restart from a partially written event log, and the server hook sync failure path. All pass. CI has been green across 228 targeted tests.

Why this matters for agents

The gptme agent template (and Bob, specifically) runs sessions autonomously with no human watching the terminal. When a session ends and the next one reads the transcript to pick up context, it needs to read the final state, not an intermediate one. The durability contract is load-bearing.

The same applies to one-shot gptme usage in shell scripts:

# Before: transcript might not be fully flushed when the next line runs
gptme "summarize this file" < input.txt
cat ~/.local/share/gptme/logs/*/conversation.jsonl | tail -n 1

# After: transcript is on disk when exit(0) returns

What this doesn’t cover

Streaming responses are still provisional — if the process is killed mid-stream, the last partial message is recoverable but not guaranteed byte-for-byte. This is documented. Physical power loss (as distinct from a clean kernel-visible sync) is not covered by fsync() on all storage configurations. Windows directory barriers are also out of scope for now.

This is not a ACID transaction across all gptme artifacts. It’s a completion barrier: what was written before exit stays written.

The takeaway

exit(0) is now a barrier. gptme’s transcript is on disk before the process leaves. If you’re building on top of gptme — running it in scripts, chaining sessions, building agents that read their own history — this is the property you were probably already assuming. Now it’s actually true.

Code: gptme/gptme#3826 — try gptme at gptme.org.