# Li Safe Install

> Protect explicitly owned installation files with verified snapshots and conflict-preserving restore; announce recovery paths and refuse unowned rollback.

- Skill: `jokerman89/li-safe-install` (Agent Skill)
- Install (CLI): `npx get-skill add jokerman89/li-safe-install`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/li-safe-install/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jokerman89/li-safe-install

---


> **Lintel on GitHub Copilot.** Generated from `skills/safe-install/SKILL.md`; edit the canonical file, then run
> `li-copilot init`.
> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,
>   `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`
>   tree, never into the resource root.
> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a
>   `<base>` that the workflow defines as its own directory) mean
>   `../../../skills/safe-install/` in the Lintel source, not this generated folder.
>   `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step
>   runs in the working repository, so use `$LINTEL_SKILLS_DIR/safe-install/` there.
> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never
>   `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run
>   `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`
>   and the profile context.
> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,
>   Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`
>   with that custom agent, WebFetch=`web_fetch`.
> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their
>   files. Named roles such as `CodeReviewer` are custom agents.

# Safe install

Retain backup-before-change, visible restore points, update-source choice, listing,
retention and uninstall/recovery entry points. Execute file recovery through the tested
`bin/li-snapshot.py`, never by removing/replacing an installation tree or interpreting
directory-listing text as deletion targets.

This is a local file safeguard, not a universal transactional installer. Production
services, external hooks, credentials, databases and host settings need their own approved
plans. A file snapshot cannot undo their side effects.

Windows file operations use the trusted shared `lib/native_paths.py` representation
helper after P03's ownership, containment and link checks. Reads, metadata, parents,
temporary files, both publication operands, locks and owned cleanup use the same-location
native spelling; this is not a shorter store or a host-policy change. The logical roots,
filenames, manifest/result/restore formats and explicit caller-selected spellings remain
unchanged. A missing or linked source helper is an error before mutation, never a reason
to load code from the target or `PYTHONPATH`. Other installers and their direct I/O need
their own verified integration; this helper does not establish blanket default-install support.

## Preflight and ownership

1. Resolve the trusted Lintel **source** bundle and the separately authorized **target**
   installation. No operation implicitly uses the user's home or enables private sync.
2. Read the actual installer's managed-file inventory and current diff. Identify each
   owned relative file and any planned new file. Consumer customizations are not owned.
   Stop if ownership or the mutation set is unknown; do not substitute a whole-tree copy.
3. Choose an explicit, existing backup store separate from the target. Keep it private
   to the authorized operator. Verify disk availability and a quiescent/isolated target.
   Symlinks, reparse points, traversal, aliases and Git metadata are refused.
4. Obtain any required mutation authorization before installation, restore, uninstall
   or pruning. Previously authorized scope need not be asked again.

## Snapshot and result binding

Use Python 3.9+ (`python` where that is the Python 3 command) for these snapshot
operations. This is not a prerequisite for native bare installation. All paths below
are quoted argument values; never paste untrusted strings into shell source.

```bash
python3 "$LINTEL_SOURCE_ROOT/bin/li-snapshot.py" \
  --root "$install_root" --store "$backup_store" create \
  --path 'config/settings.json' --path 'bin/tool' --absent 'bin/new-tool'
```

Replace the sample paths with the approved ownership list. The helper records exact
normalized paths, root identity, sizes, modes and SHA-256. It copies and verifies bytes,
rechecks the source, then atomically activates a uniquely identified snapshot directory.
An incomplete `.pending-*` copy is not a valid snapshot and is not automatically removed.
Announce the returned exact ID/path and verified file/byte count before proceeding.
Windows sharing/access errors during the unique directory's activation get at most four
reported retries; the result includes the actual retry count. Persistent errors remain
failures with the pending copy retained. Source-file restore conflicts are never retried
as permission to overwrite a changed file.

The authorized operation must record its **own post-images** as it changes the files.
Use `file_state` only on outputs just produced by that operation in the quiescent target.
Do not take a later arbitrary scan of user files and call those changes yours.
Bind the complete path-to-state JSON with:

```bash
python3 "$LINTEL_SOURCE_ROOT/bin/li-snapshot.py" \
  --root "$install_root" --store "$backup_store" bind "$snapshot_id" \
  --expected "$owned_result_json"
