feat(cursor): invisible sync-on-open migrator from legacy stream-json to ACP

[heavygee]

Closes #824

When the user reopens a legacy stream-json Cursor session in HAPI, the
hub now transparently transplants its ~/.cursor/chats/<wsh>/<uuid>/store.db
into ~/.cursor/acp-sessions/<uuid>/, verifies it loads via agent acp,
flips metadata.cursorSessionProtocol = 'acp', and removes the legacy
source — all before resumeSession returns. Subsequent opens are pure ACP.

Why migration (not "leave legacy alone")

The primary justification is safety, not feature parity. #784 (cursor-agent
fabricates Questions skipped by the user responses in legacy stream-json
mode) still fires regularly in dogfood despite #801's mitigation: the agent
ships destructive side effects against fabricated consent. Migration to ACP
closes the protocol-level door because the AskQuestion tool does not exist
on the ACP side — there is nothing to fabricate.

#799 deliberately left existing sessions on legacy because they kept
working. That tradeoff was reasonable at the time. The accumulated #784
evidence makes legacy sessions actively unsafe; this PR makes the upgrade
path invisible enough that users stop avoiding it.

How: transplant → verify → flip → remove

A pre-PR spike established that legacy and ACP store.db files use the
identical SQLite schema; only the directory layout differs. The migrator
therefore:

1. Sanity-checks the source store and pre-flips state (session.active,
   lifecycleState, on-disk presence, target collision)
2. Optionally archives a stale-running row (forceArchiveRunning: true is
   the default for the auto-migrate path because the caller already
   verified session.active === false)
3. Atomically creates ~/.cursor/acp-sessions/<uuid>/ with mode 0o700
4. Copies store.db and chmods to 0o600 (multi-user-host hardening)
5. Writes a minimal meta.json sidecar (schemaVersion, cwd, optional
   title) with mode 0o600
6. Spawns agent acp under HAPI_HOME isolation and verifies the session
   loads via session/load. On long histories the verify also drives a
   trivial single-turn prompt; on short ones load-only is enough
7. Flips cursorSessionProtocol = 'acp' AND clears the
   cursorMigrationState banner flag in a SINGLE metadata write
8. Removes the legacy source store (only after verify succeeded and the
   protocol flip committed). The legacy ~/.cursor/chats parent dir is
   left as-is

Every failure leaves the legacy state intact. No rm fires without a
verify success AND a committed protocol flip.

In-flight upgrade banner

The transplant takes 15-20s on long histories (copy a multi-hundred-MB
store, spawn agent acp, replay thousands of notifications, tear down
the probe). Without a progress indicator the wait reads as "broken" to
a fresh user. A minimal banner ships alongside the migrator:

• Hub sets metadata.cursorMigrationState = 'in_progress' before
  the long-running transplant. The session-cache refresh emits the
  existing session-updated SSE event (no new event type), so the web
  client picks it up in milliseconds. No client-side polling needed.
• Hub clears the flag in the same metadata write that flips
  cursorSessionProtocol to 'acp' on success, so the banner disappears
  in the same render tick the chat re-renders as ACP — no flicker window.
• Hub clears the flag explicitly in the auto-migrate helper's finally
  on failure/exception, so the banner never gets stuck if migration
  falls back to the legacy launcher.
• Web renders an accessible (role="status", aria-live="polite")
  banner with an indeterminate spinner. Deliberately no fake
  percentage — we do not have phase data and a fake progress bar
  would lie.

Coordination with the ACP refcount lock (#835 / #836 / #837)

This PR is sequenced after @swear01's three ACP mop-up PRs (merged
today as ad038bbf, 8094b500, fa363c2f), all of which are
prerequisite for safe concurrent ACP launches.

The verify probe spawns agent acp directly via AcpVerifyProbe under
HAPI_HOME isolation (the migrator overrides HOME to a temp dir for
the verify pass), so it never touches <real-HAPI_HOME>/locks/agent-acp-active/
at all. Per @swear01's #835 design note, the post-flip ACP launcher claims
the lock through the standard registerActiveAcpTransport entry and
behaves like any other concurrent ACP start. The migrator itself never
writes pid or count files directly.

Kill-switch

The auto-migrate path is gated by HAPI_CURSOR_LEGACY_AUTO_MIGRATE.
Set to 0, false, no, or off to suppress it entirely (legacy
sessions keep running through the existing stream-json launcher).
Default is on.

Single-session escape hatch

A REST endpoint at POST /api/sessions/:id/migrate-to-acp allows
explicit migration of a single session outside the sync-on-open path
(e.g. for a specific cold archived session a user wants to re-engage).
Bulk migration surfaces (CLI subcommand, web button, bulk REST endpoint,
candidate-listing API) were deliberately stripped per reviewer feedback;
per-session sync-on-open + this escape hatch are the only two paths.

Test budget

• 389 hub unit tests pass against the rebased branch (53 for the
  migrator core, 32 for the verify probe, 15 for the auto-migrate
  helper guard matrix, 4 for the migration banner flag transitions,
  plus all upstream suites)
• 3 integration tests against a real agent acp (skipped by default
  unless HAPI_CURSOR_LEGACY_MIGRATOR_INTEGRATION=1)
• 10 web unit tests for the banner component (visibility paths + a11y)
• Typecheck clean across cli + web + hub

Files

• hub/src/cursor/{acpVerifyProbe,cursorLegacyMigrator}.{ts,test.ts}:
  migrator core + verify probe + 53+32 unit tests
