Sessions, Persistence, Rewind, and Recovery.

The question: What must be stored to resume, inspect, compact, rewind, or reproduce an agent session?

Start from first principles

A session is a flight recorder. It preserves decisions and events well enough to investigate and continue, but it does not put the aircraft back into the exact same sky.

Durability changes the failure model of an agent. Without it, a killed process erases context and leaves mutations difficult to explain. With it, interruption can become a resumable transition.

The user guide describes per-project session directories under ~/.grok/sessions. JSONL streams preserve incremental events; summary and plan files expose current state; rewind and compaction artifacts connect recovery to prompt boundaries.

The engineering question is not only what is saved. It is which file is authoritative, what resume reconstructs, what rewind restores, and which effects stay outside the session envelope.

Build the smallest useful mental model

Separate durability from reversibility and reproducibility. Durability means evidence survives a process. Reversibility means selected state can be restored. Reproducibility means another environment can obtain the same result. A session helps all three but guarantees only its documented contracts.

Use append-oriented events as the causal log and summaries as indexes/projections. Never replace raw evidence with a compacted narrative when incident review needs exact tool output.

Bind resumed sessions to their original safety assumptions. The sandbox profile is persisted and cannot be changed on resume, preventing silent widening or incompatible narrowing.

Now open the hood

Only after the idea is clear does Mira open the source. She ignores most of the workspace and follows the few boundaries that must exist for this part of the story to work.

1. The next clue — Store sessions by project and ID

Mira now needs one small mechanism: Each workspace needs a stable directory and unique session identity.

She follows that responsibility into the repository. The guide documents encoded-cwd/session-ID directories beneath ~/.grok/sessions. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: Moving or cloning repositories can change identity assumptions; do not rely on path alone for audit provenance. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: User guide 17-sessions.md. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

2. The next clue — Use append-oriented JSONL

Mira now needs one small mechanism: Conversation and UI updates should persist incrementally instead of rewriting one fragile document.

She follows that responsibility into the repository. The session format includes updates.jsonl and chat_history.jsonl; the guide calls updates authoritative for resume. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: Disk-full or abrupt termination still requires validation and clear error reporting. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: Session guide file-format section. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

3. The next clue — Persist plans and control metadata

Mira now needs one small mechanism: Plan state, signals, feedback, compaction, and child sessions need durable artifacts beside chat.

She follows that responsibility into the repository. The guide lists plan.json, rewind JSONL, signals, feedback, checkpoints, and subagent folders. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: Artifacts can disagree after partial failure; loaders need ordering and authoritative-source rules. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: Session guide directory inventory. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

4. The next clue — Distinguish create, resume, and continue

Mira now needs one small mechanism: CLI flags must not silently upsert or overwrite a session.

She follows that responsibility into the repository. Headless -s creates a new UUID session; -r resumes an existing ID; -c continues the latest; fork creates a new lineage. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: Using an old assumption that -s resumes now produces errors; automation must follow current docs. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: Headless guide session-management section. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

5. The next clue — Compact as a checkpointed projection

Mira now needs one small mechanism: Context reduction should retain a recoverable raw history and record its summary boundary.

She follows that responsibility into the repository. Session folders include compaction checkpoints; the loop can auto-compact and the user can invoke /compact. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: The next model sees the projection, not raw detail; critical constraints need durable reinjection or artifacts. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: Session and compaction guides/source. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

6. The next clue — Capture prompt-level rewind points

Mira now needs one small mechanism: A selected prompt should map to before/after tracked files and a conversation boundary.

She follows that responsibility into the repository. RewindPoint stores prompt-indexed file state and /rewind restores files/truncates conversation. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: External or untracked effects remain; modifications made outside the agent can conflict with restoration. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: xai-grok-workspace/src/session/file_state.rs and session guide. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

7. The next clue — Handle interrupts with explicit exit semantics

Mira now needs one small mechanism: SIGINT/SIGTERM should cancel work, persist what is safe, and return distinguishable exit codes.

She follows that responsibility into the repository. The headless guide documents 130 for SIGINT, 143 for SIGTERM, session resume commands, and cancellation behavior. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: Automatically resuming every interrupted mutation can duplicate side effects; inspect last admitted tool state first. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: Headless guide interrupted-runs section. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

8. The next clue — Keep sandbox identity fixed on resume

Mira now needs one small mechanism: A session must not silently return under a broader OS capability profile.

She follows that responsibility into the repository. The sandbox guide says the starting profile is stored and differing resume profiles are refused. The important point is not the Rust syntax. It is ownership: this is where the system decides what crosses the boundary.

