jeo-code 0.7.48 → 0.7.50

package/CHANGELOG.md

@@ -6,6 +6,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.7.50] - 2026-07-06
+_Design-doc audit of v0.7.47's PromptRouter, dispatched as two parallel subagents (independent re-verification + gap implementation) against the original Korean-language design report. The core proposal was confirmed shipped correctly (heuristic classifier, escalation, `/model`-always-wins, tool-selection isolation — all independently re-derived from git history and grep evidence, not just re-read from the doc). Two gaps the design doc itself had flagged as open questions (§7 risks #2 and #4) were real and are fixed here; a third finding (an internal contradiction in the design doc's own §3.2 vs §3.4 text on image-attachment gating — the SHIPPED code was already correct, only the doc's prose disagreed with itself) required no code change._
+
+### Added
+- **`jeo doctor` routing diagnostic** (`src/commands/doctor.ts`) — when `routing.enabled` is true but `roles.smol` is unset, `routePrompt`'s LLM-escalation path silently never fires every turn (it degrades to heuristic-only tier resolution, the same paradox `routePrompt` itself already guards against at runtime via its one-time `warnOnce`). `jeo doctor` now surfaces this proactively at onboarding time instead of only mid-session: a `routing: { enabled, smolConfigured, note? }` block in `--json` output, and a yellow `[routing]` note (or a terse green confirmation when `roles.smol` IS configured) printed after the OAuth section, before the final verdict. Purely informational — never affects the `ready`/`strict` exit-code gate.
+
+### Fixed
+- **Prompt-cache-key collision on mid-session model switch** (`src/agent/prompt-router.ts`'s new `deriveCacheSessionKey`, wired into `src/commands/launch.ts`'s `runTurn`) — `sessionKey` (forwarded as `prompt_cache_key`/`session_id` to provider requests) was the bare `sessionId`, unchanged across turns. Provider-side prompt caches are keyed PER MODEL, so when `routePrompt` switches `activeModel` between turns in the same session (its entire reason for existing), every switch silently guaranteed a cache miss on the new model — undermining the exact cost/latency savings routing exists to deliver. The derived key is now `` `${sessionId}:${activeModel}` ``: stable (same key) across consecutive turns on the same model, distinct (different key) the instant the model changes, with zero effect on `--no-session` (still forwards `undefined` unchanged).
+
+### Verified
+- `bun run typecheck` clean; `bun test` 2644 pass / 0 fail across 280 files — 2 consecutive full-suite runs, both clean.
+- `test/doctor.test.ts` (+5 tests, 7 total): routing off → no `routing` block; routing on + `roles.smol` unset → note present with escalation-skip wording (both `--json` and human-output paths); routing on + `roles.smol` set → no note, `smolConfigured: true`; human-output note never flips the `ready`/`strict` verdict.
+- `test/prompt-router.test.ts` (+4 tests, 36 total): `deriveCacheSessionKey` pure-function unit tests — same session+model → same key, different model → different key, key format, `--no-session` (undefined sessionId) short-circuit.
+- `test/launch-prompt-routing.test.ts` (+2 tests, 6 total): real end-to-end proof through `runLaunchCommand` with a genuine persisted session (not `--no-session`) — two turns routed to the SAME model produce the SAME `sessionKey` (cache reuse preserved), two turns routed to DIFFERENT models produce DIFFERENT `sessionKey`s sharing the same session-id prefix (no false cross-model cache hit, still same session lineage).
+- Independent verification pass (separate subagent, read-only, no code touched) re-derived every §0–§8 claim in the design doc directly from git history (`ff7816a^` pre-PromptRouter vs. current HEAD) rather than trusting the doc's own text — confirmed the core architecture claims, design-principle-5 tool-isolation guarantee (exhaustive grep: `RouteDecision` has no tool/permission field, zero cross-references between `routing.` and any subagent-toolset code), and the bilingual heuristic test corpus; also independently ran `graphify` itself (not grep proxies) to reproduce 3 of 5 named hub-degree figures from the doc almost exactly, while flagging that 2 of the doc's supporting dependency-direction claims (`state.ts`, `model-catalog*.ts` importing `model-manager.ts`) do not hold under direct import inspection.
+
+## [0.7.49] - 2026-07-06
+_gjc Telegram-daemon parity, Tier 2 (follow-up to 0.7.37/0.7.38/0.7.48's subagent-visibility-only daemon): adds a dynamic, PER-SESSION forum topic that mirrors that session's OWN activity — not just its subagents — and lets a Telegram reply steer it directly. Opt-in via `notifications.telegram.perSessionTopics`; the flat/global `topicId` path from 0.7.48 is UNCHANGED when it's off, so existing setups see zero regression._
+
+### Added
+- **Per-session forum topics** (`src/agent/notify/topic-registry.ts`, new) — a pure, injectable-create `TopicRegistry` gives each interactive session its own Telegram forum topic (numeric `topicId`, rename-dedup via `applyName`), persisted across daemon restarts (`notifyTopicsPath()`, gjc `telegram-topics.json` parity) and reused indefinitely across `--resume` (jeo topics are never deleted, unlike gjc's). Two independent fail-closed gates protect it: the paired chat must be a confirmed private DM (`TelegramApi.getChat`, checked once per daemon lifetime and cached, fails closed on error) before a topic is ever attempted, and a per-connection `topicFailed` flag remembers a `createForumTopic` failure (e.g. Threaded Mode off in @BotFather) so it degrades to the flat/global `topicId` instead of retrying every single frame.
+- **Main-session mirroring** (`session-endpoint.ts` refactored from a per-TURN to a per-SESSION lifecycle) — `startSessionNotifyEndpoint` now starts ONE endpoint for the whole interactive REPL, with `attachRegistry`/`detachRegistry` swapping the live per-turn `SubagentRegistry` in/out at turn boundaries instead of one endpoint per turn. New push frames: `sendIdentity` (one-time `identity_header` naming the session's topic), `sendContextUpdate` (`turn_start`/`turn_end`, honors a new session-local `notifyRedact` toggle), `sendTurnStream` (the finished reply, rendered through the new `telegram-html.ts` converter).
+- **Inbound steering** (`onUserMessage` wiring in `launch.ts`) — a free-text Telegram reply in a session's own topic steers that RUNNING turn exactly like a local mid-turn Enter when one is active, or injects as the next prompt when idle — but only once the local readline buffer is confirmed empty, so it never hijacks a keystroke the user is actively typing locally. Attached photos/documents are downloaded daemon-side and resolved into real `ImageAttachment`s through the same `attachImagePaths` path local drag-drop already uses.
+- **In-thread config commands** (`src/agent/notify/config-commands.ts`, new) — `/verbose`, `/lean`, `/verbosity lean|verbose`, `/redact on|off` typed into a session's own topic flip that session's local `notifyVerbosity`/`notifyRedact` (never persisted to `~/.jeo/config.json`, mirroring gjc's session-local semantics) via a new `onConfigCommand` callback; anything else typed in that topic (including a caption-less media message) falls through to free-text steering instead.
+- **Shared `RateLimitPool`** (`src/agent/notify/rate-limit-pool.ts`, new) — a host-wide token-bucket scheduler (burst + steady refill) with 4 priority lanes (`ask`>`finalized`>`live`>`idle`), per-session round-robin fairness so one session's stream can't starve another, and coalescing of same-`coalesceKey` items. Every daemon push now routes through it (`flushPool`); current callers only submit to `finalized` in practice (subagent pushes + main-session mirroring) — the other 3 lanes exist for architectural completeness (jeo has no `ask` tool or incremental token-stream to mirror yet).
+- **Telegram HTML formatting** (`src/agent/notify/telegram-html.ts`, new) — `markdownToTelegramHtml` (a bounded markdown subset rendered into Telegram's allowed HTML tag set, escape-first-tag-second) plus `truncateTelegramHtml`/`splitTelegramHtml`, which never break a tag or entity mid-string when a rendered reply exceeds the 4096-char message cap.
+- **Telegram Bot API additions** (`telegram-api.ts`): `createForumTopic`/`editForumTopic`, `getFile`/`downloadFile` (path-traversal-guarded — rejects any `..`, leading `/`, or `\` segment in the untrusted remote `file_path` before building the download URL), `getChat`, `setMessageReaction` (a 👀 reaction acknowledges an inbound message the daemon successfully routed).
+- **`notifications.verbosity`/`notifications.redact`/`notifications.telegram.perSessionTopics`** config fields (`config-schema.ts`/`state.ts`) — all optional; unset behaves exactly as before (lean, not redacted, flat/global topic only).
+
+### Fixed
+- A genuine **pre-existing test-isolation bug**, surfaced only under full-280-file-suite load and never in isolation: an orphaned `mock.module("../src/agent/loop", ...)` leaked from an unrelated, never-restored test elsewhere in the suite intermittently shadowed the real LLM call for whichever test happened to run nearby. `test/launch-telegram-remote.test.ts`'s turn-completion assertion no longer depends on a specific credential-error string arriving within a fixed window (fragile under that pollution); it now races the unconditional `turn_end` context-update frame against a credential error and accepts either terminal outcome — the loop recovers and reaches its next prompt either way, which is the actual contract being tested.
+
+### Verified
+- `bun run typecheck` clean; `bun test` 2633 pass / 0 fail across 280 files — 4 consecutive full-suite runs, all clean (chasing down the flake above required reproducing it under real full-suite load first).
+- New: `test/notify-topic-registry.test.ts` (18 tests), `test/notify-rate-limit-pool.test.ts` (9), `test/notify-config-commands.test.ts` (21), `test/notify-telegram-html.test.ts` (42), `test/launch-telegram-remote.test.ts` (6, real spawned-process end-to-end through the actual CLI: session registration, `context_update` on turn start/end, remote free-text injection while idle, remote injection while mid-turn steers the running turn, `config_command` mutates session-local verbosity/redact without touching global config).
+- Extended: `test/notify-session-endpoint.test.ts` (20 tests, session-scoped construction + attach/detach lifecycle), `test/notify-telegram-api.test.ts` (26 — `createForumTopic`/`editForumTopic`/`getFile`/`downloadFile` incl. path-traversal rejection, `getChat`/`setMessageReaction` request shape), `test/notify-telegram-daemon.test.ts` (54 — topic resolution/creation/rename, rate-limit-pool flush wiring, inbound photo/document download+relay, in-thread config-command dispatch vs. free-text fallthrough, 👀 reaction on accept).
+
 ## [0.7.48] - 2026-07-06
 _gjc Telegram-daemon parity, phase 2 (follow-up to 0.7.37/0.7.38's baseline subagent-visibility daemon, which deliberately scoped OUT forum topics, inline keyboards, and image attachments — see that entry): the daemon now speaks gjc's richer notification surface instead of the plain-text-only baseline._
 

package/README.ja.md

@@ -259,11 +259,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.50]** (2026-07-06) — Design-doc audit of v0.7.47's PromptRouter, dispatched as two parallel subagents (independent re-verification + gap implementation) against the original Korean-language design report. The core proposal was confirmed shipped correctly (heuristic classifier, escalation, `/model`-always-wins, tool-selection isolation — all independently re-derived from git history and grep evidence, not just re-read from the doc). Two gaps the design doc itself had flagged as open questions (§7 risks #2 and #4) were real and are fixed here; a third finding (an internal contradiction in the design doc's own §3.2 vs §3.4 text on image-attachment gating — the SHIPPED code was already correct, only the doc's prose disagreed with itself) required no code change.
+- **[0.7.49]** (2026-07-06) — gjc Telegram-daemon parity, Tier 2 (follow-up to 0.7.37/0.7.38/0.7.48's subagent-visibility-only daemon): adds a dynamic, PER-SESSION forum topic that mirrors that session's OWN activity — not just its subagents — and lets a Telegram reply steer it directly. Opt-in via `notifications.telegram.perSessionTopics`; the flat/global `topicId` path from 0.7.48 is UNCHANGED when it's off, so existing setups see zero regression.
 - **[0.7.48]** (2026-07-06) — gjc Telegram-daemon parity, phase 2 (follow-up to 0.7.37/0.7.38's baseline subagent-visibility daemon, which deliberately scoped OUT forum topics, inline keyboards, and image attachments — see that entry): the daemon now speaks gjc's richer notification surface instead of the plain-text-only baseline.
 - **[0.7.47]** (2026-07-06) — PromptRouter (gjc-inspired, jeo-native design — NOT a port of katanemo/plano, whose always-on proxy-orchestrator architecture doesn't fit an interactive CLI's per-turn latency budget): jeo already had static, role-based model mapping (`resolveSubagentModel`/`resolveRoleModel`) but zero logic that varied the model by what THIS turn's prompt actually asks for. Adds an opt-in (default OFF), heuristic-first, fail-open per-turn router: a bilingual regex classifier scores a prompt into trivial/standard/complex, escalating to one cheap LLM call ONLY when the heuristic is genuinely ambiguous (confidence below a configurable threshold — most turns never escalate), and an explicit `/model` pin always wins over routing. No new plumbing: reuses `resolveRoleModel`, `callLlm`, `jsonMode`, `catalogMetadata`, `tryExtractJsonObject`, and the existing `onNotice` transparency pattern.
 - **[0.7.46]** (2026-07-06) — Registry-only correction: `npm publish` packs the working-tree filesystem, not the git commit — a concurrent, unrelated, uncommitted feature-in-progress from another session sharing this checkout (`src/agent/prompt-router.ts`, `src/commands/launch/route-slash.ts`, and edits to `config-schema.ts`/`state.ts`/`launch.ts`/`slash.ts`) was physically present on disk during the 0.7.45 `npm publish` and got bundled into that tarball even though it was never committed to git and is absent from the `0.7.45` git tag/branch. Unpublished `jeo-code@0.7.45` from the registry within minutes (npm then permanently blocks republishing that exact version number, hence the bump to 0.7.46) and republished from a verified-clean working tree (`git stash` of the foreign files, `npm pack --dry-run` confirmed their absence, then restored the stash afterward so the other session's in-progress work was never touched or lost). No functional change versus the intended 0.7.45 content — see that entry below.
-- **[0.7.45]** (2026-07-06) — gjc parity: jeo's subagent `task {tasks:[...]}` fan-out batches now visibly run as PARALLEL processes the way gjc's own task tool does, instead of quietly forcing the mutating executor role to serialize. Two compounding bugs made a batch of independent subagent tasks look and behave sequential even though the read-only roles were already technically concurrent: (1) the executor role's fan-out was hard-coded to concurrency 1 regardless of batch size, and (2) the TUI's live status line tracked ONE shared string clobbered by whichever worker's event landed last — worse, ANY single worker reaching "done" cleared the whole `(sub)` marker even while its siblings were still actively running.
-- **[0.7.44]** (2026-07-06) — Root-caused a real production hang reported from `jeo`'s OpenAI Codex OAuth subagent path: after roughly 20-30 minutes of active streamed traffic, `chatgpt.com`'s backend severs the live SSE connection mid-response (an infra connection-duration cap, not a broken network) and Bun's fetch/undici surfaces it as `Error: The socket connection was closed unexpectedly …`. `retryableStream` (model-manager.ts) only auto-retries losing the FIRST streamed chunk — once any chunk had reached the caller it deliberately stopped retrying (a full re-call would replay already-emitted content) — so this class of drop propagated straight out of the engine as a raw, unretried turn-ending error every time, even though nothing had been committed to history yet and a plain resend is exactly as safe as a fresh call.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -260,11 +260,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.50]** (2026-07-06) — Design-doc audit of v0.7.47's PromptRouter, dispatched as two parallel subagents (independent re-verification + gap implementation) against the original Korean-language design report. The core proposal was confirmed shipped correctly (heuristic classifier, escalation, `/model`-always-wins, tool-selection isolation — all independently re-derived from git history and grep evidence, not just re-read from the doc). Two gaps the design doc itself had flagged as open questions (§7 risks #2 and #4) were real and are fixed here; a third finding (an internal contradiction in the design doc's own §3.2 vs §3.4 text on image-attachment gating — the SHIPPED code was already correct, only the doc's prose disagreed with itself) required no code change.
+- **[0.7.49]** (2026-07-06) — gjc Telegram-daemon parity, Tier 2 (follow-up to 0.7.37/0.7.38/0.7.48's subagent-visibility-only daemon): adds a dynamic, PER-SESSION forum topic that mirrors that session's OWN activity — not just its subagents — and lets a Telegram reply steer it directly. Opt-in via `notifications.telegram.perSessionTopics`; the flat/global `topicId` path from 0.7.48 is UNCHANGED when it's off, so existing setups see zero regression.
 - **[0.7.48]** (2026-07-06) — gjc Telegram-daemon parity, phase 2 (follow-up to 0.7.37/0.7.38's baseline subagent-visibility daemon, which deliberately scoped OUT forum topics, inline keyboards, and image attachments — see that entry): the daemon now speaks gjc's richer notification surface instead of the plain-text-only baseline.
 - **[0.7.47]** (2026-07-06) — PromptRouter (gjc-inspired, jeo-native design — NOT a port of katanemo/plano, whose always-on proxy-orchestrator architecture doesn't fit an interactive CLI's per-turn latency budget): jeo already had static, role-based model mapping (`resolveSubagentModel`/`resolveRoleModel`) but zero logic that varied the model by what THIS turn's prompt actually asks for. Adds an opt-in (default OFF), heuristic-first, fail-open per-turn router: a bilingual regex classifier scores a prompt into trivial/standard/complex, escalating to one cheap LLM call ONLY when the heuristic is genuinely ambiguous (confidence below a configurable threshold — most turns never escalate), and an explicit `/model` pin always wins over routing. No new plumbing: reuses `resolveRoleModel`, `callLlm`, `jsonMode`, `catalogMetadata`, `tryExtractJsonObject`, and the existing `onNotice` transparency pattern.
 - **[0.7.46]** (2026-07-06) — Registry-only correction: `npm publish` packs the working-tree filesystem, not the git commit — a concurrent, unrelated, uncommitted feature-in-progress from another session sharing this checkout (`src/agent/prompt-router.ts`, `src/commands/launch/route-slash.ts`, and edits to `config-schema.ts`/`state.ts`/`launch.ts`/`slash.ts`) was physically present on disk during the 0.7.45 `npm publish` and got bundled into that tarball even though it was never committed to git and is absent from the `0.7.45` git tag/branch. Unpublished `jeo-code@0.7.45` from the registry within minutes (npm then permanently blocks republishing that exact version number, hence the bump to 0.7.46) and republished from a verified-clean working tree (`git stash` of the foreign files, `npm pack --dry-run` confirmed their absence, then restored the stash afterward so the other session's in-progress work was never touched or lost). No functional change versus the intended 0.7.45 content — see that entry below.
-- **[0.7.45]** (2026-07-06) — gjc parity: jeo's subagent `task {tasks:[...]}` fan-out batches now visibly run as PARALLEL processes the way gjc's own task tool does, instead of quietly forcing the mutating executor role to serialize. Two compounding bugs made a batch of independent subagent tasks look and behave sequential even though the read-only roles were already technically concurrent: (1) the executor role's fan-out was hard-coded to concurrency 1 regardless of batch size, and (2) the TUI's live status line tracked ONE shared string clobbered by whichever worker's event landed last — worse, ANY single worker reaching "done" cleared the whole `(sub)` marker even while its siblings were still actively running.
-- **[0.7.44]** (2026-07-06) — Root-caused a real production hang reported from `jeo`'s OpenAI Codex OAuth subagent path: after roughly 20-30 minutes of active streamed traffic, `chatgpt.com`'s backend severs the live SSE connection mid-response (an infra connection-duration cap, not a broken network) and Bun's fetch/undici surfaces it as `Error: The socket connection was closed unexpectedly …`. `retryableStream` (model-manager.ts) only auto-retries losing the FIRST streamed chunk — once any chunk had reached the caller it deliberately stopped retrying (a full re-call would replay already-emitted content) — so this class of drop propagated straight out of the engine as a raw, unretried turn-ending error every time, even though nothing had been committed to history yet and a plain resend is exactly as safe as a fresh call.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -262,11 +262,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.50]** (2026-07-06) — Design-doc audit of v0.7.47's PromptRouter, dispatched as two parallel subagents (independent re-verification + gap implementation) against the original Korean-language design report. The core proposal was confirmed shipped correctly (heuristic classifier, escalation, `/model`-always-wins, tool-selection isolation — all independently re-derived from git history and grep evidence, not just re-read from the doc). Two gaps the design doc itself had flagged as open questions (§7 risks #2 and #4) were real and are fixed here; a third finding (an internal contradiction in the design doc's own §3.2 vs §3.4 text on image-attachment gating — the SHIPPED code was already correct, only the doc's prose disagreed with itself) required no code change.
+- **[0.7.49]** (2026-07-06) — gjc Telegram-daemon parity, Tier 2 (follow-up to 0.7.37/0.7.38/0.7.48's subagent-visibility-only daemon): adds a dynamic, PER-SESSION forum topic that mirrors that session's OWN activity — not just its subagents — and lets a Telegram reply steer it directly. Opt-in via `notifications.telegram.perSessionTopics`; the flat/global `topicId` path from 0.7.48 is UNCHANGED when it's off, so existing setups see zero regression.
 - **[0.7.48]** (2026-07-06) — gjc Telegram-daemon parity, phase 2 (follow-up to 0.7.37/0.7.38's baseline subagent-visibility daemon, which deliberately scoped OUT forum topics, inline keyboards, and image attachments — see that entry): the daemon now speaks gjc's richer notification surface instead of the plain-text-only baseline.
 - **[0.7.47]** (2026-07-06) — PromptRouter (gjc-inspired, jeo-native design — NOT a port of katanemo/plano, whose always-on proxy-orchestrator architecture doesn't fit an interactive CLI's per-turn latency budget): jeo already had static, role-based model mapping (`resolveSubagentModel`/`resolveRoleModel`) but zero logic that varied the model by what THIS turn's prompt actually asks for. Adds an opt-in (default OFF), heuristic-first, fail-open per-turn router: a bilingual regex classifier scores a prompt into trivial/standard/complex, escalating to one cheap LLM call ONLY when the heuristic is genuinely ambiguous (confidence below a configurable threshold — most turns never escalate), and an explicit `/model` pin always wins over routing. No new plumbing: reuses `resolveRoleModel`, `callLlm`, `jsonMode`, `catalogMetadata`, `tryExtractJsonObject`, and the existing `onNotice` transparency pattern.
 - **[0.7.46]** (2026-07-06) — Registry-only correction: `npm publish` packs the working-tree filesystem, not the git commit — a concurrent, unrelated, uncommitted feature-in-progress from another session sharing this checkout (`src/agent/prompt-router.ts`, `src/commands/launch/route-slash.ts`, and edits to `config-schema.ts`/`state.ts`/`launch.ts`/`slash.ts`) was physically present on disk during the 0.7.45 `npm publish` and got bundled into that tarball even though it was never committed to git and is absent from the `0.7.45` git tag/branch. Unpublished `jeo-code@0.7.45` from the registry within minutes (npm then permanently blocks republishing that exact version number, hence the bump to 0.7.46) and republished from a verified-clean working tree (`git stash` of the foreign files, `npm pack --dry-run` confirmed their absence, then restored the stash afterward so the other session's in-progress work was never touched or lost). No functional change versus the intended 0.7.45 content — see that entry below.
-- **[0.7.45]** (2026-07-06) — gjc parity: jeo's subagent `task {tasks:[...]}` fan-out batches now visibly run as PARALLEL processes the way gjc's own task tool does, instead of quietly forcing the mutating executor role to serialize. Two compounding bugs made a batch of independent subagent tasks look and behave sequential even though the read-only roles were already technically concurrent: (1) the executor role's fan-out was hard-coded to concurrency 1 regardless of batch size, and (2) the TUI's live status line tracked ONE shared string clobbered by whichever worker's event landed last — worse, ANY single worker reaching "done" cleared the whole `(sub)` marker even while its siblings were still actively running.
-- **[0.7.44]** (2026-07-06) — Root-caused a real production hang reported from `jeo`'s OpenAI Codex OAuth subagent path: after roughly 20-30 minutes of active streamed traffic, `chatgpt.com`'s backend severs the live SSE connection mid-response (an infra connection-duration cap, not a broken network) and Bun's fetch/undici surfaces it as `Error: The socket connection was closed unexpectedly …`. `retryableStream` (model-manager.ts) only auto-retries losing the FIRST streamed chunk — once any chunk had reached the caller it deliberately stopped retrying (a full re-call would replay already-emitted content) — so this class of drop propagated straight out of the engine as a raw, unretried turn-ending error every time, even though nothing had been committed to history yet and a plain resend is exactly as safe as a fresh call.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -259,11 +259,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.50]** (2026-07-06) — Design-doc audit of v0.7.47's PromptRouter, dispatched as two parallel subagents (independent re-verification + gap implementation) against the original Korean-language design report. The core proposal was confirmed shipped correctly (heuristic classifier, escalation, `/model`-always-wins, tool-selection isolation — all independently re-derived from git history and grep evidence, not just re-read from the doc). Two gaps the design doc itself had flagged as open questions (§7 risks #2 and #4) were real and are fixed here; a third finding (an internal contradiction in the design doc's own §3.2 vs §3.4 text on image-attachment gating — the SHIPPED code was already correct, only the doc's prose disagreed with itself) required no code change.
+- **[0.7.49]** (2026-07-06) — gjc Telegram-daemon parity, Tier 2 (follow-up to 0.7.37/0.7.38/0.7.48's subagent-visibility-only daemon): adds a dynamic, PER-SESSION forum topic that mirrors that session's OWN activity — not just its subagents — and lets a Telegram reply steer it directly. Opt-in via `notifications.telegram.perSessionTopics`; the flat/global `topicId` path from 0.7.48 is UNCHANGED when it's off, so existing setups see zero regression.
 - **[0.7.48]** (2026-07-06) — gjc Telegram-daemon parity, phase 2 (follow-up to 0.7.37/0.7.38's baseline subagent-visibility daemon, which deliberately scoped OUT forum topics, inline keyboards, and image attachments — see that entry): the daemon now speaks gjc's richer notification surface instead of the plain-text-only baseline.
 - **[0.7.47]** (2026-07-06) — PromptRouter (gjc-inspired, jeo-native design — NOT a port of katanemo/plano, whose always-on proxy-orchestrator architecture doesn't fit an interactive CLI's per-turn latency budget): jeo already had static, role-based model mapping (`resolveSubagentModel`/`resolveRoleModel`) but zero logic that varied the model by what THIS turn's prompt actually asks for. Adds an opt-in (default OFF), heuristic-first, fail-open per-turn router: a bilingual regex classifier scores a prompt into trivial/standard/complex, escalating to one cheap LLM call ONLY when the heuristic is genuinely ambiguous (confidence below a configurable threshold — most turns never escalate), and an explicit `/model` pin always wins over routing. No new plumbing: reuses `resolveRoleModel`, `callLlm`, `jsonMode`, `catalogMetadata`, `tryExtractJsonObject`, and the existing `onNotice` transparency pattern.
 - **[0.7.46]** (2026-07-06) — Registry-only correction: `npm publish` packs the working-tree filesystem, not the git commit — a concurrent, unrelated, uncommitted feature-in-progress from another session sharing this checkout (`src/agent/prompt-router.ts`, `src/commands/launch/route-slash.ts`, and edits to `config-schema.ts`/`state.ts`/`launch.ts`/`slash.ts`) was physically present on disk during the 0.7.45 `npm publish` and got bundled into that tarball even though it was never committed to git and is absent from the `0.7.45` git tag/branch. Unpublished `jeo-code@0.7.45` from the registry within minutes (npm then permanently blocks republishing that exact version number, hence the bump to 0.7.46) and republished from a verified-clean working tree (`git stash` of the foreign files, `npm pack --dry-run` confirmed their absence, then restored the stash afterward so the other session's in-progress work was never touched or lost). No functional change versus the intended 0.7.45 content — see that entry below.
-- **[0.7.45]** (2026-07-06) — gjc parity: jeo's subagent `task {tasks:[...]}` fan-out batches now visibly run as PARALLEL processes the way gjc's own task tool does, instead of quietly forcing the mutating executor role to serialize. Two compounding bugs made a batch of independent subagent tasks look and behave sequential even though the read-only roles were already technically concurrent: (1) the executor role's fan-out was hard-coded to concurrency 1 regardless of batch size, and (2) the TUI's live status line tracked ONE shared string clobbered by whichever worker's event landed last — worse, ANY single worker reaching "done" cleared the whole `(sub)` marker even while its siblings were still actively running.
-- **[0.7.44]** (2026-07-06) — Root-caused a real production hang reported from `jeo`'s OpenAI Codex OAuth subagent path: after roughly 20-30 minutes of active streamed traffic, `chatgpt.com`'s backend severs the live SSE connection mid-response (an infra connection-duration cap, not a broken network) and Bun's fetch/undici surfaces it as `Error: The socket connection was closed unexpectedly …`. `retryableStream` (model-manager.ts) only auto-retries losing the FIRST streamed chunk — once any chunk had reached the caller it deliberately stopped retrying (a full re-call would replay already-emitted content) — so this class of drop propagated straight out of the engine as a raw, unretried turn-ending error every time, even though nothing had been committed to history yet and a plain resend is exactly as safe as a fresh call.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.7.48",
+  "version": "0.7.50",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/config-schema.ts

@@ -92,13 +92,27 @@ export const ConfigSchema = z
     notifications: z
       .object({
         enabled: z.boolean().optional(),
+        /** Session-local default notification verbosity; a running session's
+         *  in-memory value (mutable via a `/verbosity` config_command from
+         *  Telegram) starts from this and reverts here on restart. */
+        verbosity: z.enum(["lean", "verbose"]).optional(),
+        /** Session-local default redaction of mirrored turn/context text sent
+         *  to Telegram; same session-local-only mutability as `verbosity`. */
+        redact: z.boolean().optional(),
         telegram: z
           .object({
             botToken: z.string().optional(),
             chatId: z.string().optional(),
             /** Forum-topic thread id (message_thread_id) for supergroups with
-             *  topics enabled — daemon pushes go into this topic. */
+             *  topics enabled — daemon pushes go into this topic. Ignored for a
+             *  session-owned topic when `perSessionTopics` is true. */
             topicId: z.number().optional(),
+            /** Auto-create and manage ONE forum topic per interactive session
+             *  (gjc per-session-thread parity), instead of the single flat/global
+             *  `topicId` above. Requires the paired chat to be a supergroup with
+             *  Topics enabled AND private (fail-closed — see `TopicRegistry`).
+             *  Off by default; existing flat-topic/no-topic setups are unaffected. */
+            perSessionTopics: z.boolean().optional(),
           })
           .optional(),
       })

package/src/agent/notify/AGENTS.md

@@ -1,19 +1,33 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-07-05 -->
+<!-- Generated: 2026-07-06 -->
 
 # notify
 
 ## Purpose
-Remote subagent visibility/control over Telegram (gjc Telegram-daemon parity, scoped to jeo's subagent surface). Supports gjc's richer notification surface: forum topics (`message_thread_id`), inline keyboards (per-subagent ⏹ Cancel buttons + `callback_query` handling), and image attachments (`sendPhoto`, relayed from a session `{type:"photo"}` frame).
+Remote subagent visibility/control AND main-session mirroring over Telegram (gjc parity).
+Tier 1 (shipped v0.7.43–v0.7.48): inline images, a static forum topic, inline keyboards
+(per-subagent ⏹ Cancel buttons + `callback_query` handling), image attachments (`sendPhoto`,
+relayed from a session `{type:"photo"}` frame). Tier 2 (this pass): a dynamic, PER-SESSION
+forum topic (opt-in via `notifications.telegram.perSessionTopics`) that mirrors that session's
+OWN activity (`identity_header`/`context_update`/`turn_stream` frames), accepts free-text
+replies that steer that session directly (`user_message`, routed through `handleRemoteUserMessage`
+in `../../commands/launch.ts`), in-thread `/verbose`/`/lean`/`/redact` config commands scoped to
+that one session, and a shared `RateLimitPool` (burst/steady-rate protection across every
+session sharing one bot token). The flat/global `topicId` path is UNCHANGED when
+`perSessionTopics` is off — zero regression risk for existing setups.
 
 ## Key Files
 | File | Description |
 |------|-------------|
-| `paths.ts` | Path helpers under `<jeoHome>/notifications` (daemon lock/log, per-session discovery files) |
-| `telegram-api.ts` | Minimal, injectable-`fetch` Telegram Bot API client (`getMe`/`sendMessage`/`sendPhoto`/`answerCallbackQuery`/`getUpdates`) + `maskToken`; `sendMessage`/`sendPhoto` accept `messageThreadId` (forum topics) and `replyMarkup` (inline keyboards) |
-| `session-endpoint.ts` | Per-turn, loopback-only WebSocket server exposing ONE `SubagentRegistry` (discovery file + `snapshot`/`steer`/`cancel`/`list` protocol); lazy `ensureSessionNotifyEndpoint`/`stopSessionNotifyEndpoint` wiring, no-op unless `notifications.enabled` |
+| `paths.ts` | Path helpers under `<jeoHome>/notifications` (daemon lock/log, per-session discovery files, `notifyTopicsPath()` for the per-session topic map) |
+| `telegram-api.ts` | Minimal, injectable-`fetch` Telegram Bot API client: `getMe`/`sendMessage`(+`parseMode`)/`sendPhoto`/`answerCallbackQuery`/`getUpdates` (Tier 1) plus `createForumTopic`/`editForumTopic`/`getFile`/`downloadFile`(path-traversal-guarded)/`getChat`/`setMessageReaction` (Tier 2) + `maskToken` |
+| `telegram-html.ts` | Bounded markdown→Telegram-HTML converter (`markdownToTelegramHtml`) + safe truncate/split (`truncateTelegramHtml`/`splitTelegramHtml`, never break a tag/entity) — renders `turn_stream` frames |
+| `topic-registry.ts` | Pure, injectable-create `TopicRegistry`: one forum-topic record per session (numeric `topicId`, rename-dedup via `applyName`), concurrency-guarded `getOrCreateTopic`, serializable state |
+| `rate-limit-pool.ts` | Pure, injectable-clock `RateLimitPool`: token-bucket + 4 priority lanes (`ask`>`finalized`>`live`>`idle`, only `finalized` has a jeo caller today) + per-session round-robin fairness + coalescing |
+| `config-commands.ts` | Pure `parseInThreadConfigCommand`: `/verbose`, `/lean`, `/verbosity lean\|verbose`, `/redact on\|off` — session-local, never persisted |
+| `session-endpoint.ts` | SESSION-scoped (not per-turn) loopback WebSocket server: one per interactive REPL for its whole lifetime, `attachRegistry`/`detachRegistry` swap the live per-turn `SubagentRegistry` in/out at turn boundaries, `sendIdentity`/`sendContextUpdate`/`sendTurnStream` push main-session frames, `onUserMessage`/`onConfigCommand` receive callbacks. `startSessionNotifyEndpoint` (eager, session-scoped) is the primary entrypoint; `ensureSessionNotifyEndpoint`/`stopSessionNotifyEndpoint` (lazy, per-registry) remain as a FALLBACK for a detached subagent launched outside any interactive session |
 | `daemon-control.ts` | Daemon lifecycle: pid+startedAt lock singleton, `daemonInvocation` self-spawn argv (mirrors `memory.ts`'s `distillInvocation`), `startDaemon`/`stopDaemon`/`reloadDaemon`/`daemonStatus` |
-| `telegram-daemon.ts` | The managed daemon (`TelegramDaemon` class + `runNotifyDaemonForeground` CLI entrypoint): scans session discovery files, connects a WS per session, pushes Telegram messages on subagent status EDGES only (with an inline ⏹ Cancel button), and dispatches inbound `/subagents`/`/steer`/`/cancel`/`/help` commands AND inline-button `callback_query` taps back over the matching session's WebSocket. All pushes carry the configured forum `topicId`, and inbound is topic-filtered; a session `{type:"photo"}` frame is relayed via `sendPhoto` |
+| `telegram-daemon.ts` | The managed daemon (`TelegramDaemon` class + `runNotifyDaemonForeground` CLI entrypoint): scans session discovery files, connects a WS per session, routes ALL outbound sends through the shared `RateLimitPool`, resolves each push's topic via `TopicRegistry` when `perSessionTopics` is on (else the flat `topicId`, Tier 1 behavior), renames a topic once `identity_header` arrives, downloads inbound photo/image-document attachments for relay, reacts 👀 to an accepted inbound message, and dispatches global `/subagents`/`/steer`/`/cancel`/`/help` PLUS per-session-topic inbound (config command or free-text `user_message`) |
 
 ## Subdirectories
 *(None)*
@@ -24,24 +38,30 @@ Remote subagent visibility/control over Telegram (gjc Telegram-daemon parity, sc
 - The session-side WebSocket server MUST stay loopback-only (`127.0.0.1`); the daemon-to-Telegram hop is the only internet-facing part of this feature.
 - Every entrypoint here must stay a no-op (or refuse cleanly with a clear message) unless `notifications.enabled` + a stored bot token + chat id are all present — never assume the feature is configured.
 - `daemon-control.ts`'s singleton lock exists because Telegram allows only ONE `getUpdates` long-poll owner per bot token; never bypass it.
+- Telegram has NO live message editing anywhere in this feature — every delivered frame is a fresh `sendMessage`/`sendPhoto` call. `RateLimitPool` coalescing only ever drops a STALE, UNSENT queued item; it never edits an already-sent message.
+- jeo's forum topics are NEVER deleted (unlike gjc) — `sessionId` persists across `--resume`, so a topic, once created, is meant to be reused indefinitely across relaunches of the same session.
+- `session-endpoint.ts`'s constructor is `(cwd, sessionId?)`, NOT `(registry, cwd)` — the registry attaches/detaches after construction via `attachRegistry`/`detachRegistry`, since one endpoint now outlives many per-turn registries.
 
 ### Testing Requirements
-- Prefer real `Bun.serve`/`WebSocket` for `session-endpoint.ts` tests (fast, no mocking needed) and injected fakes (`WebSocketImpl`, `TelegramApi`, `readdir`/`readFile`/`unlink`/`isPidAlive`) for `telegram-daemon.ts`/`daemon-control.ts`.
+- Prefer real `Bun.serve`/`WebSocket` for `session-endpoint.ts` tests (fast, no mocking needed) and injected fakes (`WebSocketImpl`, `TelegramApi`, `readdir`/`readFile`/`unlink`/`isPidAlive`, `loadTopicState`/`saveTopicState`, `writeTempFile`, `now`) for `telegram-daemon.ts`/`daemon-control.ts`.
 - Any test touching `readGlobalConfig`/`saveConfigPatch` must isolate `JEO_CONFIG_DIR` to a temp directory (see `test/notify-daemon-control.test.ts`).
+- `topic-registry.ts`/`rate-limit-pool.ts`/`config-commands.ts`/`telegram-html.ts` are pure — no network/fs/real-timer dependency, test them directly with plain inputs/outputs (inject `now`/`create` callbacks where the API takes them).
 
 ### Common Patterns
 - Dependency injection for network/fs/time so daemon logic is unit-testable without a real bot token or real child processes.
 - Edge-triggered (not level-triggered) status reporting: a message is sent on a TRANSITION, never on every poll tick.
+- Fail-closed, not fail-open, on a per-session topic-creation failure (e.g. Threaded Mode off): the session's frames fall back to the flat/global `topicId` (or drop, if that's also unset) rather than retrying every frame or blocking delivery.
 
 ## Dependencies
 
 ### Internal
 - `../subagent-registry.ts` (`SubagentRegistry`, `SubagentRecord`).
-- `../state.ts` (`readGlobalConfig`/`saveConfigPatch` for `notifications` settings).
-- Consumed by `../task-tool.ts` (`ensureSessionNotifyEndpoint`), `../../commands/launch.ts` (`stopSessionNotifyEndpoint`), `../../commands/notify.ts`, `../../commands/daemon.ts`, and the hidden `notify-daemon-run` CLI entrypoint (`src/cli/runner.ts`).
+- `../state.ts` (`readGlobalConfig`/`saveConfigPatch` for `notifications` settings, incl. `verbosity`/`redact`/`telegram.perSessionTopics`).
+- `../../util/file-attachment.ts` (`attachImagePaths`) — the ONE image-ingestion path a `user_message` frame's `imagePaths` (daemon-downloaded temp files) flows through on the session side, same as local drag-drop.
+- Consumed by `../task-tool.ts` (`ensureSessionNotifyEndpoint`, now also threading an optional `sessionEndpoint` to attach to), `../../commands/launch.ts` (`startSessionNotifyEndpoint` at session start, `stopSessionNotifyEndpoint` fallback, `attachRegistry`/`detachRegistry` per turn, `sendIdentity`/`sendContextUpdate`/`sendTurnStream`, `onUserMessage`/`onConfigCommand` handlers), `../../commands/notify.ts`, `../../commands/daemon.ts`, and the hidden `notify-daemon-run` CLI entrypoint (`src/cli/runner.ts`).
 
 ### External
-- Telegram Bot HTTP API (`https://api.telegram.org`) — the only outbound network call in this feature.
+- Telegram Bot HTTP API (`https://api.telegram.org` for calls, `https://api.telegram.org/file/...` for file downloads — a DIFFERENT base path) — the only outbound network call in this feature.
 - Bun's native `Bun.serve` (WebSocket server) and global `WebSocket` (client) — zero added dependencies.
 
 <!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

package/src/agent/notify/config-commands.ts

@@ -0,0 +1,50 @@
+/**
+ * In-thread configuration slash commands for the per-session Telegram surface
+ * (gjc `notifications/config-commands.ts` parity). A user can adjust how their
+ * OWN session's activity mirrors into its topic without touching global config:
+ *
+ * - `/verbose`            switch the mirror to verbose (full tool output + reasoning)
+ * - `/lean`               switch back to lean (assistant text + tool names only)
+ * - `/verbosity lean|verbose`
+ * - `/redact on|off`      toggle redaction of mirrored turn/context text
+ *
+ * Pure and unit-testable; the daemon maps a returned change onto a
+ * `config_command` frame sent to the owning session's WebSocket. Only reachable
+ * when `notifications.telegram.perSessionTopics` is enabled — the flat/global
+ * `topicId` surface has no per-session settings to change.
+ */
+
+/** A parsed in-thread configuration change. */
+export interface ConfigCommandChange {
+  verbosity?: "lean" | "verbose";
+  redact?: boolean;
+}
+
+/**
+ * Parse an in-thread config command. Returns the requested change, or
+ * `undefined` when the text is not a recognised config command (the daemon
+ * then falls through to treating it as a free-text `user_message`).
+ */
+export function parseInThreadConfigCommand(text: string): ConfigCommandChange | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/")) return undefined;
+  const [rawCommand, ...rest] = trimmed.slice(1).split(/\s+/);
+  const command = rawCommand?.toLowerCase();
+  const arg = rest[0]?.toLowerCase();
+
+  switch (command) {
+    case "verbose":
+      return { verbosity: "verbose" };
+    case "lean":
+      return { verbosity: "lean" };
+    case "verbosity":
+      if (arg === "lean" || arg === "verbose") return { verbosity: arg };
+      return undefined;
+    case "redact":
+      if (arg === "on" || arg === "true" || arg === "1") return { redact: true };
+      if (arg === "off" || arg === "false" || arg === "0") return { redact: false };
+      return undefined;
+    default:
+      return undefined;
+  }
+}

package/src/agent/notify/paths.ts

@@ -30,6 +30,13 @@ export function notifySessionEndpointPath(sessionId: string): string {
   return path.join(notifySessionsDir(), `${sessionId}.json`);
 }
 
+/** Persisted per-session forum-topic map (`sessionId -> {topicId, name, createdAt}`),
+ *  survives daemon restarts (gjc `telegram-topics.json` parity). Only written/read
+ *  when `notifications.telegram.perSessionTopics` is enabled. */
+export function notifyTopicsPath(): string {
+  return path.join(notifyDir(), "telegram-topics.json");
+}
+
 /** Singleton lock for the daemon process (Telegram allows only one `getUpdates`
  *  long-poll owner per bot token — gjc's rationale for a daemon lock/state file). */
 export function notifyDaemonLockPath(): string {

package/src/agent/notify/rate-limit-pool.ts

@@ -0,0 +1,217 @@
+/**
+ * Host-wide shared Telegram rate-limit pool for the threaded session surface
+ * (gjc `RateLimitPool` parity).
+ *
+ * Multiple jeo sessions on one host share a single bot token and paired chat.
+ * Telegram enforces per-bot/per-chat limits (~1 message/sec, bursts up to ~20),
+ * so the singleton notifications daemon owns ONE pool that all per-session
+ * threads draw from. The pool provides:
+ *
+ * - a token bucket (burst capacity + steady refill) modelling the chat limit;
+ * - priority lanes (`ask` > `finalized` > `live` > `idle`) so urgent frames
+ *   win scarce tokens;
+ * - per-session round-robin fairness within a lane so one session's live-edit
+ *   stream cannot starve other sessions;
+ * - coalescing of live edits that share a `coalesceKey` (the latest rendered
+ *   text replaces the queued one) so throttled edit storms collapse.
+ *
+ * The core is a pull-based scheduler with an injectable clock so fairness,
+ * starvation, and burst behaviour are deterministically unit-testable without
+ * real time or a live Bot API.
+ *
+ * Current jeo callers only actually submit to the `"finalized"` lane in
+ * practice (subagent status pushes + main-session `turn_stream`/
+ * `context_update` mirroring). The `"ask"` and `"live"` lanes exist in the
+ * type for architectural completeness/future use — jeo has no `ask` tool
+ * (Tier 3, out of scope) and no incremental token-level stream to mirror yet
+ * (see the Tier 2 contract) — and `"idle"` is likewise unused today. All four
+ * lanes are kept exactly as gjc has them; this is a note about CURRENT
+ * callers, not a scope reduction of the module itself.
+ */
+
+/** Delivery lanes in descending priority. */
+export type RateLimitLane = "ask" | "finalized" | "live" | "idle";
+
+/** Lanes ordered from highest to lowest priority. */
+export const LANE_PRIORITY: readonly RateLimitLane[] = ["ask", "finalized", "live", "idle"];
+
+/** A unit of work competing for a send slot. */
+export interface RateLimitItem<T = unknown> {
+  /** Owning session id (used for per-session fairness). */
+  sessionId: string;
+  /** Priority lane. */
+  lane: RateLimitLane;
+  /**
+   * Optional coalesce key. Submitting another item with the same
+   * `(sessionId, lane, coalesceKey)` replaces the queued payload with the
+   * newer one instead of enqueuing a duplicate (used for live edits).
+   */
+  coalesceKey?: string;
+  /** Opaque payload the caller maps to an actual Telegram send. */
+  payload: T;
+}
+
+/** Options for {@link RateLimitPool}. */
+export interface RateLimitPoolOptions {
+  /** Burst capacity (max tokens). Default 20 (Telegram per-chat burst). */
+  capacity?: number;
+  /** Steady refill rate in tokens per second. Default 1 (~1 msg/sec/chat). */
+  refillPerSec?: number;
+  /** Injectable clock in ms. Default `Date.now`. */
+  now?: () => number;
+}
+
+interface QueuedItem<T> {
+  item: RateLimitItem<T>;
+  seq: number;
+}
+
+/** Build a fixed lookup table with one entry per priority lane (lanes are a
+ *  small, static, never-added-to-at-runtime key set — a plain `Record` avoids
+ *  the `Map` overhead/API surface this scheduler never needs). */
+function createLaneRecord<V>(factory: () => V): Record<RateLimitLane, V> {
+  const record = {} as Record<RateLimitLane, V>;
+  for (const lane of LANE_PRIORITY) record[lane] = factory();
+  return record;
+}
+
+/**
+ * A deterministic, pull-based shared rate-limit scheduler.
+ *
+ * Callers {@link RateLimitPool.submit} work and periodically
+ * {@link RateLimitPool.drain} (e.g. on a timer or after each submit); `drain`
+ * returns the items granted a send slot, in the order they should be sent.
+ */
+export class RateLimitPool<T = unknown> {
+  private readonly capacity: number;
+  private readonly refillPerSec: number;
+  private readonly now: () => number;
+
+  /** Per-lane FIFO queues; each lane holds items across sessions. */
+  private readonly lanes: Record<RateLimitLane, QueuedItem<T>[]>;
+  /** Rotating session cursor per lane for round-robin fairness. */
+  private readonly laneCursor: Record<RateLimitLane, number> = createLaneRecord(() => 0);
+
+  private tokens: number;
+  private lastRefill: number;
+  private seqCounter = 0;
+
+  constructor(options: RateLimitPoolOptions = {}) {
+    this.capacity = Math.max(1, options.capacity ?? 20);
+    this.refillPerSec = Math.max(0, options.refillPerSec ?? 1);
+    this.now = options.now ?? Date.now;
+    this.tokens = this.capacity;
+    this.lastRefill = this.now();
+    this.lanes = createLaneRecord<QueuedItem<T>[]>(() => []);
+  }
+
+  /** Number of items currently queued across all lanes. */
+  get pending(): number {
+    let total = 0;
+    for (const lane of LANE_PRIORITY) total += this.lanes[lane].length;
+    return total;
+  }
+
+  /** Current available token count (after refill at `now`). */
+  availableTokens(nowMs: number = this.now()): number {
+    this.refill(nowMs);
+    return this.tokens;
+  }
+
+  /**
+   * Submit an item. If it carries a `coalesceKey` matching a queued item in
+   * the same `(sessionId, lane)`, the queued payload is replaced (latest
+   * wins) and FIFO position is preserved; otherwise it is appended.
+   */
+  submit(item: RateLimitItem<T>): void {
+    const queue = this.lanes[item.lane];
+    if (!queue) throw new Error(`unknown rate-limit lane: ${item.lane}`);
+    if (item.coalesceKey !== undefined) {
+      const existing = queue.find(
+        q => q.item.sessionId === item.sessionId && q.item.coalesceKey === item.coalesceKey,
+      );
+      if (existing) {
+        existing.item = item;
+        return;
+      }
+    }
+    queue.push({ item, seq: this.seqCounter++ });
+  }
+
+  /**
+   * Grant as many queued items as tokens allow at `nowMs`. Items are selected
+   * by lane priority, then round-robin across sessions within a lane (so no
+   * single session monopolises a lane), consuming one token each.
+   */
+  drain(nowMs: number = this.now()): RateLimitItem<T>[] {
+    this.refill(nowMs);
+    const granted: RateLimitItem<T>[] = [];
+    while (this.tokens >= 1) {
+      const next = this.takeNext();
+      if (!next) break;
+      this.tokens -= 1;
+      granted.push(next);
+    }
+    return granted;
+  }
+
+  /** Remove queued items matching `predicate` without consuming tokens. Returns removed items in lane/FIFO order. */
+  removeWhere(predicate: (item: RateLimitItem<T>) => boolean): RateLimitItem<T>[] {
+    const removed: RateLimitItem<T>[] = [];
+    for (const lane of LANE_PRIORITY) {
+      const queue = this.lanes[lane];
+      let write = 0;
+      for (let read = 0; read < queue.length; read++) {
+        const queued = queue[read]!;
+        if (predicate(queued.item)) {
+          removed.push(queued.item);
+        } else {
+          queue[write++] = queued;
+        }
+      }
+      queue.length = write;
+    }
+    return removed;
+  }
+
+  private refill(nowMs: number): void {
+    if (nowMs <= this.lastRefill) return;
+    const elapsedSec = (nowMs - this.lastRefill) / 1000;
+    this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillPerSec);
+    this.lastRefill = nowMs;
+  }
+
+  /** Pop the next item by lane priority + per-session round-robin fairness. */
+  private takeNext(): RateLimitItem<T> | undefined {
+    for (const lane of LANE_PRIORITY) {
+      const queue = this.lanes[lane];
+      if (queue.length === 0) continue;
+      const picked = this.pickFairIndex(lane, queue);
+      const [removed] = queue.splice(picked, 1);
+      return removed?.item;
+    }
+    return undefined;
+  }
+
+  /**
+   * Choose the index to serve from a lane queue using round-robin over the
+   * distinct session ids present, starting just after the last-served
+   * session. Falls back to FIFO (index 0) when only one session is queued.
+   */
+  private pickFairIndex(lane: RateLimitLane, queue: QueuedItem<T>[]): number {
+    const sessions: string[] = [];
+    for (const q of queue) if (!sessions.includes(q.item.sessionId)) sessions.push(q.item.sessionId);
+    if (sessions.length <= 1) return 0;
+    const cursor = this.laneCursor[lane];
+    // Choose the earliest-queued item whose session is the next in rotation.
+    for (let offset = 0; offset < sessions.length; offset++) {
+      const candidate = sessions[(cursor + offset) % sessions.length]!;
+      const idx = queue.findIndex(q => q.item.sessionId === candidate);
+      if (idx >= 0) {
+        this.laneCursor[lane] = (cursor + offset + 1) % sessions.length;
+        return idx;
+      }
+    }
+    return 0;
+  }
+}