• hub/src/cursor/cursorLegacyMigratorIntegration.test.ts: 3 real-agent acp integration tests
• hub/src/cursor/fixtures/buildSyntheticLegacyStore.ts: synthetic store.db builder
• hub/src/sync/syncEngine.ts: flipCursorSessionProtocolToAcp,
  maybeAutoMigrateLegacyCursorSession, setCursorMigrationStateInProgress,
  clearCursorMigrationState, buildMigratorForRequest
• hub/src/sync/syncEngineAutoMigrate.test.ts: helper guard matrix
• hub/src/web/routes/{sessions,cli}.ts: per-session escape-hatch endpoint
• hub/src/store/index.ts: getCursorSessionByCursorIdAndProtocol lookup
• shared/src/{schemas,apiTypes}.ts: cursorMigrationState field + request/outcome types
• web/src/components/CursorMigrationBanner.{tsx,test.tsx}: banner + 10 tests
• web/src/components/SessionChat.tsx: render banner
• web/src/lib/locales/{en,zh-CN}.ts: banner copy
• web/src/types/api.ts: Metadata re-export
• web/src/api/client.ts: migrateCursorSessionToAcp client method

[github-actions]

Findings

• [Major] Verify probe ignores metadata.homeDir for binary lookup — migrateOneWithLock() correctly resolves the legacy store under the recorded session owner home, but the default probe factory still sets agentLookupHome from this.deps.homeDir() instead of that resolved home. In the service-account hub case described in the PR, the store is found under metadata.homeDir, then agent acp lookup falls back to the hub user's ~/.local/bin, so verification fails and sync-on-open silently falls back to legacy. Evidence: hub/src/cursor/cursorLegacyMigrator.ts:319.
  Suggested fix:

  // widen the dependency and pass the resolved source home through verifyInTempHome
  createProbe?: (env: NodeJS.ProcessEnv, agentLookupHome: string) => AcpVerifyProbe
  
  createProbe: deps.createProbe ?? ((env, agentLookupHome) => new AcpVerifyProbe({
      env,
      skipLockAcquire: true,
      agentLookupHome
  }))
  
  const probe = this.deps.createProbe(env, opts.sourceHome)

• [Major] Windows optional binary is locked to the wrong version — cli/package.json requires @twsxtd/hapi-win32-x64@0.20.1, but the added lock entry resolves @twsxtd/hapi-win32-x64@0.20.0. That can leave Windows installs pinned to the previous native binary or make frozen installs reject the lock. Evidence: bun.lock:1077.
  Suggested fix:

  -    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.20.0", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-..."]
  +    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.20.1", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-<0.20.1 integrity>"]

Summary
Review mode: initial

• Two blocking release/runtime risks found in the added migration path and lockfile.

Testing

• Not run (automation). I attempted bun install --frozen-lockfile, but bun is not available on this runner PATH.

HAPI Bot

[github-actions]

[MAJOR] migrateOneWithLock() resolves the legacy store using metadata.homeDir, but the default probe factory still builds agentLookupHome from this.deps.homeDir(). In the service-account hub deployment this PR calls out, that means the store is found under the human user's home, then agent acp lookup falls back to the hub user's ~/.local/bin and verification fails back to legacy. Pass the resolved source home into the probe instead.

Suggested fix:

createProbe?: (env: NodeJS.ProcessEnv, agentLookupHome: string) => AcpVerifyProbe

createProbe: deps.createProbe ?? ((env, agentLookupHome) => new AcpVerifyProbe({
    env,
    skipLockAcquire: true,
    agentLookupHome
}))

const probe = this.deps.createProbe(env, opts.sourceHome)

[github-actions]

[MAJOR] This added package entry resolves @twsxtd/hapi-win32-x64@0.20.0, while cli/package.json requires 0.20.1. That can pin Windows installs to the previous native binary or make frozen installs reject the lock. Regenerate/update the lockfile so the package entry is also 0.20.1 with the matching integrity.

Suggested fix:

-    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.20.0", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-..."]
+    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.20.1", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-<0.20.1 integrity>"]

[heavygee]

Thanks for the review. Both Major findings addressed in e3e1c0b3:

Finding 1 — verify probe agentLookupHome ignored metadata.homeDir: Widened CursorLegacyMigratorDeps.createProbe signature from (env) => AcpVerifyProbe to (env, agentLookupHome) => AcpVerifyProbe. The default factory now uses the passed arg; verifyInTempHome threads opts.sourceHome (already the resolved session-owner home from metadata.homeDir) through. The earlier rounds plumbed the type into the factory default but never threaded the resolved home through the call path — exactly the gap you spotted. Two regression tests added in cursorLegacyMigrator.test.ts:

• Service-account case (metadata.homeDir != deps.homeDir()): captured agentLookupHome MUST equal metadata.homeDir
• Legacy session record (no metadata.homeDir): falls back to deps.homeDir() correctly

Finding 2 — bun.lock win32-x64 pin mismatch: Rebase artifact. The squash-rebase onto upstream/main 1f92a31b (v0.20.1 release) updated cli/package.json to 0.20.1 but the win32-x64 lock entry stayed at 0.20.0. Regenerated with bun install; bun install --frozen-lockfile is now clean.

Status:

• 391 hub unit tests pass (+2 new)
• Typecheck clean across cli + web + hub

Ready for re-review.

[github-actions]

Findings

• None.

Summary

• Review mode: follow-up after new commits
• The prior bot findings are addressed in the latest head: the Windows optional binary lock entry now points at @twsxtd/hapi-win32-x64@0.20.1, and the verify probe now receives the resolved session-owner home for agentLookupHome.
• Residual risk: the real agent acp migration integration tests are opt-in, so this review relies on source inspection plus the added unit coverage for the destructive migration paths.

Testing

• Not run (automation); bun is not available on this runner PATH.

HAPI Bot