revealui-snapshot

Capture a session snapshot while fidelity is high — before context compaction — so the eventual /checkpoint composes its handoff from a fresh record, not from now-deep (or already-compacted) session memory. The producer half of GAP-317; revealui-checkpoint Step 1b is the consumer.

This skill is mandatory this turn when any of these fire. Do not continue other work first:

1. A Stop hook blocks with BLOCKED: context occupancy … Run the revealui-snapshot skill NOW
2. A [snapshot] advisory from track-session.js (Claude UserPromptSubmit; Grok discards that stdout)
3. The user runs /compact, or auto-compact is about to run

The compact line is the control-layer token budget (token-economy, authored in packages/harnesses/src/token-budget.ts). Grok's ~/.grok/config.toml is written from that file. Do not invent a second threshold. The Stop reason names the token count in force. 4. The current snapshot file has origin: precompact-mechanical (last-ditch hook capture — replace it with a real authoring)

The five sections are a hook-can't-author artifact: you assemble mechanical state and author the narrative. The file is keyed to the resolved session id (ss_session_id), so a peer's snapshot is structurally unreachable at consume time. Vendor env vars (e.g. CLAUDE_CODE_SESSION_ID) are aliases, not the only key (GAP-469).

Compaction path (do not weaken):

Load helpers:

. "$REVEALFLEET_ROOT/revskills/scripts/lib/session-state.sh"

Step 1 — Pre-flight: resolve the session id + target path

SID="$(ss_session_id 2>/dev/null || true)"
if [ -z "$SID" ]; then
  echo "ABORT: could not auto-resolve session id (ss_session_id). Expected Grok active_sessions / SessionStart stamp / CLAUDE_CODE_SESSION_ID. Do not invent an id."
else
  WRITE_PATH="$(ss_snapshot_write_path "$SID")"
  SNAP_DIR="$(ss_snap_dir)"
  echo "session id (auto): $SID"
  echo "snapshot target (neutral SSOT): $WRITE_PATH"
  [ -f "$WRITE_PATH" ] && echo "(exists — this run REFRESHES it)" || echo "(new)"
  LEGACY="$(ss_snapshot_path "$SID" 2>/dev/null || true)"
  if [ -n "$LEGACY" ] && [ "$LEGACY" != "$WRITE_PATH" ]; then
    echo "note: legacy snapshot also present at $LEGACY (will not be written; prefer neutral write)"
  fi
fi

ss_session_id is automatic (GAP-469): vendor env aliases, SessionStart PID stamps, and Grok ~/.grok/active_sessions.json (ancestor PID match). The operator does not export anything. If it aborts, stop — do not invent a filename (GAP-317 id-match contract).## Step 2 — Assemble mechanical state (cheap, factual)

Reuse the existing fleet verifier for the objective scaffold — do NOT re-derive per-repo git state by hand (a bare git loop trips the cd-first bash guard anyway). prepare-for-exit.js already reports fleet clean-checkouts, lingering worktrees, and unpushed commits:

cd "$JV_REPO" && node scripts/prepare-for-exit.js

Then, for each repo you actually TOUCHED this session, grab the branch + short status directly (each command cd-prefixed, per the fleet bash rule — never git -C):

cd "$REVEALFLEET_ROOT/revealui" && git status -sb | head -1

Open PRs you authored (best-effort — skip if gh is slow or offline; list from memory if so):

cd "$REVEALFLEET_ROOT/revealui" && gh pr list --author "@me" --state open --json number,title,headRefName --limit 20

Step 2.5 — Peer packet (GAP-494, read-only)

node "$REVEALFLEET_ROOT/revskills/skills/revealui-coordinate/scripts/coordinate.js" --mode=report

Fold the roster into ## Active-Constraints as a short Peers list. Do not write workboard fragments from snapshot.

Step 3 — Author the five sections + Write the file

