@selesai/code 0.10.2 → 0.12.0

package/dist/extensions/pi-rewind-hook/README.md

@@ -1,245 +1,245 @@
-# Rewind Extension
-
-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
-
-![Selecting a message to branch from](rewind1.png)
-
-![Choosing a restore option](rewind2.png)
-
-## Requirements
-
-- Pi agent v0.65.0+
-- Node.js (for installation)
-- Git repository
-
-## Installation
-
-```bash
-pi install npm:pi-rewind-hook
-```
-
-This will:
-1. Create `~/.pi/agent/extensions/rewind/`
-2. Download the extension files
-3. Auto-discover the extension from the extensions directory (no `settings.json` extension entry required)
-4. Remove legacy hooks/explicit rewind extension entries from `settings.json` if present
-5. Clean up old `hooks/rewind` directory (if present)
-
-## Works with pi-custom-compaction
-
-Rewind works seamlessly with [`pi-custom-compaction`](https://github.com/nicobailon/pi-custom-compaction). When `pi-custom-compaction` writes visible background-summary markers, it can ask Rewind to bind an exact file checkpoint to that marker’s own session-tree node. That means `/tree` can offer the normal `Restore files to that point` option directly on the custom compaction marker instead of falling back to a nearby parent node.
-
-Install the companion extension with:
-
-```bash
-pi install npm:pi-custom-compaction
-```
-
-This is optional. Pi’s default compaction and Rewind’s native compaction checkpoints continue to work without `pi-custom-compaction`.
-
-## Configuration
-
-Optionally add settings to `~/.pi/agent/settings.json`.  For example:
-
-```json
-{
-  "rewind": {
-    "silentCheckpoints": true,
-    "retention": {
-      "maxSnapshots": 2000,
-      "maxAgeDays": 30,
-      "pinLabeledEntries": true
-    }
-  }
-}
-```
-
-### Settings
-
-- `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
-
-If `rewind.retention` is omitted, Rewind keeps exact history with no automatic expiration. This can grow git object storage without bound over time.
-
-## Usage
-
-### Rewinding via `/fork`
-
-1. Type `/fork` in Pi
-2. Select a message to branch from
-3. Choose a restore option
-
-**Options:**
-
-| 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 |
-
-`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.
-
-When you restore files during `/fork`, the undo snapshot is persisted in the **new child session**, because that is where you continue working.
-
-### Rewinding via `/tree`
-
-1. Press `Tab` to open the session tree
-2. Navigate to a different node
-3. Choose a restore option
-
-**Options:**
-
-| Option | Files | Conversation |
-|--------|-------|-------------|
-| **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 |
-
-If you navigate with `Keep current files`, Rewind still persists the resulting session position's exact current file baseline via `rewind-op.current`.
-
-### Examples
-
-**Undo a bad refactor:**
-
-```
-You: refactor the auth module to use JWT
-Agent: [makes changes you don't like]
-
-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 an earlier point:**
-
-```
-You: /fork
-→ Select an earlier message
-→ Select "Restore all (files + conversation)"
-
-Result: Both files and conversation reset to that point.
-```
-
-## How Rewind works
-
-Rewind stores its ledger in hidden session `custom` entries:
-
-- `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
-
-Snapshots are only considered at visible boundaries:
-
-- the user pre-prompt boundary
-- each assistant `turn_end`
-- selected stateful session operations
-
-Rewind does not create per-tool snapshots.
-
-### Canonical exact rewind points
-
-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
-```
-
-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
-
-Show the store ref head:
-
-```bash
-git rev-parse refs/pi-rewind/store
-```
-
-Show the hidden rewind ledger in a session file:
-
-```bash
-grep '"customType":"rewind-' ~/.pi/agent/sessions/**/*.jsonl
-```
-
-## Uninstalling
-
-1. Remove the extension directory:
-   ```bash
-   rm -rf ~/.pi/agent/extensions/rewind
-   ```
-
-2. Remove any `rewind` key from `~/.pi/agent/settings.json` if you added one
-
-3. Optionally, clean up the git reachability ref in each repo where you used the extension:
-   ```bash
-   git update-ref -d refs/pi-rewind/store
-   ```
-
-## Limitations
-
-- Only works in git repositories
-- 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
+# Rewind Extension
+
+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
+
+![Selecting a message to branch from](rewind1.png)
+
+![Choosing a restore option](rewind2.png)
+
+## Requirements
+
+- Pi agent v0.65.0+
+- Node.js (for installation)
+- Git repository
+
+## Installation
+
+```bash
+pi install npm:pi-rewind-hook
+```
+
+This will:
+1. Create `~/.pi/agent/extensions/rewind/`
+2. Download the extension files
+3. Auto-discover the extension from the extensions directory (no `settings.json` extension entry required)
+4. Remove legacy hooks/explicit rewind extension entries from `settings.json` if present
+5. Clean up old `hooks/rewind` directory (if present)
+
+## Works with pi-custom-compaction
+
+Rewind works seamlessly with [`pi-custom-compaction`](https://github.com/nicobailon/pi-custom-compaction). When `pi-custom-compaction` writes visible background-summary markers, it can ask Rewind to bind an exact file checkpoint to that marker’s own session-tree node. That means `/tree` can offer the normal `Restore files to that point` option directly on the custom compaction marker instead of falling back to a nearby parent node.
+
+Install the companion extension with:
+
+```bash
+pi install npm:pi-custom-compaction
+```
+
+This is optional. Pi’s default compaction and Rewind’s native compaction checkpoints continue to work without `pi-custom-compaction`.
+
+## Configuration
+
+Optionally add settings to `~/.pi/agent/settings.json`.  For example:
+
+```json
+{
+  "rewind": {
+    "silentCheckpoints": true,
+    "retention": {
+      "maxSnapshots": 2000,
+      "maxAgeDays": 30,
+      "pinLabeledEntries": true
+    }
+  }
+}
+```
+
+### Settings
+
+- `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
+
+If `rewind.retention` is omitted, Rewind keeps exact history with no automatic expiration. This can grow git object storage without bound over time.
+
+## Usage
+
+### Rewinding via `/fork`
+
+1. Type `/fork` in Pi
+2. Select a message to branch from
+3. Choose a restore option
+
+**Options:**
+
+| 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 |
+
+`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.
+
+When you restore files during `/fork`, the undo snapshot is persisted in the **new child session**, because that is where you continue working.
+
+### Rewinding via `/tree`
+
+1. Press `Tab` to open the session tree
+2. Navigate to a different node
+3. Choose a restore option
+
+**Options:**
+
+| Option | Files | Conversation |
+|--------|-------|-------------|
+| **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 |
+
+If you navigate with `Keep current files`, Rewind still persists the resulting session position's exact current file baseline via `rewind-op.current`.
+
+### Examples
+
+**Undo a bad refactor:**
+
+```
+You: refactor the auth module to use JWT
+Agent: [makes changes you don't like]
+
+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 an earlier point:**
+
+```
+You: /fork
+→ Select an earlier message
+→ Select "Restore all (files + conversation)"
+
+Result: Both files and conversation reset to that point.
+```
+
+## How Rewind works
+
+Rewind stores its ledger in hidden session `custom` entries:
+
+- `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
+
+Snapshots are only considered at visible boundaries:
+
+- the user pre-prompt boundary
+- each assistant `turn_end`
+- selected stateful session operations
+
+Rewind does not create per-tool snapshots.
+
+### Canonical exact rewind points
+
+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
+```
+
+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
+
+Show the store ref head:
+
+```bash
+git rev-parse refs/pi-rewind/store
+```
+
+Show the hidden rewind ledger in a session file:
+
+```bash
+grep '"customType":"rewind-' ~/.pi/agent/sessions/**/*.jsonl
+```
+
+## Uninstalling
+
+1. Remove the extension directory:
+   ```bash
+   rm -rf ~/.pi/agent/extensions/rewind
+   ```
+
+2. Remove any `rewind` key from `~/.pi/agent/settings.json` if you added one
+
+3. Optionally, clean up the git reachability ref in each repo where you used the extension:
+   ```bash
+   git update-ref -d refs/pi-rewind/store
+   ```
+
+## Limitations
+
+- Only works in git repositories
+- 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