Skip to content

fix(agent-org): [11/11] harden full-stack upgrade and rollback compatibility #840

Description

@ShiboSheng

Dependency and goal

Stack after #765 as the final compatibility gate for the Agent Org redesign in #755 and #756#765.

The first ten PRs deliver the product behavior. This issue owns the cross-version compatibility sweep after the full stack is complete. Any additional upgrade or rollback problem found while implementing the remaining PRs should be recorded here and fixed together before release.

Problem discovered during PR3 testing

The real-machine rollback matrix from the current PR3 BuildFast to the official v1.2.6 Release did not reach a usable old UI:

  • the current app persisted a WorkStation Team-tab snapshot using the new members model;
  • v1.2.6 only understands the old children model;
  • v1.2.6 crashed in flattenOrgToMembers(selectedOrg.children) with undefined is not an object.

This was not SQLite corruption. quick_check passed, and the current 15 Agent Org runtime tables plus Turn, context, Task, Inbox, materialization, and session_turn_intents data had zero logical differences from the backup. v1.2.6 created seven empty legacy tables; the three pre-existing legacy tables were unchanged.

#791 covers the database namespace portion of downgrade safety. This issue covers the missing full-product boundary, including browser/WebView persisted state.

Scope

  • Inventory every persisted surface shared across the current full Agent Org stack and the previous official Release: SQLite, WorkStation tabs, WebView/local storage, Agent Org definitions, settings, and ordinary SDE/session data.
  • Fix the children / members cache collision. Prefer versioned or isolated storage over teaching an old binary the new model or clearing unrelated user data.
  • Add any compatibility issue discovered during PR4–PR10 to this issue with its producer, old/new consumer, reproduction, affected data, and evidence.
  • Keep the current canonical schema strict. Do not restore PR828→PR3 compatibility: PR828 is not a release or rollback target.
  • Define a documented, reversible rollback procedure for any state that cannot be transparently shared.

Acceptance

Using a backed-up, completely quiescent real home:

  1. Verify official v1.2.6 → final Agent Org stack.
  2. Verify final Agent Org stack → official v1.2.6 → final Agent Org stack.
  3. v1.2.6 reaches a usable UI without the children / members crash.
  4. The final stack's canonical Agent Org data retains the same logical fingerprints across rollback and return.
  5. Legacy data created by v1.2.6 is isolated or cleaned by the documented current-version behavior without weakening fail-closed schema checks.
  6. Ordinary SDE/session data remains usable in both versions.
  7. Add automated fixtures for every compatible persisted format and complete a real signed-Release/BuildFast matrix on macOS.

If a schema error, application error, or logical fingerprint difference appears, stop without Restart, blanket cache clearing, or manual database repair; record the evidence here.

Plain-language contract

The first ten PRs build the new Agent Org. This eleventh issue makes sure the new version and the previous official Release do not break each other's saved data. New compatibility findings belong here and are fixed as one final release gate.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions