fix(gateway): one session queue, LRU eviction, telegram-only /start, awaited shutdown, webhook usage/502

[Moikapy]

Part of #144. This is the first PR for #144: section A's first item, plus the G-10 and webhook fixes. Persistence and per-chat profiles are deferred to a follow-up, as agreed.

Changes

• One queue implementation: GatewayBus now queues each conversation on the shared SessionManager (src/session/manager.ts) instead of its own chains map of promise chains. Behavior is unchanged: one conversation runs in order, and different conversations run concurrently.
• G-10, eviction: beyond max_conversations (200), the least recently used conversation is evicted. Before, the oldest inserted one was. History is re-inserted on every store, so the Map's order tracks use.
• G-10, /start: only Telegram's bot-start command (/start, /start@bot, /start <payload>) is rewritten to "hello". Before, any message on any platform that started with /start, including /started ..., was replaced.
• G-10, shutdown: SIGINT and SIGTERM now await every adapter's stop(), capped at 5 s so a hung platform socket can't block exit, before releasing the bus and agent and exiting. Before, stop() calls were fire-and-forget, followed by an immediate process.exit. This lives in the new exported shutdown_gateway.
• Webhook (breaking): bus.reply() returns { text, usage, failed }.
  • POST /message now returns the run's token usage instead of null.
  • An agent failure returns 502 {"error":"agent error: ..."} instead of 200 with the error in reply.
  • Chat adapters are unchanged. InboundHandler accepts either a string or the reply object, and reply_text() normalizes it.
• Docs: gateway.md, godot.md, getting-started.md, the persona_orchestrator README and the CHANGELOG are updated for the new webhook shape and the eviction and /start behavior.

Tests

• New in gateway.test.ts:
  • LRU eviction: a conversation used after another survives the next eviction.
  • Telegram-only /start: the bare, @bot and payload forms are rewritten; /started and webhook /start are not.
  • reply() returns usage and a failure flag.
  • The webhook returns 200 with real usage, and 502 with the error.
• New gateway_shutdown.test.ts: adapters are awaited before bus.stop and agent.close, including one adapter that throws, and the timeout path when an adapter hangs.
• Two existing tests read the removed private chains map. They now check SessionManager.pending_count() instead, with the same intent: settled queues are released (G-6), and an evicted conversation keeps its in-flight queue.
• Mutation check: I reverted each of the five changes in turn, and a test failed each time.

Checks

• tsc --noEmit: clean.
• vitest: 704/706 pass. The two failures happen only in this container: serve_transport "accepts ::1 clients" (no IPv6) and tools_review_shouldfix S-6 (process-group zombies).
• vitepress build docs: passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LHQAfXHofy6QkAgmfmJava

---

Generated by Claude Code

[cursor]

Stale comment

PR #174 — Risk: HIGH (breaking webhook wire contract is an ambiguous public API, so one level up from MEDIUM; gateway session queue and shutdown. Auth, loopback bind, allowlists, LICH_GATEWAY_TOKEN, and gateway.tools_enabled are unchanged. 12 files, +271/−71.)
Findings: Critical 0 / Warning 1 / Suggestion 2 (src/gateway/bus.ts:101 enforce the cap on store and touch LRU at run start; src/gateway/runner.ts:134 closeAllConnections so webhook stop() can finish; docs/user-guide/gateway.md:7 mention HTTP 502)
Regressions of settled findings: none (first review)
Not reviewed: none (full three-dot diff, plus session queue, reply formatting, adapter stop, and the webhook token check)
Action: escalated to @Moikapy
Log: 2026-10-05 UTC, COMMENT, HIGH because the webhook success/failure shape is a breaking client contract and the gateway lifecycle changed; auto-merge left off. Also blocked by head commit author claude (not @Moikapy) and typecheck_and_test (20) and (22) still in progress. needs-review added.

  

_{Sent by Cursor Automation: PR REVIEW}

[cursor]

PR #174 — Risk: HIGH (breaking webhook client contract is an ambiguous public API, so one level up from MEDIUM; gateway session queue and shutdown. Auth, loopback bind, allowlists, LICH_GATEWAY_TOKEN, and gateway.tools_enabled are unchanged. 12 files, +334/−71.)

Findings: Critical 0 / Warning 0 / Suggestion 0

Regressions of settled findings: none

• src/gateway/bus.ts cap on store: fixed. Concurrent new chats trim to max_conversations and the just-stored key is kept.
• docs/user-guide/gateway.md HTTP 502: fixed in the overview sentence.
• src/gateway/runner.ts keep-alive close: stated decision stands (engines is node >= 20; the new stop test passed on CI).

Not reviewed: none (delta b95516b5..53d81181; earlier commits reviewed at b95516b5)

Action: escalated to @Moikapy
Log: 2026-10-05 05:53 UTC, COMMENT, HIGH unchanged after the follow-up commit. Auto-merge left off. needs-review already set. typecheck_and_test (20) and (22), ossuary, wiki_lint, WIP, and AccessLint are green. Merge is also blocked because every commit author is claude. Auto-merge allows @Moikapy or a configured approved bot, and no approved-bot list was set.

  

_{Sent by Cursor Automation: PR REVIEW}