feat(delegates): restore-from-snapshot API and CLI for delegate secrets

[sanity]

Problem

PR #4034 added per-secret snapshot-on-write retention so prior values survive an accidental overwrite. The snapshots are encrypted, decryptable, and bounded — but there is no API or CLI to actually restore one. Today users must manually move files in {delegate_dir}/.snapshots/{secret_id}/ over the active path.

Proposal

A read API on SecretsStore:

pub fn list_snapshots(&self, delegate: &DelegateKey, key: &SecretsId)
    -> Result<Vec<SnapshotMetadata>, SecretStoreError>;

pub fn restore_snapshot(&mut self, delegate: &DelegateKey, key: &SecretsId,
                        timestamp_ms: u64) -> Result<(), SecretStoreError>;

And an fdev wrapper:

fdev delegate snapshots list <delegate_key> <secret_id>
fdev delegate snapshots restore <delegate_key> <secret_id> <timestamp_ms>

Restore semantics: copy the chosen snapshot back through the same hard-link + atomic rename path that store_secret uses, taking a fresh snapshot of the value being replaced first (so restore is itself recoverable).

Why a separate issue

The base PR scoped to "preserve prior values, don't lose data". User-facing recovery UX has its own design questions (timestamp display, partial restores, dry-run). Worth its own review cycle.

Related

• PR feat: per-secret snapshots with tiered retention for delegates #4034 introduces the snapshot history this would consume
• Delegates as durable vaults: multi-device sync and backup for private data #3050 vault delegate plan would expose restore through the multi-device sync layer eventually

[AI-assisted - Claude]

[github-actions]

🤖 Auto-labeled

Applied labels:

• T-feature (95% confidence)
• P-medium (90% confidence)
• E-medium (80% confidence)
• A-contracts (85% confidence)
• A-developer-xp (80% confidence)
• S-needs-design (80% confidence)

Reasoning: The issue requests new API and CLI functionality to restore encrypted snapshots for delegate secrets, which is a feature request (T-feature). It is a normal-priority UX/management enhancement (P-medium). Implementing the read/restore API and safe atomic restore semantics plus CLI wrappers is moderate complexity (E-medium). The change touches delegate/secret management which in this project maps to the contracts area and also impacts developer-facing tooling (fdev CLI), so A-contracts and A-developer-xp are appropriate. The issue explicitly calls out UX/design questions (timestamp display, partial restores, dry-run) so it needs design discussion (S-needs-design).

Previous labels: P-medium, T-feature, A-contracts

If these labels are incorrect, please update them. This helps improve the auto-labeling system.