AGENT SKILL

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-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:

  1. 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.
  2. 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.
  3. 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-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)

  1. A compacted seat forgets active workflow state and drops the hot potato. Compaction without continuity preservation is silent failure.
  2. A restore packet preserves details but loses the user's product intent. Restore must preserve why this work matters, not just what was happening.
  3. A runtime resume is mistaken for a seat handover or fork. These have different continuity outcomes and provenance — don't conflate.
  4. 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-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

04 同仓库更多 Skills

mvschwarz
mvschwarz/openrig-world

notes

Use when taking notes.

★ 16
mvschwarz
mvschwarz/openrig-world

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.

★ 16
mvschwarz
mvschwarz/openrig-world

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).

★ 16
mvschwarz
mvschwarz/openrig-world

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.

★ 16
mvschwarz
mvschwarz/openrig-world

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).

★ 16
mvschwarz
mvschwarz/openrig-world

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.

★ 16