#17132: fix: filter out invalid session entries with empty sessionFile
channel: telegram
gateway
scripts
commands
stale
size: S
Cluster:
Session Management Enhancements
Fixes #17107
## Problem
In multi-agent setups, `sessions.json` files accumulate entries with empty `sessionFile` values (especially from isolated cron jobs). When processing messages, these cause:
```
Error: Session file path must be within sessions directory
```
This freezes Telegram message delivery - agents process internally but replies never reach the user.
## Root Cause
The path validation in `resolveSessionFilePath` throws when `sessionFile` is empty, null, or an absolute path. Stale entries accumulate over time.
## Solution
Filter out invalid session entries during store loading:
- Empty `sessionFile`
- `sessionFile` starting with `..` (escape attempt)
- `sessionFile` starting with `/` (absolute path)
## Impact
- Gateway no longer crashes on stale session entries
- Telegram delivery works even with corrupted sessions.json
- Auto-cleanup of invalid entries on next gateway start
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Fixes issue #17107 where invalid session entries with empty `sessionFile` values caused gateway crashes with "Session file path must be within sessions directory" errors, blocking Telegram message delivery.
**Key Changes:**
- **src/config/sessions/store.ts**: Added filtering during session store loading to remove entries with empty, `..`-prefixed, or absolute path `sessionFile` values (lines 180-212)
- **src/auto-reply/reply/session.ts**: Preserved `responseUsage` setting across session resets (similar to existing `ttsAuto`, `verboseLevel` preservation)
- **src/telegram/bot-message-context.ts**: Fixed variable declaration order - moved `preflightTranscript` declaration before usage, and extended audio transcription to all DM voice messages (not just group mentions)
- **src/gateway/server/ws-connection/message-handler.ts**: Added default `operator.read` scope for Control UI and webchat when using token-only auth
- **src/commands/status.command.ts**: Added `.catch(() => undefined)` to gracefully handle gateway unreachable errors
- **scripts/shell-helpers/clawdock-helpers.sh**: Support for optional extra docker compose file
**Impact:** Gateway no longer crashes on stale session entries, enabling auto-cleanup on next start. The filtering provides defense-in-depth alongside existing path validation in `resolvePathWithinSessionsDir()`.
<h3>Confidence Score: 4/5</h3>
- Safe to merge with minor improvement opportunity
- The PR effectively solves the stated problem with a defense-in-depth approach. The session store filtering prevents crashes from invalid entries, while existing validation in `resolvePathWithinSessionsDir()` provides comprehensive path security. Other changes (responseUsage preservation, Telegram transcription fix, gateway scope defaults) are incremental improvements with low risk. One minor suggestion: using `path.isAbsolute()` would be more robust for cross-platform absolute path detection, though the current implementation works in conjunction with downstream validation.
- No files require special attention - all changes are incremental bug fixes
<sub>Last reviewed commit: f751103</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#15888: fix: store relative session file paths instead of absolute
by devAnon89 · 2026-02-14
85.9%
#16061: fix(sessions): tolerate invalid sessionFile metadata
by haoyifan · 2026-02-14
85.7%
#15684: fix(telegram): persist relative session transcript paths
by Jdo300 · 2026-02-13
82.4%
#15176: fix(sessions): allow channel-routed session IDs and cross-agent paths
by cathrynlavery · 2026-02-13
82.2%
#20336: fix(sessions): resolve transcriptPath using agentId when storePath ...
by Limitless2023 · 2026-02-18
80.7%
#20431: fix(sessions): add session contamination guards and self-leak lock ...
by marcomarandiz · 2026-02-18
80.6%
#4664: fix: per-session metadata files to eliminate lock contention
by tsukhani · 2026-01-30
80.0%
#22469: fix(gateway): avoid stale whatsapp labels on direct sessions
by loganprit · 2026-02-21
80.0%
#15744: fix: allow cross-agent session path validation
by scottgl9 · 2026-02-13
79.9%
#3410: fix(sessions): always compute session paths from current environment
by sakunsylvi · 2026-01-28
79.9%