snapshot-wipe-resilience

Detect and repair partially wiped agent workspaces with integrity checks, signed manifests, guarded restore recipes, bounded local recovery state, and explicit off-box sync. Use when files, scripts, trees, models, or build outputs disappear or lose integrity between turns.

Version 1.5.6. This skill is a small, provider-neutral recovery utility; it does not depend on an AI provider or a particular agent runtime. It helps an operator detect state loss between turns and run a reviewed recovery plan.

It is not a backup service, immutable storage system, sandbox boundary, or secret manager. A restore recipe is executable code. Review it, sign the manifest, and rehearse recovery before relying on it.

When to use it

Use it when a workspace can be partially persisted or recreated:

• a directory survives but its contents are empty or incomplete;
• a download has a valid header but is truncated;
• a script keeps its contents but loses its executable bit;
• build, dependency, model, or skill trees disappear between turns;
• the manifest itself needs an explicit off-box recovery copy.

The tool does not infer that a file is safe to restore merely because its path exists. It compares the current state to a healthy capture in the manifest.

Quick start

bash

python3 scripts/swr.py init --workspace "$HOME"
python3 scripts/swr.py autopilot --workspace "$HOME"
python3 scripts/swr.py sign
python3 scripts/swr.py --json check

check does not alter the workspace and skips recorded smoke commands unless the operator adds --run-smoke; it may refresh the local cache. That option requires a trusted manifest because a smoke string is also shell code. restore and doctor verify a manifest before executing recipes; use --dry-run to inspect a plan without executing it.

bash

python3 scripts/swr.py doctor --dry-run
python3 scripts/swr.py doctor --quarantine --resume
python3 scripts/swr.py why --only entry-id

Run a turn-start hook only after reviewing every recipe and its required network, credentials, and destructive operations. The reference hook is an example, not an automatic installation step.

Integrity model

Kind	Default check	What it catches
file	SHA-256 and executable mode	edits, truncation, and lost +x
blob	exact byte count plus 1 MiB head/tail digest	truncation and sampled same-size corruption with bounded I/O
tree	sentinels and a tight file-count lower bound	empty or partially installed trees
tree with --content-hash	full-content tree digest	same-size edits in every regular file, at the cost of reading the tree

--content-hash is the supported name; --merkle remains a CLI alias for compatibility. New entries store tree_sha256, a deterministic full-content tree digest. Older entries containing merkle are still read as legacy metadata-only fingerprints over relative path, size, and mode. That legacy field is not a content hash and is not called a Merkle tree here.

--no-cache forces re-verification. The normal cache is a performance optimization based on size, mtime, and inode plus an expiry; it is not a tamper boundary. A hostile actor who can change a file and preserve those attributes can defeat a cached check, so use --no-cache for a high-assurance check.

Add entries while healthy:

bash

swr add run.sh --kind file --tier 1 --restore 'chmod +x "$HOME/run.sh"'
swr add src --kind tree --tier 2 --sentinel main.c --content-hash \
  --restore 'rebuild-command'
swr models                    # report large model/weight files
swr models --apply            # track them as byte-counted blobs; no recipe is invented

The --restore and --smoke values are stored shell strings. They are not parsed into a safe command list. This is intentional for portability, but it means the author must quote paths and review side effects.

Ordering, repair, and output

Tiers are a sorting hint. --needs ID expresses a real dependency. A failed dependency skips its dependent; a dependency cycle fails closed. doctor checks, restores damaged entries, and checks again. --quarantine preserves a copy of the previous tracked path in private ~/.swr/quarantine before a recipe runs. Inline escrow restores use a bounded decompressor and an atomic file replacement; general shell recipes cannot be made atomic by this tool.

Machine-readable output is available with the global option before the command:

bash

swr --json check
swr --json doctor --dry-run
swr --json why --only entry-id
swr --json stats
swr --json verify

Exit codes are stable: 0 healthy/success, 1 damaged, 2 unrepairable, 3 re-check failure, and 4 malformed or unsupported manifest. selftest executes selected signed recipes twice and verifies the entry after each run. An empty selection fails rather than pretending to provide coverage; use --allow-empty only when checking a newly initialized manifest.

export-recipes --format sh|md|json emits a recovery plan; Markdown is the safe default. Shell output contains the recorded recipe strings and requires --allow-shell-export plus a trusted manifest (or a second explicit override for an untrusted manifest). bash -n is a useful syntax check but not a safety review and does not execute the recipes.

Signatures and trust

A manifest stores a local HMAC-SHA256 signature. When a local ML-DSA-87 identity is available, swr sign also stores a public-key signature. A restore operation accepts the local HMAC or a public-key signature whose fingerprint is in ~/.swr/trusted_signers.json:

bash

swr sign                         # a new local manifest
swr sign --approve-digest DIGEST # an edited/pulled manifest after review
swr verify
swr trust mine
swr trust add FINGERPRINT operator-name   # verify out of band first

A pulled, edited, unsigned, untrusted, or altered manifest cannot run recipes. Mutation commands do not silently convert an untrusted loaded manifest into a locally signed one. To sign a new or edited manifest, review its exact digest and pass swr sign --approve-digest DIGEST; the digest is checked immediately before signing. For a deliberate one-off execution review, restore, doctor, and selftest accept --i-trust-this-manifest DIGEST; the digest must match the exact content at execution time. These are explicit consent paths, not authentication.

