Skip to content

feat: restore exact Hermes terminal sessions - #691

Closed
TheXRMonk wants to merge 6 commits into
0-AI-UG:mainfrom
TheXRMonk:feat/hermes-session-resume
Closed

TheXRMonk wants to merge 6 commits into
0-AI-UG:mainfrom
TheXRMonk:feat/hermes-session-resume

Conversation

@TheXRMonk

Copy link
Copy Markdown

Summary

  • Teach Cate to identify Hermes terminal sessions, persist each panel's exact profile/session identity, and restore it with hermes --profile <profile> chat --resume <session-id>.
  • Add a separately installed, profile-scoped cate-agent-state integration plugin under integrations/hermes, plus managed install/status/uninstall commands. This PR does not modify Hermes core.
  • Normalize authenticated Hermes lifecycle events into Cate's existing agent presence/session-stamp pipeline and guard against stale or out-of-order events, overlapping processes, PID reuse, and non-resumable replacement sessions.
  • Add regression coverage for two-pane cold restart while preserving existing Codex restore behavior.
  • Use Windows' inbox System32/tar.exe for packaged runtime extraction so drive-letter paths work when Git's GNU tar precedes System32 on PATH.

Why

A bare "continue latest" flow is ambiguous when multiple Hermes terminals share a working directory. Persisting the authoritative session ID together with its canonical profile lets every restored panel reattach to its own conversation rather than whichever conversation happens to be newest.

How it works

  1. Cate puts a loopback hook endpoint, per-terminal bearer token, and terminal ID in each PTY environment.
  2. The opt-in Hermes plugin reports root interactive CLI lifecycle events; it is inert outside Cate terminals and ignores subagent, cron, and gateway sessions.
  3. Cate authenticates and normalizes those events, validates process identity/generation, and stamps a session only once it is resumable.
  4. The panel persists { agentId, sessionId, profile, cwd } and, after a cold restart, launches a fresh shell with the explicit profile and session ID.

Manual installation

From a Cate checkout, install the plugin separately for each Hermes profile used in Cate:

bun run hermes:integration -- install --profile work
bun run hermes:integration -- status --profile work

Use --profile default explicitly for the default profile, then restart any running Hermes CLI so it loads the plugin. To remove it:

bun run hermes:integration -- uninstall --profile work

Validation

  • Targeted unit selection before the final v2.0.2 rebase: 194 passed, 4 skipped.
  • Final focused runtime suite: 7/7 passed.
  • Two-pane Hermes cold-restart E2E passed, including distinct per-pane profiles/session IDs and resumed-output assertions.
  • Codex regression E2E passed.
  • TypeScript typecheck and lint passed.
  • Windows production package succeeded.
  • Installed Cate 2.0.2 probe returned runtimeReady, terminalWritable, and fileRead all true.
  • Two independent final reviews passed.
  • All six commits in this PR are GitHub-verified.

The broad Windows baseline is not claimed fully green: known symlink-privilege and environment-dependent failures remain.

Risk and security

  • The plugin runs inside Hermes but is a separate, explicitly installed profile plugin; Hermes core is unchanged. It sends only lifecycle metadata, accepts no command from Cate, uses loopback HTTP with a per-terminal bearer token, disables proxy/redirect forwarding, and times out after 750 ms without failing the Hermes session.
  • Processes within the same Cate terminal inherit the bearer token, so the trust boundary is the terminal, not each child process.
  • The installer requires an explicit canonical profile, rejects custom/unsafe profiles, foreign or symlinked plugin paths, uses a Cate ownership marker and atomic replacement/rollback, and enables the plugin without tool overrides.
  • Exact session/profile validation plus process-generation high-water marks prevent stale hooks or reused PIDs from restoring the wrong conversation; malformed or unproven identity degrades to a plain shell instead of a guessed resume.

@Anton-Horn

Copy link
Copy Markdown
Contributor

Thanks for the work on this! We’re continuing the Hermes integration in #697, which includes session restoration as part of the full CLI integration. Closing this in favor of that PR.

@Anton-Horn Anton-Horn closed this Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants