pi-rewind-hook 1.7.2 → 1.8.0

package/CHANGELOG.md

@@ -4,18 +4,30 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-### Changed
-- Added `pi-package` keyword for npm discoverability (pi v0.50.0 package system)
-
-## [1.7.1] - 2026-01-22
+## [1.8.0] - 2026-04-03
 
 ### Changed
-- Reordered restore menus to show non-file-restorative options first (most common action)
-  - Branch menu: "Conversation only" now appears first
-  - Tree navigation: "Keep current files" now appears first
+- Replaced the old git-ref checkpoint ledger with session-native `rewind-turn` and `rewind-op` records
+- Rewind points are now aligned to visible session nodes: the triggering user node and each assistant step captured at `turn_end`
+- Snapshot commits are now kept reachable through a single `refs/pi-rewind/store` keepalive ref instead of one ref per checkpoint
+- Removed the fixed 100-checkpoint per-session pruning model; exact mode now has no cap by default
+- `/fork` and `/tree` now persist resulting exact file state through `rewind-op.current`, including keep-current-files flows
+- Undo snapshots now persist with the resulting session state instead of depending on old before-restore refs
+
+### Added
+- Lineage-aware exact snapshot lookup through `parentSession`
+- Exact assistant-node rewind for v2 captures
+- Compaction and branch-summary snapshot aliasing without creating fresh snapshots when files did not change
+- Optional retention over unique snapshot commits via `rewind.retention.maxSnapshots`, `rewind.retention.maxAgeDays`, and `rewind.retention.pinLabeledEntries`
+- Retention discovery mode setting via `rewind.retention.scanMode` (`ancestor-only` default, optional `repo-sessions`)
+- Startup retention sweep budget setting via `rewind.retention.startupBudgetMs`
 
 ### Fixed
-- Resume checkpoint now session-scoped (`checkpoint-resume-{sessionId}-{timestamp}`) for consistency with other checkpoint types
+- Restore now deletes files absent from the target snapshot before worktree-only restore, producing exact restore for tracked and untracked non-ignored files in the snapshot domain without staging the repo index
+- Rewind bookkeeping for reconstruction, capture, migration, and retention no longer depends on UI availability
+- `/tree` restore options now match actual exact rewind availability: user, assistant, compaction, and branch-summary nodes only
+- Critical rewind handlers now fail closed with user-facing errors instead of bubbling git/storage exceptions through `/fork` and `/tree`
+- Turn capture/finalization now warns and recovers when snapshot writes fail, avoiding stale collector state
 
 ## [1.7.0] - 2026-01-15
 
@@ -37,12 +49,12 @@ All notable changes to this project will be documented in this file.
 - Old-format checkpoints are not pruned (to avoid cross-session interference)
 - New checkpoints are created in the new session-scoped format
 
-## [1.6.0] - 2025-01-13
+## [1.6.0] - 2026-01-13
 
 ### Added
 - `rewind.silentCheckpoints` setting to hide checkpoint status and notifications
 
-## [1.5.0] - 2025-01-10
+## [1.5.0] - 2026-01-10
 
 ### Changed
 - Replaced noisy stderr logging with clean TUI output
@@ -88,7 +100,7 @@ All notable changes to this project will be documented in this file.
 - Install script now migrates old hooks config and cleans up old directory
 - Renamed "Hook" to "Extension" throughout codebase and docs
 
-## [1.2.0] - 2025-01-03
+## [1.2.0] - 2026-01-03
 
 ### Added
 - Tree navigation support (`session_before_tree`) - restore files when navigating session tree
@@ -102,13 +114,13 @@ All notable changes to this project will be documented in this file.
 - Removed `agent_end` handler that was clearing checkpoints after each turn
 - "Undo last file rewind" now cancels branch instead of creating unwanted branch
 
-## [1.1.1] - 2024-12-27
+## [1.1.1] - 2025-12-27
 
 ### Fixed
 - Use `before_branch` event instead of `branch` for proper hook timing (thanks @badlogic)
 - Cancel branch when user dismisses restore options menu
 
-## [1.1.0] - 2024-12-27
+## [1.1.0] - 2025-12-27
 
 ### Added
 - "Undo last file rewind" option - restore files to state before last rewind
@@ -122,7 +134,7 @@ All notable changes to this project will be documented in this file.
 ### Fixed
 - Code-only restore options now properly skip conversation restore
 
-## [1.0.0] - 2024-12-19
+## [1.0.0] - 2025-12-19
 
 ### Added
 - Initial release

