Rewind checkpoints

The pi-rewind-hook extension records exact file-state checkpoints and restores them during /fork and /tree navigation. It is not bundled in the default Selesai boot manifest and must be treated as an optional extension.

Optional extension

Not loaded automatically. Install or enable it separately before use.

Runtime surface: Automatic

Setup and prerequisites

The source directory exists but pi-rewind-hook is not listed in src/extensions/package.json, so Selesai does not load it automatically.
To use it, install it as a Pi/Selesai extension from npm:pi-rewind-hook (or load it explicitly if you maintain your own extension list).
Requires a git repository. It does not work outside a git worktree.
Requires a compatible Pi/Selesai version and Node.js runtime.

What it sets up

Hooks into session lifecycle events (session_start, session_tree, session_before_fork, session_before_tree, turn_start, turn_end, agent_end, session_compact, session_shutdown) to record worktree snapshots.
Stores metadata in hidden rewind-turn and rewind-op custom session entries.
Uses a single git reachability ref, refs/pi-rewind/store, to keep snapshot commits alive.

What you can configure

Optional Rewind reads all settings from the rewind key in settings.json. It has no standalone /rewind command.

Configuration locations and precedence

User settings
~/.selesai/agent/settings.json
All Rewind settings live under rewind.*.

Settings

Key / path	Type, default, and values	Description
`rewind.silentCheckpoints`	boolean Default: false	Hide footer/status and checkpoint notifications.
`rewind.retention.maxSnapshots`	number Default: (unlimited)	Optional cap on unpinned unique snapshot commits kept reachable.
`rewind.retention.maxAgeDays`	number Default: (unlimited)	Optional age limit in days for unpinned snapshot commits.
`rewind.retention.pinLabeledEntries`	boolean Default: false	Keep snapshots bound to labeled nodes exempt from maxSnapshots/maxAgeDays pruning.
`rewind.retention.scanMode`	string Default: "ancestor-only" Allowed values: "ancestor-only", "repo-sessions"	Retention discovery mode: follow current session lineage only, or scan discovered session roots.
`rewind.retention.startupBudgetMs`	number Default: (unlimited)	Optional startup time budget for retention sweeps. Exceeded sweeps are skipped and deferred.

Command, tool, and shortcut controls

Key / path	Description
`/fork and /tree`	Rewind triggers automatically during fork and tree navigation.

Source evidence

src/extensions/pi-rewind-hook/index.ts
src/extensions/pi-rewind-hook/README.md

What you can do

During /fork, select a message and choose a restore option: Conversation only, Restore all, Code only, or Undo last file rewind when an exact rewind point is available.
During /tree navigation, choose Keep current files, Restore files to that point, or Undo last file rewind when the target node has an exact checkpoint.
Keep automatic checkpoints at user pre-prompt boundaries, assistant turn_end boundaries, and selected stateful operations.

Commands, tools, and shortcuts

There is no /rewind command. Rewind is triggered automatically as part of /fork and /tree flows.
The extension itself does not register any commands, tools, or shortcuts.

Limits and safety

Only works inside a git repository.
Restores the exact file state for tracked files and untracked, non-ignored files. It deletes paths present in the current snapshot but absent from the target snapshot, then restores the target snapshot into the worktree without staging the real git index.
Submodules are supported only when their paths stay unchanged, their worktrees are clean and initialized, and each target commit is already available locally. Rewind checks out those target commits without fetching. Exact restore is refused with a clear error for dirty or unavailable submodule state, added or removed submodule paths, and nested submodules; uncommitted files inside submodules are not part of snapshots.
Ignored files, empty directories, exact checkpoints for toolResult nodes, and exact checkpoints for bashExecution nodes are outside the snapshot model.
Retention only affects git object reachability. Session JSONL metadata is append-only and is never compacted by Rewind.
Snapshot commits may be pruned if retention is enabled and they are not pinned; Rewind validates commit existence before offering restore.
The session ledger, not the refs/pi-rewind/store ref, is authoritative for which checkpoint applies to each session node.

Source evidence

Selesai version: 0.10.0