feat(session): durable save/resume via FileSessionStore

[divo12]

User description

Summary

Typed FileSessionStore / SessionSnapshot (transcript + tool-call records + cost) under DreamPaths.sessions_dir, wired through Session.snapshot / restore_from_snapshot and Harness.save_session / resume_session for cross-process resume.

Snapshots are private by construction — they contain full transcripts, so they're written atomic_write_text(..., mode=0o600) rather than at the default umask.

Resume also restores the session's shape, not just its messages: SessionSnapshot persists max_turns and JSON-compatible metadata, and resume_session rebuilds SessionOptions from them when the caller passes none. response_format and non-JSON metadata values are deliberately not serialized (they aren't JSON-representable) — the resume_session / Session.snapshot docstrings state that callers must pass those explicitly.

Type

• Bug fix
• Feature
• Refactor / docs / chore

Checklist

• Tests added or updated for behaviour changes
• tests/test_public_api.py updated if the public API changed
• CHANGELOG.md updated for user-visible changes
• No secrets, .env.local, or credentials in the diff
• Scope stays within dream (org/company features belong in sibling repos)

Test plan

• uv run pytest tests/test_services/test_session_store.py tests/evals/eval_session_save_resume.py — 17 passed
• New coverage: snapshot file mode is exactly 0o600, serializable options round-trip, non-JSON metadata excluded
• uv run ruff check src tests / uv run mypy
• CI: 3.11 / 3.12 / 3.13 green. The Python 3.14 job fails during uv sync --all-extras — librt==0.15.0 publishes no cp314 wheel or sdist — before any test runs. feat(observability): default-on OTLP export beside JSONL traces #93/feat(security): tool-call SecretProxy (placeholders + redact) #94/feat(tools): slim default registry to Level-2 coding surface #95 pass 3.14 with identical dependency declarations, so this is registry availability drift, not this diff; the job can't be re-run from the API.

Link to Devin session: https://app.devin.ai/sessions/4f7deb4af0914056a24a4d660a661713
Requested by: @divo12

---

CodeAnt-AI Description

Save and resume sessions across process restarts

What Changed

• Sessions can be saved to disk and resumed later with their transcript, tool calls, usage costs, and conversation state intact
• Resumed sessions create a fresh engine and continue from the saved conversation
• Model, system prompt, turn limits, and JSON-compatible metadata are restored automatically when no options are supplied
• Snapshots are written atomically with restricted file permissions, and unsafe session IDs are rejected

Impact

✅ Sessions survive process restarts
✅ Tool calls remain connected to their results
✅ Continued conversations retain prior history and usage costs

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[codeant-ai]

🤖 CodeAnt AI — Review Status

Status	Commit	Started (UTC)	Finished (UTC)
✅ Incremental review completed	a91922b	Aug 08, 2026 · 09:42	09:42
✅ Reviewed your PR	19d48f9	Aug 07, 2026 · 09:43	09:46

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[divo12]

@greptileai please review

[greptile-apps]

Greptile Summary

The PR adds durable, private session snapshots and harness APIs for saving and resuming conversations across process restarts.

• Serializes transcripts, paired tool-call records, usage cost, effective turn limits, and JSON-compatible metadata.
• Restores snapshots into newly created session engines while preserving conversation history and cost.
• Rejects unsafe session IDs and writes snapshot files atomically with owner-only permissions.
• Prevents snapshots during an active send and preserves the engine’s effective turn limit when no explicit session limit exists.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the effective turn-limit and snapshot-consistency issues from the previous review are addressed by persisting the bound engine’s resolved limit and synchronously rejecting snapshots while a send is active.

Important Files Changed

Filename	Overview
src/dream/session.py	Adds consistent snapshot creation and restoration, including effective turn-limit persistence, transcript sanitization, metadata filtering, and active-send rejection.
src/dream/harness.py	Adds configurable file-store resolution and high-level save/resume APIs that bind restored state to a fresh engine.
src/dream/services/session_store.py	Implements typed snapshot serialization, strict JSON decoding, safe session paths, atomic private writes, tool-call extraction, and cost conversion.
tests/test_services/test_session_store.py	Covers persistence, permissions, traversal rejection, option restoration, active-send rejection, tool-call integrity, cost restoration, and resumed execution.
tests/evals/eval_session_save_resume.py	Exercises cross-process transcript, tool-call, cost, and metadata restoration as an end-to-end correctness evaluation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Active Session] -->|snapshot when idle| B[SessionSnapshot]
    B -->|atomic JSON write, mode 0600| C[FileSessionStore]
    C -->|load by safe session ID| D[SessionSnapshot]
    D -->|restore options, transcript, and cost| E[Fresh Session Engine]
    E --> F[Continued Conversation]

Loading

_{Reviews (3): Last reviewed commit: "fix(session): stabilize snapshots for sa..." | Re-trigger Greptile}

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn