polygram 0.12.0-rc.21 → 0.12.0-rc.22

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,12 @@ 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;
     // 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 +1553,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 +1569,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 +1597,76 @@ 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 });
+      }
+      this._bgWorkSince = null;
+      this._bgWorkEscalations = 0;
+      return;
+    }
+    if (this._bgWorkSince === null) {
+      // First idle observation of a live background shell — start the clock.
+      this._bgWorkSince = Date.now();
+      this._bgWorkEscalations = 0;
+      this._logEvent('cli-bg-work-detected', { shell_count: count });
+      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 +2502,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/package.json

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