Multi-Session Continuity

Governed runs are not bound to a single process. You can start a run, close your terminal, and resume it hours or days later from a fresh session. State, history, decisions, turn sequence, and session checkpoints all persist on disk in .agentxchain/.

This is the foundation for long-horizon execution: runs that outlive any single operator session.

How It Works

AgentXchain stores governed continuity state in these files inside .agentxchain/:

File	Format	Purpose
state.json	JSON	Current run status, active turns, phase, gates
history.jsonl	JSONL (append-only)	Every turn assignment, acceptance, and state transition
decision-ledger.jsonl	JSONL (append-only)	Every governed decision across all turns
session.json	JSON	Latest checkpoint for cross-session restart
SESSION_RECOVERY.md	Markdown	Human-readable restart briefing generated after agentxchain restart

Because state is file-based and append-only, there is no in-memory state to lose when a process exits. Any fresh process that reads the same directory picks up exactly where the last one left off.

Restart After Losing Session Context

Use resume when you still have the run context and just need the next turn. Use restart when the session itself is gone: terminal closed, machine rebooted, agent crashed, or context was exhausted.

agentxchain status
# Surfaces the latest continuity checkpoint, exact next command, and checkpoint drift state

agentxchain restart
# Rebuilds session context from .agentxchain/state.json + .agentxchain/session.json

restart does not guess from memory. It reads the durable governed state, warns if session.json is stale relative to state.json, and writes .agentxchain/SESSION_RECOVERY.md so the next agent session has a briefing document instead of a cold start.

Pending gate preservation: if a phase transition or run completion is waiting for approval when restart runs, it surfaces the approval command and does not reactivate the run or assign a new turn. This ensures governance gates cannot be bypassed by restarting.

Repo-drift detection: restart compares the checkpoint's saved git HEAD, branch, and workspace dirty status against the current workspace. If anything has changed since the last checkpoint, it warns in both console output and the recovery report so the operator knows the codebase has moved.

Resume a Run

# Session 1: start a run and complete a turn
agentxchain resume --role pm
# ... agent does work, stages turn result ...
agentxchain accept-turn

# Session 1 ends (terminal closed, machine rebooted, etc.)

# Session 2: fresh process, same directory
agentxchain resume --role dev
# Run continues with the same run_id, full history intact

The resume command detects the existing run and assigns a new turn within it. It never creates a duplicate run.

What Is Preserved Across Sessions

• run_id — identical across all sessions for the same run
• Turn history — every prior turn's assignment and acceptance
• Decision ledger — every governed decision from every session
• Turn sequence — monotonically increasing; later sessions get higher turn numbers
• Phase and gate status — the run picks up in the same phase with the same gate verdicts

Recover From Blocked State

If a run is blocked (via escalation, hook failure, or governance barrier), recovery works across sessions:

# Session 1: something goes wrong
agentxchain escalate --reason "Need architecture review before proceeding"
# Run is now blocked. Session ends.

# Session 2: operator returns, resolves the issue
agentxchain resume
# Blocked state is cleared, run is active again

The decision ledger records both the escalation and the resolution as separate entries from separate sessions. Use agentxchain status at any time to see the current state and the exact recovery action.

Approve Phase Transitions Across Sessions

Phase exits can also cross session boundaries. A role can request the next phase in one process, and a human can approve that phase transition later from a fresh process:

# Session 1: PM finishes planning
agentxchain resume --role pm
# Agent stages turn result with phase_transition_request: "implementation"
agentxchain accept-turn
# Run pauses with pending_phase_transition set

# Session 2: operator returns in a fresh process
agentxchain status
# Shows: "Run agentxchain approve-transition to advance"

agentxchain approve-transition
# Run advances from planning to implementation

# Session 3: later fresh process resumes the next phase
agentxchain resume --role dev
# Run continues in the same run_id inside the implementation phase

This matters because phase approval is a governance boundary, not a side effect. Fresh-session approval proves the human can keep control even when work spans multiple terminals, reboots, or days.

Complete a Run Across Sessions

Run completion in AgentXchain requires explicit operator approval — this is a governance gate, not an automatic transition. The QA agent requests completion, and a human approves it:

# Session 1: QA agent finishes final review
agentxchain resume --role qa
# Agent stages turn result with run_completion_request: true
agentxchain accept-turn
# Run pauses with status: "paused", pending_run_completion set

# Session 2: operator reviews and approves
agentxchain status
# Shows: "Run completion pending. Use agentxchain approve-completion to finalize."

agentxchain approve-completion
# Run transitions to "completed". Final gate marked passed.

This separation ensures that no agent can unilaterally complete a governed run. The human retains final authority even when sessions span hours or days.

Invariants

These guarantees hold across any number of sessions:

1. Run identity — run_id never changes for a given run, regardless of how many sessions touch it
2. Append-only history — no session truncates or rewrites entries written by a prior session
3. Append-only ledger — same guarantee for the decision ledger
4. Monotonic turns — turn sequence numbers always increase; a later session cannot produce a lower-numbered turn
5. State consistency — state.json reflects the cumulative result of all sessions

Limitations

• Single operator — the file-based model assumes one operator at a time. Concurrent access from multiple processes writing simultaneously is not governed. (Future: file locking or hosted runner coordination.)
• Cross-machine continuity is narrow in this slice — use export + restore only when the destination is another checkout of the same repo at the same git HEAD.

Restore On Another Machine

You can now move governed continuity state from machine A to machine B without copying the entire directory, but the contract is intentionally strict:

1. The source repo must export a restore-safe run bundle.
2. The destination must be another checkout of the same repo at the same git HEAD.
3. Dirty source files outside the exported governed roots will block restore.
4. The input must be a governed run export; coordinator exports are valid for replay/reporting, not restore.

# Machine A
agentxchain export --output run-export.json

The export artifact includes workspace.git metadata showing:

• the source HEAD
• every dirty path
• whether restore is safe in this slice
• explicit blockers when it is not

# Machine B: same repo, same git HEAD, clean checkout
agentxchain restore --input /path/to/run-export.json
agentxchain resume

restore replaces the governed continuity roots (agentxchain.json, .agentxchain/**, .planning/**, TALK.md) from the export artifact, then resume continues inside the same run_id.

This is not a general source-sync system. If the source workspace changed product files outside those governed roots, the export remains valid for reporting and verification, but restore will fail closed and name the blocking paths. The same boundary applies to coordinator exports: they remain valid audit/report/replay artifacts, but they are not valid restore inputs.

Keep the command boundary explicit when you move that export between machines:

• agentxchain audit still inspects the live repo/workspace you are currently in.
• agentxchain report --input /path/to/run-export.json reads the saved artifact and renders the verified derived summary.
• agentxchain replay export /path/to/run-export.json opens the saved artifact in the read-only dashboard for interactive post-mortem work.

Coordinator partials do not break that rule. If a coordinator export contains repos.<repo_id>.ok === false, it is still a valid report --input or replay export artifact: report keeps repo_ok_count / repo_error_count plus the failed repo row and error, and replay export restores a placeholder governed repo for the missing child export. What it is not is a valid restore input.

Operator Checklist

Scenario	Command	What happens
Continue work on an existing run	agentxchain resume --role <role>	Assigns next turn in same run
Restart after losing session context	agentxchain restart	Rebuilds context from checkpoint, warns on repo drift, preserves pending gates
Check current state after returning	agentxchain status	Shows run state, active turns, recovery actions
Recover from blocked	agentxchain resume	Clears block, resumes run
Approve phase transition	agentxchain approve-transition	Passes gate, advances phase
Approve run completion	agentxchain approve-completion	Finalizes run, marks complete
View full decision trail	cat .agentxchain/decision-ledger.jsonl	Every decision across all sessions
View full turn history	cat .agentxchain/history.jsonl	Every turn across all sessions