session-compaction-and-restore

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