polygram 0.10.0-rc.28 → 0.10.0-rc.29

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.28",
+  "version": "0.10.0-rc.29",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/process/tmux-process.js

@@ -43,6 +43,7 @@ const { getTopicConfig } = require('../session-key');
 const { POLYGRAM_DISPLAY_HINT } = require('../telegram/display-hint');
 const { verifyPinnedClaudeBin } = require('../claude-bin');
 const { createAsyncLock } = require('../async-lock');
+const { TurnPhase, isLegalTransition } = require('./turn-phase');
 
 // ─── Pinned claude CLI version ───────────────────────────────────────
 //
@@ -160,6 +161,16 @@ const APPROVAL_PROMPT_RE = /Do you want to [^\n?]{1,80}\??[\s\S]{0,400}?(?:^|\n)
 // approval prompt. Capture-pane preserves the ⏺ marker.
 const TOOL_INVOCATION_RE = /⏺\s+([A-Za-z_]\w*)\s*\((.*?)\)\s*$/m;
 
+// 0.10.0 predicate H1 fallback (paste-parked via capture-pane). The
+// claude TUI shows this indicator when a paste was rejected to the
+// queue because the previous turn was busy. The JSONL
+// `queue-operation enqueue` is the primary signal for `paste-parked`
+// (correlation-token bound); this regex is the fallback path when
+// JSONL hasn't tailed in yet (typical 50-200ms gap between TUI
+// rendering and JSONL flush) so the predicate doesn't briefly stall
+// on `pasted-unconfirmed`.
+const QUEUED_PASTE_RE = /Press up to edit queued messages/;
+
 // ─── Defaults — overridable per construction for tests ───────────────
 
 // Cold-spawn budget for claude TUI to reach "? for shortcuts" / "accept