Using the mechanical state above plus what you actually did this session, Write $WRITE_PATH (from Step 1; always the neutral SSOT under ss_snap_dir) with exactly this shape (frontmatter + the five sections the checkpoint consumer maps onto the rolling handoff). Fill <> placeholders; never leave a section empty — write "none" if truly empty.

---
session_id: <the $SID value>
created: <run: date -u +%Y-%m-%dT%H:%M:%SZ>
model: <your model id, e.g. claude-opus-4-8>
occupancy-pct: <the last [context] advisory pct if you saw one, else omit this line>
---

# Snapshot — <one-line session theme>

## Resume-From-Here
<The single most important thing: what the next actor does next, with exact commands / PR numbers / paths. Written so a fresh session needs nothing else to continue.>

## What-Shipped
<Merged/opened PRs with numbers, commits, what landed and where (test/main). Facts, not intentions.>

## Active-Constraints
<Load-bearing constraints in force this session: locked posture, gotchas discovered, tool/shell quirks, dirty files not to touch, peer worktrees.>

## Do-Not-Repeat
<Mistakes made + corrected this session, so the next actor does not re-make them.>

## Open-Loose-Ends
<Unfinished threads, owner-gated items, verdict-pending PRs, follow-ups filed.>

Refresh semantics: re-running /snapshot overwrites the same $SID.md with the current state — later in a session is more accurate, so refresh freely when the picture has materially changed.

Step 4 — Memory promotion

Durable lessons are product memory in the knowledge graph (revealui.memory.v1), as skills/multi-agent-memory defines it. Claude ~/.claude memory files, Grok [memory], and any other vendor home are pointers. They are not a second durable store. Do not write ~/.claude/projects/<project>/memory/ from this step.

Scan ## Active-Constraints and ## Do-Not-Repeat:

• Session-only facts stay in the snapshot.
• A feedback-class or rule-class lesson that should outlive the session stays in those sections and is named under ## Open-Loose-Ends until the knowledge graph is available. Do not copy it into a vendor memory directory.
• Do not add a memory-promoted: line that points at Claude vendor memory files.

Step 5 — Best-effort daemon dual-write (GAP-342)

After the filesystem write succeeds, dual-write the five sections into the RevDev daemon when it is running (Pro license). The file under $WRITE_PATH remains the skill SSOT; the daemon store is additive for Studio resume-by-id.

# Soft-fail: prints ok:… or skipped:… — never aborts the skill
ss_daemon_snapshot_write "$WRITE_PATH" "$SID"

Requires ~/.local/share/revealui/harness.sock (or REVEALUI_SOCKET / DAEMON_SOCKET). Optional bind: REVDEV_ACTOR_AGENT_ID. Free-tier or missing socket → skipped:… (ok).

Do not

• Do NOT write to any path other than $WRITE_PATH from ss_snapshot_write_path (neutral coordination root). The filename IS the id-match contract the consumer depends on.
• Do NOT ask the operator to export AGENT_SESSION_ID / CLAUDE_CODE_SESSION_ID — resolution is automatic via ss_session_id (GAP-469).
• Do NOT invent mechanical state — if gh/git could not answer, say so in the section rather than guessing PR numbers or branch names.
• Do NOT promote session-scoped facts to memory; only durable feedback/rule-class lessons. Over-promotion is drift.
• Do NOT skip this skill when Stop-blocked or when a [snapshot] advisory fires — compaction after this turn will drop session fidelity for /checkpoint.
• Do NOT treat a file with origin: precompact-mechanical as done; that is a last-ditch hook capture. Overwrite it with this skill while remainder context is still high.
• Do NOT author the five narrative sections from a hook. scripts/snapshot-before-compact.js may only Stop-block or write a labeled mechanical last-ditch. See GAP-317 design ($JV_REPO/docs/gap-specs/GAP-317-session-snapshot-lifecycle-design.md) and GAP-469 design ($JV_REPO/docs/gap-specs/GAP-469-revskills-vendor-agnostic-design.md).