[Bug]: ~/.spawn/history.json has no schema version — upgrades that change SpawnRecord shape silently corrupt history

[louisgv]

What happened?

~/.spawn/history.json is read and written directly with no schema version field. The SpawnRecord and VMConnection shapes are validated on read via type guards (validateConnectionIP, validateLaunchCmd, etc.), but there is no version marker and no migration path.

Why this is a problem

When a new version of spawn adds, removes, or renames fields on SpawnRecord / VMConnection, users who upgrade with an existing history file will hit one of:

1. Silent data loss — old fields are dropped, new required fields are undefined, and the record is treated as valid but incomplete
2. Silent corruption — a new field repurposes an old key name with a different type/meaning
3. Confusing errors — the type guards reject old records and history appears empty, with no explanation

There is no "your history format is from an older version, migrating…" path. Users who have accumulated many sessions over time (SSH keys, server IDs, agent preferences) could silently lose that data on upgrade.

Suggested fix

1. Add a version field to the top-level history file structure (e.g., { "version": 1, "records": [...] })
2. On read, check the version and run any necessary migrations before passing records to the rest of the app
3. Before writing, stamp the current schema version

A minimal v1 migration would just be: "if no version field → this is v0 → apply v0→v1 transform". Keeps it simple while creating the escape hatch for future changes.

---

Filed from Slack by Ori

[louisgv]

Triage Status

Issue Type: Bug - data integrity issue

Summary: SpawnRecord history file lacks schema versioning, leading to silent corruption when updates change record shape.

Status: Safe to work - this is a straightforward bug fix involving adding schema versioning to prevent data corruption. The fix is localized to history management code.

Recommendation: This is a legitimate bug that should be fixed to protect user data. No security concerns with the fix itself.

-- security/issue-checker

[la14-1]

Fix is ready for review in PR #2256. All 1420 tests pass, biome lint clean.

Changes:

• history.json now uses a versioned envelope: { "version": 1, "records": [...] }
• loadHistory() transparently reads both v0 (bare array) and v1 formats — old files migrate on next write
• Shared writeHistory() helper stamps HISTORY_SCHEMA_VERSION on every write
• Valibot schemas validate the file structure (VMConnectionSchema, SpawnRecordSchema, HistoryFileV1Schema)

-- refactor/issue-fixer

[la14-1]

Fix in PR #2256. Adds schema versioning to history.json with a migration path for existing files.

-- refactor/community-coordinator