Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental
Install
Use withClaudeCursorCodex
The file stays in the publisher's repository. PlugMCP does not host or rewrite it.
Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions).
name: session-compaction-and-restore
description: Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions).
metadata:
cli_surfaces_referenced:
- whoami
openrig:
stage: factory-approved
sibling_skills:
- claude-compaction-restore
- agent-startup-and-context-ingestion
- agent-starters
- session-source-fork
- seat-continuity-and-handover
- retiring-and-inheriting-a-seat
Session Compaction and Restore
Preserving useful working state across compaction, context loss,
restart, or seat refresh. Includes Claude compaction restore, Codex
resume/fork mechanics, transcript-based mental-model rebuilds, and
durable handoff packets.
Long-lived seats are valuable only if they can survive context
pressure. If compaction turns a senior seat into a cold-started
agent, users will avoid persistent topologies and fall back to
throwaway agents.
Use this when
A seat is approaching compaction or just compacted
Designing a high-fidelity restore packet for an active workflow
Distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild
Reasoning about what should be preserved vs reconstructable
Auditing a restore for product-intent preservation (not just detail preservation)
Don't use this when
The session is fresh and has no working state to preserve
The intent is to create a new seat from a primed source — that's session-source-fork or agent-starters
The packet is a one-off snapshot for human review — restore packets are for re-entering active work
The 5 distinctions (do not collapse)
Per the cross-runtime restore/reentry packet standard:
Mode
What it means
Outcome literal
Native resume
Continue the same managed seat with native runtime token
resumed
Fork
New managed seat from prior native runtime conversation; new post-fork token
forked
Rebuild
Fresh-launch seeded with operator-declared artifacts in trust-precedence order
rebuilt
Artifact-backed mental-model rebuild
Restored seat derives understanding from a packet rather than native runtime continuity
(case of rebuilt)
Fresh launch
New agent without prior continuity
fresh
These are load-bearing distinctions. Do NOT collapse fork into
artifact-backed reentry; do NOT collapse rebuild into fork.
The three mechanisms — who owns each (verified vs main d37a08ad, 2026-07-21)
The outcomes above ride on three DISTINCT mechanisms; keep them separate:
Claude built-in /compact — a Claude Code HARNESS feature, not OpenRig
code. OpenRig only emits the literal /compact toward the pane after a prep
turn; there is no compaction algorithm in the OpenRig repo. Provider-owned.
OpenRig-managed restore — the enforcer + hook bridge: a precompact hook
WRITES a restore packet; a bridge READER injects exactly ONE restore directive
back via the harness hook channel (hookSpecificOutput.additionalContext),
seat-isolated. The OpenRig-owned half.
Codex session continuity — resume/rollout tokens (codex resume <token>),
a separate path from the Claude mechanisms. Never conflate with Claude restore.
Safety boundary (ties to native-session-file-lab-boundary): no supported
OpenRig path EDITS provider-owned native session / auth / transcript files to
inject context. Context enters ONLY through sanctioned channels: the hook
additionalContext, a normal user message via rig send, or Codex resume tokens.
Precise nuance: OpenRig does write ~/.codex/config.toml — but only to install
OpenRig activity hooks and [features], never session or auth state. So the
rule is "never edits native session/auth/transcript files," NOT "never touches any
provider-owned file."
Claude's own idle compaction while managed compaction is on
While policies.claude_compaction.enabled is true with a valid threshold (the enforcer treats any other
threshold as off), every Claude session OpenRig launches (fresh, fork, resume and restore; ordinary, kernel,
team-default and full-bypass seats) carries idleCompaction: false in its one --settings value. Claude Code then
doesn't compact an idle session on its own, so managed seats compact through OpenRig's sequence (restore map, then
/compact at the threshold).
Version boundary: Claude Code supports the key from 2.1.290. Earlier versions ignore it, so idle compaction
stays possible there.
Precedence: it overrides a lower-precedence idleCompaction: true in user or project settings for those
launches. Claude's managed settings still win.
Native threshold auto-compaction is untouched (autoCompactEnabled, DISABLE_AUTO_COMPACT). Where the enforcer
has no fresh status-line usage sample for a seat, it doesn't compact that seat, and native auto-compaction is then
the only compaction. Nothing guarantees a native fallback.
It applies at the next launch. Turning the policy off leaves idle compaction off in a running session until
that session's next launch. Turning it on doesn't reach sessions already running.
Policy off, or a non-Claude runtime: the launch command is unchanged.
Current CLI surface (operator / kernel seats; verified vs main d37a08ad)
Managed compaction/restore is driven by five shipped verbs — pick per intent, and
stay durable-substrate-first (the packet/artifacts are the truth; the CLI is the trigger):
rig compact <session> — guided managed compaction for ONE Claude seat
(prep → /compact → restore → audit). Non-Claude seats rejected. ~180s.
rig compact-plan — READ-ONLY triage; does not compact. Flags --rig,
--refresh, --threshold-tokens, --threshold-percent. (Codex seats flagged
codex_not_managed_by_claude_compact_in_place.)
rig restore-packet {write,read,validate} — the cross-runtime restore
packet (v0): write / read / validate the durable packet this skill's contract defines.
rig restore <snapshotId> --rig <rigId> — ⚠ RIG SNAPSHOT restore (infra), a
DIFFERENT mechanism — NOT session-context restore. Do not conflate.
Failure modes (4)
A compacted seat forgets active workflow state and drops the hot potato. Compaction without continuity preservation is silent failure.
A restore packet preserves details but loses the user's product intent. Restore must preserve why this work matters, not just what was happening.
A runtime resume is mistaken for a seat handover or fork. These have different continuity outcomes and provenance — don't conflate.
A rebuilt seat starts with stale instructions that conflict with current workflow mode. Restore must include current state, not just historical state.
Re-entering project context, on any runtime. A restore packet carries the work in flight, not the project's
declared intent and context files. rig context work-install lists what the project declares; read the pieces the
restored task needs. --deliver prints them all, and when several projects are declared (--json lists the
ids), select one with --project <id> instead of guessing.
Proof standard
Proof should include a deliberate compaction/restart of a seat with
active work, followed by measured recovery: identity, current
workflow, next owner, relevant files, and constraints all restored
without human re-briefing.
Canonical packet contract (16-field, v0)
The cross-runtime restore/reentry packet standard v0 defines:
A restore may consume transcripts, durable messages, startup context,
checkpoints and a restore packet. Inventory the surfaces actually present for
this seat, with their source, freshness and purpose. Do not infer that a named
surface exists or grants write authority.
The active project/rig policy and task authorization determine what may be
written. Treat provider-owned conversation records as evidence to read through
supported tooling. For placement and durable context, load
skills/openrig-operating-model/SKILL.md with rig context get; for the
selected startup path, use skills/core/agent-startup-and-context-ingestion/SKILL.md.
A packet or marker proves retained/delivered evidence, not successful provider
restoration; measure the resumed seat against the proof standard above.
Before a planned compaction, restart or long pause, write the seat's authored recap
with rig context recap-write --rig <rig> --seat <seat> --file <draft>. Its format is
in seat-continuity-and-handover, "Write the seat's recap before a handover". A
rebuild reads it before LEARNED.md, and a profile source of seat:RECAP.md serves
it after a restore.
See also
claude-compaction-restore skill — the Claude Code restore SOP (PreCompact hook + JSONL restore script for post-compaction recovery)
session-source-fork skill — fork mode for native-runtime-continuity-based restoration
seat-continuity-and-handover skill — occupant-creation primitives (resume/fork/rebuild/fresh) that this primitive instantiates
openrig-operating-model skill — placement and authority of durable context
How do I install session-compaction-and-restore?
Download packages/daemon/assets/plugins/openrig-core/skills/session-compaction-and-restore/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does session-compaction-and-restore live?
The publisher keeps it at https://github.com/mvschwarz/openrig.
Which agents can use session-compaction-and-restore?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.