Then she tests the unhappy path: A changed custom-profile definition can still affect interpretation; pin configuration and start a new session when policy changes materially. If the model, operator, and saved session do not receive the same honest outcome, the mechanism is not yet trustworthy.

Source: User guide 18-sandbox.md, resuming sessions. Verified against Grok Build c68e39f60462f28d9be5e683d9cbe2c57b1a5027.

Mira runs the experiment — interrupt and safely resume a headless review

Reading source gives her a hypothesis. A small experiment tells her whether that hypothesis survives contact with a real workspace. Create a session, capture its ID early, interrupt a long read-only review, and resume only after inspecting state.

1. Use an isolated checkout and read-only tool set.
2. Start streaming JSON and capture the session ID/end/error events.
3. Send SIGINT through the CI cancellation mechanism.
4. Require exit status 130.
5. Inspect working tree and session tail.
6. Confirm no mutation-capable task remains alive.
7. Resume by explicit ID with a prompt that restates acceptance criteria.
8. Archive both event streams and final evidence.

grok -p "Audit this package and cite each finding." \
  --tools "read_file,grep,list_dir" \
  --output-format streaming-json
# After a controlled interrupt:
grok -p "Continue the audit; first summarize persisted state." --resume "$SESSION_ID"

What she learns. The control system must extract a real session ID from output. The example does not imply an ID exists before session creation succeeds.

That last check matters. Grok Build can expose a mechanism and report an observation; the repository, operating system, CI platform, and reviewer decide whether those observations prove the actual task succeeded.

The whiteboard test

Before Mira explains the chapter to her team, she reduces it to three questions: what owns the decision, what evidence comes back, and what changes when the mechanism fails?

Review question	Source-backed answer	Operational consequence
What is authoritative?	Append-oriented updates for resume; summaries are projections.	Keep raw logs.
What resumes?	Conversation/session state under the same profile.	Restate acceptance conditions after inspection.
What rewinds?	Tracked files and conversation boundary.	Inventory external effects separately.
What reproduces?	Only what environment and artifacts make repeatable.	Pin dependencies and base SHA.

This is not a feature scorecard. A mechanism can work exactly as implemented and still be the wrong control for a particular threat. Defaults also change, so recheck the pinned source path before copying configuration into production.

Signals Mira keeps

• Session/project identity, base commit, creation/resume/fork lineage.
• Last complete JSONL event and flush outcome.
• Compaction/rewind point IDs and affected files.
• Interrupt signal, exit code, live task inventory, and resume decision.

Together, those signals tell a complete story: the model proposed an action, the harness admitted and routed it, the environment performed something, and a verifier measured the result.

Limits and uncertainty

The public repository is unusually detailed, but it is not the complete deployed product. The snapshot has one visible public commit, so it cannot support a rich historical explanation of why every boundary evolved. Hosted xAI model serving, account systems, and production topology remain outside this study. Where code and guide differ, this series gives the pinned implementation priority and marks documentation-only behavior instead of silently merging versions.

FAQ

Does -s resume?

No. In the researched guide it creates a new UUID session. Use -r or -c.

Is updates.jsonl a UI log only?

The guide describes it as authoritative for resume, making it part of runtime state.

Does rewind restore remote actions?

No. It targets tracked file and conversation state.

Can I resume with a different sandbox?

No. A differing profile is refused; start a new session.

Is compaction deletion?

It changes the model-visible projection while raw session artifacts/checkpoints support audit and recovery.

What changed for Mira

Mira distinguishes durable conversation state, workspace recovery, and full environmental reproducibility.

Next: Recovery is valuable only if dangerous actions were constrained before they happened.

Key takeaways

• Sessions are durable evidence bundles.
• Create, resume, continue, and fork have distinct semantics.
• Compaction is a lossy model projection over retained artifacts.
• Rewind covers tracked files and conversation, not the world.
• Resume should preserve original safety assumptions.

References & source notes

• Pinned Grok Build repository — default branch snapshot researched July 16, 2026.
• Grok Build README — first-party overview and source-build entry points.
• Session guide — format, resume, compact, rewind.
• Headless guide — session and interrupt semantics.

Freshness boundary. Grok Build claims in this article are pinned to c68e39f60462f28d9be5e683d9cbe2c57b1a5027. Pi comparison claims, where present, are pinned to 97f9978fa66685f78d2da19ae22e20c46d125f74; Hermes claims are pinned to c9c9bb33fcc6ab479846a1c496a6e9efe2c1c7d4. Recheck paths, symbols, commands, and defaults if those branches advance.