fix: recover rc3 workspace convergence state

.planning/.active_plan

@@ -1 +1 @@
-spec-025-user-initiated-join-supersession
+2026-08-21-missing-workspace-state-recovery

.planning/2026-08-21-missing-workspace-state-recovery/findings.md

@@ -0,0 +1,18 @@
+# Findings: Missing Workspace State Recovery
+
+## Production Evidence
+- The final `17:03:36Z` launch resumed the key session, then reported three peer-scope failures and forty delivery-view failures.
+- The Windows dev database was created on 2026-07-18 and still contains three member, three trusted-peer, and three peer-address relationships.
+- `workspace_convergence_state`, `workspace_convergence_v3_active`, `workspace_convergence_v3_slots`, and `workspace_convergence_v3_migrations` all contain zero rows.
+- The database therefore matches an initialized legacy profile with no convergence state, not a malformed V2 or V3 convergence row.
+
+## Root Cause
+- `build_sync_engine_assembly` always supplies `WorkspaceConvergenceStateOrigin::CurrentInstallation`.
+- When the repository returns no state, `WorkspaceConvergence::load_state` creates a fresh state and only sets legacy provenance for `UpgradeWithoutConvergenceState`.
+- All previous repairs operate on existing V2 or V3 payloads and cannot affect this profile.
+
+## Constraints
+- The decision belongs to `WorkspaceConvergence`; desktop callers must not orchestrate it.
+- Missing state alone is insufficient because a fresh install is also empty.
+- Recovery must use durable initialized-profile evidence, run after the encrypted session is ready, and fail closed on unreadable evidence.
+- No user content, device names, filenames, or paths may be logged.

.planning/2026-08-21-missing-workspace-state-recovery/progress.md

@@ -0,0 +1,21 @@
+# Progress: Missing Workspace State Recovery
+
+## 2026-08-21
+- Confirmed the original failure with a deterministic log replay: one session resume, three peer-scope failures, and forty delivery-view failures.
+- Inspected the Windows dev database read-only and found legacy relationship rows with zero convergence-state rows.
+- Located the incorrect current-installation classification in Engine assembly and the missing-state fallback in `WorkspaceConvergence::load_state`.
+- Added production-shaped tests for existing-install origin, durable missing-state recovery, and the fresh-install negative case.
+- The first short exact Cargo filter ran zero tests; it is not counted as evidence.
+- Listed the full names and ran nonzero tests: the existing-install classification failed with `CurrentInstallation`, durable recovery failed because no state was saved, and the fresh-install negative case passed.
+- Applied the minimal production change: derive origin from whether startup detected a prior installation and persist a newly inferred legacy state during recovery.
+- Reran the focused missing-state tests with nonzero counts: both durable recovery cases passed, and the existing-install classification passed.
+- Updated the architecture behavior and maintenance record for initialized profiles with no convergence row.
+- Next: run the broader convergence suite and all mandatory repository checks.
+
+## Test Results
+| Check | Result |
+|---|---|
+| Final launch log replay | RED: bug reproduced after session resume |
+| Live database state shape | Confirmed: legacy relationships present, convergence rows absent |
+| Missing-state recovery tests | GREEN: 2 passed |
+| Existing-install origin test | GREEN: 1 passed |

.planning/2026-08-21-missing-workspace-state-recovery/task_plan.md

@@ -0,0 +1,46 @@
+# Task Plan: Missing Workspace State Recovery
+
+## Goal
+Recover an upgraded initialized profile that retains legacy member relationships but has no persisted workspace convergence state.
+
+## Current Phase
+Phase 4: Verify and document
+
+## Phases
+
+### Phase 1: Confirm the production data shape
+- [x] Replay the final launch failure after session resume.
+- [x] Inspect the Windows dev database read-only.
+- [x] Confirm legacy relationships exist while all convergence state tables are empty.
+- **Status:** complete
+
+### Phase 2: Write the regression first
+- [x] Reproduce missing state plus initialized legacy relationships at the application owner seam.
+- [x] Prove current code classifies it as a current installation and does not save recovery state.
+- [x] Preserve a fresh-install negative case.
+- **Status:** complete
+
+### Phase 3: Implement the minimal owner-side repair
+- [x] Derive missing-state origin from durable initialized-profile evidence.
+- [x] Persist the recovered encrypted state after session readiness.
+- [x] Keep callers and public interfaces unchanged.
+- **Status:** complete
+
+### Phase 4: Verify and document
+- [ ] Pass the focused regression and convergence suites with nonzero counts.
+- [ ] Run all required repository checks.
+- [x] Update the architecture bible behavior and maintenance record.
+- [ ] Recheck the original diagnostic failure boundary.
+- **Status:** in_progress
+
+## Completion Criteria
+- The production-shaped missing-state regression fails before and passes after the fix.
+- Fresh installations remain unclassified as legacy upgrades.
+- The recovered state is encrypted and survives reopen.
+- All mandatory repository checks pass.
+
+## Errors Encountered
+| Error | Resolution |
+|---|---|
+| Earlier fixes assumed a convergence row existed | Use the live database row counts as the regression fixture shape. |
+| First exact Cargo filter executed zero tests | List full test names, then rerun each exact fully-qualified name and verify nonzero counts. |

.planning/2026-08-21-rc3-workspace-recovery-fix/findings.md

@@ -0,0 +1,37 @@
+# Findings: rc.3 Workspace Recovery Repair
+
+## Requirements
+- Make the recent workspace recovery actually repair the affected persisted profile.
+- Preserve encrypted persistence and fail-closed behavior.
+- Verify the work before reporting.
+- Update `docs/architecture/architecture-bible.md` for every repository change.
+
+## Research Findings
+- The desktop worktree pins Engine `f287d32715fbdac7655db5f8642e3301182ced68`.
+- The latest launch still reports current peer scope unavailable and cascades into history delivery failures.
+- Diagnostic commit `4e04a0d` observed 103 instances with Ready protection, three member rows, no current history, and `migrated_from_pre_adr_020=false`.
+- `d3f7aef` converted rc.3 V2 state to V3 while preserving the false provenance bit.
+- `8ce0c84` repairs direct V2 reads only, so it cannot repair a state already converted by `d3f7aef`.
+- `f287d32` repairs V3 only when phase is `Complete`, own identity exists, peer relationships are nonempty, and current history is absent.
+- Production state transitions initialize to `LocallyApplied`; the pre-ADR-020 converter uses `Converging`. Phase is therefore not durable migration provenance.
+- `recover_legacy_migration_marker` only clears a true marker after current history exists. It does not reconstruct a missing marker.
+- The repository test seam can write the exact rc.4 V3 layout directly into the active encrypted slot, then reopen it through current production loading.
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+| Reproduce the two-step migration in the repository test | It exercises the same persistence boundary that failed in production. |
+| Remove only the invalid phase requirement if stable identity and peer evidence remain | This is the smallest change supported by the observed profile and preserves fail-closed checks. |
+| Add explicit negative cases for missing identity, missing peer evidence, removed state, and recovery failure | These prevent broad inference from absence of current history alone. |
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+| Sanitized diagnostics do not expose the persisted phase or relationship map | Use release source semantics and replay the exact upgrade sequence at the repository seam. |
+
+## Resources
+- `crates/uc-infra/src/db/repositories/workspace_convergence_store.rs`
+- `crates/uc-application/src/space/convergence/membership/bootstrap.rs`
+- `docs/architecture/architecture-bible.md`
+- `docs/adr/021-workspace-convergence-internal-boundaries.md`
+- `docs/adr/023-legacy-profile-isolation-and-re-pairing.md`

.planning/2026-08-21-rc3-workspace-recovery-fix/progress.md

@@ -0,0 +1,55 @@
+# Progress Log: rc.3 Workspace Recovery Repair
+
+## Session: 2026-08-21
+
+### Phase 1: Diagnose the production failure
+- **Status:** complete
+- Confirmed all four Engine commits and the matching desktop pin.
+- Replayed the final launch from `uniclipboard-diagnostics-20260820-161225.zip`.
+- Verified the latest launch still reports the exact peer-scope failure.
+- Ran both existing V3 recovery tests with one test executed in each command; both passed, proving they cover only the narrow modeled states.
+
+### Phase 2: Write the regression first
+- **Status:** complete
+- Added repository-level replay tests for rc.4 V3 states originating from rc.3 with `LocallyApplied` and `Converging` phases.
+- Reworked the existing negative test to preserve fail-closed cases without treating a mutable phase as missing evidence.
+- Listed both tests before running them, then executed both with a nonzero count.
+- Both failed at the intended assertion because `migrated_from_pre_adr_020` remained false.
+
+### Phase 3: Apply the smallest durable fix
+- **Status:** complete
+- Replaced the `Complete` requirement with explicit not-removed, non-recovery, and no-failure guards.
+- Positive replay tests now pass for both `LocallyApplied` and `Converging` states.
+- Added an explicit stored-failure negative case, removed its production guard, and watched the negative test fail at the intended assertion before restoring the guard.
+
+### Phase 4: Verify behavior and repository health
+- **Status:** complete
+- Ran all 19 workspace convergence store tests; all passed with a nonzero count.
+- Passed workspace all-target checks, locked metadata, formatting, architecture validation, and diff validation.
+- Updated the architecture bible behavior description and maintenance record.
+
+## Test Results
+| Test | Expected | Actual | Status |
+|------|----------|--------|--------|
+| Latest diagnostic launch replay | Failure detected | 1 peer-scope failure after final launch | red |
+| Existing positive V3 recovery test | 1 test passes | 1 passed | pass |
+| Existing negative V3 recovery test | 1 test passes | 1 passed | pass |
+| Real rc.4 V3 replay for nonterminal rc.3 states | 2 tests fail before implementation | 0 passed, 2 failed at provenance assertion | red |
+| Real rc.4 V3 replay after implementation | 2 tests pass | 2 passed | pass |
+| Stored-failure fail-closed guard without implementation | 1 test fails | Failed at legacy-provenance assertion | red |
+| Complete workspace convergence store suite | 19 tests pass | 19 passed | pass |
+| Repository delivery checks | All required checks pass | All passed | pass |
+
+## Error Log
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+| 2026-08-21 | Streaming log assertion incorrectly passed | 1 | Counted matching events after the final launch before deciding pass/fail. |
+
+## 5-Question Reboot Check
+| Question | Answer |
+|----------|--------|
+| Where am I? | Complete and ready to commit |
+| Where am I going? | Local verified commit |
+| What's the goal? | Recover already-converted rc.3 workspaces safely |
+| What have I learned? | The phase requirement is not stable migration evidence |
+| What have I done? | Reproduced the failure, repaired it, and passed focused plus repository checks |

.planning/2026-08-21-rc3-workspace-recovery-fix/task_plan.md

@@ -0,0 +1,57 @@
+# Task Plan: rc.3 Workspace Recovery Repair
+
+## Goal
+Recover affected rc.3 workspaces that were already converted by the first rc.4 repair, without weakening fail-closed handling for unrelated or incomplete state.
+
+## Next Step
+Commit the verified recovery repair.
+
+## Current Phase
+Complete
+
+## Phases
+
+### Phase 1: Diagnose the production failure
+- [x] Confirm the desktop build pins the latest Engine repair.
+- [x] Replay the latest diagnostic log and reproduce the exact failure.
+- [x] Identify the gap between the migration tests and the real upgrade sequence.
+- **Status:** complete
+
+### Phase 2: Write the regression first
+- [x] Model an rc.3 legacy-origin state with normal nonterminal phases.
+- [x] Write it using the early rc.4 V3 layout with lost provenance.
+- [x] Prove the current code fails to restore provenance after reopen.
+- **Status:** complete
+
+### Phase 3: Apply the smallest durable fix
+- [x] Restore provenance from stable legacy evidence without requiring `Complete`.
+- [x] Preserve rejection for new, removed, failed, or evidence-free states.
+- [x] Update the architecture bible and maintenance record.
+- **Status:** complete
+
+### Phase 4: Verify behavior and repository health
+- [x] Pass focused repository tests with a nonzero count.
+- [x] Pass affected crate and workspace checks.
+- [x] Run required architecture, formatting, metadata, and diff checks.
+- [x] Confirm no debug instrumentation or unrelated changes remain.
+- **Status:** complete
+
+## Key Questions
+1. Which persisted facts survive both rc.3 and the early rc.4 conversion and uniquely identify this legacy-origin state?
+2. Can recovery avoid relying on the mutable workspace phase?
+3. Which negative cases prevent a fresh or unrelated state from being promoted?
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+| Test the full persisted upgrade sequence | Direct conversion tests missed the already-migrated user state. |
+| Treat workspace phase as mutable, not migration provenance | Production transitions normally use nonterminal phases. |
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+| Initial streaming log assertion returned a false pass | 1 | Replaced it with a deterministic count over the final launch. |
+
+## Notes
+- The original diagnostic replay remains the user-symptom boundary, but a repository sequence test is the agent-runnable fix loop.
+- Do not alter public interfaces or persistence encryption.

crates/uc-application/src/space/convergence/membership/bootstrap.rs

