polygram 0.12.0-rc.21 → 0.12.0-rc.23

package/lib/process/cli-process.js

@@ -113,6 +113,20 @@ const MID_TURN_PROMPTS = [
 // hook process.
 const STREAMING_HINT_RE = /esc to interrupt/i;
 
+// 0.12.0 background-work lifecycle: claude's TUI mode line shows a live
+// background-shell COUNT while a `run_in_background:true` Bash outlives its turn,
+// e.g. `⏵⏵ auto mode on · 1 shell · ← for agents · ↓ to manage`. Confirmed on
+// claude 2.1.158 (P0 spike — docs/0.12.0-background-work-lifecycle-plan.md): the
+// count is always-present in the viewport mode line while shells run and clears
+// IN-PLACE within ~3s when they exit (no stale scrollback). Anchored to the
+// `auto mode on` line and matched only against the captured TAIL so a scrolled-off
+// history line never trips it. R1: re-validate on each pinned-claude bump.
+const BACKGROUND_SHELL_RE = /auto mode on[^\n]*·\s*(\d+)\s+shells?\b/i;
+// How long a detached background shell may run AFTER its turn resolved (claude
+// idle) before the stall-watchdog fires one read-only self-check. Override via
+// the constructor (tests use a small value).
+const DEFAULT_BG_WORK_STALL_MS = 600_000; // 10 min
+
 // 0.12 Phase 3.3 (Q1 resolution): heuristic for "looks like an unknown
 // interactive prompt." Match common prompt shapes that don't appear in
 // MID_TURN_PROMPTS — operator gets a telemetry event so they can decide
@@ -172,6 +186,7 @@ class CliProcess extends Process {
     turnQuietMs = DEFAULT_TURN_QUIET_MS,
     turnTimeoutMs = DEFAULT_TURN_TIMEOUT_MS,
     turnAbsoluteMs = DEFAULT_TURN_ABSOLUTE_MS,
+    bgWorkStallMs = DEFAULT_BG_WORK_STALL_MS,
     interruptGraceMs = DEFAULT_INTERRUPT_GRACE_MS,
     maxRepliesPerTurn = DEFAULT_MAX_REPLIES_PER_TURN,
     queueCap = DEFAULT_QUEUE_CAP,        // Parity P2
@@ -203,6 +218,7 @@ class CliProcess extends Process {
     this.turnQuietMs = turnQuietMs;
     this.turnTimeoutMs = turnTimeoutMs;
     this.turnAbsoluteMs = turnAbsoluteMs;
+    this.bgWorkStallMs = bgWorkStallMs;
     this.interruptGraceMs = interruptGraceMs;
     this.maxRepliesPerTurn = maxRepliesPerTurn;
     this.queueCap = queueCap;
@@ -226,6 +242,15 @@ class CliProcess extends Process {
     // interval fires bridge-disconnected if too much time elapses.
     this.lastPongAt = 0;
     this.pongWatchdog = null;
+    // 0.12.0 background-work stall-watchdog state. `_bgWorkSince` = when a live
+    // background shell was first observed while idle (null = none); reset only
+    // when the shell count returns to 0. `_bgWorkEscalations` caps the watchdog
+    // at one read-only self-check per continuous background-work window.
+    this._bgWorkSince = null;
+    this._bgWorkEscalations = 0;
+    // Visibility (Use 3): whether a "⏳ working in background" status message is
+    // currently shown, so we emit exactly one running→cleared pair per window.
+    this._bgWorkStatusShown = false;
     // Review P2 ADV-6: token-bucket rate limit on Claude's reply tool calls.
     // Without this, a prompt-injected or runaway Claude can fire reply() 1000×
     // in a tight loop, flooding TG + saturating the daemon event loop.
@@ -1531,7 +1556,7 @@ class CliProcess extends Process {
    */
   async probeBusyState() {
     const base = {
-      busy: false, streaming: false,
+      busy: false, streaming: false, backgroundShell: false, shellCount: 0,
       inFlight: this.inFlight, pendingTurns: this.pendingTurns.size,
       captured: false, paneTail: null,
     };
@@ -1547,10 +1572,23 @@ class CliProcess extends Process {
     }
     if (!pane) return base;
     const streaming = STREAMING_HINT_RE.test(pane);
+    // Background-shell count from the TUI mode line. Match only the captured
+    // TAIL (the mode line lives at the bottom of the viewport) so a `· N shell ·`
+    // string scrolled off into history can't trip a stale false-positive — see
+    // BACKGROUND_SHELL_RE. A detached `run_in_background` Bash that outlived its
+    // turn shows here even while claude is idle and not streaming.
+    const m = pane.slice(-400).match(BACKGROUND_SHELL_RE);
+    const shellCount = m ? parseInt(m[1], 10) : 0;
+    const backgroundShell = shellCount > 0;
     return {
       ...base,
+      // `busy` stays streaming-only — it is the abort path's "is claude working a
+      // turn" signal and must not change behaviour. Background-shell liveness is a
+      // separate axis the stall-watchdog reads via `backgroundShell`/`shellCount`.
       busy: streaming,
       streaming,
+      backgroundShell,
+      shellCount,
       captured: true,
       paneTail: pane.slice(-200),
     };
@@ -1562,6 +1600,84 @@ class CliProcess extends Process {
     return busy;
   }
 
+  /**
+   * Does this session have a detached background shell running RIGHT NOW — a
+   * `run_in_background` Bash that may have outlived its turn? Thin probe over
+   * probeBusyState's background-shell signal; the stall-watchdog's input.
+   * @returns {Promise<{live:boolean, count:number}>}
+   */
+  async hasLiveBackgroundWork() {
+    const { backgroundShell, shellCount } = await this.probeBusyState();
+    return { live: backgroundShell, count: shellCount };
+  }
+
+  /**
+   * Stall-watchdog for detached background work (0.12.0 background-work
+   * lifecycle, shumorobot Music 7h frozen-Chrome download). Runs on the
+   * pongWatchdog 5s tick but ONLY while the session is IDLE (pendingTurns===0) —
+   * the mirror of _pollMidTurnDialogs, which only runs DURING turns. When a
+   * `run_in_background` Bash outlives its turn and keeps running while claude is
+   * idle for > bgWorkStallMs, nothing tells the agent or user whether it's
+   * progressing or stuck. One read-only self-check re-invokes the agent to
+   * diagnose — via `fireUserMessage`, NOT `injectUserMessage` (which no-ops when
+   * !inFlight, the exact idle state here). Read-only framing matters: the agent
+   * runs bypassPermissions, so an open-ended "fix it" could background another
+   * hung shell unattended.
+   *
+   * Exactly one self-check per continuous background-work window (capped by
+   * `_bgWorkEscalations`); the window resets only when the shell count returns to
+   * 0. Never throws — swallows its own errors so the pong watchdog stays clean.
+   */
+  async _pollBackgroundWork() {
+    if (this.closed || !this.bridgeReady) return;
+    // Only watch while idle. An active turn means the agent is engaged
+    // (_pollMidTurnDialogs owns that path). Crucially we do NOT reset the clock
+    // here — the same shell is still running, so the window persists across a
+    // brief self-check turn rather than restarting and re-pinging every window.
+    if (this.pendingTurns.size > 0) return;
+    let live = false;
+    let count = 0;
+    try {
+      ({ live, count } = await this.hasLiveBackgroundWork());
+    } catch (err) {
+      this.logger.warn?.(`[${this.label}] channels: bg-work probe failed: ${err.message}`);
+      return;
+    }
+    if (!live) {
+      if (this._bgWorkSince !== null) {
+        this._logEvent('cli-bg-work-cleared', { idle_ms: Date.now() - this._bgWorkSince });
+        // Visibility: tear down the status indicator once work clears.
+        if (this._bgWorkStatusShown) {
+          this.emit('bg-work-status', { state: 'cleared' });
+          this._bgWorkStatusShown = false;
+        }
+      }
+      this._bgWorkSince = null;
+      this._bgWorkEscalations = 0;
+      return;
+    }
+    if (this._bgWorkSince === null) {
+      // First idle observation of a live background shell — start the clock AND
+      // raise the visibility indicator so a long job reads as working, not stuck.
+      this._bgWorkSince = Date.now();
+      this._bgWorkEscalations = 0;
+      this._logEvent('cli-bg-work-detected', { shell_count: count });
+      this.emit('bg-work-status', { state: 'running', count });
+      this._bgWorkStatusShown = true;
+      return;
+    }
+    const idleMs = Date.now() - this._bgWorkSince;
+    if (idleMs < this.bgWorkStallMs || this._bgWorkEscalations >= 1) return;
+    const mins = Math.max(1, Math.round(idleMs / 60000));
+    const prompt =
+      `⏳ A background job has been running ~${mins} min with no update. `
+      + `Check its status and report whether it's progressing or stuck. `
+      + `Do NOT start new work, re-run it, or kill anything — report only.`;
+    const fired = this.fireUserMessage(prompt);
+    this._bgWorkEscalations = 1;
+    this._logEvent('cli-bg-work-stall-selfcheck', { idle_ms: idleMs, shell_count: count, fired });
+  }
+
   async kill(reason = 'kill') {
     if (this.closed) return;
     // Parity P19: re-entry guard for concurrent kill() calls. Mirrors
@@ -2397,6 +2513,11 @@ class CliProcess extends Process {
       this._pollMidTurnDialogs().catch((err) => {
         this.logger.warn?.(`[${this.label}] channels: mid-turn poll failed: ${err.message}`);
       });
+      // 0.12.0 background-work lifecycle: idle-side stall-watchdog, the mirror of
+      // _pollMidTurnDialogs (which only runs during turns). Fire-and-forget.
+      this._pollBackgroundWork().catch((err) => {
+        this.logger.warn?.(`[${this.label}] channels: bg-work poll failed: ${err.message}`);
+      });
     }, PONG_CHECK_INTERVAL_MS);
     this.pongWatchdog.unref?.();
   }

package/lib/process-manager.js

@@ -47,6 +47,12 @@ const CALLBACK_TO_EVENT = {
   // auto-compacting now. The callback posts a chat message proposing /compact
   // — opt-in per chat. See docs/0.12.0-file-send.md / lib/compaction-warn.js.
   onCompactionWarn:             'compaction-warn',
+  // 0.12.0 background-work visibility (Use 3). CliProcess emits 'bg-work-status'
+  // {state:'running'|'cleared', count?} when a detached background shell is first
+  // observed running idle past its turn, and again when it clears. The callback
+  // posts/edits a "⏳ working in background" status message so a long job reads as
+  // working, not stuck. See docs/0.12.0-background-work-lifecycle-plan.md.
+  onBgWorkStatus:               'bg-work-status',
   onQueueDrop:                  'queue-drop',
   onThinking:                   'thinking',
   // Tmux backend: TUI shows in-pane approval prompt. SDK backend

package/lib/sdk/callbacks.js

@@ -60,6 +60,10 @@ function createSdkCallbacks({
   // because the TUI's queue is FIFO and we only watch one extra turn
   // at a time per session.
   const extraTurnTracker = new Map(); // sessionKey → { msgId, intervalHandle, chatId }
+  // 0.12.0 background-work visibility (Use 3): sessionKey → message_id of the live
+  // "⏳ working in background" status message, so the cleared/close paths can edit
+  // it to a final state instead of leaving it dangling as "working".
+  const bgStatusMsgIds = new Map();
 
   function startExtraTurnVisuals(sessionKey, msgId) {
     if (!bot) return;
@@ -152,6 +156,17 @@ function createSdkCallbacks({
       // visuals so we don't leak the interval and aren't stuck
       // showing "writing…" on a dead session.
       stopExtraTurnVisuals(sessionKey, null);
+      // 0.12.0 bg-work visibility: if a "⏳ working in background" status is still
+      // up when the session closes, its shell died with the session — edit to a
+      // final state so it doesn't dangle as "working" forever.
+      const bgMid = bgStatusMsgIds.get(sessionKey);
+      if (bgMid != null && bot) {
+        bgStatusMsgIds.delete(sessionKey);
+        tg(bot, 'editMessageText', {
+          chat_id: entry.chatId, message_id: bgMid,
+          text: '⏹ Background work ended (session restarted).',
+        }, { source: 'bg-work-status', botName }).catch(() => {});
+      }
     },
 
     onStreamChunk: (sessionKey, partial, entry) => {
@@ -324,6 +339,49 @@ function createSdkCallbacks({
       }
     },
 
+    // 0.12.0 background-work visibility (Use 3). CliProcess emits this when a
+    // detached `run_in_background` shell is first observed running idle past its
+    // turn ('running') and again when it clears ('cleared'). We post ONE bot
+    // status message and edit it to done — so a long job reads as working, not
+    // stuck. Direct tg send (NOT via claude — this is a bot status indicator),
+    // keyed by sessionKey so the cleared/close paths can find it to edit.
+    onBgWorkStatus: async (sessionKey, payload) => {
+      try {
+        if (!bot) return;
+        const chatId = getChatIdFromKey(sessionKey);
+        const threadIdRaw = getThreadIdFromKey(sessionKey);
+        const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
+        const state = payload?.state;
+        if (state === 'running') {
+          if (bgStatusMsgIds.has(sessionKey)) return; // already showing one
+          const res = await tg(bot, 'sendMessage', {
+            chat_id: chatId,
+            text: '⏳ Working in the background — I\'ll keep an eye on it and report when it\'s done.',
+            ...(Number.isInteger(threadId) && { message_thread_id: threadId }),
+          }, { source: 'bg-work-status', botName });
+          const mid = res?.message_id ?? res?.result?.message_id ?? null;
+          if (mid != null) bgStatusMsgIds.set(sessionKey, mid);
+          logEvent('bg-work-status', {
+            chat_id: chatId, session_key: sessionKey, thread_id: threadIdRaw,
+            state: 'running', message_id: mid,
+          });
+        } else if (state === 'cleared') {
+          const mid = bgStatusMsgIds.get(sessionKey);
+          bgStatusMsgIds.delete(sessionKey);
+          if (mid == null) return;
+          await tg(bot, 'editMessageText', {
+            chat_id: chatId, message_id: mid, text: '✅ Background work finished.',
+          }, { source: 'bg-work-status', botName }).catch(() => {});
+          logEvent('bg-work-status', {
+            chat_id: chatId, session_key: sessionKey, thread_id: threadIdRaw,
+            state: 'cleared', message_id: mid,
+          });
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] bg-work-status handler: ${err.message}`);
+      }
+    },
+
     // rc.9: pair-of with onExtraTurnReply. Fires the moment
     // TmuxProcess sees the dequeued user-message in JSONL → turn 2
     // is starting. Re-engages typing indicator + ✍ on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.12.0-rc.21",
+  "version": "0.12.0-rc.23",
   "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": {