polygram 0.17.0 → 0.17.1

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.17.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": {