@@ -41,8 +41,11 @@ impl WorkspaceConvergence {
         &self,
     ) -> Result<(), WorkspaceConvergenceError> {
         let _guard = self.state_lock.lock().await;
-        let mut state = self.load_state().await?;
-        if Self::clear_legacy_migration_marker_if_current_history_exists(&mut state) {
+        let (mut state, was_persisted) = self.load_state_with_presence().await?;
+        let initialized_missing_legacy_state = !was_persisted && state.migrated_from_pre_adr_020;
+        if initialized_missing_legacy_state
+            || Self::clear_legacy_migration_marker_if_current_history_exists(&mut state)
+        {
             self.persist(&state).await?;
         }
         Ok(())

crates/uc-application/src/space/convergence/membership/tests.rs

@@ -876,6 +876,52 @@ async fn runtime_clears_a_stale_legacy_marker_after_current_history_exists() {
     assert_eq!(repository.load_state().await.unwrap().unwrap(), repaired);
 }
 
+#[test]
+fn existing_installation_without_convergence_state_keeps_upgrade_origin() {
+    assert_eq!(
+        WorkspaceConvergenceStateOrigin::from_version_transition(Some("1.1.0-rc.4"), "1.1.0-rc.4"),
+        WorkspaceConvergenceStateOrigin::UpgradeWithoutConvergenceState
+    );
+}
+
+#[tokio::test]
+async fn recovery_persists_missing_state_for_an_existing_installation() {
+    let repository = MemoryWorkspaceRepository::default();
+    let mut deps = test_deps(Arc::new(repository.clone()), "device-a", Vec::new());
+    deps.initial_state_origin = WorkspaceConvergenceStateOrigin::UpgradeWithoutConvergenceState;
+    deps.member_repo = Arc::new(FixedMemberRepo(vec![
+        legacy_member("device-a"),
+        legacy_member("device-b"),
+    ]));
+    deps.space_protection = Arc::new(ProtectsQueriedMembers::default());
+    let owner = WorkspaceConvergence::new(deps);
+
+    owner.recover_legacy_migration_marker().await.unwrap();
+
+    let recovered = repository.load_state().await.unwrap().unwrap();
+    assert!(recovered.migrated_from_pre_adr_020);
+    let snapshot = owner.snapshot().await.unwrap();
+    assert_eq!(
+        snapshot.source,
+        uc_core::membership::CurrentWorkspacePeerScopeSource::Legacy
+    );
+    assert_eq!(snapshot.peer_device_ids, vec![DeviceId::new("device-b")]);
+}
+
+#[tokio::test]
+async fn recovery_does_not_persist_missing_state_for_a_fresh_installation() {
+    let repository = MemoryWorkspaceRepository::default();
+    let owner = WorkspaceConvergence::new(test_deps(
+        Arc::new(repository.clone()),
+        "device-a",
+        Vec::new(),
+    ));
+
+    owner.recover_legacy_migration_marker().await.unwrap();
+
+    assert!(repository.load_state().await.unwrap().is_none());
+}
+
 #[tokio::test]
 async fn isolated_legacy_profile_starts_with_fresh_single_member_history() {
     let old_a = instance(0x0a);

crates/uc-application/src/space/convergence/mod.rs

@@ -147,8 +147,12 @@ pub enum WorkspaceConvergenceStateOrigin {
 }
 
 impl WorkspaceConvergenceStateOrigin {
-    pub fn from_version_transition(_previous: Option<&str>, _current: &str) -> Self {
-        Self::CurrentInstallation
+    pub fn from_version_transition(previous: Option<&str>, _current: &str) -> Self {
+        if previous.is_some() {
+            Self::UpgradeWithoutConvergenceState
+        } else {
+            Self::CurrentInstallation
+        }
     }
 }
 
@@ -461,15 +465,19 @@ impl WorkspaceConvergence {
         self.wake.notify_waiters();
     }
 
-    async fn load_state(&self) -> Result<WorkspaceConvergenceState, WorkspaceConvergenceError> {
+    async fn load_state_with_presence(
+        &self,
+    ) -> Result<(WorkspaceConvergenceState, bool), WorkspaceConvergenceError> {
         let lineage = self
             .deps
             .membership_identity
             .current_membership_identity()
             .await
             .map(|identity| identity.space_id.as_ref().to_owned())
             .unwrap_or_default();
-        let mut state = match self.deps.repository.load_state().await? {
+        let persisted = self.deps.repository.load_state().await?;
+        let was_persisted = persisted.is_some();
+        let mut state = match persisted {
             Some(state) => state,
             None => {
                 let mut state =
@@ -484,7 +492,11 @@ impl WorkspaceConvergence {
         if state.space_lineage.is_empty() {
             state.space_lineage = lineage;
         }
-        Ok(state)
+        Ok((state, was_persisted))
+    }
+
+    async fn load_state(&self) -> Result<WorkspaceConvergenceState, WorkspaceConvergenceError> {
+        Ok(self.load_state_with_presence().await?.0)
     }
 
     async fn persist(