```

Each state is `{"sha256":"<64 hex>","size":<bytes>,"mode":<integer>}` or `null` for an
attributable deletion. The shared `file_state` function produces this shape; do not
invent hashes. Binding verifies the current bytes and exact ownership set, pins the
manifest identity and cannot be overwritten to absorb later changes.

## Operation dispatch

| Entry point | Verified behavior and boundary |
|---|---|
| `--backup-only` | Run `create`, verify the result, announce exact ID/path; no installation mutation |
| `--list-backups` | Run `list`; show protected/eligible IDs and unsupported retained content |
| `--restore <id>` | Run `verify`, review owner/result identity, then explicitly authorized `restore <id>` |
| `--update` | Snapshot owned files, run the actual trusted installer at the explicitly selected local source/ref, record its result and verify; no implicit pull/network or shell command string |
| `--uninstall` | Use a verified installer's owned removal plan or the matching pre-install snapshot/result receipt; never delete the whole target root |

`restore` preflights **all** owned paths and snapshot blobs before changing any source
file. Unchanged originals are left alone. Only bytes matching the bound operation result
may be replaced or removed. Unrelated files, later user edits and foreign snapshots are
preserved. If a conflict exists, report it; there is no force/clobber option.

Restored files are individually atomic and verified. A durable `restore.json` remains
`in-progress` until the entire owned set verifies; a multi-file restore is **not** an
all-or-nothing filesystem transaction. Its version-2 per-file journal records `pending`,
`applying` and `restored` progress, content digests and filesystem observations. Intent
is saved before each mutation and verified completion afterward. A restored file's write
permission is consumed: resuming cannot reuse the old operation receipt to overwrite a
later edit, even when the user saves bytes identical to that old operation's output.

Rerun the same ID after an interruption: every recorded file is preflighted before any
remaining mutation. An unfinished file must retain its recorded identity/state. If the
replacement succeeded before its completion record was saved, an already verified original
can be recognized without rewriting it; ambiguous changed states fail closed. An earlier
aggregate-only version-1 journal cannot establish this ownership and is refused for
automatic resume; preserve it and the verified snapshot for explicit manual recovery.
Snapshots and result receipts retain their existing formats.

A process crash may leave `.operation-lock`;
verify that no operation is running before an operator removes that exact empty lock.
Never automatically steal a lock or roll back the rollback.

An installer without an exact ownership/result contract cannot promise automatic
rollback or uninstall. Stop that mutation and report the missing integration explicitly;
the installer lifecycle owns completing it. Keep the snapshot and original error.
In particular, unmanaged historical installations do not become safely uninstallable
merely because this skill was invoked.

## Retention and historical backups

`list` computes the **union** of the newest five verified snapshots and every snapshot
from the last thirty days. An in-progress/locked or unsupported-journal restore is also protected. Only IDs
outside that union are eligible. It never deletes while listing.

After specific deletion authorization, pass exact eligible IDs to `prune`. The helper
revalidates ownership, hashes and the known file inventory before targeted deletion.
Unexpected files/directories block pruning; there is no wildcard or recursive root
removal. Failed/unsupported backups stay visible and untouched.

Old timestamped `cp -r` backups lack the ownership/digest contract. They remain available
for explicit read-only inspection and comparison, but automatic restore/prune refuses
them. An operator can authorize a separately reviewed file-level recovery after comparing
the historical bytes and current edits. Never auto-select "latest", fall back to an older
snapshot after corruption, or relabel an old backup as verified.

## Report

Record the selected operation, trusted source, target/owned paths, exact snapshot ID,
copy/restore evidence, conflicts, interrupted state and unresolved host side effects.
Report success only when the actual selected operation and its post-check succeeded.
Backup creation alone does not prove update or uninstall completion.

