session-compaction-and-restore
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).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-12
- Stars
- ★ 16
- Forks
- 4
01 前言 Front Matter
- name
- session-compaction-and-restore
- metadata
- { "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" ] }, "cli_surfaces_referenced": [ "whoami" ] }
- 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).
03 SKILL.md 正文
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-forkoragent-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/compacttoward 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: truein 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 flaggedcodex_not_managed_by_claude_compact_in_place.)rig restore-check— restore-readiness probe across running rigs; read-only; exit 0/1/2. Flags--full,--ready,--rig,--no-queue,--no-hooks.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:
- Source/target identity
- Runtimes
- Workspace root, default repo, role pointer
- Bounded latest transcript
- Touched-path inventory
- Durable work pointers
- Current work + next owner
- Caveats + authority boundaries
- Omitted classes + redaction policy
- Source-trust ranking
- Generated-at + generator version
Plus a 6-item restored-seat acceptance checklist.
Source-trust ranking applies when restored seat ingests packet evidence:
rig whoami > target rigspec > bounded latest transcript > full
transcript > touched-files > restore-summary.json.
Memory surfaces consumed at restore time
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 --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-restoreskill — the Claude Code restore SOP (PreCompact hook + JSONL restore script for post-compaction recovery)session-source-forkskill —forkmode for native-runtime-continuity-based restorationseat-continuity-and-handoverskill — occupant-creation primitives (resume/fork/rebuild/fresh) that this primitive instantiatesopenrig-operating-modelskill — placement and authority of durable context
04 同仓库更多 Skills
notes
Use when taking notes.
software-for-agents
Use when older OpenRig instructions name software-for-agents or describe agent-in-the-middle or studio software under the former skill name.
session-compaction-and-restore
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).
seat-continuity-and-handover
Use when replacing a seat's occupant (rebuild/handover/swap), reasoning about stable-seat-identity vs fluid-occupant-identity, choosing an old-occupant disposition (retire/advise/shadow), or recording provenance for an occupant change. Two independent outcomes (continuityOutcome + seatBindingOutcome) and the 5 failure modes that prevent silent dishonesty.
retiring-and-inheriting-a-seat
Use when you are a sitting agent near your context threshold (~85%) and a PLANNED seat transition is due — retire deliberately and hand your seat to a fresh successor primed from a packet, rather than let compaction degrade you. Covers the handover packet, the append-only lineage ledger (one row per tenure), physical-seat continuity, the do-not-over-inherit framing, the optional warm-handoff window, and wake-v0 (consulting a retired predecessor). NOT for unplanned compaction/crash recovery (session-compaction-and-restore / claude-compaction-restore) and NOT the seat-binding primitive mechanics (seat-continuity-and-handover).
refocusing
Use when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints.