polygram 0.12.0-rc.31 → 0.12.0-rc.32

package/lib/process/cli-process.js

@@ -1732,6 +1732,18 @@ class CliProcess extends Process {
     return { live: backgroundShell, count: shellCount };
   }
 
+  /**
+   * LRU eviction pin (0.12.0 spec). Cached read of `_bgWorkSince` — the idle bg-work
+   * watchdog state maintained by `_pollBackgroundWork` on the ≤5s pong tick. Non-null ⟺ a
+   * detached background shell has been observed while idle. No time cap: a job that runs for
+   * hours stays pinned (elapsed time can't tell "slow-but-progressing" from "stuck"). Cheap,
+   * sync — safe to call from `_evictLRU`.
+   * @returns {boolean}
+   */
+  hasActiveBackgroundWork() {
+    return this._bgWorkSince !== null;
+  }
+
   /**
    * Stall-watchdog for detached background work (0.12.0 background-work
    * lifecycle, shumorobot Music 7h frozen-Chrome download). Runs on the

package/lib/process/process.js

@@ -160,6 +160,19 @@ class Process extends EventEmitter {
     return false;
   }
 
+  /**
+   * Does this session have a DETACHED background job running (a `run_in_background`
+   * shell that outlives the dispatch turn)? Used by ProcessManager._evictLRU to PIN
+   * the session — skip it for eviction the same way `inFlight` is skipped — so a live
+   * job isn't silently killed under budget pressure. Default: no signal → false.
+   * Backends that can detect detached shells (cli) override this. Must be cheap + sync.
+   *
+   * @returns {boolean}
+   */
+  hasActiveBackgroundWork() {
+    return false;
+  }
+
   /**
    * Push priority='now' style steer (rare; legacy of OpenClaw shape).
    * Hot-path-safe.

package/lib/process-manager.js

@@ -245,16 +245,36 @@ class ProcessManager {
     const newCost = newProc.cost;
 
     while (this.totalCost + newCost > this.budget) {
-      const evicted = this._evictLRU();
-      if (!evicted) {
-        // All entries in-flight — park.
-        await this._awaitLruSlot();
-        if (this._shuttingDown) {
-          try { await newProc.kill('shutdown'); } catch {}
-          throw new Error('shutdown');
-        }
-        // Loop again — budget may have freed up.
+      const evicted = this._evictLRU();   // skips inFlight + background-job-pinned
+      if (evicted) continue;
+      // _evictLRU freed nothing. Policy C — split by WHY:
+      if (this._hasPinnedSession()) {
+        // A DURABLE blocker (live background job) holds a slot. Don't park on it (could be
+        // ~an hour) and don't kill it. The budget caps RSS, not correctness — so treat it as
+        // SOFT: spawn over budget + warn; the operator reclaims by /reset-ing a chat.
+        const pinned = this._pinnedSessionKeys();
+        this._logEvent('lru-overflow-pinned', {
+          active: this.procs.size,
+          totalCost: this.totalCost,
+          budget: this.budget,
+          newCost,
+          pinned,
+        });
+        this.logger.warn?.(
+          `[pm] budget ${this.budget} exceeded (~${this.totalCost + newCost}): all free slots hold ` +
+          `live background jobs [${pinned.join(', ')}]. Spawning over limit — /reset one of those ` +
+          `chats to reclaim memory.`,
+        );
+        break;   // soft overflow — spawn anyway
+      }
+      // No pin — the blockers are all in-flight TURNS (transient, finish in seconds). Keep the
+      // existing behavior: park briefly for a slot rather than needlessly overflow.
+      await this._awaitLruSlot();
+      if (this._shuttingDown) {
+        try { await newProc.kill('shutdown'); } catch {}
+        throw new Error('shutdown');
       }
+      // Loop again — budget may have freed up.
     }
 
     this._wireCallbacks(newProc);
@@ -278,8 +298,12 @@ class ProcessManager {
   _evictLRU() {
     let oldest = null;
     let oldestKey = null;
+    let pinnedSkipped = 0;
     for (const [k, p] of this.procs.entries()) {
       if (p.inFlight) continue;
+      // PIN: a session with a live detached background job is NOT evictable — killing it
+      // would silently drop the job (and its report-back wakeup). Skip like inFlight.
+      if (p.hasActiveBackgroundWork()) { pinnedSkipped++; continue; }
       if (!oldest || (p.lastUsedTs || 0) < (oldest.lastUsedTs || 0)) {
         oldest = p;
         oldestKey = k;
@@ -290,6 +314,7 @@ class ProcessManager {
         active: this.procs.size,
         totalCost: this.totalCost,
         budget: this.budget,
+        pinnedSkipped,
       });
       return false;
     }
@@ -297,12 +322,33 @@ class ProcessManager {
       session_key: oldestKey,
       cost: oldest.cost,
       backend: oldest.backend,
+      pinnedSkipped,
     });
     oldest.kill('evict').catch(() => {});
     this.procs.delete(oldestKey);
     return true;
   }
 
+  /**
+   * A DURABLE eviction blocker: a non-inFlight session holding a slot because it has a live
+   * background job (vs an inFlight TURN, which is transient and frees in seconds). Used to
+   * split park-vs-overflow when _evictLRU can free nothing.
+   */
+  _hasPinnedSession() {
+    for (const p of this.procs.values()) {
+      if (!p.inFlight && p.hasActiveBackgroundWork()) return true;
+    }
+    return false;
+  }
+
+  _pinnedSessionKeys() {
+    const keys = [];
+    for (const [k, p] of this.procs.entries()) {
+      if (!p.inFlight && p.hasActiveBackgroundWork()) keys.push(k);
+    }
+    return keys;
+  }
+
   async _awaitLruSlot() {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {

package/package.json

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