check validates manifest entries without executing restore or smoke strings. check --run-smoke is the exception and requires the same signature guard. verify reports both signature paths without modifying the manifest.

Declared operational permissions

• Local file read: reads the manifest and tracked workspace paths to hash, verify, and plan recovery.
• Local file write: writes only the explicitly selected manifest, private state under ~/.swr, quarantine copies, and requested restore targets inside the manifest workspace. Quarantine preserves existing data rather than deleting it.
• Shell execution: restore recipes, smoke commands, and exported runbooks are executable content and run only after the documented trust/consent checks; ordinary check does not execute them.
• Environment access: reads configuration such as the manifest path and optional redaction variables, but does not read credential values implicitly. Identity/private-key files are used only by the explicit crypto and sync commands.
• Network: the core checker makes no network calls. Only the explicit swr_paste.py sync component uses HTTPS, and only for the documented Pastebin, dpaste, and paste.rs hosts; it bounds payloads and refuses redirects. Network access is not required for local recovery.

Privacy and local state

The core checker makes no network calls and does not read credential values. Presets can hash-track credential files but their placeholder recipes only recreate directories, permissions, or empty files. Supply secret values through a password manager or other manual secret channel; this utility does not read those values implicitly. Redaction is a precaution, not proof that a document contains no secret.

By default, check and doctor do not write history. Add --record to append local status codes to ~/.swr/history.jsonl for stats; --no-record remains as a compatibility flag. The file is local-only, private, rotated, and contains entry IDs and statuses rather than file contents. No telemetry is sent. Cache and resume state are also local and best-effort.

The optional canary command deliberately writes probe files to the workspace and /tmp; run swr canary clean after reading the result. It is not part of a normal check.

Off-box manifest sync

swr_paste.py is separate from the local checker. It is an explicit network operation for a recovery copy:

bash

python3 scripts/swr_crypto.py keygen --name this-machine
python3 scripts/swr_paste.py push --mirror
python3 scripts/swr_paste.py pull 'https://dpaste.com/EXAMPLE' \
  --out "$HOME/.swr/manifest.json"
python3 scripts/swr.py verify

With an identity, push encrypts to that identity by default. Otherwise the operator must choose --pq-to, --encrypt-to for an age recipient, or explicitly acknowledge cleartext with --plaintext-ok. A manifest containing inline escrow is never accepted for cleartext upload: compression and Base64 are not confidentiality, so escrow requires encrypted transport. Unencrypted pushes redact known token formats; --paranoid adds a heuristic entropy pass and --strict refuses when unknown candidates remain. Encrypted pushes also scan for known secret-shaped values and refuse by default; --allow-encrypted-secrets is an explicit exception for a reviewed encrypted manifest. Encryption and redaction are not combined by default because redacting changes signed manifest bytes; --force-redact is a deliberate signature-breaking option, not a normal recovery path.

Supported upload backends are Pastebin (when PASTEBIN_API_KEY is available), dpaste, and paste.rs. --verify is enabled by default and compares the transport payload after upload. Responses and decompressed payloads are capped at 64 MiB, pull accepts only HTTPS URLs for those three approved hosts, refuses embedded credentials and non-default ports, does not follow redirects, and writes atomically. Pulled ${ENV_VAR} placeholders are never expanded from this process environment; set values manually through the operator's own secret channel after review. Backend availability, expiry, access logs, URL metadata, and service compromise remain outside this utility's control.

Hybrid-PQ encryption limits

swr_crypto.py requires OpenSSL 3.5 or newer with ML-KEM-1024 and ML-DSA-87:

• X25519 ephemeral key agreement (RFC 7748);
• ML-KEM-1024 (NIST FIPS 203);
• HKDF-SHA-512 with a transcript (RFC 5869);
• ChaCha20 plus HMAC-SHA-512/256 encrypt-then-MAC;
• optional ML-DSA-87 sender authentication (NIST FIPS 204).

SWR-HYBRID-v1 is an application-specific, unaudited composition. It is not RFC 8439 ChaCha20-Poly1305, and this skill makes no formal claim that either KEM can be broken only by breaking both, or that captured data is guaranteed safe against every future adversary. Verify peer fingerprints out of band. For high-consequence data, use a reviewed protocol such as age or Signal. Private key files are mode 600 under a mode 700 identity directory; Python memory cannot be reliably zeroized.

Release and compatibility checks

Use a temporary HOME and a non-empty harmless fixture for restore tests. Do not call an empty manifest a restore test. A local gate should include:

bash

python3 -m py_compile scripts/*.py
python3 scripts/swr_crypto.py selftest
python3 scripts/swr.py attacktest
bash -n reference/turn-start-hook.sh
# then test init/add/escrow/corruption/restore/re-check with a temp workspace

The scripts use Python standard-library modules. The PQ layer has an external OpenSSL requirement; integrity checking, local HMAC signing, and guarded shell restoration do not require ML-KEM. The skill emits text, Markdown, JSON, and shell plans rather than depending on a specific model's output format.

Files

• scripts/swr.py — integrity checker, signer, planner, and guarded restorer.
• scripts/swr_paste.py — explicit sync, redaction, and bounded transport.
• scripts/swr_crypto.py — OpenSSL-backed identity and hybrid-PQ envelopes.
• reference/manifest.example.json — annotated manifest schema.
• reference/turn-start-hook.sh — optional start-of-turn example.
• skill-card.md — risks and output summary.

MIT-0. Use normal backup, immutable-copy, access-control, and disaster-recovery practices for important data.