fix telegram html send failures and harden docker rebuild fingerprinting

Author: Traves-Theberge

CHANGELOG.md

@@ -11,6 +11,7 @@ All notable changes to this project are documented in this file.
 ### Added
 
 - Deterministic Docker redeploy script: `scripts/docker-redeploy.sh` (`npm run docker:redeploy`).
+  - now auto-stamps `OPENCODE_REMOTE_BUILD_ID` from git short SHA + timestamp when not explicitly set.
 - Runtime fingerprint logging at startup (version/build-id/token fingerprint/mode summary).
 - Polling recovery diagnostics in status surfaces:
   - reset cooldown timing
@@ -134,6 +135,7 @@ All notable changes to this project are documented in this file.
 - Telegram polling conflict owner alerts are now cooldown-limited to reduce repeated notification spam.
 - Telegram polling startup now prepares session state (`deleteWebhook` + `close` with retry-after-aware cooldown handling).
 - Polling loop now enforces single in-flight cycle to avoid overlap and improve conflict stability.
+- Telegram outbound message send now escapes HTML entities before `parse_mode=HTML` delivery to prevent `can't parse entities` send failures.
 - Runtime `/status` output now includes transport health and polling conflict recovery timing.
 - SQLite schema now includes transport lease support (`transport_leases`) to protect polling ownership on shared DB deployments.
 - Webhook mode now fails fast unless `telegram.webhookSecret` is configured.

README.md

@@ -86,6 +86,7 @@ docker compose logs -f remote
 ```
 
 This redeploy command forces a no-cache image build and container recreate so Docker always runs the latest source changes.
+It also stamps each build with `OPENCODE_REMOTE_BUILD_ID` (git short SHA + timestamp by default) for runtime fingerprint verification.
 
 Webhook-first production profile:
 

docs/OPERATIONS.md

@@ -96,6 +96,7 @@ npm run docker:redeploy
 ```
 
 This performs a no-cache image rebuild and force-recreates the `remote` service to prevent stale code/image mismatches.
+By default it sets `OPENCODE_REMOTE_BUILD_ID` to `git-short-sha + timestamp` so startup fingerprint logs prove which build is running.
 
 ## Initial Provisioning
 

scripts/docker-redeploy.sh

@@ -4,6 +4,17 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT_DIR"
 
+if [[ -z "${OPENCODE_REMOTE_BUILD_ID:-}" ]]; then
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    OPENCODE_REMOTE_BUILD_ID="$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"
+  else
+    OPENCODE_REMOTE_BUILD_ID="local-$(date +%Y%m%d%H%M%S)"
+  fi
+fi
+export OPENCODE_REMOTE_BUILD_ID
+
+echo "[redeploy] Using build id: ${OPENCODE_REMOTE_BUILD_ID}"
+
 echo "[redeploy] Building compose service image (no cache)..."
 docker compose build --no-cache remote
 

src/transport/telegram.ts

@@ -553,7 +553,8 @@ export class TelegramTransport {
       return;
     }
 
-    const chunks = this.chunkMessage(String(text || ''), 4096);
+    const escaped = this.escapeHtml(String(text || ''));
+    const chunks = this.chunkMessage(escaped, 4096);
     for (const chunk of chunks) {
       await this.api('sendMessage', {
         chat_id: chatId,
@@ -587,6 +588,13 @@ export class TelegramTransport {
     return chunks;
   }
 
+  escapeHtml(text: string): string {
+    return String(text || '')
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
   async moveToDeadLetter(update: TelegramUpdate, error: unknown, attempts: number) {
     const sender =
       String(update?.message?.from?.id || update?.callback_query?.from?.id || '') || null;

tests/telegram.test.ts

@@ -139,6 +139,14 @@ test('normalizes plain telegram shorthand to slash commands', () => {
   assert.equal(transport.normalizeBody('help'), '/help');
 });
 
+test('escapes html entities for telegram html parse mode', () => {
+  const transport = new TelegramTransportStub(async () => null);
+  assert.equal(
+    transport.escapeHtml('Run: <runId> & <status>'),
+    'Run: &lt;runId&gt; &amp; &lt;status&gt;',
+  );
+});
+
 test('polling loop does not overlap concurrent getUpdates requests', async () => {
   class PollingProbe extends TelegramTransport {
     current = 0;