package/README.md

@@ -1,6 +1,8 @@
 # Rewind Extension
 
-A Pi agent extension that enables rewinding file changes during coding sessions. Creates automatic checkpoints using git refs, allowing you to restore files to previous states while optionally preserving conversation history.
+A Pi agent extension that records exact file-state rewind points, allowing restoration of file states during `/tree` navigation and across resumed and forked sessions
+
+Rewind metadata lives in the session itself as hidden entries, so rewind history survives across forks, resumes, tree navigation, and compaction. Snapshot commits are kept reachable through a single git ref rather than one ref per checkpoint, and rewind points can be resolved across session lineage via `parentSession` links. Retention is optional and configurable; without it, exact history is kept indefinitely.
 
 ## Screenshots
 
@@ -10,9 +12,9 @@ A Pi agent extension that enables rewinding file changes during coding sessions.
 
 ## Requirements
 
-- Pi agent v0.35.0+ (unified extensions system)
+- Pi agent v0.35.0+
 - Node.js (for installation)
-- Git repository (checkpoints are stored as git refs)
+- Git repository
 
 ## Installation
 
@@ -24,173 +26,191 @@ This will:
 1. Create `~/.pi/agent/extensions/rewind/`
 2. Download the extension files
 3. Add the extension to your `~/.pi/agent/settings.json`
-4. Migrate any existing hooks config to extensions (if upgrading from v1.2.0)
+4. Migrate any existing hooks config to extensions (if upgrading from an older version)
 5. Clean up old `hooks/rewind` directory (if present)
 