@@ -650,6 +661,8 @@ class TmuxProcess extends Process {
       // interleave keystrokes with this primary prompt.
       const result = await this._pasteAndEnter(
         this._embedToken(turn.prompt, turn.token));
+      // Predicate (observer-only): paste returned, no JSONL signal yet.
+      this._setPhase(turn, TurnPhase.PASTED_UNCONFIRMED, 'paste:returned');
       if (result.stripped > 0) {
         this.logger.warn?.(
           `[${this.label}] stripped ${result.stripped} control chars from prompt`,
@@ -903,6 +916,16 @@ class TmuxProcess extends Process {
       const u = this._lastUsage;
       const cost = u ? computeCostUsd(u, u.model) : null;
       turn.state = 'done';
+      // Predicate (observer-only): terminal phase. The JSONL `result`
+      // event also drives this via `_evaluatePhaseFromSessionEvent`,
+      // but the capture-pane / interrupt / submit-fail branches do
+      // not; this ensures every successful exit lands the turn in
+      // `done` regardless of which racer won.
+      this._setPhase(
+        turn,
+        TurnPhase.DONE,
+        `runTurn:resolve:${resultSubtype}:${resolvedVia}`,
+      );
       turn.resolve({
         text,
         sessionId: this.claudeSessionId,
@@ -923,6 +946,15 @@ class TmuxProcess extends Process {
       });
     } catch (err) {
       turn.state = 'failed';
+      // Predicate (observer-only): terminal phase on the error path.
+      // Includes the err.code in `reason` so phase-change observers
+      // can distinguish TMUX_SUBMIT_FAILED / TMUX_NO_JSONL_TEXT /
+      // TMUX_EMPTY_JSONL_RESULT / TMUX_TURN_TIMEOUT / etc.
+      this._setPhase(
+        turn,
+        TurnPhase.FAILED,
+        `runTurn:reject:${err.code || 'tmux_send_error'}`,
+      );
       turn.resolve(this._errorResult(err.code || 'tmux_send_error', err.message || String(err)));
     } finally {
       this._finishTurn(turn);
@@ -995,6 +1027,7 @@ class TmuxProcess extends Process {
   /** Build a fresh Turn record. */
   _makeTurn({ kind, prompt = '', opts = {}, context = {}, msgIds = [] }) {
     this._turnSeq += 1;
+    const now = this._now();
     return {
       turnId: this._turnSeq,
       token: this._mintToken(),
@@ -1022,6 +1055,22 @@ class TmuxProcess extends Process {
       // `_runTurn` race end promptly instead of hanging until
       // `turnTimeoutMs`. Armed at the top of `_runTurn`.
       signalInterrupt: null, interruptP: null, interrupted: false,
+      // 0.10.0 predicate (Commit 1, observer-only): unified turn
+      // phase. See lib/process/turn-phase.js. Mutated only via
+      // `_setPhase`; consumed by no existing control flow in this
+      // commit. Subsequent commits replace the patience timers that
+      // currently race on a turn's behalf (`_runTurn`'s 5-way race,
+      // §6 fail-loud, B10 outstanding-Agent suppression).
+      phase: TurnPhase.QUEUED,
+      phaseSince: now,
+      lastActivityAt: now,
+      submitConfirmed: false,
+      parked: false,
+      // Generalisation of `outstandingSubagents` — every non-Agent
+      // tool_use's id while it is in flight. Today only Agent is
+      // tracked (B10); the predicate uses both sets to keep `quiet`
+      // unreachable while any tool is genuinely outstanding.
+      outstandingTools: new Set(),
     };
   }
 
@@ -1086,6 +1135,175 @@ class TmuxProcess extends Process {
     this._pruneLedger();
   }
 
+  // ─── 0.10.0 turn-phase predicate (Commit 1: observer-only) ────────
+  //
+  // The five-agent investigation (docs/0.10.0-tmux-patience-model-
+  // solution.md) found 14+ uncoordinated patience timers, several
+  // mutually inconsistent under the music-curation workload. The fix
+  // is one state machine fed by all signals continuously; timers only
+  // demote phases on silence, never advance them.
+  //
+  // This commit lands the predicate as an OBSERVER. Every signal that
+  // reaches `_handleSessionEvent`, the capture-pane poll, and the
+  // debug-log poll feeds `_setPhase` / `_heartbeat`. `phase-change`
+  // events fire for observability. **No existing control flow reads
+  // `turn.phase` yet** — `_runTurn`'s 5-way race, §6 fail-loud, B10
+  // outstanding-Agent suppression, and `_sweepStaleTurns` remain
+  // exactly as they are. Commits 2-3 replace them one at a time.
+
+  /**
+   * Transition `turn` to `next` phase if and only if it is different
+   * from the current phase. Emits a `phase-change` event for
+   * observability. Soft-asserts the transition is legal — logs at
+   * warn level and proceeds (observer-only must never block).
+   *
+   * @param {object} turn      - the turn whose phase changes
+   * @param {string} next      - the next TurnPhase value
+   * @param {string} reason    - short tag for the trigger (e.g. 'jsonl:user-message')
+   * @returns {boolean}         true iff phase actually changed
+   */
+  _setPhase(turn, next, reason) {
+    if (!turn) return false;
+    const prev = turn.phase;
+    if (prev === next) return false;
+    if (!isLegalTransition(prev, next)) {
+      // Observer-only: log and proceed. A real illegal transition is
+      // either a bug in the wiring or a signal pattern the design
+      // didn't anticipate — both worth surfacing without breaking the
+      // turn. Tests assert the legal graph; production prefers honesty
+      // over rigidity.
+      this.logger.warn?.(
+        `[${this.label}] phase illegal transition: ${prev} → ${next}`
+        + ` (turn ${turn.turnId}, reason ${reason})`,
+      );
+    }
+    const now = this._now();
+    turn.phase = next;
+    turn.phaseSince = now;
+    turn.lastActivityAt = now;
+    this.emit('phase-change', {
+      turnId: turn.turnId,
+      msgId: turn.msgIds[0] ?? null,
+      kind: turn.kind,
+      prev,
+      next,
+      reason,
+      ts: now,
+      sessionId: this.claudeSessionId,
+      backend: 'tmux',
+    });
+    return true;
+  }
+
+  /**
+   * Mark a turn as having received a liveness signal at this instant.
+   * Bumps `lastActivityAt`; does NOT change phase by itself. The
+   * demote-on-silence path (future commit) compares `lastActivityAt`
+   * to `quietToleranceMs` to decide when to demote to `quiet`.
+   *
+   * Sources that should call this on every event:
+   *   - assistant-chunk / tool-use / tool-result / usage (JSONL)
+   *   - capture-pane sees `esc to interrupt`
+   *   - debug-log size grew
+   *
+   * Phase-advancing signals call `_setPhase` instead (which also
+   * bumps `lastActivityAt` internally).
+   */
+  _heartbeat(turn, source) {
+    if (!turn) return;
+    turn.lastActivityAt = this._now();
+    // No event emission — heartbeats are high-frequency; the
+    // phase-change event is the consumer-visible surface. Source tag
+    // is reserved for future debug telemetry.
+    void source;
+  }
+
+  /**
+   * Drive the predicate for an active group from a JSONL session
+   * event. Pure routing — each event maps to a phase transition (or
+   * a heartbeat for in-phase signals).
+   *
+   * Called from `_handleSessionEvent` AFTER the existing branches do
+   * their work, so today's behaviour is untouched.
+   *
+   * @param {object} ev - the parsed session-log event
+   * @param {Array<object>} turns - the active group turns (may be empty)
+   */
+  _evaluatePhaseFromSessionEvent(ev, turns) {
+    if (!Array.isArray(turns) || turns.length === 0) return;
+    for (const t of turns) {
+      // Don't move terminal phases — `done`/`failed` are absorbing.
+      if (t.phase === TurnPhase.DONE || t.phase === TurnPhase.FAILED) continue;
+
+      if (ev.type === 'user-message') {
+        // Submit landed. Set both the flag and the phase.
+        if (!t.submitConfirmed) t.submitConfirmed = true;
+        this._setPhase(t, TurnPhase.SUBMITTED, 'jsonl:user-message');
+      } else if (ev.type === 'assistant-chunk') {
+        this._setPhase(t, TurnPhase.STREAMING, 'jsonl:assistant-chunk');
+      } else if (ev.type === 'tool-use') {
+        if (typeof ev.id === 'string' && ev.name !== 'Agent') {
+          t.outstandingTools.add(ev.id);
+        }
+        // Phase choice: subagent > tool > streaming. A Bash tool-use
+        // arriving while an Agent is outstanding must NOT demote
+        // SUBAGENT_RUNNING — both are "in flight," but the predicate's
+        // public contract is "the most-restrictive active phase wins."
+        // Agent absence + outstanding Agent set is impossible (the
+        // existing branch added before us), so we read both sets.
+        if (t.outstandingSubagents.size > 0) {
+          this._setPhase(t, TurnPhase.SUBAGENT_RUNNING, `jsonl:tool-use:${ev.name || 'unknown'}`);
+        } else if (t.outstandingTools.size > 0) {
+          this._setPhase(t, TurnPhase.TOOL_RUNNING, `jsonl:tool-use:${ev.name || 'unknown'}`);
+        } else {
+          // No id (rare — older event shapes) — heartbeat only.
+          this._heartbeat(t, 'jsonl:tool-use:no-id');
+        }
+      } else if (ev.type === 'tool-result') {
+        if (typeof ev.toolUseId === 'string') {
+          t.outstandingTools.delete(ev.toolUseId);
+        }
+        // Phase choice: prefer the most-active outstanding state.
+        // Subagent > tool > streaming.
+        if (t.outstandingSubagents.size > 0) {
+          // Still waiting on a subagent; phase stays.
+          this._heartbeat(t, 'jsonl:tool-result:subagent-still-out');
+        } else if (t.outstandingTools.size > 0) {
+          this._setPhase(t, TurnPhase.TOOL_RUNNING, 'jsonl:tool-result:tool-still-out');
+        } else {
+          this._setPhase(t, TurnPhase.STREAMING, 'jsonl:tool-result:drained');
+        }
+      } else if (ev.type === 'usage') {
+        this._heartbeat(t, 'jsonl:usage');
+      } else if (ev.type === 'result') {
+        if (ev.subtype === 'tool_use') {
+          // Non-terminal — agent paused for a tool. The matching
+          // tool-use line will have moved the phase already.
+          this._heartbeat(t, 'jsonl:result:tool_use-nonterm');
+        } else {
+          // Terminal stop_reason — turn ended.
+          this._setPhase(t, TurnPhase.DONE, `jsonl:result:${ev.subtype || 'success'}`);
+        }
+      } else if (ev.type === 'queue-operation') {
+        if (ev.operation === 'enqueue' && ev.content) {
+          const tokens = this._extractTokens(ev.content);
+          if (tokens.includes(t.token)) {
+            // Our paste landed in the TUI queue (proof of arrival AND
+            // proof of parking). The W11/W25 C1 resolution: the
+            // future B7 successor will read `turn.parked === true`
+            // and stop re-sending Enter.
+            t.parked = true;
+            this._setPhase(t, TurnPhase.PASTE_PARKED, 'jsonl:queue-operation:enqueue');
+          }
+        }
+        // remove/dequeue do not change phase by themselves — the
+        // follow-up user-message moves the turn to `submitted` if it
+        // is the head being released.
+      }
+      // Other event types (last-prompt, queue-folded) — observer-only
+      // no-ops in this commit.
+    }
+  }
   _dropFromActiveGroup(turn) {
     this._activeGroup.turns = this._activeGroup.turns.filter((t) => t !== turn);
   }
@@ -1147,6 +1365,16 @@ class TmuxProcess extends Process {
   }
 
   _handleSessionEvent(ev) {
+    // Predicate (observer-only): snapshot the active group's turns
+    // BEFORE the existing branches run. The `result` and `last-prompt`
+    // branches flush the group (clearing `_activeGroup.turns`) — if
+    // the predicate evaluates against `this._activeGroup.turns` at the
+    // bottom of this method, it sees an empty array for those events.
+    // The snapshot is by-reference (same turn objects), so any
+    // mutations the existing branches make (e.g. outstandingSubagents
+    // updates) ARE visible to the predicate.
+    const activeTurnsSnapshot = (this._activeGroup?.turns || []).slice();
+
     if (ev.type === 'assistant-chunk') {
       // Assistant text belongs to whatever turn(s) the latest
       // `user-message` token routed into the active group. The
@@ -1319,6 +1547,59 @@ class TmuxProcess extends Process {
         });
       }
     }
+
+    // 0.10.0 predicate (Commit 1, observer-only): every event also
+    // drives the phase machine. Runs LAST so today's existing
+    // branches above have already executed and the predicate sees
+    // post-mutation state (e.g. `outstandingSubagents` already
+    // updated for `tool-use`/`tool-result`). Emits `phase-change`
+    // events only — no consumer reads `turn.phase` in this commit.
+    //
+    // `queue-operation enqueue` and `user-message` may route to
+    // turns OUTSIDE the active group (an autosteer in the ledger
+    // that has not yet folded). For those we evaluate the ledger
+    // turn directly.
+    try {
+      this._evaluatePhaseFromSessionEvent(ev, activeTurnsSnapshot);
+      if (ev.type === 'queue-operation'
+        && ev.operation === 'enqueue'
+        && ev.content) {
+        const tokens = this._extractTokens(ev.content);
+        const extra = [];
+        for (const tok of tokens) {
+          const t = this._ledger.find(
+            (x) => x.token === tok
+              && x.state !== 'done' && x.state !== 'failed'
+              && !activeTurnsSnapshot.includes(x),
+          );
+          if (t) extra.push(t);
+        }
+        if (extra.length > 0) {
+          this._evaluatePhaseFromSessionEvent(ev, extra);
+        }
+      }
+      if (ev.type === 'user-message') {
+        const tokens = this._extractTokens(ev.text);
+        const extra = [];
+        for (const tok of tokens) {
+          const t = this._ledger.find(
+            (x) => x.token === tok
+              && x.state !== 'done' && x.state !== 'failed'
+              && !activeTurnsSnapshot.includes(x),
+          );
+          if (t) extra.push(t);
+        }
+        if (extra.length > 0) {
+          this._evaluatePhaseFromSessionEvent(ev, extra);
+        }
+      }
+    } catch (err) {
+      // Observer-only: a bug in the predicate must not break the
+      // existing turn flow. Log and swallow.
+      this.logger.warn?.(
+        `[${this.label}] predicate error: ${err.message || err}`,
+      );
+    }
   }
 
   /**
@@ -1862,10 +2143,34 @@ class TmuxProcess extends Process {
         const bottomTail = lastBuf.slice(-2000);  // ~10-20 lines of pane bottom
         cachedReady = READY_HINTS_RE.test(lastBuf) && !TUI_BANNER_RE.test(bottomTail);
         cachedStreaming = STREAMING_HINT_RE.test(lastBuf);
+        // Predicate (observer-only): capture-pane signals heartbeat
+        // the active turns. `esc to interrupt` is the single most-
+        // useful TUI signal (Agent C) — always present mid-turn,
+        // including during subagent runs. The H1 indicator is the
+        // fallback for `paste-parked` when JSONL hasn't tailed yet.
+        const activeTurns = this._activeGroup?.turns || [];
+        if (cachedStreaming) {
+          for (const t of activeTurns) this._heartbeat(t, 'capture:streaming');
+        }
+        if (QUEUED_PASTE_RE.test(lastBuf)) {
+          for (const t of activeTurns) {
+            if (t.phase === TurnPhase.PASTED_UNCONFIRMED && !t.parked) {
+              t.parked = true;
+              this._setPhase(t, TurnPhase.PASTE_PARKED, 'capture:queued-fallback');
+            }
+          }
+        }
         // Approval-prompt detection ONLY runs on changed captures.
         // It's the heaviest regex (`[\s\S]{0,400}?` non-greedy) so
         // worth skipping on quiescent ticks.
         if (APPROVAL_PROMPT_RE.test(lastBuf)) {
+          // Predicate (observer-only): approval-pending blocks turn
+          // progress until respondToApproval lands. Mark BEFORE the
+          // existing handler runs so observers see the transition
+          // before any side-effects.
+          for (const t of activeTurns) {
+            this._setPhase(t, TurnPhase.APPROVAL_PENDING, 'capture:approval-prompt');
+          }
           await this._handleApprovalPrompt(lastBuf);
           firstReadyAt = null;     // approval pause resets ready clock
           if (await raceAbort(this._waitForNextTick()) === ABORT_SENTINEL) {
@@ -1959,6 +2264,16 @@ class TmuxProcess extends Process {
         await this.runner.sendControl(this.tmuxName, 'Enter');
       }
       this._pendingApprovalId = null;
+      // Predicate (observer-only): the approval was decided. The
+      // assistant will resume — demote `approval-pending` back to
+      // `streaming` on every active-group turn that is still in
+      // that phase. The next assistant-chunk / tool-use will move
+      // them again from there.
+      for (const t of this._activeGroup?.turns || []) {
+        if (t.phase === TurnPhase.APPROVAL_PENDING) {
+          this._setPhase(t, TurnPhase.STREAMING, `approval:${decision}`);
+        }
+      }
       return true;
     } catch (err) {
       this.emit('approval-fail', { id, err: err.message });

package/lib/process/turn-phase.js

@@ -0,0 +1,142 @@
+/**
+ * TurnPhase — unified per-turn liveness state.
+ *
+ * Companion to `docs/0.10.0-tmux-patience-model-solution.md`. This
+ * module exports the enum and the active/inactive partition only.
+ * Phase computation lives on TmuxProcess so it can reach turn state
+ * (`outstandingTools`, `outstandingSubagents`, `submitConfirmed`,
+ * `parked`) without leaking those internals here.
+ *
+ * Commit 1 (predicate as observer):
+ *   - Every signal that reaches `_handleSessionEvent` / the capture
+ *     poll / the debug-log poll feeds the predicate.
+ *   - The predicate transitions per-turn state and emits a
+ *     `phase-change` event.
+ *   - **NO existing control flow consumes `turn.phase` yet** — the
+ *     5-way `Promise.race` in `_runTurn`, the §6 fail-loud branch,
+ *     B10's outstanding-Agent check, `_sweepStaleTurns`, and the
+ *     reactor remain untouched. This commit is purely additive.
+ *
+ * Subsequent commits replace those consumers one at a time
+ * (Commit 2: `_confirmSubmitViaJsonl`; Commit 3: `_runTurn`'s race).
+ *
+ * @see docs/0.10.0-tmux-patience-model-solution.md
+ */
+
+'use strict';
+
+/**
+ * The 13-state phase enum.
+ *
+ *  queued              in pendingQueue, not yet pasted
+ *  pasted-unconfirmed  _pasteAndEnter returned; no JSONL signal yet
+ *  paste-parked        queue-operation enqueue carrying our corr-id seen,
+ *                      or capture-pane fallback ("Press up to edit
+ *                      queued messages")
+ *  submitted           JSONL user-message reproducing our corr-id seen
+ *  streaming           assistant text/thinking arriving
+ *  tool-running        ≥1 outstanding non-Agent tool_use
+ *  subagent-running    ≥1 outstanding `Agent` tool_use (existing B10)
+ *  bg-shell-running    session-level (no in-flight turn); TUI shows
+ *                      `N shell` — not per-turn but included for
+ *                      catalogue completeness
+ *  approval-pending    approval prompt detected; awaiting respondToApproval
+ *  quiet               no active phase + no heartbeat for quietToleranceMs
+ *  wedged              `quiet` held for quietToWedgedMs with empty
+ *                      outstanding sets AND submitConfirmed
+ *  done                terminal JSONL `result` flushed
+ *  failed              explicit failure (TMUX_SUBMIT_FAILED, kill, drain)
+ */
+const TurnPhase = Object.freeze({
+  QUEUED:             'queued',
+  PASTED_UNCONFIRMED: 'pasted-unconfirmed',
+  PASTE_PARKED:       'paste-parked',
+  SUBMITTED:          'submitted',
+  STREAMING:          'streaming',
+  TOOL_RUNNING:       'tool-running',
+  SUBAGENT_RUNNING:   'subagent-running',
+  BG_SHELL_RUNNING:   'bg-shell-running',
+  APPROVAL_PENDING:   'approval-pending',
+  QUIET:              'quiet',
+  WEDGED:             'wedged',
+  DONE:               'done',
+  FAILED:             'failed',
+});
+
+/**
+ * Active phases — the predicate's "turn is making progress" set.
+ *
+ * Any phase here means we have *positive evidence* the turn is alive:
+ * either we just acted on it (paste/park/submit), or a signal
+ * arrived (streaming/tool/subagent/approval), or it's holding the
+ * session (bg-shell).
+ *
+ * Inactive: queued (not started), quiet (silence — demoted), wedged
+ * (silence past the wedged threshold), done/failed (terminal).
+ */
+const ACTIVE_PHASES = Object.freeze(new Set([
+  TurnPhase.PASTED_UNCONFIRMED,
+  TurnPhase.PASTE_PARKED,
+  TurnPhase.SUBMITTED,
+  TurnPhase.STREAMING,
+  TurnPhase.TOOL_RUNNING,
+  TurnPhase.SUBAGENT_RUNNING,
+  TurnPhase.BG_SHELL_RUNNING,
+  TurnPhase.APPROVAL_PENDING,
+]));
+
+const TERMINAL_PHASES = Object.freeze(new Set([
+  TurnPhase.DONE,
+  TurnPhase.FAILED,
+]));
+
+/** True when phase is one of the "turn making progress" states. */
+function isActive(phase) {
+  return ACTIVE_PHASES.has(phase);
+}
+
+/** True when phase is terminal — `done` or `failed`. */
+function isTerminal(phase) {
+  return TERMINAL_PHASES.has(phase);
+}
+
+/**
+ * The set of phases that are reachable FROM a given phase. Used by
+ * tests to assert no illegal jumps; also documents the state machine
+ * shape in code. Terminal phases have no successors.
+ *
+ * The graph is intentionally permissive — observer-only Commit 1
+ * doesn't gate any transitions; future commits MAY tighten this.
+ */
+const ALLOWED_TRANSITIONS = Object.freeze({
+  [TurnPhase.QUEUED]:             new Set([TurnPhase.PASTED_UNCONFIRMED, TurnPhase.FAILED]),
+  [TurnPhase.PASTED_UNCONFIRMED]: new Set([TurnPhase.PASTE_PARKED, TurnPhase.SUBMITTED, TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.PASTE_PARKED]:       new Set([TurnPhase.SUBMITTED, TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.SUBMITTED]:          new Set([TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.STREAMING]:          new Set([TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.TOOL_RUNNING]:       new Set([TurnPhase.TOOL_RUNNING, TurnPhase.STREAMING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.SUBAGENT_RUNNING]:   new Set([TurnPhase.SUBAGENT_RUNNING, TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.BG_SHELL_RUNNING]:   new Set([TurnPhase.STREAMING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.APPROVAL_PENDING]:   new Set([TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.QUIET, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.QUIET]:              new Set([TurnPhase.STREAMING, TurnPhase.TOOL_RUNNING, TurnPhase.SUBAGENT_RUNNING, TurnPhase.APPROVAL_PENDING, TurnPhase.WEDGED, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.WEDGED]:             new Set([TurnPhase.STREAMING, TurnPhase.DONE, TurnPhase.FAILED]),
+  [TurnPhase.DONE]:               new Set(),
+  [TurnPhase.FAILED]:             new Set(),
+});
+
+/** True iff `next` is a legal successor of `prev`. */
+function isLegalTransition(prev, next) {
+  if (prev === next) return true;
+  const successors = ALLOWED_TRANSITIONS[prev];
+  return Boolean(successors && successors.has(next));
+}
+
+module.exports = {
+  TurnPhase,
+  ACTIVE_PHASES,
+  TERMINAL_PHASES,
+  ALLOWED_TRANSITIONS,
+  isActive,
+  isTerminal,
+  isLegalTransition,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.10.0-rc.28",
+  "version": "0.10.0-rc.29",
   "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": {