polygram 0.16.0 → 0.17.1

package/lib/claude-bin.js

@@ -3,6 +3,7 @@
 const os = require('os');
 const path = require('path');
 const fs = require('fs');
+const { execFileSync } = require('child_process');
 
 // 0.12 Phase 4: moved from lib/process/tmux-process.js into the helper module
 // that consumes it, so the constant survives TmuxProcess deletion. CliProcess
@@ -41,9 +42,13 @@ const CLAUDE_CLI_PINNED_VERSION = '2.1.173';
  * lands — so a $PATH spawn silently drifts (shumorobot 2026-05-16:
  * CLI auto-updated 2.1.142 → 2.1.143 between deploys).
  *
- * Spawning the ABSOLUTE versioned path is immune to that: the
- * updater only ADDS new version files, it never overwrites an
- * existing one. `versions/2.1.142` stays byte-identical forever.
+ * Spawning the ABSOLUTE versioned path avoids the symlink-drift, but is
+ * NOT immune to the updater: claude keeps only the ~3 newest versions
+ * and PRUNES (deletes) the rest. Once the pin falls out of the top 3 the
+ * pinned path is a dead file → every cli spawn exits in ~14ms (prod
+ * outages 2026-06-21/22). So `verifyPinnedClaudeBin` (point-in-time check)
+ * is not enough; `ensureVendoredClaudeBin` (below, 0.17) keeps a
+ * polygram-owned copy the pruner can't touch.
  */
 
 /**
@@ -92,4 +97,150 @@ function verifyPinnedClaudeBin(version) {
   }
 }
 
-module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin, CLAUDE_CLI_PINNED_VERSION };
+// ─── 0.17: vendored pinned binary (immune to claude's auto-pruner) ──────────
+//
+// claude's updater deletes all but the ~3 newest versions, so the pinned
+// version eventually vanishes from ~/.local/share/claude/versions and every
+// cli spawn dies. We can't fall forward (the cli backend reads version-specific
+// TUI internals). Fix: polygram keeps its OWN copy of the exact pinned binary
+// in a dir the pruner never touches, and spawns from there. Once vendored it
+// never depends on the system copy or the network again.
+
+/**
+ * polygram-owned vendor dir for claude binaries. Under ~/.local/share/polygram
+ * (XDG data) — claude's pruner only touches ~/.local/share/claude/versions, and
+ * `npm i -g polygram` only replaces the package dir, so this survives both.
+ * Override with POLYGRAM_CLAUDE_VENDOR_DIR.
+ */
+function vendorDir() {
+  return process.env.POLYGRAM_CLAUDE_VENDOR_DIR
+    || path.join(os.homedir(), '.local', 'share', 'polygram', 'claude-bin');
+}
+
+function isExecutable(p) {
+  try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+// Atomic: copy to a unique tmp in the same dir, chmod, then rename over.
+function _atomicCopyExec(src, dst) {
+  const tmp = `${dst}.tmp.${process.pid}.${Date.now()}`;
+  fs.copyFileSync(src, tmp);
+  fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, dst);
+}
+
+// Remove vendored binaries (and stale .tmp.*) that aren't the live version.
+function _gcVendored(dir, keepVersion, logger) {
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (name === keepVersion) continue;
+    // Never delete an in-flight copy: a CONCURRENT boot (multi-bot host shares
+    // this dir) may be mid-copy into `<keepVersion>.tmp.<pid>.<ts>`; removing it
+    // ENOENTs that boot's rename → it falls back to SDK. Skip all .tmp.* — a
+    // genuinely orphaned tmp is cheap to leave (cleaned when its version is GC'd
+    // by name, or harmless). Defense-in-depth: only GC version-shaped names so a
+    // misconfigured vendor dir can't nuke unrelated files.
+    if (name.includes('.tmp.')) continue;
+    if (!/^\d+\.\d+\.\d+$/.test(name)) continue;
+    try { fs.rmSync(path.join(dir, name), { force: true }); } catch (e) {
+      logger?.warn?.(`[claude-bin] vendor GC: could not remove ${name}: ${e.message}`);
+    }
+  }
+}
+
+/**
+ * Ensure a polygram-owned copy of the pinned claude binary exists and return
+ * its path. Steady state is a single stat (fast). On a cold/pruned host it
+ * obtains the binary once (copy from the system install, else `claude install`
+ * then copy) and caches it forever.
+ *
+ * @param {string} version
+ * @param {{ logger?: object }} [opts]
+ * @returns {{ ok: boolean, path: string, vendored?: boolean, reason?: string }}
+ */
+function ensureVendoredClaudeBin(version, { logger = console } = {}) {
+  // Explicit override wins, unchanged — non-standard installs / CI / tests.
+  const override = process.env.POLYGRAM_CLAUDE_BIN;
+  if (override) {
+    return isExecutable(override)
+      ? { ok: true, path: override, vendored: false }
+      : { ok: false, path: override, reason: `POLYGRAM_CLAUDE_BIN=${override} not executable` };
+  }
+
+  const dir = vendorDir();
+  const vendored = path.join(dir, version);
+
+  // Fast path: already vendored.
+  if (isExecutable(vendored)) {
+    _gcVendored(dir, version, logger);
+    return { ok: true, path: vendored, vendored: true };
+  }
+
+  // Need to obtain it. Ensure the dir exists.
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {
+    return { ok: false, path: vendored, reason: `cannot create vendor dir ${dir}: ${e.message}` };
+  }
+
+  const versionsDir = process.env.POLYGRAM_CLAUDE_VERSIONS_DIR
+    || path.join(os.homedir(), '.local', 'share', 'claude', 'versions');
+  const systemPath = path.join(versionsDir, version);
+
+  // (a) copy from the system install if present.
+  if (isExecutable(systemPath)) {
+    try {
+      _atomicCopyExec(systemPath, vendored);
+      logger?.log?.(`[claude-bin] vendored claude v${version} ← ${systemPath} → ${vendored}`);
+    } catch (e) {
+      return { ok: false, path: vendored, reason: `copy ${systemPath} → ${vendored} failed: ${e.message}` };
+    }
+  } else {
+    // (b) try to install the exact version, then copy. If
+    // POLYGRAM_CLAUDE_INSTALL_BIN is set, use it VERBATIM (no fallback — an
+    // explicit override that's wrong must fail loudly, not silently shell out to
+    // a different claude). Otherwise prefer ~/.local/bin/claude, else PATH.
+    let installerBin = process.env.POLYGRAM_CLAUDE_INSTALL_BIN;
+    if (!installerBin) {
+      const localBin = path.join(os.homedir(), '.local', 'bin', 'claude');
+      installerBin = isExecutable(localBin) ? localBin : 'claude';
+    }
+    logger?.warn?.(`[claude-bin] pinned claude v${version} absent from ${systemPath}; installing via ${installerBin}…`);
+    try {
+      // Synchronous: blocks boot until the install completes. Rare (deploys
+      // pre-install the pin → the fast copy path above is the norm). On the VPS
+      // polygram boots DETACHED in tmux (Type=oneshot start-sessions.sh), so
+      // this block is NOT gated by systemd's TimeoutStartSec; on the Mac launchd
+      // has no hard start-timeout. Timeout kept under the VPS unit's 120s anyway.
+      execFileSync(installerBin, ['install', version], { timeout: 110_000, stdio: 'ignore' });
+    } catch (e) {
+      return {
+        ok: false, path: vendored,
+        reason: `claude v${version} not present and \`claude install ${version}\` failed (${e.message}). `
+          + 'Install it manually or set POLYGRAM_CLAUDE_BIN.',
+      };
+    }
+    if (!isExecutable(systemPath)) {
+      return { ok: false, path: vendored, reason: `claude install ${version} ran but ${systemPath} still missing` };
+    }
+    try {
+      _atomicCopyExec(systemPath, vendored);
+      logger?.log?.(`[claude-bin] installed + vendored claude v${version} → ${vendored}`);
+    } catch (e) {
+      return { ok: false, path: vendored, reason: `copy after install failed: ${e.message}` };
+    }
+  }
+
+  _gcVendored(dir, version, logger);
+  if (!isExecutable(vendored)) {
+    return { ok: false, path: vendored, reason: `vendored copy ${vendored} is not executable after copy` };
+  }
+  return { ok: true, path: vendored, vendored: true };
+}
+
+module.exports = {
+  resolvePinnedClaudeBin,
+  verifyPinnedClaudeBin,
+  ensureVendoredClaudeBin,
+  vendorDir,
+  CLAUDE_CLI_PINNED_VERSION,
+};

