@openrig/cli 0.6.4-rc.1 → 0.6.5

package/daemon/context-packs/reference/instance-layout.md

@@ -104,3 +104,14 @@ runtime reads for compatibility. Treat the two-home state as an explicit
 limitation: use the live spec-library commands to determine where a spec is
 served from, and do not infer convergence merely because the canonical
 directory exists.
+
+Config updates publish a complete replacement file atomically where directory
+permissions and the filesystem allow it. On POSIX systems, replacement preserves
+the existing owner, group, and read/write/execute permission bits. If creating or
+preparing the replacement, or renaming it, fails with `EACCES`, `EPERM`, or `EBUSY`,
+the stores write the writable target in place, preserving compatibility with
+unwritable directories and single-file bind mounts. This fallback is not atomic
+and retains the previous partial-write risk. Read-only config files are refused.
+Other errors, including `ENOSPC`, leave the original file intact on the atomic
+path. Atomic replacement does not carry extended ACLs or other inode metadata;
+a hard-linked second name continues to refer to the previous file.

package/daemon/context-packs/reference/manifest.yaml

@@ -1,7 +1,7 @@
 # Reference guides the help pack links to, loaded one file or section at a time by address
 # (rig context get reference/<file>#<section>). Each file is a symlink to docs/reference/.
 name: reference
-version: "0.6.4-rc.1"
+version: "0.6.5"
 taxonomy: world
 purpose: "Version-matched reference guides the help guide links to. Load a single file or section by address; don't load the whole pack."
 files:

package/daemon/context-packs/reference/rig-spec.md

@@ -247,7 +247,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Pod identifier. Must not contain dots. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
+| `id` | string | yes | — | Pod identifier. Must not contain dots or `@`. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
 | `label` | string | yes | — | Human-readable pod name. Shown in UI explorer, graph groupings, and detail surfaces. |
 | `summary` | string | no | — | Pod description. |
 | `continuity_policy` | ContinuityPolicy | no | — | Pod-level continuity/restore policy. Controls compaction recovery, artifact management, and peer-driven restoration. |
@@ -258,6 +258,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 ### Pod ID Rules
 
 - Must not contain dots (`.`)
+- Must not contain `@`, which separates the pod/member portion from the rig name in session addresses
 - Must be unique across all pods in the rig
 - Becomes the first segment of the qualified logical ID: `{podId}.{memberId}`
 - Becomes the first segment of the canonical session name: `{podId}-{memberId}@{rigName}`
@@ -268,17 +269,35 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Member identifier. Must not contain dots. Must be unique within the pod. |
+| `id` | string | yes | — | Member identifier. Must not contain dots or `@`. Must be unique within the pod. |
 | `agent_ref` | string | yes | — | Reference to an AgentSpec. Must start with `local:` (relative) or `path:` (absolute). Exception: `builtin:terminal` for infrastructure nodes. |
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
 | `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
-| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `terminal`. |
+| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
 | `cwd` | string | yes | — | Working directory for the agent. Resolved relative to the rig root (the directory containing the rig spec). Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |
 | `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
 | `restore_policy` | string | no | `resume_if_possible` | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. |
 | `startup` | StartupBlock | no | — | Member-level startup files and actions. Applied only to this member. |
 
