Gateway Module — `sessions/`

1. Purpose

The sessions module is the cross-channel session registry (Dispatch 399/650) — it tracks live VS Code and Genkan (Hermes) sessions, their heartbeats, working state, active dispatches, and conversation turns, and provides the cross-channel directive-injection mechanism. It carries the module's own SSE event stream (GET /events), a heartbeat update path, a stale detector that auto-ends sessions silent >30min, and three transcript-read carve-outs (vscode, hermes, :id/turns) that leak operator conversation state and are therefore explicitly Bearer-gated post-AK-415/AK-334.

2. File Inventory

3. Public API Surface

REST Endpoints (mount: index.ts:752 → /api/sessions)

Several session endpoints that would otherwise be broadly readable are explicitly Bearer-gated because they expose session metadata, transcripts, or full conversation turns. The event stream is the exception: it uses a read-only-token handshake instead of an Authorization header, because EventSource cannot set request headers.

MCP Tools

list_sessions (RO → /active); post_session_directive_raw (RAW-ONLY → /directive). No MCP tool targets the transcript readers or SSE stream.

4. Internal API

createSessionLayer(db, psychicCacheRepo) → {repo, router, staleDetector}. SessionRepository: register, heartbeat, end, findActive, findById, cleanStale, writeTurn, readTurns. Re-exports sessionEventBus + event types from events.ts. The /directive route depends on PsychicCacheRepository.write — sessions has no cache table of its own; directives are ordinary psychic-cache directive entries.

5. Background Services

6. Data Contracts

• RegisterSessionInputSchema: id, channel (vscode|hermes), current_mission_namespaces?, active_dispatches? (positive int[]), working_state_prose?, metadata?.
• HeartbeatInputSchema: same optional fields + last_exchange_summary? (≤500), status? (active|idle).
• PostDirectiveInputSchema: content, directive_target, directive_priority (default medium), mission_id, tags (min 1), plus targeting/source attribution optionals.
• WriteTurnInputSchema: role (user|assistant|system), content (min 1, max 10000 validated; truncated to 2000 at repo).
• SessionEvent = DirectiveEvent | SessionStateEvent (events.ts). Row JSON columns (current_mission_namespaces, active_dispatches, metadata) parse with fail-safe defaults (class-(b) silent-catch, intentional).

7. Dependencies

• Gateway modules: psychic-cache/types.js (PsychicCacheRepository, WriteCacheInputSchema), shared/zod-error.js.
• External: better-sqlite3 (incl. a second read-only Database handle opened per-request for HERMES_STATE_DB), express, zod, Node fs/os/path.
• Environment variables: CLAUDE_CODE_JSONL_DIR, CLAUDE_CODE_SESSION_ID_PATH (default ~/.claude/session-env/.active-session-id), HERMES_STATE_DB_PATH.

8. Test Coverage

9. Known Limitations

• register uses INSERT OR REPLACE — re-registering an existing session id silently overwrites started_at/turn linkage rather than erroring. Intentional for reconnect, but destructive if an id collides across channels.
• The hermes/transcript reader opens a fresh read-only SQLite handle per request and closes it inline; no pooling. Low-frequency endpoint, acceptable, but not free under burst.
• Two commented-but-absent route markers remain in routes.ts (a stray GET /hermes/transcript header comment mid-file and a POST /:id/turn marker) — cosmetic drift, no functional impact.
• /events channel filter logic is inverted-looking: it returns (skips) when event.*_channel === channelFilter, i.e. the channel= param excludes that channel rather than including it. Worth confirming against dashboard intent. [DIVERGENCE — LOW, verify]

10. Change History