package/lib/process/channels-bridge.mjs

@@ -317,6 +317,13 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
         turn_id: { type: 'string', description: 'Echo of turn_id from inbound channel meta (required for correct turn routing).' },
         text:    { type: 'string', description: 'Message body (markdown ok).' },
         files:   { type: 'array',  items: { type: 'string' }, description: 'Optional absolute file paths to attach.' },
+        interim: {
+          type: 'boolean',
+          description: 'Set true ONLY for a short status/progress update on a long task '
+            + '(e.g. "Looking into that now…"). An interim reply is shown to the user but is '
+            + 'NOT the turn\'s answer — you MUST still deliver the real result as a later reply '
+            + 'with interim omitted/false in the SAME turn. NEVER end a turn on an interim reply.',
+        },
         // 0.13 D2 Tier 2C: the fold-acknowledgment contract. The single turn_id
         // field can't express a combined reply that covers a mid-turn follow-up
         // (P0 spike Q-B: claude echoes only the trigger id) — this array can.

package/lib/process/cli-process.js

@@ -776,14 +776,21 @@ class CliProcess extends Process {
       '',
       'So once you are clearly into multi-step work — you have run a couple of tool',
       'calls without replying, or the request plainly needs research / several steps —',
-      'send a SHORT one-line status via `reply` (it returns a `message_id`), then use',
-      '`mcp__polygram-bridge__edit_message` on that SAME `message_id` to update the',
-      'bubble as you progress. `edit_message` is for INTERIM status ONLY.',
+      'send a SHORT one-line status via `reply` WITH `interim: true` (it returns a',
+      '`message_id`), then use `mcp__polygram-bridge__edit_message` on that SAME',
+      '`message_id` to update the bubble as you progress. `edit_message` is for',
+      'INTERIM status ONLY.',
       '',
-      'Deliver the FINAL answer as a fresh `reply`, never as an edit: a fresh reply',
-      'notifies the user and carries `consumed_turn_ids`; an edit does neither. If you',
-      'no longer have the status bubble\'s message_id, just send a fresh `reply` —',
-      'never guess an id.',
+      'HARD RULE — a status is a MID-TURN update, NOT the end of work. After an',
+      'interim reply you MUST keep working in the SAME turn and deliver the real',
+      'result. NEVER end your turn on a status / "give me a couple min" / "looking',
+      'into it" reply with no result behind it — that leaves the user staring at a',
+      'promise with nothing delivered. Do the work, then answer.',
+      '',
+      'Deliver the FINAL answer as a fresh `reply` with interim omitted/false, never',
+      'as an edit: a fresh reply notifies the user and carries `consumed_turn_ids`; an',
+      'edit does neither. If you no longer have the status bubble\'s message_id, just',
+      'send a fresh `reply` — never guess an id.',
       '',
       'If you will finish in one or two tool calls, just answer — no status bubble.',
       'Status is for work that takes time, not for quick answers (do not spam it).',
@@ -1320,6 +1327,7 @@ class CliProcess extends Process {
         threadId: this.threadId,
         toolName: msg.name,
         text: args.text,
+        interim: args.interim === true,     // status/progress reply — not the turn's answer
         files: args.files,
         messageId: args.message_id,         // 0.13: edit_message target bubble
         sourceMsgId,                        // reaction/quote target (A2)
@@ -1373,7 +1381,7 @@ class CliProcess extends Process {
     // fall back to the SINGLE pending turn if exactly one exists, else the
     // oldest pending — log a warning either way so we can audit drift.
     if (msg.name === 'reply' && result?.ok && typeof args.text === 'string' && args.text.length > 0) {
-      this._recordReplyForPendingTurn(args.text, args.turn_id);
+      this._recordReplyForPendingTurn(args.text, args.turn_id, args.interim === true);
     }
   }
 
@@ -1382,8 +1390,10 @@ class CliProcess extends Process {
    *
    * @param {string} text
    * @param {string|undefined} replyTurnId — echoed from Claude's reply tool args
+   * @param {boolean} interim — true for a status/progress reply (`interim:true`),
+   *        which is NOT the turn's answer. A reply is FINAL by default (fail-safe).
    */
-  _recordReplyForPendingTurn(text, replyTurnId) {
+  _recordReplyForPendingTurn(text, replyTurnId, interim = false) {
     // 0.13 D2 (S5 tightening): a reply echoing a KNOWN ledgered turn_id that is
     // NOT the current pending is a LATE reply from an earlier cycle (post-
     // finalize tails, fireUserMessage cycles, ask wrap-ups). Pre-P3 the
@@ -1469,6 +1479,12 @@ class CliProcess extends Process {
 
     target.replies.push(text);
     target.replyCount = (target.replyCount || 0) + 1;
+    // A status/progress reply (`interim:true`) is delivered but is NOT the turn's
+    // answer — track it so the finalizer can tell an interim-only turn (a promise
+    // like "give me a couple min") from a delivered result, and so the ceilings
+    // keep extending it as still-working rather than resolving it as done.
+    // docs/progress-is-not-turn-end-spec.md
+    if (interim) target._interimReplyCount = (target._interimReplyCount || 0) + 1;
 
     if (this._sawHookStream) {
       // 0.13 D1: a delivered reply is ACTIVITY — rung 2 (activity-quiet) owns
@@ -1756,9 +1772,11 @@ class CliProcess extends Process {
    */
   _armActivityQuiet(turnId, pending) {
     if (!this._sawHookStream) return;
-    // ≥1 reply, OR seen + consumed-acked (the answer rode a sibling turn_id —
-    // fold-id echo; see _ledgerAckConsumed). Same eligibility as the fire site.
-    if ((!pending.replies || pending.replies.length === 0)
+    // ≥1 FINAL reply, OR seen + consumed-acked (the answer rode a sibling turn_id —
+    // fold-id echo; see _ledgerAckConsumed). Same eligibility as the fire site. An
+    // interim-only turn (status promise, no final reply) is NOT eligible — it must
+    // keep working, not quiet-finalize as done. docs/progress-is-not-turn-end-spec.md
+    if (!this._turnHasFinalReply(pending)
         && !(pending.seen === true && pending._consumedAcked === true)) return;
     if (this._openQuestions.size > 0) return;
     if (pending._stopGracePending) return;
@@ -1792,7 +1810,7 @@ class CliProcess extends Process {
     // Eligibility: ≥1 bound reply, OR seen + consumed-acked (the answer went
     // out under a sibling turn_id — fold-id echo; see _ledgerAckConsumed).
     const consumedAcked = pending.seen === true && pending._consumedAcked === true;
-    if ((!pending.replies || pending.replies.length === 0) && !consumedAcked) return;
+    if (!this._turnHasFinalReply(pending) && !consumedAcked) return;
     const lastHookAgeMs = this._lastHookEventAt ? Date.now() - this._lastHookEventAt : null;
     this._logEvent('cli-activity-quiet-finalize', {
       turn_id: turnId,
@@ -1910,6 +1928,81 @@ class CliProcess extends Process {
     this.on('stop-hook', onStop);
   }
 
+  /**
+   * Has this turn delivered a FINAL (non-interim) reply? A reply is final by
+   * default; only `interim:true` status replies don't count. A turn whose only
+   * output is a status promise has NOT delivered its answer. Used by the
+   * finalizer and the absolute checkpoint so an interim-only turn is treated as
+   * still-working (keep extending / deliver the produced result), not as done.
+   */
+  _turnHasFinalReply(pending) {
+    return (pending?.replies?.length || 0) > (pending?._interimReplyCount || 0);
+  }
+
+  /**
+   * Compute the {text, alreadyDelivered} a resolving turn delivers, honoring the
+   * interim-reply rules. Shared by BOTH resolve paths — `_finalizeTurn` (Stop /
+   * activity-quiet) AND the `fireTimeout` ceiling-resolve — so neither drops the
+   * produced answer of an interim-only turn. docs/progress-is-not-turn-end-spec.md
+   *
+   *   - a FINAL reply landed → its text was already delivered incrementally
+   *     (polygram.js short-circuits) → alreadyDelivered.
+   *   - zero replies → 0.12/0.13 Stop-fallback: deliver last_assistant_message
+   *     unless a consuming sibling already carried it (consumed-ack).
+   *   - interim-only (status promise, no final) → deliver the produced final answer
+   *     (last_assistant_message) if it exists and is distinct from the status / a
+   *     sibling's text; otherwise leave the status (nothing more to send).
+   */
+  _resolveTurnDelivery(pending, turnId) {
+    const norm = (s) => (s || '').trim();
+    const interimText = pending.replies.join('\n\n');
+    const fallbackText = pending._stopHookData?.lastAssistantMessage || '';
+
+    if (this._turnHasFinalReply(pending)) {
+      return { text: interimText, alreadyDelivered: true };
+    }
+    if (pending.replies.length === 0) {
+      // 0.12 Phase 1.7 fallback: no reply tool call landed — use the Stop hook's
+      // last_assistant_message so the user isn't left with silence (rc.41 H4).
+      const usedStopFallback = !!fallbackText;
+      const text = usedStopFallback ? fallbackText : '';
+      if (usedStopFallback) {
+        this.logger.warn?.(`[${this.label}] cli: turn finalized via stop-hook fallback (no reply tool call); text_len=${text.length}`);
+      }
+      // A _consumedAcked turn is "already delivered" ONLY when the consuming sibling
+      // reply actually carried THIS text — not merely an ack (prod 2026-06-13: a
+      // "Researching now…" ack then the real answer as Stop-fallback was suppressed
+      // and dropped for 5h20m). docs/0.13-consumed-ack-stop-fallback-drop-spec.md
+      const consumedCoversFallback = !usedStopFallback || norm(text) === norm(pending._consumedByText);
+      const alreadyDelivered = pending._consumedAcked === true && consumedCoversFallback;
+      if (usedStopFallback && pending._consumedAcked === true && !consumedCoversFallback) {
+        this.logger.warn?.(`[${this.label}] cli: consumed-ack did NOT cover the Stop-fallback answer — delivering rescued text (len=${text.length})`);
+        this._logEvent('cli-consumed-ack-fallback-rescued', {
+          turn_id: turnId, session_key: this.sessionKey, backend: this.backend,
+          rescued_len: text.length, ack_len: norm(pending._consumedByText).length,
+        });
+      }
+      return { text, alreadyDelivered };
+    }
+    // Interim-only: the turn delivered ONLY status/progress promises ("give me a
+    // couple min") and never a final reply. If claude produced a substantive final
+    // answer as its last assistant message — distinct from the status, and not text a
+    // consuming sibling already delivered — DELIVER it (the status bubbles are already
+    // on screen, so send the FINAL only). Else leave the status; don't re-deliver it.
+    const interimRescue = !!fallbackText
+      && norm(fallbackText) !== norm(interimText)
+      && norm(fallbackText) !== norm(pending._consumedByText);
+    if (interimRescue) {
+      this.logger.warn?.(`[${this.label}] cli: interim-only turn — delivering the produced final answer the status promise didn't (len=${fallbackText.length})`);
+      this._logEvent('cli-interim-only-final-rescued', {
+        turn_id: turnId, session_key: this.sessionKey, backend: this.backend,
+        rescued_len: fallbackText.length, interim_count: pending.replies.length,
+      });
+      return { text: fallbackText, alreadyDelivered: false };
+    }
+    return { text: interimText, alreadyDelivered: true };
+  }
+
   _finalizeTurn(turnId) {
     const pending = this.pendingTurns.get(turnId);
     if (!pending) return;
@@ -1924,39 +2017,7 @@ class CliProcess extends Process {
     if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
     if (pending._activityQuietTimer) clearTimeout(pending._activityQuietTimer);   // 0.13 D1
     if (pending._onStop) { this.off('stop-hook', pending._onStop); pending._onStop = null; }
-    const hadReplyToolCalls = pending.replies.length > 0;
-    let text = pending.replies.join('\n\n');
-    // 0.12 Phase 1.7 fallback: if no reply tool calls landed (claude ended
-    // the turn without calling mcp__polygram-bridge__reply), use the Stop
-    // hook's last_assistant_message as the text. Same rescue pattern rc.41
-    // H4 uses on tmux backend when JSONL stream is broken.
-    const usedStopFallback = !text && !!pending._stopHookData?.lastAssistantMessage;
-    if (usedStopFallback) {
-      text = pending._stopHookData.lastAssistantMessage;
-      this.logger.warn?.(`[${this.label}] cli: turn finalized via stop-hook fallback (no reply tool call); text_len=${text.length}`);
-    }
-    // A _consumedAcked turn is "already delivered" ONLY when the consuming
-    // sibling reply actually carried THIS text — not merely an ack. Prod
-    // 2026-06-13 (Shumabit@UMI/37): the consuming reply was a 294-char
-    // "Researching now…" ack, then the real answer arrived as Stop-fallback
-    // text. Suppressing it (alreadyDelivered=true → polygram.js short-circuit)
-    // dropped the answer silently for 5h20m. Only suppress when the rescued
-    // text matches what the sibling delivered.
-    // docs/0.13-consumed-ack-stop-fallback-drop-spec.md
-    const norm = (s) => (s || '').trim();
-    const consumedCoversFallback = !usedStopFallback || norm(text) === norm(pending._consumedByText);
-    const alreadyDelivered = hadReplyToolCalls
-      || (pending._consumedAcked === true && consumedCoversFallback);
-    if (usedStopFallback && pending._consumedAcked === true && !consumedCoversFallback) {
-      this.logger.warn?.(`[${this.label}] cli: consumed-ack did NOT cover the Stop-fallback answer — delivering rescued text (len=${text.length})`);
-      this._logEvent('cli-consumed-ack-fallback-rescued', {
-        turn_id: turnId,
-        session_key: this.sessionKey,
-        backend: this.backend,
-        rescued_len: text.length,
-        ack_len: norm(pending._consumedByText).length,
-      });
-    }
+    const { text, alreadyDelivered } = this._resolveTurnDelivery(pending, turnId);
     const duration = Date.now() - pending.startedAt;
     // Review AC4: cost=null + metrics-tokens=null signal "unmeasured-subscription"
     // (channels protocol doesn't expose per-turn cost or token breakdowns).
@@ -2007,7 +2068,13 @@ class CliProcess extends Process {
     // claude copied in to send don't accumulate on disk across turns. Only
     // when fully idle, so a file staged for a still-pending concurrent turn
     // isn't yanked mid-send.
-    if (this.pendingTurns.size === 0) this._purgeStagingDir();
+    if (this.pendingTurns.size === 0) {
+      this._purgeStagingDir();
+      // B3: fully idle — drop any in-flight sub-agent bookkeeping so a lost
+      // SubagentStop can't leak a stale count (a stuck "working" hold) into the
+      // next turn. Safe only when no turn is pending (it's proc-wide state).
+      this._pendingSubagentStarts = [];
+    }
   }
 
   /**
@@ -2129,14 +2196,20 @@ class CliProcess extends Process {
         // 2026-06-11 19:49 false ⏱; see _ledgerAckConsumed).
         if ((pending.replies?.length || 0) > 0
             || (pending.seen === true && pending._consumedAcked === true)) {
+          // Interim-aware: an interim-only turn delivers its PRODUCED final answer
+          // here too (not the status promise) — the same rescue as _finalizeTurn, so
+          // the answer isn't dropped when the turn resolves at a ceiling rather than
+          // via Stop. docs/progress-is-not-turn-end-spec.md
+          const { text, alreadyDelivered } = this._resolveTurnDelivery(pending, turnId);
           this._logEvent('cli-turn-ceiling-resolved', {
             reason, turnTimeoutMs, reply_count: pending.replies?.length || 0,
             consumed_acked: pending._consumedAcked === true,
+            interim_only: !this._turnHasFinalReply(pending),
           });
           this.emit('idle');
           resolve({
-            text: pending.replies.join('\n\n'),
-            alreadyDelivered: true,
+            text,
+            alreadyDelivered,
             sessionId: this.claudeSessionId,
             cost: null,
             duration: Date.now() - pending.startedAt,
@@ -2378,8 +2451,11 @@ class CliProcess extends Process {
   async _checkpointAbsolute(turnId) {
     if (!this.pendingTurns.has(turnId)) return;
     let pending = this.pendingTurns.get(turnId);
-    // Replied turn (or consumed-acked): the ceiling RESOLVES it, never extends.
-    if ((pending.replies?.length || 0) > 0
+    // Turn with a FINAL reply (or consumed-acked): the ceiling RESOLVES it, never
+    // extends. An interim-only turn (status promise, no final reply) is still
+    // working — fall through to the busy-aware probe so it extends, not resolves.
+    // docs/progress-is-not-turn-end-spec.md
+    if (this._turnHasFinalReply(pending)
         || (pending.seen === true && pending._consumedAcked === true)) {
       pending._fireTimeout('absolute');
       return;
@@ -2394,7 +2470,7 @@ class CliProcess extends Process {
     // now would resurrect a settling turn (spurious "still working" right as the
     // real answer lands). It will finalize through its own quiet/grace path.
     if (pending._stopGracePending
-        || (pending.replies?.length || 0) > 0
+        || this._turnHasFinalReply(pending)
         || (pending.seen === true && pending._consumedAcked === true)) return;
     const now = Date.now();
     const elapsed = now - pending.startedAt;
@@ -2830,6 +2906,9 @@ class CliProcess extends Process {
             // SubagentStop). We still emit the start event so the reactor
             // can transition into SUBAGENT state immediately.
             toolUseId: ev.toolUseId,
+            // B3: in-flight sub-agent count so the reactor holds a "working" face
+            // (suppresses the 🥱/😨 decay) until the LAST sub-agent finishes.
+            inFlight: this._pendingSubagentStarts.length,
             backend: this.backend,
           });
           return;
@@ -2879,6 +2958,9 @@ class CliProcess extends Process {
           agentId: ev.agentId,
           durationMs: ev.durationMs,
           toolUseId: subagentToolUseId,
+          // B3: remaining in-flight sub-agents (post-decrement). 0 ⇒ the reactor
+          // resumes the normal stall/freeze cascade.
+          inFlight: this._pendingSubagentStarts.length,
           backend: this.backend,
         });
         return;

package/lib/sdk/callbacks.js

@@ -787,7 +787,13 @@ function createSdkCallbacks({
         // prior tool's emoji. The plan promised this; previously the handler
         // only persisted the DB row and never touched the reactor.
         const r = entry?.pendingQueue?.[0]?.context?.reactor;
-        if (r) r.setState('SUBAGENT');
+        if (r) {
+          r.setState('SUBAGENT');
+          // B3: hold a "working" face for the whole sub-agent run — the quiet
+          // stretch between its tool hooks is expected, not a stall, so suppress
+          // the 🥱/😨 decay until it finishes. docs/progress-is-not-turn-end-spec.md
+          if (typeof r.setWorkInFlight === 'function') r.setWorkInFlight(true);
+        }
       } catch (err) {
         logger.error?.(`[${botName}] subagent-start handler: ${err.message}`);
       }
@@ -798,7 +804,12 @@ function createSdkCallbacks({
         // L9/L14: heartbeat at subagent end so the cascade/stall clock
         // resets; the next tool's PreToolUse sets the following state.
         const r = entry?.pendingQueue?.[0]?.context?.reactor;
-        if (r && typeof r.heartbeat === 'function') r.heartbeat();
+        if (r) {
+          // B3: release the working-hold only when the LAST sub-agent finishes
+          // (inFlight === 0) — nested/parallel sub-agents keep it held.
+          if (typeof r.setWorkInFlight === 'function') r.setWorkInFlight((payload?.inFlight ?? 0) > 0);
+          if (typeof r.heartbeat === 'function') r.heartbeat();
+        }
         logEvent('subagent-done', {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,

package/lib/telegram/reactions.js

@@ -226,6 +226,9 @@ function createReactionManager({
   // Chaining all applies through `applyChain` guarantees they're sent
   // to Telegram in setState() invocation order.
   let applyChain = Promise.resolve();
+  // B3: set true while a sub-agent / background work is in flight — suppresses the
+  // stall/freeze decay so a working-but-quiet turn never shows 🥱/😨.
+  let workInFlight = false;
   // States the auto-stall path may transition to. Once we've already
   // shown STALL or TIMEOUT we don't downgrade or rearm — only an
   // explicit setState() call (Claude resumed) can move us forward.
@@ -330,6 +333,10 @@ function createReactionManager({
   const armStallTimers = () => {
     clearStallTimers();
     if (stopped) return;
+    // B3: while a sub-agent (or background work) is genuinely in flight, a quiet
+    // stretch is EXPECTED — the turn is working, not stalled. Don't arm the
+    // 🥱/😨 decay; hold the current working face until work drains.
+    if (workInFlight) return;
     if (!STALL_PROMOTABLE.has(currentState)) return;
     stallTimer = setTimeout(() => {
       stallTimer = null;
@@ -432,6 +439,7 @@ function createReactionManager({
 
   const stop = () => {
     stopped = true;
+    workInFlight = false;   // B3: defense-in-depth if a reactor is ever reused
     if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
     clearStallTimers();
     clearDeepeningTimers();
@@ -452,11 +460,24 @@ function createReactionManager({
     armStallTimers();
   };
 
+  // B3: mark whether work (a sub-agent / background shell) is in flight. While
+  // active, the silence between tool hooks is expected, so the stall/freeze decay
+  // is suppressed and the reactor holds its working face. When work drains, the
+  // normal cascade resumes from now. docs/progress-is-not-turn-end-spec.md
+  const setWorkInFlight = (active) => {
+    const next = !!active;
+    if (next === workInFlight) return;
+    workInFlight = next;
+    if (workInFlight) clearStallTimers();   // cancel any pending 🥱/😨 decay
+    else armStallTimers();                   // work drained — resume the cascade
+  };
+
   return {
     setState,
     clear,
     stop,
     heartbeat,
+    setWorkInFlight,
     // Introspection for tests:
     get currentState() { return currentState; },
     get currentEmoji() { return currentEmoji; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "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": {

package/polygram.js

@@ -2484,12 +2484,16 @@ async function main() {
   // 0.11.0: binCheck reused for channels backend wiring below.
   let pinnedClaudeBin = null;
   {
-    const { CLAUDE_CLI_PINNED_VERSION } = require('./lib/claude-bin');
-    const { verifyPinnedClaudeBin } = require('./lib/claude-bin');
-    const binCheck = verifyPinnedClaudeBin(CLAUDE_CLI_PINNED_VERSION);
+    // 0.17: vendor a polygram-owned copy of the pinned binary so claude's
+    // auto-pruner (keeps only ~3 newest, deletes the rest) can't take cli chats
+    // down. Spawns from ~/.local/share/polygram/claude-bin/<version>, immune to
+    // pruning. Self-heals on boot (copy from the system install, else install).
+    const { CLAUDE_CLI_PINNED_VERSION, ensureVendoredClaudeBin } = require('./lib/claude-bin');
+    const binCheck = ensureVendoredClaudeBin(CLAUDE_CLI_PINNED_VERSION, { logger: console });
     if (binCheck.ok) {
       console.log(
-        `[polygram] CliProcess pinned to claude CLI v${CLAUDE_CLI_PINNED_VERSION}: ${binCheck.path}`,
+        `[polygram] CliProcess pinned to claude CLI v${CLAUDE_CLI_PINNED_VERSION}: ${binCheck.path}`
+        + `${binCheck.vendored ? ' (vendored)' : ''}`,
       );
       pinnedClaudeBin = binCheck.path;
     } else {