+### Pi (`runtime: pi`)
+
+`runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
+
+- **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
+- **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
+- **Credentials:** The Pi process receives only `PATH`, `HOME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY` or `KIMI_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>` or `kimi-coding/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
+
+### Oh My Pi (`runtime: omp`)
+
+`runtime: omp` launches Oh My Pi through OpenRig's RPC runner. It is separate from `runtime: pi`; OMP does not use Pi's `--name` or `--approve` flags.
+
+- **State:** Each seat uses `$OPENRIG_HOME/state/omp/<seat>/agent` and `sessions/` instead of your default `~/.omp` profile, and runs with that seat directory as `HOME`. OpenRig does not copy OMP credentials. The runner finds the real `omp` binary before switching `HOME`, so a version-manager shim such as mise on the daemon's `PATH` still works.
+- **Credentials:** Provision each seat separately, or put the provider's key variable in `recovery.provider_auth_env_allowlist` (for example `ANTHROPIC_API_KEY` or `MISTRAL_API_KEY`). The allowlist accepts the key variable of every provider in OpenRig's OMP provider map, from `anthropic` through `litellm`. A seat receives a key only when its `model` is written as `provider/id`, such as `anthropic/claude-sonnet-4-5`. Short names such as `opus` pass no key. OMP also reads the launch directory's `.env`, so use a trusted working directory.
+- **Approval posture:** The default floor is `--approval-mode always-ask`. Because the runner is headless, OMP approval requests are cancelled and the seat stays in needing-attention after the turn ends, until the next agent run starts. A `full_bypass` permission policy selects `--approval-mode yolo`.
+- **Model errors:** A rejected prompt, a provider or authentication error during a turn, or exhausted automatic retries is printed in the pane and keeps the seat in needing-attention until the next agent run starts.
+- **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token; restoring it requires `rig up --existing <rig> --fresh <seat>`. After that file exists, OpenRig restores that exact session file. If a full rig restore leaves an OMP seat in `attention_required` or `failed`, `rig seat clear-attention` cannot yet reconcile it to `operator_recovered`, even with `--reason`, because restore reconciliation only verifies Claude Code and Codex processes ([#41](https://github.com/mvschwarz/openrig/issues/41)). Relaunch that seat with `rig up --existing <rig> --fresh <seat>`, or restore it manually.
+
 ### Terminal Nodes
 
 Terminal nodes are infrastructure processes (servers, log tails, build watchers) that are not agent runtimes. They require an exact triple:
@@ -309,6 +328,9 @@ The canonical session name is derived from the pod ID, member ID, and rig name:
 
 Example: pod `dev`, member `impl`, rig `my-team` → session `dev-impl@my-team`
 
+Pod and member IDs cannot contain `@` because the first `@` separates their portion
+of the session address from the rig name. Rig names may still contain `@`.
+
 This is human-authored (you choose the pod/member IDs) and system-validated (the system enforces the format).
 
 ---
@@ -369,6 +391,7 @@ Startup blocks can appear at three levels: rig, pod, and member. They are merged
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `path` | string | yes | — | Relative path to the file. Must be a safe relative path. |
+| `orientation` | string | no | — | Set to `role` to identify a per-seat role file for `rig queue whoami --json` and refocus. Does not change delivery or replay startup. |
 | `delivery_hint` | string | no | `auto` | How the file is delivered. One of: `auto`, `guidance_merge`, `skill_install`, `send_text`. |
 | `required` | boolean | no | `true` | Whether startup fails if this file cannot be delivered. |
 | `applies_on` | string[] | no | `[fresh_start, restore]` | When this file is delivered. Subset of: `fresh_start`, `restore`. |
@@ -454,7 +477,8 @@ Each target must define exactly one of `service`, `url`, or `tcp`:
 
 ```yaml
 wait_for:
-  # HTTP probe — hits the URL, expects 2xx
+  # HTTP probe — any 2xx or 3xx response passes the HTTP wait target; redirects are not followed.
+  # This proves the server answered, not application readiness.
   - url: http://127.0.0.1:8200/v1/sys/health
 
   # TCP probe — connects to host:port
@@ -536,7 +560,10 @@ continuity_policy:
 
 ## Validation Rules Summary
 
-These rules are enforced by the validator. A spec that violates any of these will be rejected by `rig spec validate` and `rig up`.
+Schema validation checks the structural rules below. Pod and member IDs containing
+`@` are additionally rejected during preflight and member creation or launch; a
+spec can pass `rig spec validate` and then fail at preflight or import. Run
+`rig spec preflight` before creation or import.
 
 1. `version` and `name` are required non-empty strings.
 2. `pods` must be a non-empty array.

package/daemon/context-packs/skills/agent-operated-software/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-operated-software"
-version: "0.6.4-rc.1"
+version: "0.6.5"
 taxonomy: "skills"
 purpose: "Use when designing, building, operating, or diagnosing an ongoing application whose live backend or control loop includes OpenRig agents, including applications with a Markdown, YAML, or JSON agent control plane or a thin surface over specialist agent roles."
 files:

package/daemon/context-packs/skills/agent-operated-workflows/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-operated-workflows"
-version: "0.6.4-rc.1"
+version: "0.6.5"
 taxonomy: "skills"
 purpose: "Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable, or partially knowable state; when an operation must resume from verified evidence; or when deciding whether agent judgment or ordinary code should own a procedure's control loop."
 files:

package/daemon/context-packs/skills/applying-a-permission-policy/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "applying-a-permission-policy"
-version: "0.6.4-rc.1"
+version: "0.6.5"
 taxonomy: "skills"
 purpose: "Use before launching a team during agent-guided setup, or when a user asks to configure OpenRig command permissions, reduce repeated native approval prompts, or apply a selected rig/seat permission policy."
 files:

package/daemon/context-packs/skills/claude-compaction-restore/SKILL.md

@@ -1,158 +1,227 @@
 ---
 name: claude-compaction-restore
-description: Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files.
+description: Use when a Claude Code session is about to compact, has just compacted, reached its context limit, resumed after /compact, or must rebuild its working picture of a long-running seat from its own restore map, its JSONL transcript and the files it touched.
 metadata:
   openrig:
     sibling_skills:
-      - mental-model-ha
-      - scope-recovery
       - session-compaction-and-restore
       - agent-startup-and-context-ingestion
       - agent-starters
-      - composable-priming-packs
       - session-source-fork
       - seat-continuity-and-handover
-      - claude-compact-in-place
-      - pre-maintenance-agent-preservation
 ---
 
 # Claude Compaction Restore
 
-Use this skill to preserve continuity before Claude Code compacts and to
-restore continuity after compaction. Follow the active restore request or
-configured continuity policy. A hook notice identifies available evidence; it
-does not by itself request a seat restoration.
+Compaction keeps facts and loses connections. After a compaction you still know file names, row ids and
+decisions as items. What you lose is the web between them: why a file matters, what depends on what, which
+decision produced which artifact, what you were about to do next, and how this window relates to the ones
+before it. Seats whose value is a wide, long-running picture (planners, orchestrators, reviewers holding a
+standard) lose the most.
+
+This skill keeps that picture alive across compactions. Before compacting, you write a **restore map**: a
+short summary plus the connections between things that already exist on disk. After compacting, you
+re-enter the world, read your own map, and rebuild the picture before acting. Over several compactions the
+maps chain into one continuous record: a global context window that outlives any single session.
+
+The previous version of this skill is kept at `reference/SKILL-v1.md` for comparison.
+
+## What survives, and what you write
+
+**Already on disk; point to it, don't copy it:**
+- your session JSONL at `~/.claude/projects/<cwd-slug>/<session-uuid>.jsonl` (the post-compaction restore
+  request names the exact path). It holds every message and tool call you made, in order. It does not hold
+  your reasoning;
+- the restore packet the PreCompact hook writes (transcript extract, touched-file triage);
+- queue rows and their transitions, mission files (`SPEC.md`, `NOTES.md`, `PROGRESS.md`), your seat's
+  `LEARNED.md`, evidence folders, branches and PRs.
+
+**Only in your head; write it down:**
+- why each important thing matters, and to whom;
+- how things relate: depends on, supersedes, answers, contradicts, was produced by, is owned by;
+- decisions and the reasons for them, options you rejected, judgment and taste you applied;
+- where you were in time: what earlier windows established, what this window did, what comes next and who
+  authorizes it;
+- where to look deeper: which JSONL range or file answers which question.
+
+The map is the second list, pinned to the first.
+
+## Two restore classes
+
+Every restored seat must come back competent. It should understand the OpenRig world and its command
+surface, the project, its own role, and where it stands in time. Some seats also need the global picture.
+
+Both classes read the same thing: the **ranked reading list** in your own map, in order. They differ only in
+how far down the list they go.
+
+| Class | Who | Reads |
+|---|---|---|
+| **Default** | drivers, builders, reviewers, QA, and any seat not listed below | Tier 1: the top of the list, to about **100k** of real context |
+| **High-context** | orchestrators, planners, advisors, leads: any seat that makes product, scope or routing decisions | Tier 1 and Tier 2, to about **200k** of real context |
+
+The tiers are **real context added by the restore**, on top of what the compaction summary leaves (about 60k).
+These budgets assume a context window of about 1M tokens; on a smaller window, scale them to about 10% and
+20% of it. File size is a poor guide to that cost: in OpenRig's own runs, real context grew 1.7 to 2 times the bytes ÷ 4 estimate,
+because of line numbers on reads, tool output and your own reasoning. So rank to about **50k of bytes ÷ 4 for
+Tier 1** and about **100k for Tier 2**, and check real usage at each checkpoint with
+`rig compact-plan --json` (your seat's `estimatedUsedTokens`).
+
+Tier 2 buys **width, not depth**: more sources, more connections, more of the mission's history and the wider
+worlds, not the same files read more fully. Choose your class from your role (`rig whoami --json`). A per-seat
+instruction file or your own map can name the class explicitly, and that overrides the role default. In both
+classes, transcripts and the session JSONL appear only as targeted line ranges, never as whole files.
+
+If there is no ranked list (no preparation turn happened), use this default order. Default seats stop at about
+100k of real context:
+1. the post-compaction world profile;
+2. the mission or slice `SPEC.md` and `NOTES.md`;
+3. rows you hold.
+
+High-context seats then add, to about 200k:
+1. the full System World install;
+2. the full Project World, public and private;
+3. the mission's `PROGRESS.md` and recent returns;
+4. previous maps and `RESTORED` notes;
+5. `LEARNED.md`.
 
 ## If You Are About To Compact
 
-Prepare durable continuity before the context boundary.
-
-1. Identify the active task, queue item, mission/slice, branch or commit, and
-   current working directory.
-2. Record the current state: decisions made, files changed, commands/tests run,
-   evidence produced, blockers, caveats, and the next concrete step.
-3. Create or update a durable mental-model restore map. This map is the main
-   artifact future-you will use to rebuild context after compaction.
-4. In the restore map, write an ASCII file/folder tree of every path that
-   mattered to your working mental model during this session. Include:
-   - the active queue item or mission packet;
-   - mission notes, progress, decisions, and evidence files;
-   - Claude memory/project notes you used or wrote, especially when the memory
-     folder is shared by many agents;
-   - files with active edits or recently inspected source;
-   - root instructions such as `AGENTS.md`, `CLAUDE.md`, or `README.md`;
-   - as-built docs, codemaps, conventions, skills, and product docs needed
-     before code/review work;
-   - source files, tests, scripts, UI evidence, screenshots, logs, or reports
-     that shaped your current state.
-5. For every file or folder in the tree, add a short note explaining why it
-   matters and whether it is required reading after compaction.
-6. Write any important glue context that is not already on disk into the
-   handoff/restore map. This includes assumptions, partial conclusions, failed
-   paths, and why the listed files fit together.
-7. In the compaction summary, include the restore map path and the top required
-   reading paths from that map.
+You are about to lose every connection you have built. Spend this turn making them durable.
+
+1. **Think back before writing.** Walk the session and, through your previous map, the windows before it.
+   What were the threads? What did you work out about how the pieces fit? What is unfinished? What did you
+   decide, and why? What were you about to be wrong about?
+2. **Write the restore map** in your seat folder, not in scratch (scratch can be cleaned while you are
+   compacted): `<topology root>/rigs/<rig>/seats/<seat>/RESTORE-MAP-<UTC yyyymmdd-hhmm>.md`. Derive the
+   folder from `rig whoami --json` and `rig config get topology.root`. **Run `date -u` for the timestamp and
+   every time you write in the map. Do not estimate times**: an estimated time can land before events it
+   describes, as one did in an early run.
+3. **Open the map with a summary** of 10 to 20 lines: who you are, what you hold, what mattered in this
+   window, what is next and who authorizes it, and any hold in force. **Publish that summary as your seat
+   recap** too: save it, plus a line naming the map's path, to a file and run
+   `rig context recap-write --rig <rig> --seat <seat> --file <that file>`. If your world profile has a seat
+   recap atom, it loads this recap, and an old recap would be served as if it were current.
+4. **Then write the connections.** Choose what this seat needs; these are examples, not a template:
+   - **State:** rows you hold (id, state), branches and PR heads, the hold or release in force and who gave
+     it, the mission and slice you work in.
+   - **Nodes with purpose:** each file, row, PR or evidence folder that matters, one line each on what it is
+     and why it matters.
+   - **Edges:** "A depends on B", "C supersedes D", "this decision produced that file", "E answers question
+     F", "G is owned by seat H", "I and J disagree; unresolved".
+   - **Judgment:** decisions with reasons, rejected options, what the human cares about here, the tells you
+     caught or nearly missed.
+   - **Time:** what the previous map said happened before, what happened this window, what is next.
+   - **Lookups:** JSONL line ranges or uuids for threads worth re-reading (`grep -n` the JSONL for a row id
+     or timestamp), and which file holds the evidence for which claim.
+   - **A small file tree** of the paths above, each with a one-line note, when that helps navigation.
+5. **Rank what your restored self should read.** End the map with a reading list ordered by importance.
+   - **What each entry gives:**
+     - the path;
+     - the exact part to read (a heading, a line range, or a JSONL range found with `grep -n`), not the
+       whole file unless the whole file is the point;
+     - its approximate size (bytes ÷ 4 ≈ tokens; `wc -c`);
+     - one line on why it matters.
+   - **The first entry** is the post-compaction world profile, with its size from
+     `rig context profile … --json` (`totalEstimatedTokens`).
+   - **Tier lines:** keep a running bytes ÷ 4 total, draw the Tier 1 line at about 50k (about 100k of real
+     context), and continue to about 100k for Tier 2 (about 200k real).
+   - **Rank for connections.** Prefer the entry that connects the most other things you need, and choose a
+     section that explains how things fit over a long file of detail you can look up later.
+6. **Link the chain.** Name the previous restore map (and its `RESTORED` note, if one exists) so a later
+   reader can walk back through earlier windows.
+7. **Keep it readable in one pass.** Aim for something you could read in a few minutes: point instead of
+   copying, and leave out what a command can re-derive.
+8. **Update the durable homes you own** as usual: a lesson that changes future decisions goes in
+   `LEARNED.md`; mission state goes in the mission's own files; work another seat must act on goes in a queue
+   row. The map points to these rather than repeating them.
+9. **End the preparation turn** by stating the map path. OpenRig sends `/compact` next; the summary should
+   name the map path and the next authorized step.
+
+A map that lists files without saying how they connect is an inventory, and an inventory is what compaction
+already leaves you. The edges are the point.
 
 ## If You Just Compacted
 
-Restore from the evidence for this session before relying on remembered task state.
-
-1. Inspect the restore request and any named marker, packet, transcript, restore
-   map, or extra instruction file. Check recorded seat/session/transcript identity
-   against the current request, and verify that the referenced packet is readable.
-   A marker path alone does not prove a usable packet; do not substitute another
-   seat's packet or select one only because it is the newest.
-2. **Use the existing packet when usable.** Read its `restore-instructions.md`,
-   `touched-files.md`, and any named restore map. A packet already prepared for this
-   session does not need rebuilding merely because compaction occurred.
-3. **Fall back when the packet is absent or unusable.** Record what is missing or
-   mismatched. Resolve this skill's installed directory and run its
-   `scripts/restore-from-jsonl.mjs` with the matching Claude JSONL transcript and a
-   separate output directory. For a skill installed in the global Claude skill root:
-
-```bash
-node ~/.claude/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs /path/to/session.jsonl --out /tmp/claude-compaction-restore
-```
-
-   If no transcript was named, identify the current session's transcript first.
-   The script can discover a transcript from a working directory, but inspect that
-   selection before relying on it. If the session cannot be identified, report
-   the missing input instead of reconstructing from an unrelated conversation.
-   Read the resulting `restore-instructions.md` and `touched-files.md`.
-4. Inspect the actual packet and transcript sizes before choosing how much to read.
-   The generated instructions report estimated token cost. State a read budget
-   and stopping rule that leave room for the task. For a large transcript, begin
-   with the most recent task-relevant unique narrative; read earlier material when
-   a specific missing decision or dependency requires it. Report ranges actually
-   read rather than treating a chosen budget as completed coverage.
-5. Use the restore map and touched-file list to identify current task files.
-   The list is a triage aid, not an exhaustive inventory. Prioritize the active
-   queue/mission packet, decisions and memory named in the map, files with active
-   edits, root instructions, and relevant as-built docs or codemaps. Read required
-   task files in full within the stated budget; record any remaining gaps.
-6. Re-establish the task's purpose and operating context from the current project,
-   mission and seat files. A transcript summary alone does not establish current
-   scope or obligations. Use the shipped `refocusing` skill for the path-only
-   topology/work trace when operating inside OpenRig.
-7. Report the read-depth audit below. Once the required context is restored, use
-   the packet's requested acknowledgment, normally:
-
-```text
-restored from packet at <path>; resumed at step <X>
-```
-
-   Include the main files actually read in full. If essential context remains
-   missing, report partial restoration and the next recovery action instead of
-   claiming completion.
-
-The packaged PreCompact writer can prepare a packet and a per-seat pending marker;
-the restore bridge can deliver its pointer once for a matching session. Inspect
-those actual artifacts. Their creation or delivery is not proof that a provider
-restored its context, that the files were read, or that task understanding returned.
+You have facts without connections. Rebuild the connections before you act on anything.
+
+1. **Check for a hold first.** Read the restore request, the per-seat instruction file
+   (`<OPENRIG_HOME>/compaction/post-compact-extra/<session>.md`, named by your full session such as
+   `dev-impl@my-rig.md`) when it exists, the newest row or message from whoever routes your work, and any hold
+   from the authority above them. A hold, a release order or an operator's own restore map overrides the default
+   order below. Before any write, also run `rig whoami --json` and `rig queue whoami`.
+2. **Name your class and state its read budget** before reading (see "Two restore classes"), with a
+   checkpoint at each step below. The budget exists so that the restore leaves room for the work it was
+   restored to do. Step 5 takes a high-context seat to its Tier 2 line; the extra sources under "Two restore classes" apply only
+   when there is no ranked list.
+3. **Re-enter the world.** Load the post-compaction world profile your instance provides. Find it with
+   `rig context list`; for a private world install, run
+   `rig context profile <world-ref> --situation post-compaction --rig <rig> --seat <seat>` (the seat flags are
+   needed for its seat-scoped recap atom; take both values from `rig whoami --json`). Without a private world,
+   run `rig context profile world-public --situation post-compaction` and `rig context get onboarding-width`. This restores how the system works before you
+   restore what you were doing in it. If your work belongs to a project, re-enter its declared context too:
+   `rig context work-install` lists what the project declares (intent, context files, skills), so read the pieces
+   your task needs. `--deliver` prints them all; when several projects are declared (`--json` lists the ids), name
+   one with `--project <id>`.
+4. **Read your own restore map in full**: the newest `RESTORE-MAP-*.md` in your seat folder, which the
+   compaction summary should name. If it points to an earlier map for context you need, read that too.
+5. **Read down the map's ranked list** to your class's tier line, reading exactly the parts each entry names.
+   Then check every row you hold (`rig queue show <id> --full --json`) and anything that may have changed since
+   the map was written: merged PRs, new rows, a new hold. The map records what was true when it was written;
+   current state still has to be derived.
+6. **Use the packet and the JSONL as lookups**, not as reading lists: go to a specific line range when a
+   specific question needs it. The packet's `restore-instructions.md` and `touched-files.md` help find
+   things the map does not cover.
+7. **If there is no map** (the preparation turn did not happen), fall back to the packet: read
+   `restore-instructions.md`, then the most recent unique narrative, tail first, within the budget; and say in
+   your report that you restored without a map.
+8. Reply with the sentence the restore request asks for, normally
+   `restored from packet at <path>; resumed at step <X>`, naming the map you used. When no packet exists, give
+   the map's path as `<path>` and say that you restored from the map.
 
 ## Required Read-Depth Audit
 
-After the first restore pass, audit yourself before continuing.
-
-1. List every file, packet, marker, restore map, instruction file, and source
-   document you were asked to read during restore.
-2. Mark each item as `FULL`, `PARTIAL`, or `NOT_READ`.
-3. Distinguish essential current-task context from supplementary history, using
-   the actual restore request and active task.
-4. Read `PARTIAL`/`NOT_READ` items in full — but **to a declared budget with a stopping rule**, not
-   unbounded. Prioritize by relevance to the active task; for a large transcript read the most recent
-   unique narrative first (see *If You Just Compacted*), not front-to-back.
-5. **Stop** when either every task-relevant item is `FULL`, or you reach the budget — *a restore that
-   cannot leave room for the work it was restored to do is not a successful restore.* "Read everything,
-   never conserve" has no termination condition; that open-endedness is the bug, not the goal.
-6. Report the final read-depth table **honestly** (`FULL`/`PARTIAL`/`NOT_READ`, each with a reason)
-   before task work. **An honest `PARTIAL` with its reason is a correct outcome, not a failure** — do
-   not claim a completion you did not reach.
+The audit message asks for a read-depth table and tells you not to conserve tokens. Do both in this form:
+
+1. **List every item** you were asked to read (request, instruction files, packet, map, and the sources the
+   map marks required) with `FULL`, `PARTIAL` or `NOT_READ`, the ranges you actually read, and a reason.
+   Mark `FULL` only for content you read after this compaction; content carried in through the summary is
+   inherited, not read, and a file the harness re-attached after compaction is
+   `PARTIAL (injected)`, not `FULL`, until you read it.
+2. **Read in full now** every required item that is not yet `FULL`. "Required" means the ranked entries
+   above your class's tier line, in the exact parts they name. Everything else is lookup-only: **every file in the restore packet**
+   (`touched-files.md`, `restore-instructions.md`, `transcript.md`, `transcript-latest.md`, `restore-summary.json`),
+   the session JSONL and archives. Those stay
+   `NOT_READ` with the reason "lookup only", unless a human or the owning seat releases them. The audit
+   message's "do not optimize for token conservation" applies to required items: read those fully rather
+   than skimming them. It does not turn lookups into reading lists. In an early run of this skill, reading
+   the packet transcripts during the audit cost a default seat about 75k, more than the restore itself.
+3. **Reconnect, in writing.** In the same reply, and in a short `RESTORED-<UTC yyyymmdd-hhmm>.md` beside the
+   map:
+   - where you are in time: what earlier windows established, what the last window did, what is true now;
+   - the connections you have rebuilt, in a few lines;
+   - the connections you could not rebuild, and where you would look;
+   - the next authorized step and who authorizes it. If a hold stands, the next step is waiting.
+
+The next restore map links this note, which keeps the chain unbroken.
 
 ## Guardrails
 
-- Compaction is survival, not housekeeping — never compact to free space, "lean" a seat, or capture/prepare an agent starter (the `rig agent-image` library). It is lossy (a compacted Claude is confident-but-hollow); compact only when a seat is genuinely near its context limit, with a before/after plan. A starter's value is being *functional*, not small — see the `agent-starters` skill.
-- Do not silently launch fresh after compaction.
-- Do not continue from memory when restore evidence exists.
-- Do not defer required restore reading until a later user task. The restore is
-  the current task.
-- Do not skip root instructions, as-built docs, or codemaps before product
-  code/review work.
-- Do not treat the generated touched-file list as exhaustive.
-- Do not mark a file `FULL` unless you actually read the full file content
-  after compaction.
-- Do not resume task work until the restore sentinel and read-depth audit are
-  complete.
-
-## Failure Modes To Avoid
-
-1. **Confidently-wrong restoration**: claiming restoration after reading only
-   the touched-file list or summary.
-2. **Unreported partial restore**: continuing without essential task context or
-   claiming full coverage after a budget-limited read.
-3. **Skipping project instructions**: missing `AGENTS.md`, `CLAUDE.md`,
-   `README.md`, as-built docs, or codemaps that govern the task.
-4. **Treating the packet as exhaustive**: ignoring mission or workspace files
-   that are important but were not discovered by the script.
-5. **Waiting for the next task**: treating restore reading as conditional on a
-   future user assignment instead of completing it immediately.
+- Compaction is survival, not housekeeping. Compact only when a seat is genuinely near its limit, never to
+  "lean" a seat or prepare a starter image; a compacted seat can sound confident while missing the context it needs.
+- Continue from the map and the files, not from the summary's "next step" alone: a hold placed after the
+  summary was written still binds.
+- Do not launch a fresh session in place of restoring.
+- An honest `PARTIAL` with its reason is a correct outcome. Claiming coverage you did not reach is the
+  failure.
+- Do not resume task work until the read-depth table and the reconnect note exist.
+
+## Failure modes
+
+1. **Inventory instead of map:** a list of paths with no edges. The restored seat knows where things are and
+   not why they matter.
+2. **Confident restoration:** acting on the summary after reading only the touched-file list.
+3. **Reading to exhaustion:** reading the whole transcript or every linked file and leaving no room for the
+   work.
+4. **Map in scratch:** writing the map somewhere that is cleaned before you restore.
+5. **Broken chain:** a map that does not name the previous one, so earlier windows are lost on the second
+   compaction.

package/daemon/context-packs/skills/claude-compaction-restore/manifest.yaml

@@ -1,13 +1,15 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "claude-compaction-restore"
-version: "0.6.4-rc.1"
+version: "0.6.5"
 taxonomy: "skills"
-purpose: "Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files."
+purpose: "Use when a Claude Code session is about to compact, has just compacted, reached its context limit, resumed after /compact, or must rebuild its working picture of a long-running seat from its own restore map, its JSONL transcript and the files it touched."
 files:
   - path: "SKILL.md"
     role: "instruction"
-    summary: "Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files."
+    summary: "Use when a Claude Code session is about to compact, has just compacted, reached its context limit, resumed after /compact, or must rebuild its working picture of a long-running seat from its own restore map, its JSONL transcript and the files it touched."
+  - path: "reference/SKILL-v1.md"
+    role: "reference"
   - path: "scripts/precompact-hook.mjs"
     role: "reference"
   - path: "scripts/restore-from-jsonl.mjs"