fix(cursor): migrator path-priority + ambiguity surface (closes #844 regression)

[heavygee]

Summary

• Part 1 - Path-priority discovery: findLegacyChatStore() now accepts an optional canonical workspace path. It computes md5(canonicalPath) and checks that drawer first; only falls back to readdirSync scanning when the canonical drawer has no match. This eliminates the readdir-ordering-dependent first-match-wins behaviour that caused the feat(cursor): invisible sync-on-open migrator from legacy stream-json to ACP #844 regression.
• Part 2 - Ambiguity surface: When multiple drawers contain the same cursorSessionId and none matches the canonical path hash, the migrator throws AmbiguousLegacyStoreError (listing all candidates with workspaceHash, bytes, mtimeMs) instead of silently transplanting. The caller in syncEngine promotes the session's cursorMigrationState to 'ambiguous' and the web CursorMigrationBanner renders a "Manual review needed" state so the operator can resolve on disk.
• Part 3 - Size sanity check before transplant: Before copying, the migrator compares HAPI's known message count for the session against the candidate store's SELECT COUNT(*) FROM blobs. If HAPI message count > 100 AND candidate blob count < messageCount / 4, the transplant is refused with size_mismatch and the ambiguous banner is surfaced. Skipped when HAPI message count == 0 (brand-new session).
• Part 4 - Diagnostic logging on successful transplant: Every successful transplant now logs migrator:transplanted at info with cursorSessionId, workspaceHash, total candidate count at discovery time, sourceBytes, sourceBlobCount, targetAcpPath, sourceRemoved, and canonicalPathMd5. Future session losses are diagnosable from journalctl alone.

Test plan

Extended hub/src/cursor/cursorLegacyMigrator.test.ts:

• Single drawer -> returns it (regression guard)
• Three drawers + canonical path matching one -> returns canonical-hash drawer, not first readdir match
• Three drawers + no canonical path -> throws AmbiguousLegacyStoreError listing all three
• Three drawers + canonical path matching none -> throws AmbiguousLegacyStoreError
• Size sanity: 19-blob candidate vs 6000-message HAPI session -> refuses size_mismatch; 200-blob padded candidate vs same -> proceeds
• 0-message HAPI session + 19-blob candidate -> size check skipped, proceeds
• messageCount = 101 boundary test (first value above skip threshold)
• workspaceHashFromPath contract pinned against independently-computed md5sum values (prevents algorithm drift)
• countLegacyStoreBlobs and listLegacyChatStoreCandidates unit tests

Added hub/src/sync/syncEngineAutoMigrate.test.ts tests:

• cursorMigrationState promoted to 'ambiguous' on both ambiguous_legacy_store and size_mismatch refusals

All existing hub/src/cursor/*.test.ts and hub/src/sync/*.test.ts pass. bun typecheck && bun run test green (82 hub migrator tests, 964 web tests, 972 total non-integration tests).

Closes #873

Disclosure

Drafted with claude-sonnet-4-5 (claude-4.6-sonnet-medium-thinking) via Cursor; reviewed and tested by the human contributor.

[github-actions]

Findings

• [Minor] Banner points operators at log tags that are never emitted — the new ambiguous-state copy tells users to search for migrator:ambiguous_legacy_store / migrator:size_mismatch, but the server logs [migrator] ambiguous legacy store; refusing transplant and [migrator] size sanity check refused transplant instead. That makes the manual-recovery path harder right when the user needs the candidate list. Evidence: web/src/lib/locales/en.ts:124, web/src/lib/locales/zh-CN.ts:124, hub/src/cursor/cursorLegacyMigrator.ts:621, hub/src/cursor/cursorLegacyMigrator.ts:681.
  Suggested fix:

  log.warn('migrator:ambiguous_legacy_store', {
      sessionId: session.id,
      cursorSessionId,
      canonicalWorkspacePath: canonicalWorkspacePath.length > 0 ? canonicalWorkspacePath : null,
      canonicalHash: canonicalHashStr,
      candidates: err.candidates
  })
  
  log.warn('migrator:size_mismatch', {
      sessionId: session.id,
      cursorSessionId,
      ...sizeMismatch.context
  })

Summary

• Review mode: initial
• One recovery-path issue found. I did not find other high-confidence correctness/security regressions in the changed migrator, sync-state promotion, schemas, or banner behavior. Residual risk: the size threshold is heuristic and should be watched in real deployments.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Minor] Canonical path hashing trims valid path bytes — Cursor's drawer name is pinned as md5 of the raw workspace path, but the lookup trims before hashing, so a valid workspace path with leading/trailing spaces hashes to the wrong drawer and can either fall back to a stale single candidate or surface a false ambiguity. Evidence: hub/src/cursor/cursorLegacyMigrator.ts:292.
  Suggested fix:

  const canonicalPath = typeof sessionWorkspacePath === 'string' ? sessionWorkspacePath : ''
  if (canonicalPath.length > 0) {
      const canonicalHash = workspaceHashFromPath(canonicalPath)
      // ...
  }

• [Minor] Exported candidate scanner bypasses the cursorSessionId basename guard — findLegacyChatStore now protects against traversal ids, but the newly exported listLegacyChatStoreCandidates joins the id directly into each drawer path. Any future direct caller can reintroduce the same boundary bug and receive stat metadata for paths outside the intended <wsh>/<cursorSessionId>/store.db shape. Evidence: hub/src/cursor/cursorLegacyMigrator.ts:322.
  Suggested fix:

  export function listLegacyChatStoreCandidates(cursorSessionId: string, home: string): LegacyStoreCandidate[] {
      if (!CURSOR_SESSION_ID_RE.test(cursorSessionId) || cursorSessionId === '.' || cursorSessionId === '..') {
          return []
      }
      const chatsRoot = join(home, '.cursor', 'chats')
      // ...
  }

Summary

• Review mode: follow-up after new commits
• Two minor lookup-boundary issues remain in the new migrator helpers. The prior bot finding about mismatched log-search strings was addressed in this follow-up.

Testing

• Not run (automation: bun is not installed in this runner)

HAPI Bot

[github-actions]

Findings
None.

Summary

• Review mode: follow-up after new commits
• No issues found in the current diff. The prior bot findings about raw-path hashing and scanner boundary validation are addressed in this head. Residual risk is in the heuristic nature of the message-count/blob-count size sanity floor; the PR adds targeted migrator and auto-migration banner coverage for that path.

Testing

• Not run (automation: bun is not installed in this runner)

HAPI Bot