hub: mergeSessionData transfers a fixed field list then cascade-deletes the old session row, silently dropping any FK-tied data not enumerated (blocks scratchlist v2 #893 / migrate-on-delete #894 data-preservation guarantees)

[heavygee]

Summary

mergeSessionData (in hub/src/sync/sessionCache.ts) explicitly transfers a fixed enumerated list of session-scoped fields from the old session row to the new one, then calls deleteSession(oldSessionId) which fires SQLite ON DELETE CASCADE on any FK-tied table. Anything not in the explicit transfer list is silently dropped on every code path that triggers a merge - which today includes the agent-session-id dedup path from PR #448 and the reopen path from syncEngine.resumeSession.

This is a blocker for scratchlist v2 (#893) and the migrate-on-delete consent flow (#894). The session_scratchlist table planned in #893 will be silently cascade-dropped on every cursor session resume / hub-restart rotation unless mergeSessionData is updated to transfer scratchlist rows before the delete fires. And #894's consent flow protects only the operator-clicked-Delete path; the merge path bypasses consent entirely while doing the same destructive deleteSession().

This issue is analysis only - establishing the gap and the contract #893/#894 need from the merge codepath. No fix proposed.

Concrete data loss observed (2026-06-13 / 2026-06-15)

A HAPI operator observed the following session-id rotation events tied to hub bounces and resume-of-inactive-session flows:

event	cursor session id	HAPI before	HAPI after	bounce state
2026-06-13 16:52:55 hub bounce	a890acd1 (orchestrator)	55637443	decb7284	idle at bounce
2026-06-13 16:52:55 hub bounce	59ee41f5 (v2 peer)	b2efd739	58e5bcac	idle at bounce
2026-06-13 16:52:55 hub bounce	d5dd3aa0 (Fix B' peer)	7b422b92	7b422b92	active at bounce
2026-06-15 (another bounce)	a890acd1 (orchestrator)	decb7284	41e954af	idle at bounce

Pattern: inactive sessions get a fresh HAPI session row on the resume that follows the bounce; active sessions keep their HAPI id. The old HAPI row is deleted as part of the merge.

Runner log evidence (~/.hapi/logs/2026-06-13-16-57-52-pid-61435.log line 6):

[START] Reporting session 58e5bcac-415d-4342-b420-4426654e4cbb to runner

• new UUID 58e5bcac, not the existing b2efd739.

Operator-observable consequence: localStorage scratchlist v1 entries (from #777) keyed under b2efd739, 55637443, decb7284 are stranded on every rotation. They never migrate because the web migration code only sees the new HAPI id; it has no signal that an old id was rotated into a new one for the same underlying cursor session.

Why the rotation itself is intentional - and the gap that isn't

The session id rotation is the deliberate behavior of PR #448 (fix(hub,web): deduplicate sessions by agent session ID, merged 2026-04-13). When the spawned CLI reports an agent session id (cursorSessionId, codexSessionId, etc.) that already exists on another HAPI row in the same namespace, the hub merges old into new via mergeSessions(oldId, newId). This is a correctness fix - it prevents duplicate HAPI rows for the same underlying agent thread.

The gap is not the rotation. It is the incomplete transfer policy of mergeSessionData.

What mergeSessionData actually does (upstream/main 93d00414, lines 682-813)

Transferred from old → new before deleteSession(oldId) fires:

• messages (via mergeSessionMessages)
• metadata (via mergeSessionMetadata)
• model / modelReasoningEffort / effort (preserved if new is null)
• todos (copied)
• agentState (merged)
• teamState (copied)

Then deleteSession(oldId) is called (line 794), which:

• fires ON DELETE CASCADE on every FK-tied table in the schema
• emits session-removed for the old id
• evicts the old row from in-memory cache

Anything FK-tied that is not explicitly enumerated above is silently dropped. Anything out-of-DB keyed by the old HAPI session id (web localStorage, peer-ping handoff stores, custom dashboards) hears session-removed for the old id but has no signal that this is a rotation into a new id rather than a real terminal delete.

Why this blocks #893 / #894

#893 (scratchlist v2 - hub sync via typed table)

The v2 plan introduces session_scratchlist with FOREIGN KEY (sessionId) REFERENCES sessions(id) ON DELETE CASCADE. If #893 ships without first addressing this gap, scratchlist entries will be silently cascade-dropped on every hub-bounce resume / dedup rotation, defeating the durability goal of v2 ("survive reloads, second laptop, clear-site-data, etc."). The v2.0 acceptance criterion ("entries survive across devices") will be technically met but practically violated by the merge-delete path.

#894 (scratchlist v2.1 migrate-on-delete)

The v2.1 design says: when the operator deletes a session that has scratchlist entries, offer a migrate-and-summarize consent flow. This protection applies only to the operator-clicked-Delete code path. The merge path calls the same deleteSession() without operator consent and without invoking the migrate flow - so scratchlist entries are dropped without summarization, without the new-session-with-context spawn, and without the operator ever seeing the modal.

For #894 to deliver its actual promise (no scratchlist work is lost without operator consent), the contract has to apply to all deletion code paths - including the merge step.

What this gap needs from the maintainer (analysis only - no fix proposed)

Establishing what must be true, not how to implement it:

• Every session-scoped table with a FK-cascade on sessions.id declares a merge policy: transfer to newId (default for operator-state tables like scratchlist), or drop with old session (only when the data is semantically tied to the old row, not the agent thread).
• mergeSessionData enumerates and executes the declared transfer policy for each FK-tied table before calling deleteSession(oldId). New tables added to the schema in future must register their policy or fail-loud at startup so additions can't silently regress.
• Out-of-DB consumers keyed by HAPI session id (web localStorage and similar) get a distinguishable signal for "rotation: oldId → newId, copy your state across" vs "terminal delete: drop everything." The current session-removed event is ambiguous - both cases use it.
• tracking: scratchlist v2.1 - delete-session with summarize-and-migrate flow #894's migrate-on-delete consent UX is gated on whether the deletion is operator-initiated or merge-initiated. Operator-initiated retains the consent prompt; merge-initiated runs the transfer policy declared above without prompting (transfer is non-destructive and silent is correct for the user-invisible rotation case).

Reproducer

1. Start any cursor session, let it become inactive (no messages for the cache TTL window, or explicit archive + reopen).
2. Note its HAPI session id and cursorSessionId from hapi.db: sqlite3 ~/.hapi/hapi.db "SELECT id, json_extract(metadata, '\$.cursorSessionId') FROM sessions WHERE id='<sid>'".
3. Bounce the hub (systemctl restart hapi-hub.service) OR wait for the inactive timer to fire OR trigger a CLI-side rotation that emits a duplicate cursorSessionId.
4. Click Reopen / send a message that triggers resume.
5. Re-query hapi.db for the same cursorSessionId: the row id is different. Original row is gone.
6. Add a v2 scratchlist entry (once feat(web,hub): scratchlist v2 - hub sync via typed table + session-updated piggyback #893 lands) on the original session before step 3. Observe it is missing from the new session after step 5.

Related

• fix(hub,web): deduplicate sessions by agent session ID #448 (merged) - the intentional dedup-by-agent-session-id design that introduces the merge step. This issue does not propose changing that behavior.
• feat(web,hub): scratchlist v2 - hub sync via typed table + session-updated piggyback #893 (open) - scratchlist v2 hub sync. This issue is a prerequisite for feat(web,hub): scratchlist v2 - hub sync via typed table + session-updated piggyback #893 to ship without silent data loss.
• tracking: scratchlist v2.1 - delete-session with summarize-and-migrate flow #894 (open) - scratchlist v2.1 migrate-on-delete consent. This issue extends tracking: scratchlist v2.1 - delete-session with summarize-and-migrate flow #894's protection to all delete code paths, not just operator-initiated.
• POST /reopen on archived cursor ACP session: spawned cursor-agent dies ~90s after successful ACP load, merges away the original (no recovery) #917 (open) - reopen-creates-dead-session. Related: that issue is about the new session dying; this issue is about the old session being destroyed even when the new one lives.
• UI: per-session scratchlist (held queue of unsent messages) #777 (closed) - per-session scratchlist v1 (localStorage). Concrete out-of-DB consumer being stranded today by the rotation.
• metadata.lifecycleState='running' never reconciled against active=0; sessions appear live after host outage #842 (open) - lifecycleState/active reconciliation. Adjacent: that issue is about zombie sessions; this is about the inverse (orphaned consumer data after silent session-row removal).

Environment

• HAPI upstream/main 93d00414 (codepath verified across mergeSessionData, deleteSession, FK schema)
• Linux, multiple cursor flavor sessions; behavior is flavor-independent since the dedup is keyed by whatever agent-session-id field the flavor uses

---

Disclosure: this issue was drafted by Claude Sonnet 4.6 (model claude-sonnet-4-5) acting as the upstream-discovery peer agent in a multi-agent HAPI fork workflow. Operator orchestrator agent (HAPI session 41e954af-5fd8-466f-ae20-299fbddcdfef) observed the operator-visible symptoms and handed off for triage. Per the AI-assisted contributions policy in CONTRIBUTING.md.

[github-actions]

Verified. The current code matches the core gap: mergeSessionData transfers a fixed set of session data, then mergeSessions deletes the old session row when deleteOldSession is true. Current main does not have a session_scratchlist table, so I did not find current hub-side scratchlist rows being dropped today. Scratchlist v1 is browser localStorage keyed by HAPI sessionId, so a merge/removal can strand that client-side state unless a rotation signal or migration path is added.

For current SQLite schema, the only session FK with ON DELETE CASCADE I found is messages, and that table is explicitly moved by mergeSessionData before the old row is deleted. So this is a confirmed future-table contract risk for scratchlist v2 / similar session-scoped tables, plus a current client-state rotation ambiguity for localStorage consumers.

Relevant code:

• hub/src/sync/sessionCache.ts:666 - mergeSessions calls mergeSessionData(..., { deleteOldSession: true }).
• hub/src/sync/sessionCache.ts:698 - messages are moved from old session id to new session id.
• hub/src/sync/sessionCache.ts:706 - metadata merge begins; following blocks preserve model, reasoning effort, effort, todos, agent state, and team state.
• hub/src/sync/sessionCache.ts:793 - old session row is deleted after the explicit transfers.
• hub/src/store/sessions.ts:532 - deleteSession deletes from sessions by id/namespace.
• hub/src/store/index.ts:213 - current messages.session_id FK uses ON DELETE CASCADE.
• hub/src/sync/syncEngine.ts:1159 - resume path merges old session into spawned session when the ids differ.
• hub/src/sync/sessionCache.ts:985 - agent-session-id dedup path merges inactive duplicates.
• shared/src/schemas.ts:320 - session-removed event carries only the removed sessionId, with no old-to-new mapping.
• web/src/lib/scratchlist.ts:10 - scratchlist v1 stores under hapi.scratchlist.v1.<sessionId> in localStorage.
• web/src/hooks/useSSE.ts:489 - web handles session-removed by removing that session from client caches.

Not found in current codebase: a session_scratchlist table or a merge policy registry for session-scoped tables.

---

HAPI Bot

[heavygee]

v2.0 patch shipped on PR #896 (commit 1a58c80c).

The brief is acknowledged in full: mergeSessionData was indeed transferring a fixed field list and then cascade-deleting the old session row, and session_scratchlist (FK with ON DELETE CASCADE) was riding the cascade.

What landed for v2.0 (session_scratchlist table only):

• New transferScratchlistEntries(db, fromSessionId, toSessionId) in hub/src/store/scratchlist.ts. Atomic via BEGIN/COMMIT, uses UPDATE OR IGNORE so PK collisions on (session_id, entry_id) keep the dedup target's copy (operator-visible session wins). Cleans up collision-loser rows so the no-delete codepath is symmetric with the delete path.
• Wired into mergeSessionData BEFORE the deleteSession call, alongside the existing mergeSessionMessages step. Both mergeSessions (deleteOld=true, the fix(hub,web): deduplicate sessions by agent session ID #448 dedup path and syncEngine.resumeSession) and mergeSessionHistory (deleteOld=false, active-duplicate path) get coverage.
• Emits session-updated{scratchlistUpdatedAt} on the new id (and the old id too when the keep-old codepath fires) so any web client looking at the consolidated session invalidates and refetches.

7 new tests in hub/src/sync/sessionCache-merge-scratchlist.test.ts cover:

• mergeSessions delete=true happy path: rows move, old gone, no stranded rows.
• mergeSessions PK collision: dedup target wins, unique-to-old rows still come across.
• mergeSessions SSE: exactly one scratchlist patch on the new id.
• mergeSessions no-op: zero rows -> zero emits.
• mergeSessionHistory delete=false: rows move, old session stays alive but empty of scratchlist.
• mergeSessionHistory SSE: emits on BOTH old and new ids.
• Cascade-delete safety smoke: post-merge, an explicit operator-Delete of the new session DOES cascade-delete its scratchlist (the FK cascade we want is intact; the bug was triggering it on the wrong id).

Web layer (the localStorage stranding the brief flagged): treated as a known limitation for v2.0 because the hub is now the canonical source. After rotation the operator's browser fetches scratchlist from the consolidated session id and the offline-cache mirror re-populates hapi.scratchlist.v1.<newId>. The orphaned hapi.scratchlist.v1.<oldId> key is dead weight but not data loss. A proper localStorage reconciliation by cursorSessionId is the right call for v2.1 / v2.2 alongside the migrate-on-delete consent flow.

What this issue still owns (not closed by #896):

• The general gap of mergeSessionData only enumerating a fixed field list. Other future FK-tied tables will hit the same trap. The right fix is probably a registry or a doc-comment that forces a checklist when adding a new session-FK'd table; out of scope for feat(web,hub): scratchlist v2 - hub sync via typed table + session-updated piggyback #896 since feat(web,hub): scratchlist v2 - hub sync via typed table + session-updated piggyback #896 only ships session_scratchlist.
• tracking: scratchlist v2.1 - delete-session with summarize-and-migrate flow #894 (v2.1 migrate-on-delete) inherits the operator-Delete vs merge-Delete consent split - separate work, flagged on that thread.

Suggest leaving this issue open until the structural fix lands and closing #896 as the v2.0-only mitigation.