[teknium1]

Plugins now get one on_session_delete(session_id, reason, profile, ...) call, after the commit, whenever a session is deleted or deliberately archived, from any surface.

Closes #124511. Salvages #124988 by @Finn763 (state-layer delete hook, commits kept with authorship) and folds in #132639 by @pieralukasz (archive as a "done" signal; Co-authored-by).

What plugins get

Field	Value
session_id	the session the caller targeted
reason	delete, archive, empty_sweep, prune, ghost_prune, profile_repair
profile	profile owning the store (default for the root home); dispatch runs under that profile's home, so its plugins get the event even when another profile's process did the delete
deleted_ids	every removed or hidden row (delegate children, compression-chain links, bulk rows) when more than one went
sessions_dir	the profile's sessions/ dir when the caller had one

Observer only: return ignored, a raising callback is logged and skipped, the delete still commits. Process-local delivery, no exactly-once guarantee (documented).

Changes

• hermes_state_common.emit_session_deleted: one late-bound, fail-open seam into lifecycle.invoke_hook, called right after _execute_write returns and before media/transcript cleanup (which can raise).
• Fired from delete_session, delete_sessions, delete_session_if_empty, delete_empty_sessions, prune_sessions, prune_empty_ghost_sessions, delete_moved_session (Finn's commits).
• Added on top: mutate_runtime_session fires for delete and for a real archive flip. Desktop/dashboard single delete and archive go through this canonical receipt, not SessionDB.delete_session, so before this commit Desktop never fired. An exact retry replays the receipt and stays silent.
• Archive (from feat(plugins): on_session_archived hook for deliberate session archives #132639): set_session_archived fires reason="archive" only on a real unarchived → archived flip. That covers TUI session.archive, deferred TUI archives and hermes sessions archive. Repeat archives, un-archives, the idle auto-archive sweep and profile adoption (notify=False) stay silent. One hook with a reason field replaces the separate on_session_archived hook.
• Docs: hooks reference (table + section), plugin guide hook table, observer-hooks list, plugins.md observer list, zh-Hans rows.

Callers covered (grep of every DELETE FROM sessions / archive writer): CLI sessions delete|prune|archive, /exit --delete, quit-time empty discard, curses browser, auto-maintenance ghost prune and auto-prune, dashboard bulk delete / "Delete empty" / prune, Desktop DELETE + PATCH archived, TUI session.delete / session.archive, onboarding reset, gateway API server delete, gateway never-active prune, profile repair. Not fired: the api_server title-conflict rollback of a row inserted in the same transaction (commented), the seed-copy discard_unadmitted_session compensation path.

Validation

Check	Result
tests/hermes_state/test_session_delete_hook.py (2 invariant tests, real SessionDB + real hook registry)	head 2/2 pass; origin/main 0/2 (no events fired)
Neighbors: session archiving, archive RPC, repair-profiles, auto-archive (reactivation, lease, gateway lock, profile config), pinned/archived sidebar, web_server, adopted bot chat, hooks, plugins, branched-root delete, session API, housekeeping scope, export retention	669 passed, 0 failed (final head)
tests/hermes_state/test_hermes_state.py alone, head vs origin/main	297/297 both; 172 s vs 165 s (no slowdown)
scripts/check (incl. code health)	ok; maybe_auto_archive moved to hermes_state_maintenance.py to keep hermes_state_sessions.py under 2000 lines

Cross-profile check: a default-profile process ran delete_moved_session on profiles/work/state.db. Only the work profile's plugin logged {"reason": "profile_repair", "profile": "work"}.

Live repro (real hermes processes, scratch HERMES_HOME, a scratch user plugin registering on_session_delete, three real chat sessions on Hermes-4-70B):

$ hermes sessions archive --title ok2 --yes
[delete-probe] {"session_id": "local-1b46…", "reason": "archive", "profile": "default"}
$ hermes sessions archive --title ok2 --yes        # already archived → no event
$ hermes sessions delete local-4440… --yes
[delete-probe] {"session_id": "local-4440…", "reason": "delete", "profile": "default", "sessions_dir": ".../home/.hermes/sessions"}
# hermes dashboard (Desktop's REST surface)
PATCH  /api/sessions/local-bc6a…  {"archived": true}
  → {"session_id": "local-bc6a…", "reason": "archive", "profile": "default"}
DELETE /api/sessions/local-bc6a…
  → {"session_id": "local-bc6a…", "reason": "delete", "profile": "default"}
DELETE (same request_id, exact retry) → receipt replayed, no event

On origin/main none of these produced a callback (hook not in VALID_HOOKS, no dispatch).

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 3d79bd7 — fix(plugins): on_session_delete review findings}

debug info

CI timings

CI timings · View report · View job

Wall time 8m59s vs 13m1s (-31.0%). 2 job(s) slower, 15 faster, 3 unchanged.

• OS-specific tests / Windows-only tests (arm64, 1/2): -134.0s
• Python tests / Run tests (2/2): +106.0s
• OS-specific tests / Windows-only tests (arm64, 2/2): -79.0s
• OS-specific tests / Windows-only tests: -26.0s
• Catalog tests / Catalog tests: -22.0s

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; all five previous findings are fixed, and no new blocking issue was found.

Summary

Adds on_session_delete notifications after committed deletes and deliberate archives across session entry points.

• Plugins can hear when a session is deleted or deliberately archived.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Delete or deliberate archive] --> B[Commit database write]
    B --> C{Event to send?}
    C -->|No change or receipt replay| G[Return result]
    C -->|Yes| D[Bind owning profile home]
    D --> E[Invoke on_session_delete]
    E --> F[Restore previous profile home]
    F --> H[Run follow-up cleanup where needed]
    H --> G

Loading

_{Reviews (2) · Last reviewed commit: "fix(plugins): on_session_delete review f..." · Reviewed by Greptile}

[teknium1]

All five Greptile findings were valid and are fixed in e4ff3c7:

1. Wrong profile receives delete events: emit_session_deleted now dispatches with the store's home bound (set_hermes_home_override) whenever it differs from the active home. Live check: a default-profile process ran delete_moved_session on profiles/work/state.db. Only the work profile's plugin logged {"reason": "profile_repair", "profile": "work"}, and the default plugin logged nothing.
2. Archive events omit chain rows: both archive paths now pass the affected lineage ids (deleted_ids) and keep the requested id as session_id. The invariant test covers a root+tip chain on the SessionDB path and on the runtime path.
3. Event state has no contract: write returns (result, SessionGoneEvent | None), a NamedTuple. The shared list is gone.
4. Cleanup failures skip delete events: every delete path now emits right after _execute_write and before collect_retired_media / transcript removal.
5. Hook reference contradicts itself: removed the leftover duplicate block.

Tests: 669 passed across 17 neighbor files, including test_hermes_state.py.

@greptileai review