polygram 0.10.0-rc.40 → 0.10.0-rc.42

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.40",
+  "version": "0.10.0-rc.42",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/process/hook-event-tail.js

@@ -121,15 +121,26 @@ function pipeHookParser(tail) {
 
 /**
  * One-shot helper: build a LogTail at the given path with the
- * H1-typical config (watch mode, no skipExisting because a fresh
- * spawn's ndjson is empty), wire the hook parser, and return it.
- * Caller calls `.start()` and `.on('event', ...)`.
+ * H1-typical config (watch mode), wire the hook parser, and return
+ * it. Caller calls `.start()` and `.on('event', ...)`.
+ *
+ * `skipExisting`:
+ *   - false (default) for a FRESH spawn — the ndjson was just
+ *     touched at start time and is empty, so any future write IS a
+ *     new event.
+ *   - true for a `--resume` spawn — `writeHookFiles` uses 'a' mode
+ *     (append) and never truncates, so the prior session's hook
+ *     events are still on disk. Without skipExisting they replay
+ *     into the fresh process, arming a Stop synth against the
+ *     fresh turn (H4) and heartbeating it (H3) from stale events.
+ *     rc.42 #5 (review-driven): mirror what `_armSessionLogTail`
+ *     already does for the JSONL tail.
  */
-function createHookTail({ path: filePath, logger = console } = {}) {
+function createHookTail({ path: filePath, skipExisting = false, logger = console } = {}) {
   const tail = new LogTail({
     path: filePath,
     intervalMs: 50,
-    skipExisting: false,
+    skipExisting,
     useWatch: 'auto',
     logger,
   });

package/lib/process/tmux-process.js

@@ -202,6 +202,14 @@ const DEFAULT_QUIESCE_MS       = 500; // require READY for this long before decl
 //                              wedge-detection delay is bounded.
 const DEFAULT_HARD_BACKSTOP_MS = 4 * 60 * 60_000;     // 4 hours
 const IDLE_POLL_INTERVAL_MS    = 30_000;              // 30 s
+// 0.10.0 H4 — `Stop` hook as authoritative turn-done.
+//   The Stop hook fires when claude finishes responding — same
+//   semantic as the JSONL `result` event. Both should land within
+//   ms of each other; this grace gives JSONL a chance to win (full
+//   result data: subtype, stopReason, all the metadata) before the
+//   Stop hook synthesizes a fallback settle. If the JSONL stream is
+//   broken or stuck, Stop carries the turn to completion alone.
+const DEFAULT_STOP_GRACE_MS    = 2_000;               // 2 s
 
 // B8 (slow-MCP readiness): how long the claude `--debug-file` log must
 // have had NO new bytes appended before the startup is considered
@@ -251,6 +259,7 @@ class TmuxProcess extends Process {
     readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS,
     turnTimeoutMs = DEFAULT_TURN_TIMEOUT_MS,
     hardBackstopMs = DEFAULT_HARD_BACKSTOP_MS,
+    stopGraceMs = DEFAULT_STOP_GRACE_MS,
     pollMs = DEFAULT_POLL_MS,
     quiesceMs = DEFAULT_QUIESCE_MS,
     lateGraceMs = 1500,
@@ -293,8 +302,25 @@ class TmuxProcess extends Process {
 
     // Tunables
     this.readyTimeoutMs = readyTimeoutMs;
+    // rc.42 #7 (review-driven): validate timer config at construction
+    // so a misconfigured process fails loud here instead of silently
+    // mid-turn (NaN → setInterval ≈1 ms spin; 0/negative → instant
+    // idle-timeout).
+    for (const [name, v] of [
+      ['turnTimeoutMs', turnTimeoutMs],
+      ['hardBackstopMs', hardBackstopMs],
+      ['stopGraceMs', stopGraceMs],
+    ]) {
+      if (!Number.isFinite(v) || v < 0) {
+        throw Object.assign(
+          new TypeError(`TmuxProcess: ${name} must be a finite non-negative number (got ${v})`),
+          { code: 'TMUX_INVALID_TIMEOUT_CONFIG', field: name, value: v },
+        );
+      }
+    }
     this.turnTimeoutMs = turnTimeoutMs;
     this.hardBackstopMs = hardBackstopMs;
+    this.stopGraceMs = stopGraceMs;
     this.pollMs = pollMs;
     this.quiesceMs = quiesceMs;
     this.readyDebugQuietMs = readyDebugQuietMs;
@@ -635,8 +661,10 @@ class TmuxProcess extends Process {
         this._armSessionLogTail({ resuming: Boolean(ctx.existingSessionId) });
         // H1 — same-pattern hook tail. Only arm when the settings
         // write succeeded above (otherwise there's nothing to tail).
+        // rc.42 #5: on `--resume`, pass skipExisting through so
+        // prior-process hook events aren't replayed into this turn.
         if (this._hookNdjsonPath) {
-          this._armHookTail();
+          this._armHookTail({ resuming: Boolean(ctx.existingSessionId) });
         }
 
         // G6 — block until TUI is responsive.
@@ -767,7 +795,22 @@ class TmuxProcess extends Process {
     this.inFlight = true;
     turn.state = 'pasted';
     turn.startedAt = this._now();
-    const turnTimeoutMs = turn.opts.timeoutMs || this.turnTimeoutMs;
+    // rc.42 #7 (review-driven): validate the resolved turnTimeoutMs.
+    // NaN would coerce setInterval cadence to ≈1 ms (spin-loop);
+    // 0 or negative would trip the idle-ceiling on the first poll.
+    // Neither is reachable via current defaults, but a config override
+    // can produce them. Fall back to the instance default (already
+    // validated as a finite positive number at construction time).
+    const rawTimeoutMs = turn.opts.timeoutMs || this.turnTimeoutMs;
+    const turnTimeoutMs = (Number.isFinite(rawTimeoutMs) && rawTimeoutMs > 0)
+      ? rawTimeoutMs
+      : this.turnTimeoutMs;
+    if (turnTimeoutMs !== rawTimeoutMs) {
+      this.logger.warn?.(
+        `[${this.label}] invalid turn timeoutMs (${rawTimeoutMs}); `
+        + `falling back to ${turnTimeoutMs} ms`,
+      );
+    }
     // Internal turn-done signal — settled by _flushActiveGroup when
     // this turn's group is flushed on a terminal `result`.
     turn.resultPromise = new Promise((resolve) => { turn.settleResult = resolve; });
@@ -835,15 +878,46 @@ class TmuxProcess extends Process {
       //                   outstanding (subsumes B10 — capture can no
       //                   longer settle a turn mid-subagent, so the old
       //                   nested re-wait is unnecessary)
-      //   - timeout     : W1 absolute deadline (one setTimeout, not a
-      //                   racer)
+      //   - timeout     : EITHER idle-ceiling poller (#5a) OR
+      //                   hard-backstop setTimeout (#5b) — see H3
+      //                   in `_awaitSettle`. The `reason` field on
+      //                   the outcome carries which racer fired so
+      //                   operators can distinguish a wedged-silent
+      //                   turn (idle-ceiling) from a 4-hour runaway
+      //                   tool loop (hard-backstop).
       const outcome = await this._awaitSettle(turn, { turnTimeoutMs, confirmP });
 
       if (outcome.kind === 'submit-fail') throw outcome.err;
       if (outcome.kind === 'timeout') {
+        // rc.42 #1 (review-driven): thread the racer-specific
+        // `reason` + observed `idleMs` onto the thrown Error AND
+        // emit a `turn-timeout` event (mirrors sdk-process.js's
+        // pattern at line 532) so the events DB records WHICH
+        // racer fired. Pre-rc.42 the diagnostic value of H3 was
+        // silently dropped — operators couldn't distinguish a
+        // wedged-silent subagent (idle-ceiling) from a 4-hour
+        // runaway tool loop (hard-backstop).
+        this.logger.warn?.(
+          `[${this.label}] turn timeout (${outcome.reason || 'unknown'}`
+          + `${outcome.idleMs != null ? `, idle ${Math.round(outcome.idleMs)} ms` : ''})`,
+        );
+        this.emit('turn-timeout', {
+          turnId: turn.turnId,
+          reason: outcome.reason || null,
+          idleMs: outcome.idleMs ?? null,
+          turnTimeoutMs,
+          hardBackstopMs: this.hardBackstopMs,
+          sessionId: this.claudeSessionId,
+          backend: 'tmux',
+        });
         throw Object.assign(
           new Error('TmuxProcess: turn did not complete in time'),
-          { code: 'TMUX_TURN_TIMEOUT', tmuxName: this.tmuxName },
+          {
+            code: 'TMUX_TURN_TIMEOUT',
+            tmuxName: this.tmuxName,
+            reason: outcome.reason || null,
+            idleMs: outcome.idleMs ?? null,
+          },
         );
       }
 
@@ -867,6 +941,20 @@ class TmuxProcess extends Process {
         resultSubtype = outcome.ev.subtype || 'success';
         stopReason = outcome.ev.stopReason || null;
         if (outcome.ev.sessionId) this.claudeSessionId = outcome.ev.sessionId;
+        // rc.42 #15 (review-driven): if the settle came via the H4
+        // Stop-hook synth (not the JSONL `result`), surface that
+        // distinction. Track it on `resolvedVia` so the result event
+        // downstream consumers see the provenance, and emit a
+        // `stop-hook-resolved` event for forensic count of how often
+        // Stop actually rescued a JSONL-stuck turn.
+        if (outcome.ev.via === 'stop-hook') {
+          resolvedVia = 'stop-hook';
+          this.emit('stop-hook-resolved', {
+            turnId: turn.turnId,
+            sessionId: this.claudeSessionId,
+            backend: 'tmux',
+          });
+        }
         // R10: a genuinely-empty terminal `result` — end_turn, no
         // reply text, AND no tool ran this turn — is the agent
         // producing literally nothing (a thinking-only terminal
@@ -1038,7 +1126,12 @@ class TmuxProcess extends Process {
    *                                TMUX_SUBMIT_FAILED (B7)
    *   { kind: 'quiesced' }       — capture-pane idle AND the predicate
    *                                says it is SAFE to conclude
-   *   { kind: 'timeout' }        — W1 absolute deadline
+   *   { kind: 'timeout',
+   *     reason: 'idle-ceiling'    — H3 idle-poller (#5a)
+   *           | 'hard-backstop'   — H3 absolute backstop (#5b)
+   *           | 'idle-poller-error' — defensive: throw inside the
+   *                                   idle-poller callback (rc.42 #3)
+   *     idleMs? }                 — observed idle for idle-ceiling
    *
    * The structural win over the old race:
    *   - B7 gate: capture quiescence is ignored until
@@ -1139,9 +1232,21 @@ class TmuxProcess extends Process {
         Math.min(IDLE_POLL_INTERVAL_MS, Math.floor(turnTimeoutMs / 4)),
       );
       idlePoller = setInterval(() => {
-        const idleMs = this._now() - turn.lastActivityAt;
-        if (idleMs >= turnTimeoutMs) {
-          finish({ kind: 'timeout', reason: 'idle-ceiling', idleMs });
+        // rc.42 #3 (review-driven): try/catch around the body.
+        // Adaptive poll cadence can fire as often as every 50 ms;
+        // a repeating throw here would trip process-guard's
+        // 100-in-5s sliding-window panicExit(2) and kill the
+        // daemon. Catch + finish-on-error fails fast instead.
+        try {
+          const idleMs = this._now() - turn.lastActivityAt;
+          if (idleMs >= turnTimeoutMs) {
+            finish({ kind: 'timeout', reason: 'idle-ceiling', idleMs });
+          }
+        } catch (err) {
+          this.logger.warn?.(
+            `[${this.label}] idle-poller error: ${err.message}`,
+          );
+          finish({ kind: 'timeout', reason: 'idle-poller-error' });
         }
       }, pollIntervalMs);
       idlePoller.unref?.();
@@ -1154,10 +1259,19 @@ class TmuxProcess extends Process {
       //     from turn start.
       const backstopRemaining = Math.max(
         0, (turn.startedAt + this.hardBackstopMs) - this._now());
-      hardBackstopTimer = setTimeout(
-        () => finish({ kind: 'timeout', reason: 'hard-backstop' }),
-        backstopRemaining,
-      );
+      // rc.42 #3 (review-driven): try/catch in the one-shot
+      // setTimeout callback. Symmetric with the idle-poller +
+      // Stop-synth fixes — protects against any future change
+      // that introduces a throw surface here.
+      hardBackstopTimer = setTimeout(() => {
+        try {
+          finish({ kind: 'timeout', reason: 'hard-backstop' });
+        } catch (err) {
+          this.logger.warn?.(
+            `[${this.label}] hard-backstop error: ${err.message}`,
+          );
+        }
+      }, backstopRemaining);
       hardBackstopTimer.unref?.();
     });
   }
@@ -1178,6 +1292,15 @@ class TmuxProcess extends Process {
     // rejects in `_runTurn`, never resolving `resultPromise`) would
     // otherwise leave a dangling Map entry. Defensive + cheap.
     if (turn?.token) this._submitConfirms.delete(turn.token);
+    // rc.42 #6 (review-driven): clear the H4 Stop-synth setTimeout
+    // when the turn retires through any other path. Idempotency
+    // makes a post-retirement settleResult call harmless, but the
+    // timer handle would otherwise sit in the event loop for up to
+    // `stopGraceMs` past the turn's death.
+    if (turn?._stopSynthTimer) {
+      clearTimeout(turn._stopSynthTimer);
+      turn._stopSynthTimer = null;
+    }
     const qi = this.pendingQueue.indexOf(turn);
     if (qi >= 0) this.pendingQueue.splice(qi, 1);
     this._dropFromActiveGroup(turn);
@@ -1585,23 +1708,43 @@ class TmuxProcess extends Process {
    *
    * See docs/0.10.0-tmux-hook-observability.md.
    */
-  _armHookTail() {
+  _armHookTail({ resuming = false } = {}) {
     if (this._hookTail) return; // idempotent
     if (!this._hookNdjsonPath) {
       this.logger.warn?.(`[${this.label}] _armHookTail: no ndjson path, skipping`);
       return;
     }
-    const tail = createHookTail({ path: this._hookNdjsonPath, logger: this.logger });
+    // rc.42 #5 (review-driven): on `--resume`, the per-session hook
+    // ndjson kept by `writeHookFiles` (opened in append mode) still
+    // carries the prior process's events. `skipExisting:true`
+    // mirrors `_armSessionLogTail`'s handling so historic Stop
+    // events don't replay into the fresh turn (would arm a synth
+    // settle on a freshly-pasted prompt with stale text) and stale
+    // heartbeats don't reset the new turn's idle clock.
+    const tail = createHookTail({
+      path: this._hookNdjsonPath,
+      skipExisting: resuming,
+      logger: this.logger,
+    });
     tail.on('event', (ev) => this._handleHookEvent(ev));
     tail.on('error', (err) => {
       this.logger.warn?.(`[${this.label}] hook-tail error: ${err.message}`);
+      // rc.42 #8 (review-driven): make the tail-degradation
+      // observable so msg-884-shaped silent regressions surface in
+      // the events DB instead of just the daemon log.
+      this.emit('hook-tail-error', {
+        message: err.message,
+        path: this._hookNdjsonPath,
+        sessionId: this.claudeSessionId,
+        backend: 'tmux',
+      });
     });
     tail.start();
     this._hookTail = tail;
   }
 
   /**
-   * Hook-event handler. Three roles, layered over time:
+   * Hook-event handler. Four roles, layered over time:
    *
    *   H1 (rc.36) — emit `hook-event` so polygram persists each event
    *     to the events DB; observer-only.
@@ -1615,25 +1758,107 @@ class TmuxProcess extends Process {
    *     the structural fix for the msg-884 incident (49-min
    *     SoundCloud subagent killed at the 30-min wall-clock while
    *     demonstrably alive).
-   *
-   *   H4 — `Stop` as authoritative completion (still pending).
+   *   H4 (rc.41) — `Stop` hook is an authoritative turn-done signal.
+   *     If JSONL `result` doesn't fire within `stopGraceMs`,
+   *     synthesize a settle from the Stop payload so a broken or
+   *     stuck JSONL stream can't strand a finished turn. Promise-
+   *     resolve idempotency means JSONL still wins when both fire.
    *
    * Parse errors and unknown event shapes are intentionally still
    * forwarded — observer-only metrics for stream-reliability soak.
    */
   _handleHookEvent(ev) {
-    // H3: every hook event (except the diagnostic types) is liveness
-    // evidence. Heartbeat every turn in the active group so the
-    // idle-ceiling poller resets. We don't differentiate by event
-    // type — even Notification or UserPromptSubmit prove claude is
-    // active in this session.
-    if (ev?.type && ev.type !== 'parse-error' && ev.type !== 'unknown') {
-      const turns = this._activeGroup?.turns || [];
-      for (const t of turns) {
-        this._heartbeat(t, `hook:${ev.type}`);
+    // rc.42 #2 (review-driven): wrap the whole body in try/catch.
+    // pipeHookParser emits 'event' synchronously inside LogTail's
+    // `for (const line of parts)` loop in _readNew; a throw here
+    // would propagate back into that loop AFTER _offset is already
+    // advanced past the unread lines, silently dropping every
+    // remaining line in the batch. With H3 making hook events
+    // load-bearing for liveness, lost events cause false idle
+    // timeouts. Catch + warn + continue keeps the rest of the
+    // batch flowing.
+    try {
+      // H3: every hook event (except the diagnostic types) is liveness
+      // evidence. Heartbeat every turn we can identify as in-flight so
+      // the idle-ceiling poller resets. We don't differentiate by event
+      // type — even Notification or UserPromptSubmit prove claude is
+      // active in this session.
+      //
+      // Two scopes are searched (deduped via Set): active group turns
+      // (the steady state once `user-message` has landed) AND the
+      // pendingQueue head (the PRE-active window between turn start
+      // and the first `user-message`). Hook events can fire in either
+      // window — e.g. `UserPromptSubmit` arrives just after claude
+      // receives the paste but BEFORE the `user-message` is echoed
+      // back into the JSONL. Without the pendingQueue fallback, that
+      // window leaves the turn un-heartbeated and the idle poller
+      // could fire on a turn that's actively starting up.
+      if (ev?.type && ev.type !== 'parse-error' && ev.type !== 'unknown') {
+        const turns = new Set(this._activeGroup?.turns || []);
+        const head = this.pendingQueue[0];
+        if (head) turns.add(head);
+        for (const t of turns) {
+          this._heartbeat(t, `hook:${ev.type}`);
+        }
       }
+      // H4: Stop hook → synthesize a settle for the primary turn after
+      // a grace, so JSONL `result` (which carries richer metadata)
+      // wins when both fire. If JSONL never arrives — broken stream,
+      // stuck parser — the Stop synth settles the turn instead of
+      // stranding it. Idempotent: a later JSONL settleResult call is
+      // a no-op once the promise has resolved.
+      //
+      // rc.42 #6 (review-driven): per-primary `_stopSynthScheduled`
+      // guard + stored timer ref so kill()/`_finishTurn` can clear
+      // the pending synth. Without these, repeated Stop events
+      // accumulate N independent timers (rare in production, but a
+      // possible memory leak), and a synth scheduled against a
+      // primary that retires via another path (timeout, interrupt)
+      // fires post-mortem against a freed promise. Idempotency
+      // makes both harmless TODAY; defensive future-proofing.
+      if (ev?.type === 'Stop') {
+        const primary = (this._activeGroup?.turns || [])
+          .find((t) => t.kind === 'primary');
+        if (primary
+          && typeof primary.settleResult === 'function'
+          && !primary._stopSynthScheduled) {
+          const synth = {
+            text: primary.text || ev.lastAssistantMessage || '',
+            subtype: 'success',
+            stopReason: 'stop_hook',
+            sessionId: this.claudeSessionId,
+            via: 'stop-hook',
+          };
+          primary._stopSynthScheduled = true;
+          // rc.42 #3 (review-driven): try/catch in the timer callback.
+          // settleResult is a Promise resolver (cannot throw under
+          // current spec), but a future refactor where settleResult
+          // gates on instance state could; the surrounding setTimeout
+          // has no recovery path otherwise.
+          primary._stopSynthTimer = setTimeout(() => {
+            try {
+              // Recheck the turn is still in a state where the synth
+              // is meaningful — if `_finishTurn` already retired it,
+              // settleResult is idempotent but skipping is cleaner.
+              if (typeof primary.settleResult === 'function') {
+                primary.settleResult(synth);
+              }
+            } catch (err) {
+              this.logger.warn?.(
+                `[${this.label}] Stop-synth settle error: ${err.message}`,
+              );
+            }
+          }, this.stopGraceMs);
+          primary._stopSynthTimer.unref?.();
+        }
+      }
+      this.emit('hook-event', ev);
+    } catch (err) {
+      this.logger.warn?.(
+        `[${this.label}] _handleHookEvent error (${ev?.type || 'unknown'}): `
+        + `${err.message}`,
+      );
     }
-    this.emit('hook-event', ev);
   }
 
   _handleSessionEvent(ev) {
@@ -2959,6 +3184,16 @@ class TmuxProcess extends Process {
     for (const finish of [...this._submitConfirms.values()]) {
       try { finish(); } catch { /* swallow */ }
     }
+    // rc.42 #6 (review-driven): drop pending H4 Stop-synth timers
+    // across every turn the ledger still holds. Symmetric with the
+    // _finishTurn cleanup — kill() bypasses _finishTurn for the
+    // drainQueue'd turns, so do it here.
+    for (const turn of this._ledger) {
+      if (turn?._stopSynthTimer) {
+        try { clearTimeout(turn._stopSynthTimer); } catch { /* swallow */ }
+        turn._stopSynthTimer = null;
+      }
+    }
     if (this._sessionLogTail) {
       try { this._sessionLogTail.close(); } catch { /* swallow */ }
       this._sessionLogTail = null;

package/lib/process-manager.js

@@ -98,6 +98,27 @@ const CALLBACK_TO_EVENT = {
   // unification). SDK backend never emits — hooks are tmux-specific.
   // See docs/0.10.0-tmux-hook-observability.md.
   onHookEvent:                  'hook-event',
+  // 0.10.0 rc.42 (review-driven #1): tmux backend turn-timeout event.
+  // Mirrors sdk-process.js's `_logEvent('turn-timeout', ...)` so both
+  // backends emit the same diagnostic. Payload distinguishes
+  // `idle-ceiling` vs `hard-backstop` (the H3 racers) so operators can
+  // tell a wedged-silent subagent from a runaway tool loop.
+  onTurnTimeout:                'turn-timeout',
+  // 0.10.0 rc.42 (review-driven #8): tmux backend hook-tail
+  // degradation event. The hook ndjson is load-bearing for H3 idle
+  // heartbeats; a persistently broken tail silently resurrects
+  // msg-884-class kills. Emitting the event surfaces the degradation
+  // in the events DB so it's visible in forensics, not just
+  // logger.warn.
+  onHookTailError:              'hook-tail-error',
+  // 0.10.0 rc.42 (review-driven #15): tmux backend stop-hook-resolved
+  // event. Fires when a turn settled via the H4 Stop-hook synth path
+  // instead of the canonical JSONL `result` (i.e. JSONL was broken or
+  // stuck and Stop rescued the turn). The synth's `via: 'stop-hook'`
+  // field was previously dead — only the tests read it. Persisting
+  // the event lets the soak count how often H4 actually fires its
+  // rescue contract.
+  onStopHookResolved:           'stop-hook-resolved',
 };
 
 class ProcessManager {

package/lib/sdk/callbacks.js

@@ -459,6 +459,67 @@ function createSdkCallbacks({
       }
     },
 
+    // 0.10.0 rc.42 #1: tmux backend turn-timeout observability.
+    // H3 introduced two timeout racers (idle-ceiling, hard-backstop)
+    // but their `reason`/`idleMs` were silently dropped at the throw
+    // site, so the events DB couldn't distinguish a wedged-silent
+    // subagent (msg-884 shape) from a 4-hour runaway tool loop. The
+    // handler persists the distinguisher.
+    onTurnTimeout: (sessionKey, payload /* , entry */) => {
+      try {
+        logEvent('turn-timeout', {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: 'tmux',
+          turn_id:             payload?.turnId ?? null,
+          reason:              payload?.reason ?? null,
+          idle_ms:             payload?.idleMs ?? null,
+          turn_timeout_ms:     payload?.turnTimeoutMs ?? null,
+          hard_backstop_ms:    payload?.hardBackstopMs ?? null,
+          claude_session_id:   payload?.sessionId ?? null,
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] turn-timeout handler: ${err.message}`);
+      }
+    },
+
+    // 0.10.0 rc.42 #8: tmux backend hook-tail error observability.
+    // Persistent failures of the hook ndjson tail degrade H3 idle-
+    // ceiling accuracy and H4 Stop-synth coverage with no surface
+    // signal. Record one event per error so post-mortem can correlate
+    // unexpected idle-timeouts to a broken tail.
+    onHookTailError: (sessionKey, payload /* , entry */) => {
+      try {
+        logEvent('hook-tail-error', {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: 'tmux',
+          message:           (payload?.message || '').slice(0, 200),
+          path:              payload?.path ?? null,
+          claude_session_id: payload?.sessionId ?? null,
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] hook-tail-error handler: ${err.message}`);
+      }
+    },
+
+    // 0.10.0 rc.42 #15: H4 Stop-hook synth fired and won the race
+    // against JSONL `result` (or JSONL never landed). Forensic count
+    // of how often Stop actually rescues a stuck JSONL stream.
+    onStopHookResolved: (sessionKey, payload /* , entry */) => {
+      try {
+        logEvent('stop-hook-resolved', {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: 'tmux',
+          turn_id:           payload?.turnId ?? null,
+          claude_session_id: payload?.sessionId ?? null,
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] stop-hook-resolved handler: ${err.message}`);
+      }
+    },
+
     onInjectFail: (sessionKey, payload /* , entry */) => {
       try {
         const msgId = payload?.msgId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.10.0-rc.40",
+  "version": "0.10.0-rc.42",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {