tooling: hapi-resurrect-session + auto-migrate chain-forward

[heavygee]

Summary

Force-pushed 2026-06-08 to drop the obsolete post-attach hint commit. PR #34 evolved between 2026-06-06 and 2026-06-08 from "operator-driven CLI/button migrator" to "invisible auto-migrate inside SyncEngine.resumeSession". The post-attach hint's reference to hapi cursor migrate <id> was already wrong by the time #34 settled, so dropping it is the honest fix.

Two-commit branch now:

• tooling(resurrect) (2ed1bb30) — commits scripts/tooling/hapi-resurrect-session.sh (361 lines, operator-authored 2026-06-06). Recovers HAPI sessions auto-archived on agent crash with cursorSessionId=NULL (the failure mode where POST /api/sessions/:id/resume returns 500 "Resume session ID unavailable").
• tooling(resurrect) chain-forward (228757ce) — adds 18 lines of stdout polish at the end of the script that points the operator at Reopen → auto-migrate (feat(cursor): operator-driven legacy stream-json -> ACP session migrator (transplant) #34) as the next step. Pure UX polish; no code-path change.

Why this matters relative to #34

#34's maybeAutoMigrateLegacyCursorSession fires inside SyncEngine.resumeSession. But resumeSession never reaches the auto-migrate call if it errors out at the cursorSessionId lookup first. A crashed-archived session with cursorSessionId=NULL is permanently stranded as un-resumable — auto-migrate has nothing to migrate because there's no resume token to look up the legacy store with.

hapi-resurrect-session.sh fixes the null first (path-hash discovery against ~/.cursor/chats/<md5(metadata.path)>/, sqlite metadata patch, hub restart, POST /resume). After this script succeeds, the session is back to lifecycleState=inactive with cursorSessionProtocol=stream-json. The operator clicks Reopen → #34's auto-migrate fires transparently → session ends up on ACP.

The chain is: resurrect → Reopen → auto-migrate. The polish commit's stdout lines literally walk the operator through that chain so they don't have to remember step 3 exists.

End-to-end flow (crash branch, after #34 lands)

# 1. Operator notices a session is stuck "archived, Session crashed"
# 2. Run the script
scripts/tooling/hapi-resurrect-session.sh <hapi-session-id>
# 3. Script prints "next: open this session in the HAPI web UI and click Reopen"
#    plus the kill-switch env var, plus the in-flight banner expectation
# 4. Operator clicks Reopen in web UI
# 5. SyncEngine.resumeSession -> maybeAutoMigrateLegacyCursorSession -> transparent ACP transplant
# 6. Done. Session is now on ACP.

Refusal contract for hapi-resurrect-session.sh

Exit	Meaning
0	Session resurrected (or dry-run plan printed)
1	Discovery failed (no matching cursor chat on disk)
2	sqlite patch failed
3	/api/sessions/<id>/resume returned non-2xx
4	Spawned cursor-agent crashed within 8s of spawn

Idempotent: re-running on an already-resurrected session is safe. --dry-run prints the discovery + planned patch without writing.

Why this stays as a script (not a hub endpoint)

• This is fork-only operator tooling for the current failure mode. Upstream has zero issues filed about session resurrection / cursorSessionId=NULL recovery (verified via gh search issues --repo tiann/hapi).
• The CONCEPT belongs upstream — either as a POST /api/sessions/:id/resurrect endpoint, or better, as prevention: capture cursorSessionId to a session-events log BEFORE archive so the token is never lost in the first place. Either of those is a separate upstream issue/PR.
• Script form ships today, no review cycle, operator-iterable. Right MVP shape.

Test plan

• bash -n scripts/tooling/hapi-resurrect-session.sh syntax-checks
• --help prints the documented usage block
• Script was hand-used by operator to resurrect at least one crashed session before commit
• After feat(cursor): operator-driven legacy stream-json -> ACP session migrator (transplant) #34 merges: run resurrect on a known archived-crashed session, observe the new stdout footer, click Reopen, confirm auto-migrate fires and session lands on ACP

Companion branch

tooling/backfill-truncation-warnings (#37) — raises backfill MAX_MESSAGES cap from 2000 to 50_000 and surfaces a BACKFILL TRUNCATED warning when transcripts exceed the cap. Independent of migration concerns; should land on its own merits.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[heavygee]

Closing without merging.

The chain-forward polish commit (228757c) was self-contradicting under the broader strategic call: cursor-agent will deprecate legacy stream-json eventually, so any HAPI tool that creates or shepherds a stream-json row is building tech debt. The right next move is a larger upstream PR for Cursor import that mirrors codex (tiann#796) but produces ACP sessions directly via #34's cursorLegacyMigrator as a transplant primitive - never touching stream-json at any point.

The branch `tooling/legacy-chat-acp-alignment` will be kept alive (not deleted) as the durable location for `hapi-resurrect-session.sh` so the operator capability survives. The script will be retired in favor of the hub-side import primitive once the bigger PR lands.

Plan doc: `docs/plans/2026-06-08-upstream-cursor-import-acp-only.md` (in fork).