-### Alternative Installation
-
-Using curl:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main/install.js | node
-```
-
-Or clone the repo and configure manually:
-
-```bash
-git clone https://github.com/nicobailon/pi-rewind-hook ~/.pi/agent/extensions/rewind
-```
-
-Then add to `~/.pi/agent/settings.json`:
-
-```json
-{
-  "extensions": ["~/.pi/agent/extensions/rewind/index.ts"]
-}
-```
-
-### Platform Notes
-
-**Windows:** The `npx` command works in PowerShell, Command Prompt, and WSL. If you prefer curl on Windows without WSL:
-
-```powershell
-Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main/install.js" -OutFile install.js; node install.js; Remove-Item install.js
-```
-
-### Upgrading from v1.2.0
-
-If you're upgrading from pi-rewind-hook v1.2.0 (which used the hooks system), simply run `npx pi-rewind-hook` again. The installer will:
-- Move the extension from `hooks/rewind` to `extensions/rewind`
-- Migrate your settings.json from `hooks` to `extensions`
-- Clean up the old hooks directory
-
-**Note:** v1.3.0+ requires pi v0.35.0 or later. If you're on an older version of pi, stay on pi-rewind-hook v1.2.0.
+Or clone the repo into `~/.pi/agent/extensions/rewind/` — Pi discovers extensions in that directory automatically.
 
 ## Configuration
 
-You can configure the extension by adding settings to `~/.pi/agent/settings.json`:
+Optionally add settings to `~/.pi/agent/settings.json`.  For example:
 
 ```json
 {
-  "extensions": ["~/.pi/agent/extensions/rewind/index.ts"],
   "rewind": {
-    "silentCheckpoints": true
+    "silentCheckpoints": true,
+    "retention": {
+      "maxSnapshots": 2000,
+      "maxAgeDays": 30,
+      "pinLabeledEntries": true
+    }
   }
 }
 ```
 
 ### Settings
 
-- **`rewind.silentCheckpoints`** (boolean, default: `false`): When set to `true`, disables checkpoint status messages. The footer checkpoint count (`◆ X checkpoints`) and checkpoint saved notifications (`Checkpoint X saved`) will not be displayed.
+- `rewind.silentCheckpoints` — hides footer/status and checkpoint notifications
+- `rewind.retention.maxSnapshots` — optional cap on unpinned unique snapshot commits kept reachable
+- `rewind.retention.maxAgeDays` — optional age limit for unpinned snapshot commits
+- `rewind.retention.pinLabeledEntries` — when true, snapshot commits bound to **labeled nodes** in the Pi session tree are exempt from `maxSnapshots` and `maxAgeDays` pruning (useful for bookmarking important rewind points you want to prevent getting garbage-collected)
+- `rewind.retention.scanMode` — retention discovery mode: `ancestor-only` (default, follow current session lineage only) or `repo-sessions` (scan discovered session roots)
+- `rewind.retention.startupBudgetMs` — optional startup time budget for retention sweeps; if exceeded, startup sweep is skipped and deferred
 
-## How It Works
+If `rewind.retention` is omitted, Rewind keeps exact history with no automatic expiration. This can grow git object storage without bound over time.
 
-### Checkpoints
+## Usage
 
-The extension creates git refs at two points:
+### Rewinding via `/fork`
 
-1. **Session start** - When pi starts, creates a "resume checkpoint" of the current file state
-2. **Each turn** - Before the agent processes each message, creates a checkpoint
+1. Type `/fork` in Pi
+2. Select a message to branch from
+3. Choose a restore option
 
-Checkpoints are stored as git refs under `refs/pi-checkpoints/` and are scoped per-session (so multiple pi sessions in the same repo don't interfere with each other). Each session maintains its own 100-checkpoint limit.
+**Options:**
 
-### Rewinding
+| Option | Files | Conversation |
+|--------|-------|-------------|
+| **Conversation only (keep current files)** | Unchanged | Reset to that point |
+| **Restore all (files + conversation)** | Restored | Reset to that point |
+| **Code only (restore files, keep conversation)** | Restored | Unchanged |
+| **Undo last file rewind** | Restored to before last rewind | Unchanged |
 
-To rewind via `/branch`:
+`Restore all`, `Code only`, and `Undo last file rewind` are only shown when an exact rewind point or undo snapshot is available for the selected message.
 
-1. Type `/branch` in pi
-2. Select a message to branch from
-3. Choose a restore option
+When you restore files during `/fork`, the undo snapshot is persisted in the **new child session**, because that is where you continue working.
 
-To rewind via tree navigation:
+### Rewinding via `/tree`
 
 1. Press `Tab` to open the session tree
 2. Navigate to a different node
 3. Choose a restore option
 
-**For messages from the current session:**
+**Options:**
 
 | Option | Files | Conversation |
-|--------|-------|--------------|
-| **Restore all (files + conversation)** | Restored | Reset to that point |
-| **Conversation only (keep current files)** | Unchanged | Reset to that point |
-| **Code only (restore files, keep conversation)** | Restored | Unchanged |
-| **Undo last file rewind** | Restored to before last rewind | Unchanged |
+|--------|-------|-------------|
+| **Keep current files** | Unchanged | Navigated to that point |
+| **Restore files to that point** | Restored | Navigated to that point |
+| **Undo last file rewind** | Restored to before last rewind | Navigated to that point |
 
-**For messages from before the current session (uses resume checkpoint):**
+If you navigate with `Keep current files`, Rewind still persists the resulting session position's exact current file baseline via `rewind-op.current`.
 
-| Option | Files | Conversation |
-|--------|-------|--------------|
-| **Restore to session start (files + conversation)** | Restored to session start | Reset to that point |
-| **Conversation only (keep current files)** | Unchanged | Reset to that point |
-| **Restore to session start (files only, keep conversation)** | Restored to session start | Unchanged |
-| **Undo last file rewind** | Restored to before last rewind | Unchanged |
-
-### Resumed Sessions
-
-When you resume a session (`pi --resume`), the extension creates a resume checkpoint. If you branch to a message from before the current session, you can restore files to the state when you resumed (not per-message granularity, but a safety net).
+### Examples
 
-## Examples
-
-### Undo a bad refactor
+**Undo a bad refactor:**
 
 ```
 You: refactor the auth module to use JWT
 Agent: [makes changes you don't like]
 
-You: /branch
+You: /fork
 → Select "refactor the auth module to use JWT"
 → Select "Code only (restore files, keep conversation)"
 
 Result: Files restored, conversation intact. Try a different approach.
 ```
 
-### Start fresh from a checkpoint
+**Start fresh from an earlier point:**
 
 ```
-You: /branch
+You: /fork
 → Select an earlier message
 → Select "Restore all (files + conversation)"
 
 Result: Both files and conversation reset to that point.
 ```
 
-### Recover after resuming
+## How Rewind works
 
-```bash
-pi --resume  # resume old session
-```
+Rewind stores its ledger in hidden session `custom` entries:
 
-```
-Agent: [immediately breaks something]
+- `rewind-turn` — one per prompt, containing the triggering user-node snapshot plus any assistant-node snapshots produced during that prompt
+- `rewind-op` — sparse records for `/fork`, `/tree`, compaction aliases, summary aliases, and undo state
 
-You: /branch
-→ Select any old message
-→ Select "Restore to session start (files only, keep conversation)"
+Snapshots are only considered at visible boundaries:
 
-Result: Files restored to state when you resumed.
-```
+- the user pre-prompt boundary
+- each assistant `turn_end`
+- selected stateful session operations
 
-## Viewing Checkpoints
+Rewind does not create per-tool snapshots.
 
-List all checkpoint refs:
+### Canonical exact rewind points
 
-```bash
-git for-each-ref refs/pi-checkpoints/
+Exact file restore is available for:
+
+- user nodes
+- assistant nodes
+- compaction nodes aliased to the current exact state
+- branch-summary nodes aliased during `/tree`
+
+Exact file restore is not offered for toolResult nodes.
+
+### Git storage model
+
+Snapshot commits are kept reachable through a single repo-local ref:
+
+```text
+refs/pi-rewind/store
 ```
 
-Checkpoint ref format: `checkpoint-{sessionId}-{timestamp}-{entryId}`
+That ref is only for git object reachability; the session ledger is authoritative.
+
+### Deduplication
+
+Before creating a snapshot commit, Rewind captures the worktree tree SHA. If it matches the latest exact snapshot tree, Rewind reuses that existing snapshot commit instead of creating a new one.
+
+### Restore exactness and scope
+
+Rewind restores the exact file state for the snapshot domain it owns:
+
+- tracked files
+- untracked, non-ignored files
+- without staging the real git index during restore
+
+Before restoring target contents, it deletes paths present in the current snapshot but absent from the target snapshot, then restores the target snapshot into the worktree only.
+
+Out of scope:
+
+- ignored files
+- empty directories
+- exact rewind points for `toolResult` nodes
+- exact rewind points for `bashExecution` nodes
+
+## Lineage and resume behavior
+
+Rewind resolves exact rewind points across session lineage by following `parentSession` links and reading rewind metadata from ancestor session files.
+
+Rewind v2 uses only session-native `rewind-turn`/`rewind-op` metadata and does not read legacy checkpoint refs.
+
+## Retention
+
+Retention only affects git reachability. Session JSONL metadata is append-only and is never compacted by Rewind.
+
+When retention is enabled, Rewind keeps snapshot commits alive if they are referenced by:
+
+- a `rewind-turn` or `rewind-op` binding in a discovered same-repo session
+- the latest `rewind-op.current` for a discovered same-repo session
+- the latest `rewind-op.undo` for a discovered same-repo session
+- a labeled bound entry when `pinLabeledEntries` is enabled
+
+If a snapshot commit has been pruned, Rewind validates commit existence before offering restore.
+
+If retention discovery yields an empty live set, Rewind preserves the existing `refs/pi-rewind/store` ref rather than deleting it.
+
+## Viewing storage
 
-Manually restore to a checkpoint (copy ref name from list above):
+Show the store ref head:
 
 ```bash
-git checkout refs/pi-checkpoints/checkpoint-abc12345-...-... -- .
+git rev-parse refs/pi-rewind/store
 ```
 
-Delete all checkpoints:
+Show the hidden rewind ledger in a session file:
 
 ```bash
-git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git update-ref -d
+grep '"customType":"rewind-' ~/.pi/agent/sessions/**/*.jsonl
 ```
 
 ## Uninstalling
@@ -199,19 +219,17 @@ git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git upda
    ```bash
    rm -rf ~/.pi/agent/extensions/rewind
    ```
-   On Windows (PowerShell): `Remove-Item -Recurse -Force ~/.pi/agent/extensions/rewind`
 
-2. Remove the extension from `~/.pi/agent/settings.json` (delete the line with `rewind/index.ts` from the `extensions` array)
+2. Remove any `rewind` key from `~/.pi/agent/settings.json` if you added one
 
-3. Optionally, clean up git refs in each repo where you used the extension:
+3. Optionally, clean up the git reachability ref in each repo where you used the extension:
    ```bash
-   git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git update-ref -d
+   git update-ref -d refs/pi-rewind/store
    ```
 
 ## Limitations
 
 - Only works in git repositories
-- Checkpoints are scoped per-session (multiple sessions in the same repo don't share checkpoints)
-- Resumed sessions only have a single resume checkpoint for pre-session messages
-- Tracks working directory changes only (not staged/committed changes)
-- Each session has its own 100-checkpoint limit (pruning doesn't affect other sessions)
+- Session metadata grows append-only; retention only trims git reachability
+- Discovery for retention is best-effort across discovered Pi session roots and explicit `parentSession` ancestors
+- Ignored files and empty directories are outside the snapshot model