Save, list or restore a working-tree restore point

This procedure is user-invoked only; there is no automatic hook. The agent enforces the user's clear yes before restoring by judgment (advisory). The script enforces git-only operation, restore-point name validation, symlink refusal across the repository root, .git and ref paths, a private temporary index that leaves the real index, branch and HEAD untouched, preview by default with a SHA-256 digest, an automatic pre-restore snapshot before overwriting files, keeping files that exist now but not in the point, bounded printable output, and local restore refs. The script makes no network call itself and passes hardening options to git (core.hooksPath=/dev/null and core.fsmonitor=false); a repository's own configuration can still make git run its filters.

Untracked files that git does not ignore, .env included, are captured into the local object store; they stay local unless someone pushes all refs or makes a mirror clone or bundle, so never push refs/finolabs/*.

1. For list (or when no action is named), run python3 -I <this skill folder>/scripts/restore_point.py list. In a git repository it lists restore points under refs/finolabs/restore/ newest first with their name, timestamp and files changed against the commit they were taken from (enforced by the script). Outside a git repository, every action prints "Not a git repository: this cannot help here. Run git init yourself to start one; nothing was created." without creating anything (restore exits 1; create and list exit 0) (enforced by the script); report that message and stop (advisory: agent judgment).
2. For create, run python3 -I <this skill folder>/scripts/restore_point.py create. Using GIT_INDEX_FILE inside a fresh 0700 temporary folder that is removed afterwards, the script snapshots tracked, modified and non-ignored untracked files into a commit object on refs/finolabs/restore/<YYYYMMDDTHHMMSSZ> without modifying the user's index, branch, HEAD or working tree, and without creating branches or tags or running git gc or git stash (enforced by the script). Report the ref name and the number of files.
3. For restore <name>, failures exit nonzero. First run python3 -I <this skill folder>/scripts/restore_point.py restore <name> without --yes. The script validates <name> against ^[0-9]{8}T[0-9]{6}Z(-[a-z0-9-]{1,20})?$, accepts a single-line .git file pointing to an existing git directory owned by the user (linked worktrees require a matching gitdir back-pointer; submodules remain supported), refuses symlinks in .git, the repository root and paths below it, or ref paths, allows symlinked parents above the repository root, and prints a preview only: the diff stat and name-status against a temporary-index tree of the current working tree, which files would be overwritten, which files exist now but not in the restore point (and states that these are NOT deleted), and a Digest: line binding the preview, restore commit oid and current-state tree oid (enforced by the script). File names are limited to 80 characters with an ellipsis when truncated. Show the preview and ask for a clear yes to restore <name>, through the host's native question tool when the session has one (advisory: agent judgment). Offer neutral Yes and No choices with none preselected or marked recommended; a default, a timeout or an auto-selected option never counts as the yes (advisory: agent judgment). Advisory (agent judgment): Talk to the user in the language they are using, including questions and option labels; keep command names, flags, file paths, skill names and other technical names unchanged. Script output stays English; report it to the user in their language (advisory, agent judgment).
4. Only after that yes (advisory: agent judgment), run python3 -I <this skill folder>/scripts/restore_point.py restore <name> --yes --digest <sha256 prefix> with at least eight hexadecimal characters of the Digest: printed by the preview. On a missing or mismatched digest the script changes no working files, index or refs (building the preview still writes local git objects); on a match it first creates a pre-restore restore point of the current working tree so the restore can be undone, then checks out the restore point's files into the working tree via a temporary index without deleting extra current files or touching the real index, HEAD or branches (enforced by the script). Report the pre-restore restore point and the restored state.

Git failures, including timeouts, print a plain diagnostic; restore failures and usage errors exit nonzero, while create and list failures retain exit 0. The script allows 120 seconds for add -A and checkout-index, and 15 seconds for metadata calls. If restore fails after saving the pre-restore point, the diagnostic names that point, warns that the tree may be partly restored and explains that restoring that point undoes changes to captured files (enforced by the script). This is not an exact rollback: files added by a partial checkout remain because restore keeps extra files, and symlinked paths are refused and require manual review before recovery.