[bug] Telegram bridge fails with session file lock error — "Agent exited with code 255"

[arun-gupta]

Description

Expected behavior

The Telegram bridge forwards the message to the OpenClaw agent and returns a response.

Actual behavior

The bot shows "typing..." briefly then returns:

Agent exited with code 255. (node:13471) [UNDICI-EHPA] Warning: EnvHttpProxyAgent is experimental, expect them to change at any time.

May be related to #93

Reproduction Steps

Steps to reproduce

1. Complete nemoclaw onboard and connect sandbox
2. Set TELEGRAM_BOT_TOKEN and NVIDIA_API_KEY and run nemoclaw start
3. Send a message to the bot on Telegram

Environment

Environment

• NemoClaw: v0.1.0
• OpenShell: 0.0.14
• macOS: Apple M4 Pro (arm64)
• Container runtime: Docker Desktop
• OpenClaw: 2026.3.11 (29dc654)

Debug Output

Root cause
  Running the bridge's SSH command manually reproduces the failure:

  [diagnostic] lane task error: lane=main durationMs=10611 error="Error: session file locked (timeout 10000ms):
  pid=13485 /sandbox/.openclaw-data/agents/main/sessions/80799eb6-d591-4ab1-8738-e6e834477759.jsonl.lock"
  FailoverError: session file locked (timeout 10000ms): pid=13485
  /sandbox/.openclaw-data/agents/main/sessions/80799eb6-d591-4ab1-8738-e6e834477759.jsonl.lock

  The session file is locked by a previous openclaw agent process. The bridge fires a new SSH call before the
  prior one has released the lock, causing all subsequent calls to fail.

  Workaround
  Remove the stale lock file inside the sandbox:

  nemoclaw my-nemoclaw connect
  rm /sandbox/.openclaw-data/agents/main/sessions/*.lock

  Suggested fix
  The bridge should either queue messages and wait for the previous call to complete before spawning a new one,
  or use unique per-request session IDs to avoid lock contention.

Logs

Checklist

• I confirmed this bug is reproducible
• I searched existing issues and this is not a duplicate

[wscurran]

✨ Thanks for submitting this issue with a detailed summary, it addresses a bug with the Telegram bridge failing with a session file lock error, which could be related to the Telegram integration or session management.

---

Possibly related open PRs: #862 fix: auto-reset telegram bridge session after lock failure, #860 fix: queue telegram bridge messages per chat to prevent session lock contention, #865 fix(security): add rate limiting to Telegram bridge

[dknos]

Workaround: clear stale lock files at startup

We hit this constantly after restarts. The fix is to delete all .lock files from the sessions directory before the bridge starts. We do this in our startup script via SSH into the sandbox:

SANDBOX="my-assistant"
SSH_CONF=$(mktemp /tmp/nemoclaw-start-XXXXXX.conf)
openshell sandbox ssh-config "$SANDBOX" > "$SSH_CONF"
ssh -T -F "$SSH_CONF" "openshell-${SANDBOX}" \
  'find /sandbox/.openclaw-data -name "*.lock" -delete 2>/dev/null; echo "locks cleared"'
rm -f "$SSH_CONF"

Run this before starting the bridge on every boot. The lock files are stale after any crash or restart and the bridge won't clear them itself — it just fails with exit code 255. Doing this at startup has eliminated the "session file locked" errors for us entirely.

Also worth noting: the lock path in the error message (/sandbox/.openclaw-data/agents/main/sessions/*.lock) is slightly different from /sandbox/.openclaw-data/agents/main/sessions/*.jsonl.lock — the find glob above catches both patterns.