cursor: resume_unavailable when cursorSessionId never persisted (early exit before init)

[heavygee]

Summary

POST /api/sessions/:id/resume returns HTTP 500 with {"code":"resume_unavailable","error":"Resume session ID unavailable"} when resuming an inactive/archived cursor session whose hub metadata never received cursorSessionId.

This is distinct from #728 (resume/config RPC race after hub restart). Here the resume token was never persisted because the CLI archived before the Cursor system init stream event.

Root cause

syncEngine.resolveLocalResumeTarget() requires metadata.cursorSessionId for cursor flavor (hub/src/sync/syncEngine.ts):

if (flavor === 'cursor') return metadata.cursorSessionId ?? null
// ...
if (!agentSessionId) {
    return { type: 'error', message: 'Resume session ID unavailable', code: 'resume_unavailable' }
}

CursorSession.onSessionFound() persists the ID via updateMetadata, but remote cursor only calls it when the agent stream emits system/init with session_id. If the process exits or is terminated before that event, metadata stays empty even though:

• The CLI was spawned with --resume <uuid> (ID known at spawn)
• A Cursor transcript exists on disk at ~/.cursor/projects/.../agent-transcripts/<uuid>/

Note: cursorLocalLauncher already calls onSessionFound(resumeChatId) when session.sessionId is set at launch; cursorRemoteLauncher does not — asymmetry.

Reproduction (2026-05-31)

1. Spawn a cursor session with resume: cursor --resume d9c3d739-f146-434a-8339-16cfcb791422
2. Terminate the agent within ~2s (before [CursorSession] Cursor session ID ... added to metadata appears in logs)
3. Session archives with lifecycleState: archived, cursorSessionId absent in hub metadata
4. POST /api/sessions/<id>/resume → 500 resume_unavailable
5. Manual recovery: patch DB with cursorSessionId + hub restart → resume succeeds

Affected session (operator repro)

Field	Value
HAPI session	0525fe34-2eab-4d8e-a4ed-ef8210d172b6 ("android watch")
Cursor resume id (spawn arg)	d9c3d739-f146-434a-8339-16cfcb791422
Recovered after DB patch	2010b5cf-cb9e-404c-bf8e-c4968bb28e7b

Expected HTTP response

GET /api/cli/sessions/:id/resume-target already maps resume_unavailable → 409. POST /api/sessions/:id/resume returns 500 for the same code — inconsistent and misleading (looks like server fault vs. missing resume token).

Proposed fix

1. CLI: Persist cursorSessionId as early as possible — when spawn already has --resume id (mirror local launcher), and on system init event (existing path).
2. Hub: Map resume_unavailable → 409 on POST /sessions/:id/resume with actionable message (start fresh vs resume).
3. Optional: Best-effort recovery from transcript path when metadata missing (cursor only).

Related

• #728 — resume/config RPC race (resume_failed, not resume_unavailable)

[github-actions]

Confirmed against current code. The report matches the current Cursor resume path:

• Cursor resume target resolution requires metadata.cursorSessionId; if it is missing, the hub returns resume_unavailable.
• Local Cursor persists an existing session.sessionId before launching, but remote Cursor currently only calls onSessionFound() after a Cursor system/init stream event with session_id.
• POST /api/sessions/:id/resume currently maps resume_unavailable to HTTP 500, while GET /api/cli/sessions/:id/resume-target maps the same code to 409.
• I did not find a Cursor transcript-based recovery path in the current codebase.

Relevant code:

• hub/src/sync/syncEngine.ts:519 - cursor flavor resume ID comes from metadata.cursorSessionId.
• hub/src/sync/syncEngine.ts:541 - missing agent resume ID returns resume_unavailable.
• hub/src/web/routes/sessions.ts:139 - resume endpoint error status mapping falls through to 500.
• hub/src/web/routes/cli.ts:128 - CLI resume-target endpoint maps non-auth/not-found errors to 409.
• cli/src/cursor/cursorLocalLauncher.ts:20 - local Cursor calls session.onSessionFound(resumeChatId) when a resume ID already exists.
• cli/src/cursor/cursorRemoteLauncher.ts:84 - remote Cursor stores session.sessionId locally for --resume args.
• cli/src/cursor/cursorRemoteLauncher.ts:115 - remote Cursor only persists metadata after system/init supplies event.session_id.
• cli/src/agent/sessionBase.ts:106 - onSessionFound() updates session metadata.

---

HAPI Bot